API Docs for: 1.0.0-beta.15
Show:

WebMidi Class

Defined in: src/webmidi.js:5

The WebMidi object makes it easier to work with the Web MIDI API. Basically, it simplifies two things: sending and reacting upon receiving MIDI messages.

To send MIDI messages, you simply need to call the desired method (playNote(), sendPitchBend(), stopNote(), etc.) with the appropriate parameters and all the native MIDI communication will be handled for you. The only additional thing that needs to be done is enable WebMidi. Here is an example:

 WebMidi.enable(function() {
   WebMidi.playNote("C3");
 });

The code above, calls the WebMidi.enable() method. Upon success, this method executes the callback function specified as a parameter. In this case, the callback calls the playnote() function to play a 3rd octave C on all devices and channels.

Receiving messages is just as easy. You simply have to set a callback function to be triggered when a specific MIDI message is received. For example, to listen for pitch bend events on any input MIDI channels:

 WebMidi.addListener('pitchbend', function(e) {
   console.log("Pitch value: " + e.value);
 });

As you can see, this library makes it much easier to use the Web MIDI API. No need to manually craft or decode binary MIDI messages anymore!

Methods

_convertChannelToArray

(
  • [channel]
)
protected

Defined in src/webmidi.js:3106

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

Converts an input value (which can be an int, an array or the value "all" to an array of valid MIDI note numbers.

Parameters:

_deselectRegisteredParameter

(
  • output
  • channel
  • time
)
WebMidi protected static

Defined in src/webmidi.js:2168

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:

WebMidi:

_initializeUserHandlers

() private

Defined in src/webmidi.js:219

_onInterfaceStateChange

() private

Defined in src/webmidi.js:241

_onMidiMessage

() private

Defined in src/webmidi.js:882

_parseChannelEvent

(
  • e
)
private

Defined in src/webmidi.js:261

Parameters:

_parseSystemEvent

() private

Defined in src/webmidi.js:601

_parseTimeParameter

(
  • [time=0]
)
protected

Defined in src/webmidi.js:3136

Parameters:

_selectNonRegisteredParameter

(
  • parameter
  • output
  • channel
  • time
)
WebMidi protected static

Defined in src/webmidi.js:2088

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.

  • output Object
  • channel Object
  • time Object

Returns:

WebMidi:

_selectRegisteredParameter

(
  • parameter
  • output
  • channel
  • time
)
WebMidi protected static

Defined in src/webmidi.js:2048

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.

  • output Object
  • channel Object
  • time Object

Returns:

WebMidi:

_setCurrentRegisteredParameter

(
  • data
  • output
  • channel
  • time
)
WebMidi protected static

Defined in src/webmidi.js:2128

Sets the value of the currently selected MIDI registered parameter.

Parameters:

Returns:

WebMidi:

addListener

(
  • type
  • listener
  • [filters]
)
WebMidi static chainable

Defined in src/webmidi.js:947

Adds an event listener that will trigger a function callback when the specified event happens. By default, the listener is system-wide (it will listen on all MIDI channels of all MIDI input devices). To listen to a specific device or channel, you can use the filter parameter.

WebMidi must be enabled before adding event listeners.

Here is a list of events that are dispatched by the WebMidi object and that can be listened to.

MIDI interface event:

Device and channel-specific MIDI events:

System-wide MIDI events:

For system-wide events, the filters parameter (if any) will be silently ignored.

Parameters:

  • type String

    The type of the event.

  • listener Function

    A callback function to execute when the specified event is detected. This function will receive an event parameter object. For details on this object's properties, check out the documentation for the various events (links above).

  • [filters] Object optional
    • [device="all"] String | Array optional

      The id of the MIDI device to listen on. The device id can be retrieved in the WebMidi.inputs array. It is also possible to listen on several devices at once by passing in an array of ids. If set to 'all' (default) all devices will trigger the callback function.

    • [input] MIDIInput | Array(MIDIInput) optional

      A MIDI input device or an array of MIDI input devices to listen to. As a reference, all available MIDIInput objects are listed in the WebMidi.inputs array. When this parameter is left undefined, all input devices will trigger the callback function.

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

      The MIDI channel to listen on (between 1 and 16). You can also specify an array of channels to listen on. If set to 'all', all channels will trigger the callback function.

Returns:

WebMidi:

Returns the WebMidi object so methods can be chained.

Throws:

TypeError:

The 'listener' parameter must be a function.

enable

(
  • [successHandler]
  • [errorHandler]
  • [sysex=false]
)
static

Defined in src/webmidi.js:896

Checks if the Web MIDI API is available and then tries to connect to the host's MIDI subsystem. If the operation succeeds, the successHandler callback is executed. If not, the errorHandler callback is executed and passed a string describing the error.

Parameters:

  • [successHandler] Function optional

    A function to execute upon success.

  • [errorHandler] Function optional

    A function to execute upon error. This function will be passed a string describing the error.

  • [sysex=false] Boolean optional

    Whether to enable sysex or not. When this parameter is set to true, the browser may prompt the user for authorization.

getDeviceById

(
  • id
  • [type=input]
)
MIDIOutput | MIDIInput | False static

Defined in src/webmidi.js:1099

Returns a MIDIOutput or MIDIInput device matching the specified id and device type.

Parameters:

  • id String

    The id of the device. Ids can be retrieved by looking at the WebMidi.inputs or WebMidi.outputs arrays.

  • [type=input] String optional

    One of 'input' or 'output' to indicate whether your are looking for an input or an output device.

Returns:

MIDIOutput | MIDIInput | False:

A MIDIOutput or MIDIInput device matching the specified id. If no matching device can be found, the method returns false.

getDeviceIndexById

(
  • id
  • [type=input]
)
Uint | False static

Defined in src/webmidi.js:1127

Return the index of a device in the WebMidi.outputs or WebMidi.inputs arrays. The device must be specified by using its id.

Parameters:

  • id String

    The id of the device such as it is presented in the WebMidi.inputs or WebMidi.outputs arrays.

  • [type=input] String optional

    One of 'input' or 'output' to indicate whether your are looking for the index of an input or output device.

Returns:

Uint | False:

If no matching device can be found, the method returns false.

guessNoteNumber

(
  • input
)
Uint static

Defined in src/webmidi.js:3012

Returns a valid MIDI note number given the specified input. The input can be an integer represented as a string, a note name (C3, F#4, D-2, G8, etc.), a float or an int between 0 and

Parameters:

  • input Object

    A integer, float or string to extract the note number from.

Returns:

Uint:

A valid MIDI note number (0-127).

Throws:

Error:

Invalid note number.

hasListener

(
  • type
  • listener
  • [filters]
)
Boolean static

Defined in src/webmidi.js:1154

Checks if the specified event type is already defined to trigger the listener function on the specified device and channel. If more than one device and/or channel is specified, the function will return true only if all devices/channels have the listener defined.

For system-wide events (onstatechange, sysex, start, etc.), the filters parameter is silently ignored.

Parameters:

  • type String

    The type of the event.

  • listener Function

    The callback function to check for.

  • [filters] Object optional

    {Object}

    • [input] MIDIInput | Array(MIDIInput) optional

      A MIDI input device or an array of MIDI input devices to check on. As a reference, all available MIDIInput objects are listed in the WebMidi.inputs array. When this parameter is left undefined, all input devices will be checked.

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

      The MIDI channel to check on. It can be a uint (between 1 and 16) or the special value "all".

Returns:

Boolean:

Boolean value indicating whether or not the channel(s) already have this listener defined.

Throws:

TypeError:

The 'listener' parameter must be a function.

noteNameToNumber

(
  • name
)
Uint static

Defined in src/webmidi.js:3044

Returns a MIDI note number matching the note name passed in the form of a string parameter. The note name must include the octave number which should be between -2 and 8. The name can also optionally include a sharp "#" or double sharp "##" symbol and a flat "b" or double flat "bb" symbol: C5, G4, D#-1, F0, Gb7, Eb-1, Abb4, B##6, etc.

The lowest note is C-2 (MIDI note number 0) and the highest note is G8 (MIDI note number 127).

Parameters:

  • name String

    The name of the note in the form of a letter, followed by an optional "#" or "b", followed by the octave number (between -2 and 8).

Returns:

Uint:

The MIDI note number (between 0 and 127)

playNote

(
  • note
  • [velocity=0.5]
  • [duration=undefined]
  • [output]
  • [channel=all]
  • [time=undefined]
)
WebMidi static chainable

Defined in src/webmidi.js:1824

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

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

Please note that if you do use a duration, the release velocity will always be 64. If you want to tailor the release velocity, you need to use separate playNote() and stopNote() calls.

Parameters:

  • note Array | Uint | String

    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).

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

  • [output] MIDIOutput | Array(MIDIOutput) optional

    A MIDI output device or an array of MIDI output devices to send the message to. All available MIDIOutput objects are listed in the WebMidi.outputs array. When this parameter is left undefined, the message is sent to all currently available output MIDI devices.

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

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

removeListener

(
  • type
  • listener
  • [filters]
)
WebMidi static chainable

Defined in src/webmidi.js:1236

Removes the specified listener from all requested input devices and channel(s). If more than one devices and/or channels are specified, the function will remove the listener from all devices/channels.

For system-wide events (onstatechange, sysex, start, etc.), the filters parameter is silently ignored.

Parameters:

  • type String

    The type of the event.

  • listener Function

    The callback function to check for.

  • [filters] Object optional

    {Object}

    • [input] MIDIInput | Array(MIDIInput) optional

      A MIDI input device or an array of MIDI input devices to remove from. As a reference, all available MIDIInput objects are listed in the WebMidi.inputs array. When this parameter is left undefined, removal will occur for all input devices.

    • [channel=all] Uint | String optional

      The MIDI channel(s) to check on. It can be a uint (between 1 and 16) or the special value "all".

Returns:

WebMidi:

The WebMidi object for easy method chaining.

Throws:

Error:

WebMidi must be enabled before removing event listeners.

send

(
  • status
  • [data=[]]
  • [output]
  • [timestamp=0]
)
WebMidi static chainable

Defined in src/webmidi.js:1319

Sends a MIDI message to the specified MIDI output device(s) at the specified timestamp. The output parameter must refer to an actual available output device or an array of output devices such as those listed in the WebMidi.outputs array.

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 Uint

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

  • [data=[]] Array(uint) 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. Each byte must be between 0 and 255.

  • [output] MIDIOutput | Array(MIDIOutput) optional

    A MIDI output device or an array of MIDI output devices to send the message to. All available MIDIOutput objects are listed in the WebMidi.outputs array. When this parameter is left undefined, the message is sent to all currently available output MIDI devices.

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

WebMidi:

Returns the WebMidi object so methods can be chained.

Throws:

RangeError:

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

sendActiveSensing

(
  • [output=undefined]
  • [time=undefined]
)
WebMidi static chainable

Defined in src/webmidi.js:1703

Sends an Active Sensing real-time message to the specified output device(s). This tells the remote device 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:

  • [output=undefined] MIDIOutput | Array(MIDIOutput) optional

    A MIDI output device or an array of MIDI output devices to send the message to. All available MIDIOutput objects are listed in the WebMidi.outputs array. When this parameter is left undefined, the message is sent to all currently available output MIDI devices.

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

sendChannelAftertouch

(
  • [pressure=0.5]
  • [output=undefined]
  • [channel=all]
  • [time=undefined]
)
WebMidi static chainable

Defined in src/webmidi.js:2903

Sends a MIDI channel aftertouch message to the specified device(s) and 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.

  • [output=undefined] MIDIOutput | Array(MIDIOutput) optional

    A MIDI output device or an array of MIDI output devices to send the message to. All available MIDIOutput objects are listed in the WebMidi.outputs array. When this parameter is left undefined, the message is sent to all currently available output MIDI devices.

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

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

sendChannelMode

(
  • command
  • value
  • [output=undefined]
  • [channel=all]
  • [time=undefined]
)
WebMidi static chainable

Defined in src/webmidi.js:2787

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

Parameters:

  • command Uint

    The MIDI channel mode command (120-127).

  • value Uint

    The value to send (0-127)

  • [output=undefined] MIDIOutput | Array(MIDIOutput) optional

    A MIDI output device or an array of MIDI output devices to send the message to. All available MIDIOutput objects are listed in the WebMidi.outputs array. When this parameter is left undefined, the message is sent to all currently available output MIDI devices.

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

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

Throws:

RangeError:

Value must be between 0 and 127.

sendClock

(
  • [output=undefined]
  • [time=undefined]
)
WebMidi static chainable

Defined in src/webmidi.js:1589

Sends a MIDI Clock real-time message to the specified output device(s). According to the standard, there are 24 MIDI Clocks for every quarter note.

Parameters:

  • [output=undefined] MIDIOutput | Array(MIDIOutput) optional

    A MIDI output device or an array of MIDI output devices to send the message to. All available MIDIOutput objects are listed in the WebMidi.outputs array. When this parameter is left undefined, the message is sent to all currently available output MIDI devices.

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

sendContinue

(
  • [output=undefined]
  • [time=undefined]
)
WebMidi static chainable

Defined in src/webmidi.js:1646

Sends a Continue real-time message to the specified output device(s). 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:

  • [output=undefined] MIDIOutput | Array(MIDIOutput) optional

    A MIDI output device or an array of MIDI output devices to send the message to. All available MIDIOutput objects are listed in the WebMidi.outputs array. When this parameter is left undefined, the message is sent to all currently available output MIDI devices.

  • [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]
  • [output]
  • [channel=all]
  • [time=undefined]
)
WebMidi static chainable

