API Docs for: 2.5.2
Show:

Output Class

Defined in: src/webmidi.js:2443

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

_convertNoteToArray

(
  • [note]
)
Array protected

Defined in src/webmidi.js:4393

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:

Returns:

Array:

_deselectRegisteredParameter

(
  • channel
  • time
)
Output protected

Defined in src/webmidi.js:3518

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:

Output:

_parseTimeParameter

(
  • [time]
)
protected

Defined in src/webmidi.js:4364

Returns a timestamp, relative to the navigation start of the document, derived from the time parameter. If the parameter is a string starting with the "+" sign and followed by a number, the resulting value will be the sum of the current timestamp plus that number. Otherwise, the value will be returned as is.

If the calculated return value is 0, less than zero or an otherwise invalid value, undefined will be returned.

Parameters:

Returns:

DOMHighResTimeStamp

_selectNonRegisteredParameter

(
  • parameter
  • channel
  • time
)
Output protected

Defined in src/webmidi.js:3443

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:

Output:

_selectRegisteredParameter

(
  • parameter
  • channel
  • time
)
Output protected

Defined in src/webmidi.js:3406

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:

Output:

_setCurrentRegisteredParameter

(
  • data
  • channel
  • time
)
Output protected

Defined in src/webmidi.js:3480

Sets the value of the currently selected MIDI registered parameter.

Parameters:

Returns:

Output:

decrementRegisteredParameter

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

Defined in src/webmidi.js:3782

Decrements the specified MIDI registered parameter by 1.

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:3707

Increments the specified MIDI registered parameter by 1.

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.

Throws:

Error The specified parameter is not available.

playNote

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

Defined in src/webmidi.js:3072

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.

Note: As per the MIDI standard, a note on event with a velocity of 0 is considered to be a note off.

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 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
    • [duration=undefined] Number optional

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

    • [rawVelocity=false] Boolean optional

      Controls whether the attack and release velocities are set using integers between 0 and 127 (true) or a decimal number between 0 and 1 (false, default).

    • [release=0.5] Number optional

      The velocity at which to release the note (between 0 and 1). If the rawVelocity option is true, the value should be specified as an integer between 0 and 127. An invalid velocity value will silently trigger the default of 0.5. This is only used with the note off event triggered when options.duration is set.

    • [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.

    • [velocity=0.5] Number optional

      The velocity at which to play the note (between 0 and 1). If the rawVelocity option is true, the value should be specified as an integer between 0 and 127. An invalid velocity value will silently trigger the default of 0.5.

Returns:

Output:

Returns the Output object so methods can be chained.

send

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

Defined in src/webmidi.js:2542

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.

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 (use undefined or an empty array in this case). 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:

Data bytes must be integers between 0 (0x00) and 255 (0x7F).

sendActiveSensing

(
  • [options={}]
)
Output chainable

Defined in src/webmidi.js:2932

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:4262

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=0]
  • [channel=all]
  • [options={}]
)
Output chainable

Defined in src/webmidi.js:4128

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)

It should be noted that, per the MIDI specification, only localcontrol and monomodeon may require a value that"s not zero. For that reason, the value parameter is optional and defaults to 0.

Parameters:

  • command Number | String

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

  • [value=0] Number optional

    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 an integer between 0 and 127.

sendClock

(
  • [options={}]
)
Output chainable

Defined in src/webmidi.js:2831

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:2881

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:3271

Sends a MIDI control change message (a.k.a. CC 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.

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:3204

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:4311

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:4212

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:2962

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:2721

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:2760

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.

Throws:

The song number must be between 0 and 127.

sendStart

(
  • [options={}]
)
Output chainable

Defined in src/webmidi.js:2856

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:2907

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:2600

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

To use the sendSysex() method, system exclusive message support must have been enabled. To do so, you must pass true as the second parameter to WebMidi.enable():

WebMidi.enable(function (err) {
    if (err) {
        console.warn(err);
    } else {
        console.log("Sysex is enabled!");
    }
}, true);

Note that, depending on browser, version and platform, it may be necessary to serve the page over HTTPS to enable sysex support.

Examples

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, [0x1, 0x2, 0x3, 0x4, 0x5]);

The parameters can be specified using any number notation (decimal, hex, binary, etc.). Therefore, the code below is equivalent to the code above:

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

The above code sends the byte values 1, 2, 3, 4 and 5 to Korg devices (hex 42 is the same as decimal 66).

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], [0x1, 0x2, 0x3, 0x4, 0x5]);

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:2693

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:2799

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:3972

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:3914

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:3629

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:3855

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:3546

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:4082

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:4036

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:2987

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 (in milliseconds).

Parameters:

  • note Number | Array | String

    The note(s) you wish to stop. The notes can be specified in one of three 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. The final way is to use the special value all to send an "allnotesoff" channel message.

  • [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
    • [rawVelocity=false] Boolean optional

      Controls whether the release velocity is set using an integer between 0 and 127 (true) or a decimal number between 0 and 1 (false, 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.

    • [velocity=0.5] Number optional

      The velocity at which to release the note (between 0 and 1). If the rawVelocity option is true, the value should be specified as an integer between 0 and 127. An invalid velocity value will silently trigger the default of 0.5. Note that when the first parameter to stopNote() is all, the release velocity is silently ignored.

Returns:

Output:

Returns the Output object so methods can be chained.

Properties

connection

String

Defined in src/webmidi.js:2460

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

id

String

Defined in src/webmidi.js:2473

[read-only] ID string of the MIDI port

manufacturer

String

Defined in src/webmidi.js:2486

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

name

String

Defined in src/webmidi.js:2499

[read-only] Name of the MIDI port

state

String

Defined in src/webmidi.js:2512

[read-only] State of the MIDI port

type

String

Defined in src/webmidi.js:2525

[read-only] Type of the MIDI port (output)