API Docs for: 2.0.0-beta.1
Show:

Output Class

Defined in: src/webmidi.js:2039

The Output object represents a MIDI output port on the host system. This object is created by the MIDI subsystem and cannot be instantiated directly.

You will find all available Output objects in the WebMidi.outputs array.

Methods

_convertChannelToArray

(
  • [channel]
)
protected

Defined in src/webmidi.js:3910

Converts an input value (which can be an int, an array or the value "all" to an array of valid MIDI channels. If undefined is provided as the channel, an array of all channels will be returned.

Parameters:

  • [channel] Uint | Array optional

_convertNoteToArray

(
  • [note]
)
protected

Defined in src/webmidi.js:3888

Converts an input value (which can be a uint, a string or an array of the previous two) to an array of MIDI note numbers.

Parameters:

_deselectRegisteredParameter

(
  • channel
  • time
)
Output protected

Defined in src/webmidi.js:3018

Deselects the currently active MIDI registered parameter so it is no longer affected by data entry, data increment and data decrement messages.

Current best practice recommends doing that after each call to _setCurrentRegisteredParameter().

Parameters:

Returns:

_onMidiMessage

() protected

Defined in src/webmidi.js:3940

_parseTimeParameter

(
  • [time=0]
)
protected

Defined in src/webmidi.js:3861

Parameters:

_selectNonRegisteredParameter

(
  • parameter
  • channel
  • time
)
Output protected

Defined in src/webmidi.js:2943

Selects a MIDI non-registered parameter so it is affected by data entry, data increment and data decrement messages.

Parameters:

  • parameter Array

    A two-position array specifying the two control bytes (0x63, 0x62) that identify the registered parameter.

  • channel Object
  • time Object

Returns:

_selectRegisteredParameter

(
  • parameter
  • channel
  • time
)
Output protected

Defined in src/webmidi.js:2906

Selects a MIDI registered parameter so it is affected by data entry, data increment and data decrement messages.

Parameters:

  • parameter Array

    A two-position array specifying the two control bytes (0x65, 0x64) that identify the registered parameter.

  • channel Object
  • time Object

Returns:

_setCurrentRegisteredParameter

(
  • data
  • channel
  • time
)
Output protected

Defined in src/webmidi.js:2980

Sets the value of the currently selected MIDI registered parameter.

Parameters:

Returns:

decrementRegisteredParameter

(
  • parameter
  • [channel=all]
  • [options={}]
)
Output chainable

Defined in src/webmidi.js:3280

Decrements the specified MIDI registered parameter by 1. For more specific MIDI usage information, check out RP-18 regarding the usage of increment and decrement controllers.

Unless you are very familiar with the MIDI standard you probably should favour one of the simpler to use functions such as: setPitchbendRange(), setModulationRange(), setMasterTuning(), etc.

Here is the full list of parameter names that can be used with this function:

  • Pitchbend Range (0x00, 0x00): pitchbendrange
  • Channel Fine Tuning (0x00, 0x01): channelfinetuning
  • Channel Coarse Tuning (0x00, 0x02): channelcoarsetuning
  • Tuning Program (0x00, 0x03): tuningprogram
  • Tuning Bank (0x00, 0x04): tuningbank
  • Modulation Range (0x00, 0x05): modulationrange
  • Azimuth Angle (0x3D, 0x00): azimuthangle
  • Elevation Angle (0x3D, 0x01): elevationangle
  • Gain (0x3D, 0x02): gain
  • Distance Ratio (0x3D, 0x03): distanceratio
  • Maximum Distance (0x3D, 0x04): maximumdistance
  • Maximum Distance Gain (0x3D, 0x05): maximumdistancegain
  • Reference Distance Ratio (0x3D, 0x06): referencedistanceratio
  • Pan Spread Angle (0x3D, 0x07): panspreadangle
  • Roll Angle (0x3D, 0x08): rollangle

Parameters:

  • parameter String | Array

    A string identifying the parameter's name (see above) or a two-position array specifying the two control bytes (0x65, 0x64) that identify the registered parameter.

  • [channel=all] Number | Array | String optional

    The MIDI channel number (between 1 and 16) or an array of channel numbers. If the special value "all" is used, the message will be sent to all 16 channels.

  • [options={}] Object optional
    • [time=undefined] DOMHighResTimeStamp | String optional

      This value can be one of two things. If the value is a string starting with the + sign and followed by a number, the request will be delayed by the specified number (in milliseconds). Otherwise, the value is considered a timestamp and the request will be scheduled at that timestamp. The DOMHighResTimeStamp value is relative to the navigation start of the document. To retrieve the current time, you can use WebMidi.time. If time is not present or is set to a time in the past, the request is to be sent as soon as possible.

Returns:

Output:

Returns the Output object so methods can be chained.

Throws:

TypeError The specified parameter is not available.

incrementRegisteredParameter

(
  • parameter
  • [channel=all]
  • [options={}]
)
Output chainable

Defined in src/webmidi.js:3207

Increments the specified MIDI registered parameter by 1. For more specific MIDI usage information, check out RP-18 regarding the usage of increment and decrement controllers.

Unless you are very familiar with the MIDI standard you probably should favour one of the simpler to use functions such as: setPitchbendRange(), setModulationRange(), setMasterTuning(), etc.

Here is the full list of parameter names that can be used with this function:

  • Pitchbend Range (0x00, 0x00): pitchbendrange
  • Channel Fine Tuning (0x00, 0x01): channelfinetuning
  • Channel Coarse Tuning (0x00, 0x02): channelcoarsetuning
  • Tuning Program (0x00, 0x03): tuningprogram
  • Tuning Bank (0x00, 0x04): tuningbank
  • Modulation Range (0x00, 0x05): modulationrange
  • Azimuth Angle (0x3D, 0x00): azimuthangle
  • Elevation Angle (0x3D, 0x01): elevationangle
  • Gain (0x3D, 0x02): gain
  • Distance Ratio (0x3D, 0x03): distanceratio
  • Maximum Distance (0x3D, 0x04): maximumdistance
  • Maximum Distance Gain (0x3D, 0x05): maximumdistancegain
  • Reference Distance Ratio (0x3D, 0x06): referencedistanceratio
  • Pan Spread Angle (0x3D, 0x07): panspreadangle
  • Roll Angle (0x3D, 0x08): rollangle

Parameters:

  • parameter String | Array

    A string identifying the parameter's name (see above) or a two-position array specifying the two control bytes (0x65, 0x64) that identify the registered parameter.

  • [channel=all] Uint | Array | String optional

    The MIDI channel number (between 1 and 16) or an array of channel numbers. If the special value "all" is used, the message will be sent to all 16 channels.

  • [options={}] Object optional
    • [time=undefined] DOMHighResTimeStamp | String optional

      This value can be one of two things. If the value is a string starting with the + sign and followed by a number, the request will be delayed by the specified number (in milliseconds). Otherwise, the value is considered a timestamp and the request will be scheduled at that timestamp. The DOMHighResTimeStamp value is relative to the navigation start of the document. To retrieve the current time, you can use WebMidi.time. If time is not present or is set to a time in the past, the request is to be sent as soon as possible.

Returns:

Output:

Returns the Output object so methods can be chained.

playNote

(
  • note
  • [channel=all]
  • [options={}]
)
Output chainable

Defined in src/webmidi.js:2601

Requests the playback of a single note or multiple notes on the specified channel(s). You can delay the execution of the note on command by using the time property of the options parameter (milliseconds).

If no duration is specified in the options, the note will play until a matching note off is sent. If a duration is specified, a note off will be automatically sent after said duration.

Parameters:

  • note Number | String | Array

    The note(s) you wish to play. The notes can be specified in one of two ways. The first way is by using the MIDI note number (an integer between 0 and 127). The second way is by using the note name followed by the octave (C3, G#4, F-1, Db7). The octave range should be between -2 and 8. The lowest note is C-2 (MIDI note number 0) and the highest note is G8 (MIDI note number 127). It is also possible to specify and array of note numbers and/or names.

  • [channel=all] Number | Array | String optional

    The MIDI channel number (between 1 and 16) or an array of channel numbers. If the special value "all" is used (default), the message will be sent to all 16 channels.

  • [options={}] Object optional
    • [velocity=0.5] Number optional

      The velocity at which to play the note (between 0 and 1). An invalid velocity value will silently trigger the default.

    • [duration=undefined] Int optional

      The number of milliseconds to wait before sending a matching note off event. If left undefined, only a note on message is sent.

    • [release=0.5] Number optional

      The velocity at which to release the note (between 0 and 1). This is only used when a duration has been specified. An invalid release value will silently trigger the default.

    • [time=undefined] DOMHighResTimeStamp | String optional

      This value can be one of two things. If the value is a string starting with the + sign and followed by a number, the request will be delayed by the specified number (in milliseconds). Otherwise, the value is considered a timestamp and the request will be scheduled at that timestamp. The DOMHighResTimeStamp value is relative to the navigation start of the document. To retrieve the current time, you can use WebMidi.time. If time is not present or is set to a time in the past, the request is to be sent as soon as possible.

Returns:

Output:

Returns the Output object so methods can be chained.

send

(
  • status
  • [data=[]]
  • [timestamp=0]
)
Output chainable

Defined in src/webmidi.js:2125

Sends a MIDI message on the MIDI output port, at the scheduled timestamp.

Unless, you are familiar with the details of the MIDI message format, you should not use this method directly. Instead, use one of the simpler helper methods: playNote(), stopNote(), sendControlChange(), sendSystemMessage(), etc.

Details on the format of MIDI messages are available in the summary of MIDI messages of the MIDI Manufacturers Association.

Parameters:

  • status Number

    The MIDI status byte of the message (128-255).

  • [data=[]] Array optional

    An array of uints for the message. The number of data bytes varies depending on the status byte. It is perfectly legal to send no data for some message types. Each byte must be between 0 and 255.

  • [timestamp=0] DOMHighResTimeStamp optional

    The timestamp at which to send the message. You can use WebMidi.time to retrieve the current timestamp. To send immediately, leave blank or use

Returns:

Output:

Returns the Output object so methods can be chained.

Throws:

RangeError:

The data bytes must be integers between 0 (0x00) and 255 (0xFF).

sendActiveSensing

(
  • [options={}]
)
Output chainable

Defined in src/webmidi.js:2485

Sends an Active Sensing real-time message. This tells the device connected to this port that the connection is still good. Active sensing messages should be sent every 300 ms if there was no other activity on the MIDI port.

Parameters:

  • [options={}] Object optional
    • [time=undefined] DOMHighResTimeStamp | String optional

      This value can be one of two things. If the value is a string starting with the + sign and followed by a number, the request will be delayed by the specified number (in milliseconds). Otherwise, the value is considered a timestamp and the request will be scheduled at that timestamp. The DOMHighResTimeStamp value is relative to the navigation start of the document. To retrieve the current time, you can use WebMidi.time. If time is not present or is set to a time in the past, the request is to be sent as soon as possible.

Returns:

Output:

Returns the Output object so methods can be chained.

sendChannelAftertouch

(
  • [pressure=0.5]
  • [channel=all]
  • [options={}]
)
Output chainable

Defined in src/webmidi.js:3758

Sends a MIDI channel aftertouch message to the specified channel(s). For key-specific aftertouch, you should instead use sendKeyAftertouch().

Parameters:

  • [pressure=0.5] Number optional

    The pressure level (between 0 and 1). An invalid pressure value will silently trigger the default behaviour.

  • [channel=all] Number | Array | String optional

    The MIDI channel number (between 1 and 16) or an array of channel numbers. If the special value "all" is used, the message will be sent to all 16 channels.

  • [options={}] Object optional
    • [time=undefined] DOMHighResTimeStamp | String optional

      This value can be one of two things. If the value is a string starting with the + sign and followed by a number, the request will be delayed by the specified number (in milliseconds). Otherwise, the value is considered a timestamp and the request will be scheduled at that timestamp. The DOMHighResTimeStamp value is relative to the navigation start of the document. To retrieve the current time, you can use WebMidi.time. If time is not present or is set to a time in the past, the request is to be sent as soon as possible.

Returns:

Output:

Returns the Output object so methods can be chained.

sendChannelMode

(
  • command
  • value
  • [channel=all]
  • [options={}]
)
Output chainable

Defined in src/webmidi.js:3626

Sends a MIDI channel mode message to the specified channel(s).

The channel mode message to send can be specified numerically or by using one of the following common names:

  • allsoundoff (#120)
  • resetallcontrollers (#121)
  • localcontrol (#122)
  • allnotesoff (#123)
  • omnimodeoff (#124)
  • omnimodeon (#125)
  • monomodeon (#126)
  • polymodeon (#127)

Parameters:

  • command Number | String

    The numerical identifier of the MIDI channel mode message (integer between 120-127) or its name as a string.

  • value Number

    The value to send (integer between 0-127)

  • [channel=all] Number | Array | String optional

    The MIDI channel number (between 1 and 16) or an array of channel numbers. If the special value "all" is used, the message will be sent to all 16 channels.

  • [options={}] Object optional
    • [time=undefined] DOMHighResTimeStamp | String optional

      This value can be one of two things. If the value is a string starting with the + sign and followed by a number, the request will be delayed by the specified number (in milliseconds). Otherwise, the value is considered a timestamp and the request will be scheduled at that timestamp. The DOMHighResTimeStamp value is relative to the navigation start of the document. To retrieve the current time, you can use WebMidi.time. If time is not present or is set to a time in the past, the request is to be sent as soon as possible.

Returns:

Output:

Returns the Output object so methods can be chained.

Throws:

RangeError:

Value must be between 0 and 127.

sendClock

(
  • [options={}]
)
Output chainable

Defined in src/webmidi.js:2384

Sends a MIDI Clock real-time message. According to the standard, there are 24 MIDI Clocks for every quarter note.

Parameters:

  • [options={}] Object optional
    • [time=undefined] DOMHighResTimeStamp | String optional

      This value can be one of two things. If the value is a string starting with the + sign and followed by a number, the request will be delayed by the specified number (in milliseconds). Otherwise, the value is considered a timestamp and the request will be scheduled at that timestamp. The DOMHighResTimeStamp value is relative to the navigation start of the document. To retrieve the current time, you can use WebMidi.time. If time is not present or is set to a time in the past, the request is to be sent as soon as possible.

Returns:

Output:

Returns the Output object so methods can be chained.

sendContinue

(
  • [options={}]
)
WebMidi chainable

Defined in src/webmidi.js:2434

Sends a Continue real-time message. This resumes song playback where it was previously stopped or where it was last cued with a song position message. To start playback from the start, use the sendStart() function.

Parameters:

  • [options={}] Object optional
    • [time=undefined] DOMHighResTimeStamp | String optional

      This value can be one of two things. If the value is a string starting with the + sign and followed by a number, the request will be delayed by the specified number (in milliseconds). Otherwise, the value is considered a timestamp and the request will be scheduled at that timestamp. The DOMHighResTimeStamp value is relative to the navigation start of the document. To retrieve the current time, you can use WebMidi.time. If time is not present or is set to a time in the past, the request is to be sent as soon as possible.

Returns:

WebMidi:

Returns the WebMidi object so methods can be chained.

sendControlChange

(
  • controller
  • [value=0]
  • [channel=all]
  • [options={}]
)
Output chainable

Defined in src/webmidi.js:2769

Sends a MIDI control change message to the specified channel(s) at the scheduled time. The control change message to send can be specified numerically or by using one of the following common names:

  • bankselectcoarse (#0)
  • modulationwheelcoarse (#1)
  • breathcontrollercoarse (#2)
  • footcontrollercoarse (#4)
  • portamentotimecoarse (#5)
  • dataentrycoarse (#6)
  • volumecoarse (#7)
  • balancecoarse (#8)
  • pancoarse (#10)
  • expressioncoarse (#11)
  • effectcontrol1coarse (#12)
  • effectcontrol2coarse (#13)
  • generalpurposeslider1 (#16)
  • generalpurposeslider2 (#17)
  • generalpurposeslider3 (#18)
  • generalpurposeslider4 (#19)
  • bankselectfine (#32)
  • modulationwheelfine (#33)
  • breathcontrollerfine (#34)
  • footcontrollerfine (#36)
  • portamentotimefine (#37)
  • dataentryfine (#38)
  • volumefine (#39)
  • balancefine (#40)
  • panfine (#42)
  • expressionfine (#43)
  • effectcontrol1fine (#44)
  • effectcontrol2fine (#45)
  • holdpedal (#64)
  • portamento (#65)
  • sustenutopedal (#66)
  • softpedal (#67)
  • legatopedal (#68)
  • hold2pedal (#69)
  • soundvariation (#70)
  • resonance (#71)
  • soundreleasetime (#72)
  • soundattacktime (#73)
  • brightness (#74)
  • soundcontrol6 (#75)
  • soundcontrol7 (#76)
  • soundcontrol8 (#77)
  • soundcontrol9 (#78)
  • soundcontrol10 (#79)
  • generalpurposebutton1 (#80)
  • generalpurposebutton2 (#81)
  • generalpurposebutton3 (#82)
  • generalpurposebutton4 (#83)
  • reverblevel (#91)
  • tremololevel (#92)
  • choruslevel (#93)
  • celestelevel (#94)
  • phaserlevel (#95)
  • databuttonincrement (#96)
  • databuttondecrement (#97)
  • nonregisteredparametercoarse (#98)
  • nonregisteredparameterfine (#99)
  • registeredparametercoarse (#100)
  • registeredparameterfine (#101)

Note: as you can see above, not all control change message have a matching common name. This does not mean you cannot use the others. It simply means you will need to use their number instead of their name.

To view a list of all available control change messages, please consult "Table 3 - Control Change Messages" from the MIDI Messages specification.

Parameters:

  • controller Number | String

    The MIDI controller number (0-119) or name.

  • [value=0] Number optional

    The value to send (0-127).

  • [channel=all] Number | Array | String optional

    The MIDI channel number (between 1 and 16) or an array of channel numbers. If the special value "all" is used, the message will be sent to all 16 channels.

  • [options={}] Object optional
    • [time=undefined] DOMHighResTimeStamp | String optional

      This value can be one of two things. If the value is a string starting with the + sign and followed by a number, the request will be delayed by the specified number (in milliseconds). Otherwise, the value is considered a timestamp and the request will be scheduled at that timestamp. The DOMHighResTimeStamp value is relative to the navigation start of the document. To retrieve the current time, you can use WebMidi.time. If time is not present or is set to a time in the past, the request is to be sent as soon as possible.

Returns:

Output:

Returns the Output object so methods can be chained.

Throws:

RangeError:

Value must be between 0 and 127.

sendKeyAftertouch

(
  • note
  • [channel=all]
  • [pressure=0.5]
  • [options={}]
)
Output chainable

Defined in src/webmidi.js:2701

Sends a MIDI key aftertouch message to the specified channel(s) at the scheduled time. This is a key-specific aftertouch. For a channel-wide aftertouch message, use WebMidi/sendChannelAftertouch:method.

Parameters:

  • note Number | String | Array

    The note for which you are sending an aftertouch value. The notes can be specified in one of two ways. The first way is by using the MIDI note number (an integer between 0 and 127). The second way is by using the note name followed by the octave (C3, G#4, F-1, Db7). The octave range should be between -2 and 8. The lowest note is C-2 (MIDI note number 0) and the highest note is G8 (MIDI note number 127). It is also possible to use an array of note names and/or numbers.

  • [channel=all] Number | Array | String optional

    The MIDI channel number (between 1 and 16) or an array of channel numbers. If the special value "all" is used, the message will be sent to all 16 channels.

  • [pressure=0.5] Number optional

    The pressure level to send (between 0 and 1).

  • [options={}] Object optional
    • [time=undefined] DOMHighResTimeStamp | String optional

      This value can be one of two things. If the value is a string starting with the + sign and followed by a number, the request will be delayed by the specified number (in milliseconds). Otherwise, the value is considered a timestamp and the request will be scheduled at that timestamp. The DOMHighResTimeStamp value is relative to the navigation start of the document. To retrieve the current time, you can use WebMidi.time. If time is not present or is set to a time in the past, the request is to be sent as soon as possible.

Returns:

Output:

Returns the Output object so methods can be chained.

Throws:

RangeError:

The channel must be between 1 and 16.

sendPitchBend

(
  • bend
  • [channel=all]
  • [options={}]
)
Output chainable

Defined in src/webmidi.js:3807

Sends a MIDI pitch bend message to the specified channel(s) at the scheduled time.

Parameters:

  • bend Number

    The intensity level of the bend (between -1 and 1). A value of zero means no bend.

  • [channel=all] Number | Array | String optional

    The MIDI channel number (between 1 and 16) or an array of channel numbers. If the special value "all" is used, the message will be sent to all 16 channels.

  • [options={}] Object optional
    • [time=undefined] DOMHighResTimeStamp | String optional

      This value can be one of two things. If the value is a string starting with the + sign and followed by a number, the request will be delayed by the specified number (in milliseconds). Otherwise, the value is considered a timestamp and the request will be scheduled at that timestamp. The DOMHighResTimeStamp value is relative to the navigation start of the document. To retrieve the current time, you can use WebMidi.time. If time is not present or is set to a time in the past, the request is to be sent as soon as possible.

Returns:

Output:

Returns the Output object so methods can be chained.

Throws:

RangeError:

Pitch bend value must be between -1 and 1.

sendProgramChange

(
  • program
  • [channel=all]
  • [options={}]
)
Output chainable

Defined in src/webmidi.js:3708

Sends a MIDI program change message to the specified channel(s) at the scheduled time.

Parameters:

  • program Number

    The MIDI patch (program) number (0-127)

  • [channel=all] Number | Array | String optional

    The MIDI channel number (between 1 and 16) or an array of channel numbers. If the special value "all" is used, the message will be sent to all 16 channels.

  • [options={}] Object optional
    • [time=undefined] DOMHighResTimeStamp | String optional

      This value can be one of two things. If the value is a string starting with the + sign and followed by a number, the request will be delayed by the specified number (in milliseconds). Otherwise, the value is considered a timestamp and the request will be scheduled at that timestamp. The DOMHighResTimeStamp value is relative to the navigation start of the document. To retrieve the current time, you can use WebMidi.time. If time is not present or is set to a time in the past, the request is to be sent as soon as possible.

Returns:

Output:

Returns the Output object so methods can be chained.

Throws:

RangeError:

Program numbers must be between 0 and 127.

sendReset

(
  • [options={}]
)
Output chainable

Defined in src/webmidi.js:2511

Sends Reset real-time message. This tells the device connected to this port that is should reset itself to a default state.

Parameters:

  • [options={}] Object optional
    • [time=undefined] DOMHighResTimeStamp | String optional

      This value can be one of two things. If the value is a string starting with the + sign and followed by a number, the request will be delayed by the specified number (in milliseconds). Otherwise, the value is considered a timestamp and the request will be scheduled at that timestamp. The DOMHighResTimeStamp value is relative to the navigation start of the document. To retrieve the current time, you can use WebMidi.time. If time is not present or is set to a time in the past, the request is to be sent as soon as possible.

Returns:

Output:

Returns the Output object so methods can be chained.

sendSongPosition

(
  • [value=0]
  • [options={}]
)
Output chainable

Defined in src/webmidi.js:2282

Sends a Song Position MIDI message. The value is expressed in MIDI beats (between 0 and

  1. which are 16th note. Position 0 is always the start of the song.

Parameters:

  • [value=0] Number optional

    The MIDI beat to cue to (int between 0 and 16383).

  • [options={}] Object optional
    • [time=undefined] DOMHighResTimeStamp | String optional

      This value can be one of two things. If the value is a string starting with the + sign and followed by a number, the request will be delayed by the specified number (in milliseconds). Otherwise, the value is considered a timestamp and the request will be scheduled at that timestamp. The DOMHighResTimeStamp value is relative to the navigation start of the document. To retrieve the current time, you can use WebMidi.time. If time is not present or is set to a time in the past, the request is to be sent as soon as possible.

Returns:

Output:

Returns the Output object so methods can be chained.

sendSongSelect

(
  • value
  • [options={}]
)
Output chainable

Defined in src/webmidi.js:2317

Sends a Song Select MIDI message. Beware that some devices will display position 0 as position 1 for user-friendlyness.

Parameters:

  • value Number

    The number of the song to select (integer between 0 and 127).

  • [options={}] Object optional
    • [time=undefined] DOMHighResTimeStamp | String optional

      This value can be one of two things. If the value is a string starting with the + sign and followed by a number, the request will be delayed by the specified number (in milliseconds). Otherwise, the value is considered a timestamp and the request will be scheduled at that timestamp. The DOMHighResTimeStamp value is relative to the navigation start of the document. To retrieve the current time, you can use WebMidi.time. If time is not present or is set to a time in the past, the request is to be sent as soon as possible.

Returns:

Output:

Returns the Output object so methods can be chained.

sendStart

(
  • [options={}]
)
Output chainable

Defined in src/webmidi.js:2409

Sends a Start real-time message. A MIDI Start message starts the playback of the current song at beat 0. To start playback elsewhere in the song, use the sendContinue() function.

Parameters:

  • [options={}] Object optional
    • [time=undefined] DOMHighResTimeStamp | String optional

      This value can be one of two things. If the value is a string starting with the + sign and followed by a number, the request will be delayed by the specified number (in milliseconds). Otherwise, the value is considered a timestamp and the request will be scheduled at that timestamp. The DOMHighResTimeStamp value is relative to the navigation start of the document. To retrieve the current time, you can use WebMidi.time. If time is not present or is set to a time in the past, the request is to be sent as soon as possible.

Returns:

Output:

Returns the Output object so methods can be chained.

sendStop

(
  • [options={}]
)
Output chainable

Defined in src/webmidi.js:2460

Sends a Stop real-time message. This tells the device connected to this port to stop playback immediately (or at the scheduled time).

Parameters:

  • [options={}] Object optional
    • [time=undefined] DOMHighResTimeStamp | String optional

      This value can be one of two things. If the value is a string starting with the + sign and followed by a number, the request will be delayed by the specified number (in milliseconds). Otherwise, the value is considered a timestamp and the request will be scheduled at that timestamp. The DOMHighResTimeStamp value is relative to the navigation start of the document. To retrieve the current time, you can use WebMidi.time. If time is not present or is set to a time in the past, the request is to be sent as soon as possible.

Returns:

Output:

Returns the Output object so methods can be chained.

sendSysex

(
  • manufacturer
  • [data=[]]
  • [options={}]
)
Output chainable

Defined in src/webmidi.js:2184

Sends a MIDI system exclusive message. The generated message will automatically be prepended with the SysEx byte (0xF0) and terminated with the End of SysEx byte (0xF7).

For example, if you want to send a SysEx message to a Korg device connected to the first output, you would use the following code:

WebMidi.outputs[0].sendSysex(0x42, [1, 2, 3, 4, 5]);

The above code sends the byte values 1, 2, 3, 4 and 5 to Korg (ID 0x42) devices. Some manufacturers are identified using 3 bytes. In this case, you would use a 3-position array as the first parameter. For example, to send the same SysEx message to a Native Instruments device:

WebMidi.outputs[0].sendSysex([0x00, 0x21, 0x09], [1, 2, 3, 4, 5]);

There is no limit for the length of the data array. However, it is generally suggested to keep system exclusive messages to 64Kb or less.

Parameters:

  • manufacturer Number | Array

    An unsigned integer or an array of three unsigned integers between 0 and 127 that identify the targeted manufacturer. The MIDI Manufacturers Association maintains a full list of Manufacturer ID Numbers.

  • [data=[]] Array optional

    An array of uints between 0 and 127. This is the data you wish to transfer.

  • [options={}] Object optional
    • [time=undefined] DOMHighResTimeStamp | String optional

      This value can be one of two things. If the value is a string starting with the + sign and followed by a number, the request will be delayed by the specified number (in milliseconds). Otherwise, the value is considered a timestamp and the request will be scheduled at that timestamp. The DOMHighResTimeStamp value is relative to the navigation start of the document. To retrieve the current time, you can use WebMidi.time. If time is not present or is set to a time in the past, the request is to be sent as soon as possible.

Returns:

Output:

Returns the Output object so methods can be chained.

sendTimecodeQuarterFrame

(
  • value
  • [options={}]
)
Output chainable

Defined in src/webmidi.js:2254

Sends a MIDI Timecode Quarter Frame message. Please note that no processing is being done on the data. It is up to the developer to format the data according to the MIDI Timecode format.

Parameters:

  • value Number

    The quarter frame message content (integer between 0 and 127).

  • [options={}] Object optional
    • [time=undefined] DOMHighResTimeStamp | String optional

      This value can be one of two things. If the value is a string starting with the + sign and followed by a number, the request will be delayed by the specified number (in milliseconds). Otherwise, the value is considered a timestamp and the request will be scheduled at that timestamp. The DOMHighResTimeStamp value is relative to the navigation start of the document. To retrieve the current time, you can use WebMidi.time. If time is not present or is set to a time in the past, the request is to be sent as soon as possible.

Returns:

Output:

Returns the Output object so methods can be chained.

sendTuningRequest

(
  • [options={}]
)
Output chainable

Defined in src/webmidi.js:2356

Sends a MIDI tuning request real-time message.

Note: there is currently a bug in Chrome's MIDI implementation. If you try to use this function, Chrome will actually throw a "Message is incomplete" error. The bug is scheduled to be fixed.

Parameters:

  • [options={}] Object optional
    • [time=undefined] DOMHighResTimeStamp | String optional

      This value can be one of two things. If the value is a string starting with the + sign and followed by a number, the request will be delayed by the specified number (in milliseconds). Otherwise, the value is considered a timestamp and the request will be scheduled at that timestamp. The DOMHighResTimeStamp value is relative to the navigation start of the document. To retrieve the current time, you can use WebMidi.time. If time is not present or is set to a time in the past, the request is to be sent as soon as possible.

Returns:

Output:

Returns the Output object so methods can be chained.

setMasterTuning

(
  • [value=0.0]
  • [channel=all]
  • [options={}]
)
Output chainable

Defined in src/webmidi.js:3470

Sends a master tuning message to the specified channel(s). The value is decimal and must be larger than -65 semitones and smaller than 64 semitones.

Because of the way the MIDI specification works, the decimal portion of the value will be encoded with a resolution of 14bit. The integer portion must be between -64 and 63 inclusively. For those familiar with the MIDI protocol, this function actually generates Master Coarse Tuning and Master Fine Tuning RPN messages.

Parameters:

  • [value=0.0] Number optional

    The desired decimal adjustment value in semitones (-65 < x < 64)

  • [channel=all] Number | Array | String optional

    The MIDI channel number (between 1 and 16) or an array of channel numbers. If the special value "all" is used, the message will be sent to all 16 channels.

  • [options={}] Object optional
    • [time=undefined] DOMHighResTimeStamp | String optional

      This value can be one of two things. If the value is a string starting with the + sign and followed by a number, the request will be delayed by the specified number (in milliseconds). Otherwise, the value is considered a timestamp and the request will be scheduled at that timestamp. The DOMHighResTimeStamp value is relative to the navigation start of the document. To retrieve the current time, you can use WebMidi.time. If time is not present or is set to a time in the past, the request is to be sent as soon as possible.

Returns:

Output:

Returns the Output object so methods can be chained.

Throws:

RangeError:

The value must be a decimal number between larger than -65 and smaller than 64.

setModulationRange

(
  • [semitones=0]
  • [cents=0]
  • [channel=all]
  • [options={}]
)
Output chainable

Defined in src/webmidi.js:3412

Sends a modulation depth range message to the specified channel(s) so that they adjust the depth of their modulation wheel's range. The range can be specified with the semitones parameter, the cents parameter or by specifying both parameters at the same time.

Parameters:

  • [semitones=0] Number optional

    The desired adjustment value in semitones (integer between 0-127).

  • [cents=0] Number optional

    The desired adjustment value in cents (0-127).

  • [channel=all] Number | Array | String optional

    The MIDI channel number (between 1 and 16) or an array of channel numbers. If the special value "all" is used, the message will be sent to all 16 channels.

  • [options={}] Object optional
    • [time=undefined] DOMHighResTimeStamp | String optional

      This value can be one of two things. If the value is a string starting with the + sign and followed by a number, the request will be delayed by the specified number (in milliseconds). Otherwise, the value is considered a timestamp and the request will be scheduled at that timestamp. The DOMHighResTimeStamp value is relative to the navigation start of the document. To retrieve the current time, you can use WebMidi.time. If time is not present or is set to a time in the past, the request is to be sent as soon as possible.

Returns:

Output:

Returns the Output object so methods can be chained.

Throws:

RangeError:

The cents value must be between 0 and 127.

setNonRegisteredParameter

(
  • parameter
  • [data=[]]
  • [channel=all]
  • [options={}]
)
Output chainable

Defined in src/webmidi.js:3129

Sets a non-registered parameter to the specified value. The NRPN is selected by passing in a two-position array specifying the values of the two control bytes. The value is specified by passing in an single integer (most cases) or an array of two integers.

NRPNs are not standardized in any way. Each manufacturer is free to implement them any way they see fit. For example, according to the Roland GS specification, you can control the vibrato rate using NRPN (1, 8). Therefore, to set the vibrato rate value to 123 you would use:

WebMidi.outputs[0].setNonRegisteredParameter([1, 8], 123);

Obviously, you should select a channel so the message is not sent to all channels. For instance, to send to channel 1 of the first output port, you would use:

WebMidi.outputs[0].setNonRegisteredParameter([1, 8], 123, 1);

In some rarer cases, you need to send two values with your NRPN messages. In such cases, you would use a 2-position array. For example, for its ClockBPM parameter (2, 63), Novation uses a 14-bit value that combines an MSB and an LSB (7-bit values). So, for example, if the value to send was 10, you could use:

WebMidi.outputs[0].setNonRegisteredParameter([2, 63], [0, 10]);

For further implementation details, refer to the manufacturer's documentation.

Parameters:

  • parameter Array

    A two-position array specifying the two control bytes (0x63, 0x62) that identify the non-registered parameter.

  • [data=[]] Number | Array optional

    An integer or an array of integers with a length of 1 or 2 specifying the desired data.

  • [channel=all] Number | Array | String optional

    The MIDI channel number (between 1 and 16) or an array of channel numbers. If the special value "all" is used, the message will be sent to all 16 channels.

  • [options={}] Object optional
    • [time=undefined] DOMHighResTimeStamp | String optional

      This value can be one of two things. If the value is a string starting with the + sign and followed by a number, the request will be delayed by the specified number (in milliseconds). Otherwise, the value is considered a timestamp and the request will be scheduled at that timestamp. The DOMHighResTimeStamp value is relative to the navigation start of the document. To retrieve the current time, you can use WebMidi.time. If time is not present or is set to a time in the past, the request is to be sent as soon as possible.

Returns:

Output:

Returns the Output object so methods can be chained.

setPitchBendRange

(
  • [semitones=0]
  • [cents=0]
  • [channel=all]
  • [options={}]
)
Output chainable

Defined in src/webmidi.js:3353

Sends a pitch bend range message to the specified channel(s) at the scheduled time so that they adjust the range used by their pitch bend lever. The range can be specified with the semitones parameter, the cents parameter or by specifying both parameters at the same time.

Parameters:

  • [semitones=0] Number optional

    The desired adjustment value in semitones (integer between 0-127). While nothing imposes that in the specification, it is very common for manufacturers to limit the range to 2 octaves (-12 semitones to 12 semitones).

  • [cents=0] Number optional

    The desired adjustment value in cents (integer between 0-127).

  • [channel=all] Number | Array | String optional

    The MIDI channel number (between 1 and 16) or an array of channel numbers. If the special value "all" is used, the message will be sent to all 16 channels.

  • [options={}] Object optional
    • [time=undefined] DOMHighResTimeStamp | String optional

      This value can be one of two things. If the value is a string starting with the + sign and followed by a number, the request will be delayed by the specified number (in milliseconds). Otherwise, the value is considered a timestamp and the request will be scheduled at that timestamp. The DOMHighResTimeStamp value is relative to the navigation start of the document. To retrieve the current time, you can use WebMidi.time. If time is not present or is set to a time in the past, the request is to be sent as soon as possible.

Returns:

Output:

Returns the Output object so methods can be chained.

Throws:

RangeError:

The cents value must be between 0 and 127.

setRegisteredParameter

(
  • parameter
  • [data=[]]
  • [channel=all]
  • [options={}]
)
Output chainable

Defined in src/webmidi.js:3046

Sets the specified MIDI registered parameter to the desired value. The value is defined with up to two bytes of data that each can go from 0 to 127.

Unless you are very familiar with the MIDI standard you probably should favour one of the simpler to use functions such as: setPitchbendRange(), setModulationRange(), setMasterTuning(), etc.

MIDI registered parameters extend the original list of control change messages. Currently, there are only a limited number of them. Here are the original registered parameters with the identifier that can be used as the first parameter of this function:

  • Pitchbend Range (0x00, 0x00): pitchbendrange
  • Channel Fine Tuning (0x00, 0x01): channelfinetuning
  • Channel Coarse Tuning (0x00, 0x02): channelcoarsetuning
  • Tuning Program (0x00, 0x03): tuningprogram
  • Tuning Bank (0x00, 0x04): tuningbank
  • Modulation Range (0x00, 0x05): modulationrange

Note that the Tuning Program and Tuning Bank parameters are part of the MIDI Tuning Standard, which is not widely implemented.

Another set of extra parameters have been later added for 3D sound controllers. They are:

  • Azimuth Angle (0x3D, 0x00): azimuthangle
  • Elevation Angle (0x3D, 0x01): elevationangle
  • Gain (0x3D, 0x02): gain
  • Distance Ratio (0x3D, 0x03): distanceratio
  • Maximum Distance (0x3D, 0x04): maximumdistance
  • Maximum Distance Gain (0x3D, 0x05): maximumdistancegain
  • Reference Distance Ratio (0x3D, 0x06): referencedistanceratio
  • Pan Spread Angle (0x3D, 0x07): panspreadangle
  • Roll Angle (0x3D, 0x08): rollangle

Parameters:

  • parameter String | Array

    A string identifying the parameter's name (see above) or a two-position array specifying the two control bytes (0x65, 0x64) that identify the registered parameter.

  • [data=[]] Number | Array optional

    An single integer or an array of integers with a maximum length of 2 specifying the desired data.

  • [channel=all] Number | Array | String optional

    The MIDI channel number (between 1 and 16) or an array of channel numbers. If the special value "all" is used, the message will be sent to all 16 channels.

  • [options={}] Object optional
    • [time=undefined] DOMHighResTimeStamp | String optional

      This value can be one of two things. If the value is a string starting with the + sign and followed by a number, the request will be delayed by the specified number (in milliseconds). Otherwise, the value is considered a timestamp and the request will be scheduled at that timestamp. The DOMHighResTimeStamp value is relative to the navigation start of the document. To retrieve the current time, you can use WebMidi.time. If time is not present or is set to a time in the past, the request is to be sent as soon as possible.

Returns:

Output:

Returns the Output object so methods can be chained.

setTuningBank

(
  • value
  • [channel=all]
  • [options={}]
)
Output chainable

Defined in src/webmidi.js:3580

Sets the MIDI tuning bank to use. Note that the Tuning Bank parameter is part of the MIDI Tuning Standard, which is not widely implemented.

Parameters:

  • value Number

    The desired tuning bank (0-127).

  • [channel=all] Number | Array | String optional

    The MIDI channel number (between 1 and 16) or an array of channel numbers. If the special value "all" is used, the message will be sent to all 16 channels.

  • [options={}] Object optional
    • [time=undefined] DOMHighResTimeStamp | String optional

      This value can be one of two things. If the value is a string starting with the + sign and followed by a number, the request will be delayed by the specified number (in milliseconds). Otherwise, the value is considered a timestamp and the request will be scheduled at that timestamp. The DOMHighResTimeStamp value is relative to the navigation start of the document. To retrieve the current time, you can use WebMidi.time. If time is not present or is set to a time in the past, the request is to be sent as soon as possible.

Returns:

Output:

Returns the Output object so methods can be chained.

Throws:

RangeError:

The bank value must be between 0 and 127.

setTuningProgram

(
  • value
  • [channel=all]
  • [options={}]
)
Output chainable

Defined in src/webmidi.js:3534

Sets the MIDI tuning program to use. Note that the Tuning Program parameter is part of the MIDI Tuning Standard, which is not widely implemented.

Parameters:

  • value Number

    The desired tuning program (0-127).

  • [channel=all] Number | Array | String optional

    The MIDI channel number (between 1 and 16) or an array of channel numbers. If the special value "all" is used, the message will be sent to all 16 channels.

  • [options={}] Object optional
    • [time=undefined] DOMHighResTimeStamp | String optional

      This value can be one of two things. If the value is a string starting with the + sign and followed by a number, the request will be delayed by the specified number (in milliseconds). Otherwise, the value is considered a timestamp and the request will be scheduled at that timestamp. The DOMHighResTimeStamp value is relative to the navigation start of the document. To retrieve the current time, you can use WebMidi.time. If time is not present or is set to a time in the past, the request is to be sent as soon as possible.

Returns:

Output:

Returns the Output object so methods can be chained.

Throws:

RangeError:

The program value must be between 0 and 127.

stopNote

(
  • note
  • [channel=all]
  • [options={}]
)
Output chainable

Defined in src/webmidi.js:2536

Sends a MIDI note off message to the specified channel(s) for a single note or multiple simultaneous notes (chord). You can delay the execution of the note off command by using the time property of the options parameter (milliseconds).

Parameters:

  • note Number | Array | String

    The note(s) you wish to stop. The notes can be specified in one of two ways. The first way is by using the MIDI note number (an integer between 0 and 127). The second way is by using the note name followed by the octave (C3, G#4, F-1, Db7). The octave range should be between -2 and 8. The lowest note is C-2 (MIDI note number 0) and the highest note is G8 (MIDI note number 127). It is also possible to specify an array of note numbers and/or names.

  • [channel=all] Number | Array | String optional

    The MIDI channel number (between 1 and 16) or an array of channel numbers. If the special value "all" is used (default), the message will be sent to all 16 channels.

  • [options={}] Object optional
    • [velocity=0.5] Number optional

      The velocity at which to release the note (between 0 and 1). An invalid velocity value will silently trigger the default.

    • [time=undefined] DOMHighResTimeStamp | String optional

      This value can be one of two things. If the value is a string starting with the + sign and followed by a number, the request will be delayed by the specified number (in milliseconds). Otherwise, the value is considered a timestamp and the request will be scheduled at that timestamp. The DOMHighResTimeStamp value is relative to the navigation start of the document. To retrieve the current time, you can use WebMidi.time. If time is not present or is set to a time in the past, the request is to be sent as soon as possible.

Returns:

Output:

Returns the Output object so methods can be chained.

Properties

connection

String

Defined in src/webmidi.js:2056

[read-only] Status of the MIDI port's connection

id

String

Defined in src/webmidi.js:2069

[read-only] ID string of the MIDI port

manufacturer

String

Defined in src/webmidi.js:2082

[read-only] Manufacturer of the device to which this port belongs

name

String

Defined in src/webmidi.js:2095

[read-only] Name of the MIDI port

state

String

Defined in src/webmidi.js:2108

[read-only] State of the MIDI port