Defined in src/webmidi.js:1983

Sends a MIDI control change message to the specified device(s) and channel(s). The message can also be scheduled to be sent at a specific time via the time parameter.

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

Parameters:

  • controller Uint

    The MIDI controller number (0-119)

  • [value=0] Uint optional

    The value to send (0-127).

  • [output] MIDIOutput | Array(MIDIOutput) optional

    A MIDI output device or an array of MIDI output devices to send the message to. All available MIDIOutput objects are listed in the WebMidi.outputs array. When this parameter is left undefined, the message is sent to all currently available output MIDI devices.

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

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

Throws:

RangeError:

Value must be between 0 and 127.

sendKeyAftertouch

(
  • note
  • [pressure=0.5]
  • [output]
  • [channel=all]
  • [time=undefined]
)
WebMidi static chainable

Defined in src/webmidi.js:1917

Sends a MIDI key aftertouch message to the specified device(s) and channel(s). This is a key-specific aftertouch. For a channel-wide aftertouch message, use sendChannelAftertouch().

Parameters:

  • note Array | Uint | String

    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).

  • [pressure=0.5] Number optional

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

  • [output] MIDIOutput | Array(MIDIOutput) optional

    A MIDI output device or an array of MIDI output devices to send the message to. All available MIDIOutput objects are listed in the WebMidi.outputs array. When this parameter is left undefined, the message is sent to all currently available output MIDI devices.

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

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

Throws:

RangeError:

The channel must be between 1 and 16.

sendPitchBend

(
  • bend
  • [output=undefined]
  • [channel=all]
  • [time=undefined]
)
WebMidi static chainable

Defined in src/webmidi.js:2955

Sends a MIDI pitch bend message to the specified device(s) and channel(s).

Parameters:

  • bend Number

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

  • [output=undefined] MIDIOutput | Array(MIDIOutput) optional

    A MIDI output device or an array of MIDI output devices to send the message to. All available MIDIOutput objects are listed in the WebMidi.outputs array. When this parameter is left undefined, the message is sent to all currently available output MIDI devices.

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

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

Throws:

RangeError:

Pitch bend value must be between -1 and 1.

sendProgramChange

(
  • program
  • [output=undefined]
  • [channel=all]
  • [time=undefined]
)
WebMidi static chainable

Defined in src/webmidi.js:2850

Sends a MIDI program change message to the specified device(s) and channel(s).

Parameters:

  • program Uint

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

  • [output=undefined] MIDIOutput | Array(MIDIOutput) optional

    A MIDI output device or an array of MIDI output devices to send the message to. All available MIDIOutput objects are listed in the WebMidi.outputs array. When this parameter is left undefined, the message is sent to all currently available output MIDI devices.

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

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

Throws:

RangeError:

Program numbers must be between 0 and 127.

sendReset

(
  • [output=undefined]
  • [time=undefined]
)
WebMidi static chainable

Defined in src/webmidi.js:1732

Sends an Reset real-time message to the specified output device(s). This tells the remote device that is should reset itself to a default state.

Parameters:

  • [output=undefined] MIDIOutput | Array(MIDIOutput) optional

    A MIDI output device or an array of MIDI output devices to send the message to. All available MIDIOutput objects are listed in the WebMidi.outputs array. When this parameter is left undefined, the message is sent to all currently available output MIDI devices.

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

sendSongPosition

(
  • [value=0]
  • [output=undefined]
  • [time=undefined]
)
WebMidi static chainable

Defined in src/webmidi.js:1506

Sends a Song Position MIDI message to the specified output device(s). The value is expressed in MIDI beats (between 0 and 16383) which are 16th note. Position 0 is always the start of the song.

Parameters:

  • [value=0] Uint optional

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

  • [output=undefined] MIDIOutput | Array(MIDIOutput) optional

    A MIDI output device or an array of MIDI output devices to send the message to. All available MIDIOutput objects are listed in the WebMidi.outputs array. When this parameter is left undefined, the message is sent to all currently available output MIDI devices.

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

sendSongSelect

(
  • value
  • [output=undefined]
  • [time=undefined]
)
WebMidi static chainable

Defined in src/webmidi.js:1543

Sends a Song Select MIDI message to the specified output device(s). Beware that some devices will display position 0 as position for user-friendlyness.

Parameters:

  • value Uint

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

  • [output=undefined] MIDIOutput | Array(MIDIOutput) optional

    A MIDI output device or an array of MIDI output devices to send the message to. All available MIDIOutput objects are listed in the WebMidi.outputs array. When this parameter is left undefined, the message is sent to all currently available output MIDI devices.

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

sendStart

(
  • [output=undefined]
  • [time=undefined]
)
WebMidi static chainable

Defined in src/webmidi.js:1617

Sends a Start real-time message to the specified output device(s). 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:

  • [output=undefined] MIDIOutput | Array(MIDIOutput) optional

    A MIDI output device or an array of MIDI output devices to send the message to. All available MIDIOutput objects are listed in the WebMidi.outputs array. When this parameter is left undefined, the message is sent to all currently available output MIDI devices.

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

sendStop

(
  • [output=undefined]
  • [time=undefined]
)
WebMidi static chainable

Defined in src/webmidi.js:1675

Sends a Stop real-time message to the specified output device(s). This tells the remote device to stop playback immediately.

Parameters:

  • [output=undefined] MIDIOutput | Array(MIDIOutput) optional

    A MIDI output device or an array of MIDI output devices to send the message to. All available MIDIOutput objects are listed in the WebMidi.outputs array. When this parameter is left undefined, the message is sent to all currently available output MIDI devices.

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

sendSysex

(
  • manufacturer
  • [data=[]]
  • [output=undefined]
  • [time=undefined]
)
WebMidi static chainable

Defined in src/webmidi.js:1402

Sends a MIDI system exclusive message to the specified device(s). 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.sendSysex(0x42, [1, 2, 3, 4, 5], WebMidi.outputs[0]);

The above code sends the byte values 1, 2, 3, 4 and 5 to Korg devices (ID 0x42). 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.sendSysex([0x00, 0x21, 0x09], [1, 2, 3, 4, 5], WebMidi.outputs[0]);

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 Uint | Array

    A uint or an array of three uints 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.

  • [output=undefined] MIDIOutput | Array(MIDIOutput) optional

    A MIDI output device or an array of MIDI output devices to send the message to. All available MIDIOutput objects are listed in the WebMidi.outputs array. When this parameter is left undefined, the message is sent to all currently available output MIDI devices.

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

sendTimecodeQuarterFrame

(
  • value
  • [output=undefined]
  • [time=undefined]
)
WebMidi static chainable

Defined in src/webmidi.js:1475

Sends a MIDI Timecode Quarter Frame message to the specified output device(s). 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 Uint

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

  • [output=undefined] MIDIOutput | Array(MIDIOutput) optional

    A MIDI output device or an array of MIDI output devices to send the message to. All available MIDIOutput objects are listed in the WebMidi.outputs array. When this parameter is left undefined, the message is sent to all currently available output MIDI devices.

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

setMasterTuning

(
  • [value=0.0]
  • [output=undefined]
  • [channel=all]
  • [time=undefined]
)
WebMidi static chainable

Defined in src/webmidi.js:2625

Sends a master tuning message to the specified output(s) and 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)

  • [output=undefined] MIDIOutput | Array(MIDIOutput) optional

    A MIDI output device or an array of MIDI output devices to send the message to. All available MIDIOutput objects are listed in the WebMidi.outputs array. When this parameter is left undefined, the message is sent to all currently available output MIDI devices.

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

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

Throws:

RangeError:

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

setModulationRange

(
  • [semitones=0]
  • [cents=0]
  • [output=undefined]
  • [channel=all]
  • [time=undefined]
)
WebMidi static chainable

Defined in src/webmidi.js:2568

Sends a modulation depth range message to the specified output(s) and 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] Uint optional

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

  • [cents=0] Uint optional

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

  • [output=undefined] MIDIOutput | Array(MIDIOutput) optional

    A MIDI output device or an array of MIDI output devices to send the message to. All available MIDIOutput objects are listed in the WebMidi.outputs array. When this parameter is left undefined, the message is sent to all currently available output MIDI devices.

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

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

Throws:

RangeError:

The cents value must be between 0 and 127.

setNonRegisteredParameter

(
  • parameter
  • [data=[]]
  • [output=undefined]
  • [channel=all]
  • [time=undefined]
)
WebMidi static chainable

Defined in src/webmidi.js:2287

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 in 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.setNonRegisteredParameter([1, 8], 123);

Obviously, you should select an output device and channel so the message is not sent to all channels on all devices. For instance, to send to channel 1 of the first device, you would use:

WebMidi.setNonRegisteredParameter([1, 8], 123, WebMidi.outputs[0], 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.setNonRegisteredParameter([2, 63], [0, 10]);

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

Parameters:

  • parameter String | Array

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

  • [data=[]] Int | Array optional

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

  • [output=undefined] MIDIOutput | Array(MIDIOutput) optional

    A MIDI output device or an array of MIDI output devices to send the message to. All available MIDIOutput objects are listed in the WebMidi.outputs array. When this parameter is left undefined, the message is sent to all currently available output MIDI devices.

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

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

setPitchBendRange

(
  • [semitones=0]
  • [cents=0]
  • [output=undefined]
  • [channel=all]
  • [time=undefined]
)
WebMidi static chainable

Defined in src/webmidi.js:2509

Sends a pitch bend range message to the specified device(s) and channel(s) 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] Uint optional

    The desired adjustment value in semitones (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] Uint optional

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

  • [output=undefined] MIDIOutput | Array(MIDIOutput) optional

    A MIDI output device or an array of MIDI output devices to send the message to. All available MIDIOutput objects are listed in the WebMidi.outputs array. When this parameter is left undefined, the message is sent to all currently available output MIDI devices.

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

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

Throws:

RangeError:

The cents value must be between 0 and 127.

setRegisteredParameter

(
  • parameter
  • [data=[]]
  • [output=undefined]
  • [channel=all]
  • [time=undefined]
)
WebMidi static chainable

Defined in src/webmidi.js:2198

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

For more information on 3D sound controllers, please consult the RP-49 specification on Three Dimensional Sound Controllers.

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=[]] Int | Array optional

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

  • [output=undefined] MIDIOutput | Array(MIDIOutput) optional

    A MIDI output device or an array of MIDI output devices to send the message to. All available MIDIOutput objects are listed in the WebMidi.outputs array. When this parameter is left undefined, the message is sent to all currently available output MIDI devices.

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

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

setTuningBank

(
  • value
  • [output=undefined]
  • [channel=all]
  • [time=undefined]
)
WebMidi static chainable

Defined in src/webmidi.js:2739

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 Int

    The desired tuning bank (0-127).

  • [output=undefined] MIDIOutput | Array(MIDIOutput) optional

    A MIDI output device or an array of MIDI output devices to send the message to. All available MIDIOutput objects are listed in the WebMidi.outputs array. When this parameter is left undefined, the message is sent to all currently available output MIDI devices.

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

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

Throws:

RangeError:

The bank value must be between 0 and 127.

setTuningProgram

(
  • value
  • [output=undefined]
  • [channel=all]
  • [time=undefined]
)
WebMidi static chainable

Defined in src/webmidi.js:2691

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 Int

    The desired tuning program (0-127).

  • [output=undefined] MIDIOutput | Array(MIDIOutput) optional

    A MIDI output device or an array of MIDI output devices to send the message to. All available MIDIOutput objects are listed in the WebMidi.outputs array. When this parameter is left undefined, the message is sent to all currently available output MIDI devices.

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

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

Throws:

RangeError:

The program value must be between 0 and 127.

stopNote

(
  • note
  • [velocity=0.5]
  • [output=undefined]
  • [channel=all]
  • [time=undefined]
)
WebMidi static chainable

Defined in src/webmidi.js:1760

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

Parameters:

  • note Array | Uint | String

    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).

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

  • [output=undefined] MIDIOutput | Array(MIDIOutput) optional

    A MIDI output device or an array of MIDI output devices to send the message to. All available MIDIOutput objects are listed in the WebMidi.outputs array. When this parameter is left undefined, the message is sent to all currently available output MIDI devices.

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

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

Properties

connected

Boolean static

Defined in src/webmidi.js:66

[read-only] Indicates whether the interface to the host's MIDI subsystem is currently active.

inputs

MIDIInput[] static

Defined in src/webmidi.js:81

[read-only] An array of all currently available MIDI input devices.

outputs

MIDIOutput static

Defined in src/webmidi.js:102

[read-only] An array of all currently available MIDI output devices.

supported

Boolean static

Defined in src/webmidi.js:52

[read-only] Indicates whether the browser supports the Web MIDI API or not.

sysexEnabled

Boolean static

Defined in src/webmidi.js:123

[read-only] Indicates whether the interface to the host's MIDI subsystem is currently active.

time

DOMHighResTimeStamp static

Defined in src/webmidi.js:138

[read-only] Current MIDI performance time in milliseconds. This can be used to queue events in the future.

Events

activesensing

Defined in src/webmidi.js:808

Event emitted when a system active sensing MIDI message has been received.

Event Payload:

  • event Object
    • device MIDIInput

      The MIDI input device that triggered the event.

    • data Uint8Array

      The raw MIDI message as an array of 8 bit values.

    • receivedTime Number

      The time when the event occurred (in milliseconds since start).

    • timeStamp Uint

      The timestamp when the event occurred (in milliseconds since the epoch).

    • type String

      The type of event that occurred.

channelaftertouch

Defined in src/webmidi.js:530

Event emitted when a channel-wide aftertouch MIDI message has been received on a specific device and channel.

Event Payload:

  • event Object
    • device MIDIInput

      The MIDI input device that triggered the event.

    • data Uint8Array

      The raw MIDI message as an array of 8 bit values.

    • receivedTime Number

      The time when the event occurred (in milliseconds since start).

    • timeStamp Uint

      The timestamp when the event occurred (in milliseconds since the epoch).

    • channel Uint

      The channel where the event occurred (between 1 and 16).

    • type String

      The type of event that occurred.

    • value Number

      The aftertouch value received (between 0 and 1).

channelmode

Defined in src/webmidi.js:462

Event emitted when a channel mode MIDI message has been received on a specific device and channel.

Event Payload:

  • event Object
    • device MIDIInput

      The MIDI input device that triggered the event.

    • data Uint8Array

      The raw MIDI message as an array of 8 bit values.

    • receivedTime Number

      The time when the event occurred (in milliseconds since start).

    • timeStamp Uint

      The timestamp when the event occurred (in milliseconds since the epoch).

    • channel Uint

      The channel where the event occurred (between 1 and 16).

    • type String

      The type of event that occurred.

    • controller Object
      • number Uint
        The number of the controller.
      • name String
        The number of the controller.
    • value Uint

      The value received (between 0 and 127).

clock

Defined in src/webmidi.js:732

Event emitted when a system timing clock MIDI message has been received.

Event Payload:

  • event Object
    • device MIDIInput

      The MIDI input device that triggered the event.

    • data Uint8Array

      The raw MIDI message as an array of 8 bit values.

    • receivedTime Number

      The time when the event occurred (in milliseconds since start).

    • timeStamp Uint

      The timestamp when the event occurred (in milliseconds since the epoch).

    • type String

      The type of event that occurred.

continue

Defined in src/webmidi.js:770

Event emitted when a system continue MIDI message has been received.

Event Payload:

  • event Object
    • device MIDIInput

      The MIDI input device that triggered the event.

    • data Uint8Array

      The raw MIDI message as an array of 8 bit values.

    • receivedTime Number

      The time when the event occurred (in milliseconds since start).

    • timeStamp Uint

      The timestamp when the event occurred (in milliseconds since the epoch).

    • type String

      The type of event that occurred.

controlchange

Defined in src/webmidi.js:420

Event emitted when a control change MIDI message has been received on a specific device and channel.

Event Payload:

  • event Object
    • device MIDIInput

      The MIDI input device that triggered the event.

    • data Uint8Array

      The raw MIDI message as an array of 8 bit values.

    • receivedTime Number

      The time when the event occurred (in milliseconds since start).

    • timeStamp Uint

      The timestamp when the event occurred (in milliseconds since the epoch).

    • channel Uint

      The channel where the event occurred (between 1 and 16).

    • type String

      The type of event that occurred.

    • controller Object
      • number Uint
        The number of the controller.
      • name String
        The number of the controller.
    • value Uint

      The value received (between 0 and 127).

keyaftertouch

Defined in src/webmidi.js:375

Event emitted when a key-specific aftertouch MIDI message has been received on a specific device and channel.

Event Payload:

  • event Object
    • device MIDIInput

      The MIDI input device that triggered the event.

    • data Uint8Array

      The raw MIDI message as an array of 8 bit values.

    • receivedTime Number

      The time when the event occurred (in milliseconds since start).

    • timeStamp Uint

      The timestamp when the event occurred (in milliseconds since the epoch).

    • channel Uint

      The channel where the event occurred (between 1 and 16).

    • type String

      The type of event that occurred.

    • note Object
      • number Uint
        The MIDI note number.
      • name String
        The usual note name (C, C#, D, D#, etc.).
      • octave Uint
        The octave (between -2 and 8).
    • value Number

      The aftertouch amount (between 0 and 1).

noteoff

Defined in src/webmidi.js:291

Event emitted when a note off MIDI message has been received on a specific device and channel.

Event Payload:

  • event Object
    • device MIDIInput

      The MIDI input device that triggered the event.

    • data Uint8Array

      The raw MIDI message as an array of 8 bit values.

    • receivedTime Number

      The time when the event occurred (in milliseconds since start).

    • timeStamp Uint

      The timestamp when the event occurred (in milliseconds since the epoch).

    • channel Uint

      The channel where the event occurred (between 1 and 16).

    • type String

      The type of event that occurred.

    • note Object
      • number Uint
        The MIDI note number.
      • name String
        The usual note name (C, C#, D, D#, etc.).
      • octave Uint
        The octave (between -2 and 8).
    • velocity Number

      The release velocity (between 0 and 1).

noteon

Defined in src/webmidi.js:333

Event emitted when a note on MIDI message has been received on a specific device and channel.

Event Payload:

  • event Object
    • device MIDIInput

      The MIDI input device that triggered the event.

    • data Uint8Array

      The raw MIDI message as an array of 8 bit values.

    • receivedTime Number

      The time when the event occurred (in milliseconds since start).

    • timeStamp Uint

      The timestamp when the event occurred (in milliseconds since the epoch).

    • channel Uint

      The channel where the event occurred (between 1 and 16).

    • type String

      The type of event that occurred.

    • note Object
      • number Uint
        The MIDI note number.
      • name String
        The usual note name (C, C#, D, D#, etc.).
      • octave Uint
        The octave (between -2 and 8).
    • velocity Number

      The attack velocity (between 0 and 1).

pitchbend

Defined in src/webmidi.js:559

Event emitted when a pitch bend MIDI message has been received on a specific device and channel.

Event Payload:

  • event Object
    • device MIDIInput

      The MIDI input device that triggered the event.

    • data Uint8Array

      The raw MIDI message as an array of 8 bit values.

    • receivedTime Number

      The time when the event occurred (in milliseconds since start).

    • timeStamp Uint

      The timestamp when the event occurred (in milliseconds since the epoch).

    • channel Uint

      The channel where the event occurred (between 1 and 16).

    • type String

      The type of event that occurred.

    • value Number

      The pitch bend value received (between -1 and 1).

programchange

Defined in src/webmidi.js:501

Event emitted when a program change MIDI message has been received on a specific device and channel.

Event Payload:

  • event Object
    • device MIDIInput

      The MIDI input device that triggered the event.

    • data Uint8Array

      The raw MIDI message as an array of 8 bit values.

    • receivedTime Number

      The time when the event occurred (in milliseconds since start).

    • timeStamp Uint

      The timestamp when the event occurred (in milliseconds since the epoch).

    • channel Uint

      The channel where the event occurred (between 1 and 16).

    • type String

      The type of event that occurred.

    • value Uint

      The value received (between 0 and 127).

reset

Defined in src/webmidi.js:827

Event emitted when a system reset MIDI message has been received.

Event Payload:

  • event Object
    • device MIDIInput

      The MIDI input device that triggered the event.

    • data Uint8Array

      The raw MIDI message as an array of 8 bit values.

    • receivedTime Number

      The time when the event occurred (in milliseconds since start).

    • timeStamp Uint

      The timestamp when the event occurred (in milliseconds since the epoch).

    • type String

      The type of event that occurred.

songposition

Defined in src/webmidi.js:667

Event emitted when a system song position pointer MIDI message has been received.

Event Payload:

  • event Object
    • device MIDIInput

      The MIDI input device that triggered the event.

    • data Uint8Array

      The raw MIDI message as an array of 8 bit values.

    • receivedTime Number

      The time when the event occurred (in milliseconds since start).

    • timeStamp Uint

      The timestamp when the event occurred (in milliseconds since the epoch).

    • type String

      The type of event that occurred.

songselect

Defined in src/webmidi.js:692

Event emitted when a system song select MIDI message has been received.

Event Payload:

  • event Object
    • device MIDIInput

      The MIDI input device that triggered the event.

    • data Uint8Array

      The raw MIDI message as an array of 8 bit values.

    • receivedTime Number

      The time when the event occurred (in milliseconds since start).

    • timeStamp Uint

      The timestamp when the event occurred (in milliseconds since the epoch).

    • type String

      The type of event that occurred.

    • song String

      Song (or sequence) number to select.

start

Defined in src/webmidi.js:751

Event emitted when a system start MIDI message has been received.

Event Payload:

  • event Object
    • device MIDIInput

      The MIDI input device that triggered the event.

    • data Uint8Array

      The raw MIDI message as an array of 8 bit values.

    • receivedTime Number

      The time when the event occurred (in milliseconds since start).

    • timeStamp Uint

      The timestamp when the event occurred (in milliseconds since the epoch).

    • type String

      The type of event that occurred.

statechange

Defined in src/webmidi.js:247

Event emitted when the interface's state changes. Typically, this happens when a MIDI device is being plugged or unplugged. This event cannot be listened on a single specific MIDI device, it is intended to be interface-wide.

Event Payload:

stop

Defined in src/webmidi.js:789

Event emitted when a system stop MIDI message has been received.

Event Payload:

  • event Object
    • device MIDIInput

      The MIDI input device that triggered the event.

    • data Uint8Array

      The raw MIDI message as an array of 8 bit values.

    • receivedTime Number

      The time when the event occurred (in milliseconds since start).

    • timeStamp Uint

      The timestamp when the event occurred (in milliseconds since the epoch).

    • type String

      The type of event that occurred.

sysex

Defined in src/webmidi.js:619

Event emitted when a system exclusive MIDI message has been received.

Event Payload:

  • event Object
    • device MIDIInput

      The MIDI input device that triggered the event.

    • data Uint8Array

      The raw MIDI message as an array of 8 bit values.

    • receivedTime Number

      The time when the event occurred (in milliseconds since start).

    • timeStamp Uint

      The timestamp when the event occurred (in milliseconds since the epoch).

    • type String

      The type of event that occurred.

timecode

Defined in src/webmidi.js:642

Event emitted when a system MIDI time code quarter frame message has been received.

Event Payload:

  • event Object
    • device MIDIInput

      The MIDI input device that triggered the event.

    • data Uint8Array

      The raw MIDI message as an array of 8 bit values.

    • receivedTime Number

      The time when the event occurred (in milliseconds since start).

    • timeStamp Uint

      The timestamp when the event occurred (in milliseconds since the epoch).

    • type String

      The type of event that occurred.

tuningrequest

Defined in src/webmidi.js:713

Event emitted when a system tune request MIDI message has been received.

Event Payload:

  • event Object
    • device MIDIInput

      The MIDI input device that triggered the event.

    • data Uint8Array

      The raw MIDI message as an array of 8 bit values.

    • receivedTime Number

      The time when the event occurred (in milliseconds since start).

    • timeStamp Uint

      The timestamp when the event occurred (in milliseconds since the epoch).

    • type String

      The type of event that occurred.

unknownsystemmessage

Defined in src/webmidi.js:850

Event emitted when an unknown system MIDI message has been received. It could be, for example, one of the undefined/reserved messages.

Event Payload:

  • event Object
    • device MIDIInput

      The MIDI input device that triggered the event.

    • data Uint8Array

      The raw MIDI message as an array of 8 bit values.

    • receivedTime Number

      The time when the event occurred (in milliseconds since start).

    • timeStamp Uint

      The timestamp when the event occurred (in milliseconds since the epoch).

    • type String

      The type of event that occurred.