Skip to main content

Output

The Output class represents a single MIDI output port (not to be confused with a MIDI channel). A port is made available by a MIDI device. A MIDI device can advertise several input and output ports. Each port has 16 MIDI channels which can be accessed via the channels property.

The Output object is automatically instantiated by the library according to the host's MIDI subsystem and should not be directly instantiated.

You can access all available Output objects by referring to the WebMidi.outputs array or by using methods such as WebMidi.getOutputByName() or WebMidi.getOutputById().

Extends: EventEmitter

Fires: closed, disconnected, opened

Constructor

Creates an Output object.

Parameters

new Output(midiOutput)

ParameterTypeDefaultDescription
midiOutputMIDIOutput
MIDIOutput object as provided by the MIDI subsystem.

Properties

.channels

Type: Array.<OutputChannel>

Array containing the 16 OutputChannel objects available provided by this Output. The channels are numbered 1 through 16.

.connection

Type: string
Attributes: read-only

Output port's connection state: pending, open or closed.

.eventCount

Type: number
Attributes: read-only

The number of unique events that have registered listeners.

Note: this excludes global events registered with EventEmitter.ANY_EVENT because they are not tied to a specific event.

.eventMap

Type: Object
Attributes: read-only

An object containing a property for each event with at least one registered listener. Each event property contains an array of all the Listener objects registered for the event.

.eventNames

Type: Array.<string>
Attributes: read-only

An array of all the unique event names for which the emitter has at least one registered listener.

Note: this excludes global events registered with EventEmitter.ANY_EVENT because they are not tied to a specific event.

.eventsSuspended

Type: boolean

Whether or not the execution of callbacks is currently suspended for this emitter.

.id

Type: string
Attributes: read-only

ID string of the MIDI output. The ID is host-specific. Do not expect the same ID on different platforms. For example, Google Chrome and the Jazz-Plugin report completely different IDs for the same port.

.manufacturer

Type: string
Attributes: read-only

Name of the manufacturer of the device that makes this output port available.

.name

Type: string
Attributes: read-only

Name of the MIDI output.

.octaveOffset

Since: 3.0
Type: number

An integer to offset the octave of outgoing notes. By default, middle C (MIDI note number 60) is placed on the 4th octave (C4).

Note that this value is combined with the global offset value defined in WebMidi.octaveOffset (if any).

.state

Type: string
Attributes: read-only

State of the output port: connected or disconnected.

.type

Type: string
Attributes: read-only

Type of the output port (it will always be: output).


Methods

.addListener(...)

Adds a listener for the specified event. It returns the Listener object that was created and attached to the event.

To attach a global listener that will be triggered for any events, use EventEmitter.ANY_EVENT as the first parameter. Note that a global listener will also be triggered by non-registered events.

Parameters

Signature: addListener(event, callback, [options])

ParameterType(s)DefaultDescription
eventstring
Symbol
The event to listen to.
callbackEventEmitter~callback
The callback function to execute when the event occurs.
[options]Object
{}
[options.context]Object
thisThe value of this in the callback function.
[options.prepend]boolean
falseWhether the listener should be added at the beginning of the listeners array and thus executed first.
[options.duration]number
InfinityThe number of milliseconds before the listener automatically expires.
[options.remaining]number
InfinityThe number of times after which the callback should automatically be removed.
[options.arguments]array
An array of arguments which will be passed separately to the callback function. This array is stored in the arguments property of the Listener object and can be retrieved or modified as desired.

Return Value

Returns: Listener

The newly created Listener object.

Throws:

  • TypeError : The event parameter must be a string or EventEmitter.ANY_EVENT.
  • TypeError : The callback parameter must be a function.

.addOneTimeListener(...)

Adds a one-time listener for the specified event. The listener will be executed once and then destroyed. It returns the Listener object that was created and attached to the event.

To attach a global listener that will be triggered for any events, use EventEmitter.ANY_EVENT as the first parameter. Note that a global listener will also be triggered by non-registered events.

Parameters

Signature: addOneTimeListener(event, callback, [options])

ParameterType(s)DefaultDescription
eventstring
Symbol
The event to listen to
callbackEventEmitter~callback
The callback function to execute when the event occurs
[options]Object
{}
[options.context]Object
thisThe context to invoke the callback function in.
[options.prepend]boolean
falseWhether the listener should be added at the beginning of the listeners array and thus executed first.
[options.duration]number
InfinityThe number of milliseconds before the listener automatically expires.
[options.arguments]array
An array of arguments which will be passed separately to the callback function. This array is stored in the arguments property of the Listener object and can be retrieved or modified as desired.

Return Value

Returns: Listener

The newly created Listener object.

Throws:

  • TypeError : The event parameter must be a string or EventEmitter.ANY_EVENT.
  • TypeError : The callback parameter must be a function.

.clear()

Clears all messages that have been queued but not yet delivered.

Warning: this method has been defined in the specification but has not been implemented yet. As soon as browsers implement it, it will work.

You can check out the current status of this feature for Chromium (Chrome) here: https://bugs.chromium.org/p/chromium/issues/detail?id=471798

Return Value

Returns: Output

Returns the Output object so methods can be chained.

.close()

Attributes: async

Closes the output connection. When an output is closed, it cannot be used to send MIDI messages until the output is opened again by calling open(). You can check the connection status by looking at the connection property.

Return Value

Returns: Promise.<void>

.destroy()

Attributes: async

Destroys the Output. All listeners are removed, all channels are destroyed and the MIDI subsystem is unlinked.

Return Value

Returns: Promise.<void>

.emit(...)

Executes the callback function of all the Listener objects registered for a given event. The callback functions are passed the additional arguments passed to emit() (if any) followed by the arguments present in the arguments property of the Listener object (if any).

If the eventsSuspended property is true or the Listener.suspended property is true, the callback functions will not be executed.

This function returns an array containing the return values of each of the callbacks.

It should be noted that the regular listeners are triggered first followed by the global listeners (those added with EventEmitter.ANY_EVENT).

Parameters

Signature: emit(event, ...args)

ParameterType(s)DefaultDescription
eventstring
The event
args*
Arbitrary number of arguments to pass along to the callback functions

Return Value

Returns: Array

An array containing the return value of each of the executed listener functions.

Throws:

  • TypeError : The event parameter must be a string.

.getListenerCount(...)

Returns the number of listeners registered for a specific event.

Please note that global events (those added with EventEmitter.ANY_EVENT) do not count towards the remaining number for a "regular" event. To get the number of global listeners, specifically use EventEmitter.ANY_EVENT as the parameter.

Parameters

Signature: getListenerCount(event)

ParameterType(s)DefaultDescription
eventstring
Symbol
The event which is usually a string but can also be the special EventEmitter.ANY_EVENT symbol.

Return Value

Returns: number

An integer representing the number of listeners registered for the specified event.

.getListeners(...)

Returns an array of all the Listener objects that have been registered for a specific event.

Please note that global events (those added with EventEmitter.ANY_EVENT) are not returned for "regular" events. To get the list of global listeners, specifically use EventEmitter.ANY_EVENT as the parameter.

Parameters

Signature: getListeners(event)

ParameterType(s)DefaultDescription
eventstring
Symbol
The event to get listeners for.

Return Value

Returns: Array.<Listener>

An array of Listener objects.

.hasListener(...)

Returns true if the specified event has at least one registered listener. If no event is specified, the method returns true if any event has at least one listener registered (this includes global listeners registered to EventEmitter.ANY_EVENT).

Note: to specifically check for global listeners added with EventEmitter.ANY_EVENT, use EventEmitter.ANY_EVENT as the parameter.

Parameters

Signature: hasListener([event], [callback])

ParameterType(s)DefaultDescription
[event]string
Symbol
(any event)The event to check
[callback]function
Listener
(any callback)The actual function that was added to the event or the Listener object returned by addListener().

Return Value

Returns: boolean

.open()

Attributes: async

Opens the output for usage. When the library is enabled, all ports are automatically opened. This method is only useful for ports that have been manually closed.

Return Value

Returns: Promise.<Output>

The promise is fulfilled with the Output object.

.playNote(...)

Plays a note or an array of notes on one or more channels of this output. If you intend to play notes on a single channel, you should probably use OutputChannel.playNote() instead.

The first parameter is the note to play. It can be a single value or an array of the following valid values:

  • A MIDI note number (integer between 0 and 127)
  • A note identifier (e.g. "C3", "G#4", "F-1", "Db7")
  • A Note object

The playNote() method sends a note on MIDI message for all specified notes on all specified channels. If no channel is specified, it will send to all channels. If a duration is set in the options parameter or in the Note object's duration property, it will also schedule a note off message to end the note after said duration. If no duration is set, the note will simply play until a matching note off message is sent with stopNote().

The execution of the note on command can be delayed by using the time property of the options parameter.

When using Note objects, the durations and velocities defined in the Note objects have precedence over the ones specified via the method's options parameter.

Note: As per the MIDI standard, a note on message with an attack velocity of 0 is functionally equivalent to a note off message.

Parameters

Signature: playNote(note, [options])

ParameterType(s)DefaultDescription
notenumber
string
Note
Array.<number>
Array.<string>
Array.<Note>
The note(s) to play. The notes can be specified by using a MIDI note number (0-127), a note identifier (e.g. C3, G#4, F-1, Db7), a Note object or an array of the previous types. When using a note identifier, octave range must be between -1 and 9. The lowest note is C-1 (MIDI note number 0) and the highest note is G9 (MIDI note number 127).
[options]Object
{}
[options.channels]number
Array.<number>
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]The MIDI channel number (between 1 and 16) or an array of channel numbers to use. If no channel is specified, all channels will be used.
[options.duration]number
The number of milliseconds after which a note off message will be scheduled. If left undefined, only a note on message is sent.
[options.attack]number
0.5The velocity at which to play the note (between 0 and 1). If the rawAttack option is also defined, it will have priority. An invalid velocity value will silently trigger the default of 0.5.
[options.rawAttack]number
64The attack velocity at which to play the note (between 0 and 127). This has priority over the attack property. An invalid velocity value will silently trigger the default of 64.
[options.release]number
0.5The velocity at which to release the note (between 0 and 1). If the rawRelease option is also defined, it will have priority. 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.
[options.rawRelease]number
64The velocity at which to release the note (between 0 and 127). This has priority over the release property. An invalid velocity value will silently trigger the default of 64. This is only used with the note off event triggered when options.duration is set.
[options.time]number
string
(now)If time is a string prefixed with "+" and followed by a number, the message will be delayed by that many milliseconds. If the value is a positive number (DOMHighResTimeStamp), the operation will be scheduled for that time. The current time can be retrieved with WebMidi.time. If options.time is omitted, or in the past, the operation will be carried out as soon as possible.

Return Value

Returns: Output

Returns the Output object so methods can be chained.

.removeListener(...)

Removes all the listeners that were added to the object upon which the method is called and that match the specified criterias. If no parameters are passed, all listeners added to this object will be removed. If only the event parameter is passed, all listeners for that event will be removed from that object. You can remove global listeners by using EventEmitter.ANY_EVENT as the first parameter.

To use more granular options, you must at least define the event. Then, you can specify the callback to match or one or more of the additional options.

Parameters

Signature: removeListener([event], [callback], [options])

ParameterType(s)DefaultDescription
[event]string
The event name.
[callback]EventEmitter~callback
Only remove the listeners that match this exact callback function.
[options]Object
[options.context]*
Only remove the listeners that have this exact context.
[options.remaining]number
Only remove the listener if it has exactly that many remaining times to be executed.

.send(...)

Sends a MIDI message on the MIDI output port. If no time is specified, the message will be sent immediately. The message should be an array of 8 bit unsigned integers (0-225), a Uint8Array object or a Message object.

It is usually not necessary to use this method directly as you can use one of the simpler helper methods such as playNote(), stopNote(), sendControlChange(), etc.

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

Parameters

Signature: send(message, [options])

ParameterType(s)DefaultDescription
messageArray.<number>
Uint8Array
Message
An array of 8bit unsigned integers, a Uint8Array object (not available in Node.js) containing the message bytes or a Message object.
[options]object
{}
[options.time]number
string
(now)If time is a string prefixed with "+" and followed by a number, the message will be delayed by that many milliseconds. If the value is a positive number (DOMHighResTimeStamp), the operation will be scheduled for that time. The current time can be retrieved with WebMidi.time. If options.time is omitted, or in the past, the operation will be carried out as soon as possible.

Return Value

Returns: Output

Returns the Output object so methods can be chained.

Throws:

  • RangeError : The first byte (status) must be an integer between 128 and 255.

.sendActiveSensing(...)

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

Parameters

Signature: sendActiveSensing([options])

ParameterType(s)DefaultDescription
[options]object
{}
[options.time]number
string
(now)If time is a string prefixed with "+" and followed by a number, the message will be delayed by that many milliseconds. If the value is a positive number (DOMHighResTimeStamp), the operation will be scheduled for that time. The current time can be retrieved with WebMidi.time. If options.time is omitted, or in the past, the operation will be carried out as soon as possible.

Return Value

Returns: Output

Returns the Output object so methods can be chained.

.sendAllNotesOff(...)

Since: 3.0.0

Sends an all notes off channel mode message. This will make all currently playing notes fade out just as if their key had been released. This is different from the sendAllSoundOff() method which mutes all sounds immediately.

Parameters

Signature: sendAllNotesOff([options])

ParameterType(s)DefaultDescription
[options]Object
{}
[options.channels]number
Array.<number>
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]The MIDI channel number (between 1 and 16) or an array of channel numbers to use. If no channel is specified, all channels will be used.
[options.time]number
string
(now)If time is a string prefixed with "+" and followed by a number, the message will be delayed by that many milliseconds. If the value is a positive number (DOMHighResTimeStamp), the operation will be scheduled for that time. The current time can be retrieved with WebMidi.time. If options.time is omitted, or in the past, the operation will be carried out as soon as possible.

Return Value

Returns: Output

.sendAllSoundOff(...)

Since: 3.0.0

Sends an all sound off channel mode message. This will silence all sounds playing on that channel but will not prevent new sounds from being triggered.

Parameters

Signature: sendAllSoundOff([options])

ParameterType(s)DefaultDescription
[options]Object
{}
[options.channels]number
Array.<number>
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]The MIDI channel number (between 1 and 16) or an array of channel numbers to use. If no channel is specified, all channels will be used.
[options.time]number
string
(now)If time is a string prefixed with "+" and followed by a number, the message will be delayed by that many milliseconds. If the value is a positive number (DOMHighResTimeStamp), the operation will be scheduled for that time. The current time can be retrieved with WebMidi.time. If options.time is omitted, or in the past, the operation will be carried out as soon as possible.

Return Value

Returns: Output

.sendChannelAftertouch(...)

Since: 3.0.0

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

Parameters

Signature: sendChannelAftertouch([pressure], [options])

ParameterType(s)DefaultDescription
[pressure]number
0.5The pressure level (between 0 and 1). An invalid pressure value will silently trigger the default behaviour. If the rawValue option is set to true, the pressure can be defined by using an integer between 0 and 127.
[options]object
{}
[options.channels]number
Array.<number>
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]The MIDI channel number (between 1 and 16) or an array of channel numbers to use. If no channel is specified, all channels will be used.
[options.rawValue]boolean
falseA boolean indicating whether the value should be considered a float between 0 and 1.0 (default) or a raw integer between 0 and 127.
[options.time]number
string
(now)If time is a string prefixed with "+" and followed by a number, the message will be delayed by that many milliseconds. If the value is a positive number (DOMHighResTimeStamp), the operation will be scheduled for that time. The current time can be retrieved with WebMidi.time. If options.time is omitted, or in the past, the operation will be carried out as soon as possible.

Return Value

Returns: Output

Returns the Output object so methods can be chained.

.sendChannelMode(...)

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:

TypeNumberShortcut Method
allsoundoff120sendAllSoundOff()
resetallcontrollers121sendResetAllControllers()
localcontrol122sendLocalControl()
allnotesoff123sendAllNotesOff()
omnimodeoff124sendOmniMode(false)
omnimodeon125sendOmniMode(true)
monomodeon126sendPolyphonicMode("mono")
polymodeon127sendPolyphonicMode("poly")

Note: as you can see above, to make it easier, all channel mode messages also have a matching helper method.

It should also 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

Signature: sendChannelMode(command, [value], [options])

ParameterType(s)DefaultDescription
commandnumber
string
The numerical identifier of the channel mode message (integer between 120-127) or its name as a string.
[value]number
0The value to send (integer between 0-127).
[options]Object
{}
[options.channels]number
Array.<number>
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]The MIDI channel number (between 1 and 16) or an array of channel numbers to use. If no channel is specified, all channels will be used.
[options.time]number
string
(now)If time is a string prefixed with "+" and followed by a number, the message will be delayed by that many milliseconds. If the value is a positive number (DOMHighResTimeStamp), the operation will be scheduled for that time. The current time can be retrieved with WebMidi.time. If options.time is omitted, or in the past, the operation will be carried out as soon as possible.

Return Value

Returns: Output

Returns the Output object so methods can be chained.

Throws:

  • TypeError : Invalid channel mode message name.
  • RangeError : Channel mode controller numbers must be between 120 and 127.
  • RangeError : Value must be an integer between 0 and 127.

.sendClock(...)

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

Parameters

Signature: sendClock([options])

ParameterType(s)DefaultDescription
[options]object
{}
[options.time]number
string
(now)If time is a string prefixed with "+" and followed by a number, the message will be delayed by that many milliseconds. If the value is a positive number (DOMHighResTimeStamp), the operation will be scheduled for that time. The current time can be retrieved with WebMidi.time. If options.time is omitted, or in the past, the operation will be carried out as soon as possible.

Return Value

Returns: Output

Returns the Output object so methods can be chained.

.sendContinue(...)

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()` method.

Parameters

Signature: sendContinue([options])

ParameterType(s)DefaultDescription
[options]object
{}
[options.time]number
string
(now)If time is a string prefixed with "+" and followed by a number, the message will be delayed by that many milliseconds. If the value is a positive number (DOMHighResTimeStamp), the operation will be scheduled for that time. The current time can be retrieved with WebMidi.time. If options.time is omitted, or in the past, the operation will be carried out as soon as possible.

Return Value

Returns: Output

Returns the Output object so methods can be chained.

.sendControlChange(...)

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

NumberName
0bankselectcoarse
1modulationwheelcoarse
2breathcontrollercoarse
4footcontrollercoarse
5portamentotimecoarse
6dataentrycoarse
7volumecoarse
8balancecoarse
10pancoarse
11expressioncoarse
12effectcontrol1coarse
13effectcontrol2coarse
18generalpurposeslider3
19generalpurposeslider4
32bankselectfine
33modulationwheelfine
34breathcontrollerfine
36footcontrollerfine
37portamentotimefine
38dataentryfine
39volumefine
40balancefine
42panfine
43expressionfine
44effectcontrol1fine
45effectcontrol2fine
64holdpedal
65portamento
66sustenutopedal
67softpedal
68legatopedal
69hold2pedal
70soundvariation
71resonance
72soundreleasetime
73soundattacktime
74brightness
75soundcontrol6
76soundcontrol7
77soundcontrol8
78soundcontrol9
79soundcontrol10
80generalpurposebutton1
81generalpurposebutton2
82generalpurposebutton3
83generalpurposebutton4
91reverblevel
92tremololevel
93choruslevel
94celestelevel
95phaserlevel
96dataincrement
97datadecrement
98nonregisteredparametercoarse
99nonregisteredparameterfine
100registeredparametercoarse
101registeredparameterfine
120allsoundoff
121resetallcontrollers
122localcontrol
123allnotesoff
124omnimodeoff
125omnimodeon
126monomodeon
127polymodeon

Note: as you can see above, not all control change message have a matching name. This does not mean you cannot use the others. It simply means you will need to use their number (0 - 127) instead of their name. While you can still use them, numbers 120 to 127 are usually reserved for channel mode messages. See sendChannelMode() method for more info.

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

Parameters

Signature: sendControlChange(controller, [value], [options])

ParameterType(s)DefaultDescription
controllernumber
string
The MIDI controller name or number (0-127).
[value]number
0The value to send (0-127).
[options]object
{}
[options.channels]number
Array.<number>
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]The MIDI channel number (between 1 and 16) or an array of channel numbers to use. If no channel is specified, all channels will be used.
[options.time]number
string
(now)If time is a string prefixed with "+" and followed by a number, the message will be delayed by that many milliseconds. If the value is a positive number (DOMHighResTimeStamp), the operation will be scheduled for that time. The current time can be retrieved with WebMidi.time. If options.time is omitted, or in the past, the operation will be carried out as soon as possible.

Return Value

Returns: Output

Returns the Output object so methods can be chained.

Throws:

  • RangeError : Controller numbers must be between 0 and 127.
  • RangeError : Invalid controller name.

.sendKeyAftertouch(...)

Since: 3.0.0

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

Parameters

Signature: sendKeyAftertouch(note, [pressure], [options])

ParameterType(s)DefaultDescription
notenumber
Note
string
Array.<number>
Array.<Note>
Array.<string>
The note(s) for which you are sending an aftertouch value. The notes can be specified by using a MIDI note number (0 - 127), a Note object, a note identifier (e.g. C3, G#4, F-1, Db7) or an array of the previous types. When using a note identifier, octave range must be between -1 and 9. The lowest note is C-1 (MIDI note number 0) and the highest note is G9 (MIDI note number 127).
[pressure]number
0.5The pressure level (between 0 and 1). An invalid pressure value will silently trigger the default behaviour. If the rawValue option is set to true, the pressure can be defined by using an integer between 0 and 127.
[options]object
{}
[options.channels]number
Array.<number>
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]The MIDI channel number (between 1 and 16) or an array of channel numbers to use. If no channel is specified, all channels will be used.
[options.rawValue]boolean
falseA boolean indicating whether the value should be considered a float between 0 and 1.0 (default) or a raw integer between 0 and 127.
[options.time]number
string
(now)If time is a string prefixed with "+" and followed by a number, the message will be delayed by that many milliseconds. If the value is a positive number (DOMHighResTimeStamp), the operation will be scheduled for that time. The current time can be retrieved with WebMidi.time. If options.time is omitted, or in the past, the operation will be carried out as soon as possible.

Return Value

Returns: Output

Returns the Output object so methods can be chained.

.sendLocalControl(...)

Since: 3.0.0

Turns local control on or off. Local control is usually enabled by default. If you disable it, the instrument will no longer trigger its own sounds. It will only send the MIDI messages to its out port.

Parameters

Signature: sendLocalControl([state], [options])

ParameterType(s)DefaultDescription
[state]boolean
falseWhether to activate local control (true) or disable it (false).
[options]Object
{}
[options.channels]number
Array.<number>
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]The MIDI channel number (between 1 and 16) or an array of channel numbers to use. If no channel is specified, all channels will be used.
[options.time]number
string
(now)If time is a string prefixed with "+" and followed by a number, the message will be delayed by that many milliseconds. If the value is a positive number (DOMHighResTimeStamp), the operation will be scheduled for that time. The current time can be retrieved with WebMidi.time. If options.time is omitted, or in the past, the operation will be carried out as soon as possible.

Return Value

Returns: Output

Returns the Output object so methods can be chained.

.sendMasterTuning(...)

Since: 3.0.0

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. This function actually generates two MIDI messages: a Master Coarse Tuning and a Master Fine Tuning RPN messages.

Parameters

Signature: sendMasterTuning([value], [options])

ParameterType(s)DefaultDescription
[value]number
0.0The desired decimal adjustment value in semitones (-65 < x < 64)
[options]Object
{}
[options.channels]number
Array.<number>
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]The MIDI channel number (between 1 and 16) or an array of channel numbers to use. If no channel is specified, all channels will be used.
[options.time]number
string
(now)If time is a string prefixed with "+" and followed by a number, the message will be delayed by that many milliseconds. If the value is a positive number (DOMHighResTimeStamp), the operation will be scheduled for that time. The current time can be retrieved with WebMidi.time. If options.time is omitted, or in the past, the operation will be carried out as soon as possible.

Return Value

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.

.sendModulationRange(...)

Since: 3.0.0

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

Signature: sendModulationRange([semitones], [cents], [options])

ParameterType(s)DefaultDescription
[semitones]number
0The desired adjustment value in semitones (integer between 0 and 127).
[cents]number
0The desired adjustment value in cents (integer between 0 and 127).
[options]Object
{}
[options.channels]number
Array.<number>
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]The MIDI channel number (between 1 and 16) or an array of channel numbers to use. If no channel is specified, all channels will be used.
[options.time]number
string
(now)If time is a string prefixed with "+" and followed by a number, the message will be delayed by that many milliseconds. If the value is a positive number (DOMHighResTimeStamp), the operation will be scheduled for that time. The current time can be retrieved with WebMidi.time. If options.time is omitted, or in the past, the operation will be carried out as soon as possible.

Return Value

Returns: Output

Returns the Output object so methods can be chained.

Throws:

  • RangeError : The msb value must be between 0 and 127
  • RangeError : The lsb value must be between 0 and 127

.sendNoteOff(...)

Sends a note off message for the specified MIDI note number on the specified channel(s). The first parameter is the note to stop. It can be a single value or an array of the following valid values:

  • A MIDI note number (integer between 0 and 127)
  • A note identifier (e.g. "C3", "G#4", "F-1", "Db7")
  • A Note object

The execution of the note off command can be delayed by using the time property of the options parameter.

Parameters

Signature: sendNoteOff(note, [options])

ParameterType(s)DefaultDescription
notenumber
Note
string
Array.<number>
Array.<Note>
Array.<string>
The note(s) to stop. The notes can be specified by using a MIDI note number (0 - 127), a note identifier (e.g. C3, G#4, F-1, Db7) or an array of the previous types. When using a note identifier, octave range must be between -1 and 9. The lowest note is C-1 (MIDI note number 0) and the highest note is G9 (MIDI note number 127).
[options]Object
{}
[options.channels]number
Array.<number>
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]The MIDI channel number (between 1 and 16) or an array of channel numbers to use. If no channel is specified, all channels will be used.
[options.release]number
0.5The velocity at which to release the note (between 0 and 1). If the rawRelease option is also defined, rawRelease will have priority. An invalid velocity value will silently trigger the default of 0.5.
[options.rawRelease]number
64The velocity at which to release the note (between 0 and 127). If the release option is also defined, rawRelease will have priority. An invalid velocity value will silently trigger the default of 64.
[options.time]number
string
(now)If time is a string prefixed with "+" and followed by a number, the message will be delayed by that many milliseconds. If the value is a positive number (DOMHighResTimeStamp), the operation will be scheduled for that time. The current time can be retrieved with WebMidi.time. If options.time is omitted, or in the past, the operation will be carried out as soon as possible.

Return Value

Returns: Output

Returns the Output object so methods can be chained.

.sendNoteOn(...)

Sends a note on message for the specified MIDI note number on the specified channel(s). The first parameter is the number. It can be a single value or an array of the following valid values:

  • A MIDI note number (integer between 0 and 127)

  • A note identifier (e.g. "C3", "G#4", "F-1", "Db7")

  • A Note object

    The execution of the note on command can be delayed by using the time property of the options parameter.

Note: As per the MIDI standard, a note on message with an attack velocity of 0 is functionally equivalent to a note off message.

Parameters

Signature: sendNoteOn(note, [options])

ParameterType(s)DefaultDescription
notenumber
Note
string
Array.<number>
Array.<Note>
Array.<string>
The note(s) to stop. The notes can be specified by using a MIDI note number (0 - 127), a note identifier (e.g. C3, G#4, F-1, Db7) or an array of the previous types. When using a note identifier, octave range must be between -1 and 9. The lowest note is C-1 (MIDI note number 0) and the highest note is G9 (MIDI note number 127).
[options]Object
{}
[options.channels]number
Array.<number>
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]The MIDI channel number (between 1 and 16) or an array of channel numbers to use. If no channel is specified, all channels will be used.
[options.attack]number
0.5The velocity at which to play the note (between 0 and 1). If the rawAttack option is also defined, rawAttack will have priority. An invalid velocity value will silently trigger the default of 0.5.
[options.rawAttack]number
64The velocity at which to release the note (between 0 and 127). If the attack option is also defined, rawAttack will have priority. An invalid velocity value will silently trigger the default of 64.
[options.time]number
string
(now)If time is a string prefixed with "+" and followed by a number, the message will be delayed by that many milliseconds. If the value is a positive number (DOMHighResTimeStamp), the operation will be scheduled for that time. The current time can be retrieved with WebMidi.time. If options.time is omitted, or in the past, the operation will be carried out as soon as possible.

Return Value

Returns: Output

Returns the Output object so methods can be chained.

.sendNrpnValue(...)

Sets a non-registered parameter to the specified value. The NRPN is selected by passing a two-position array specifying the values of the two control bytes. The value is specified by passing a 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].sendNrpnValue([1, 8], 123);

You probably want to 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].sendNrpnValue([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].sendNrpnValue([2, 63], [0, 10], 1);

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

Parameters

Signature: sendNrpnValue(parameter, [data], [options])

ParameterType(s)DefaultDescription
parameterArray.<number>
A two-position array specifying the two control bytes (0x63, 0x62) that identify the non-registered parameter.
[data]number
Array.<number>
[]An integer or an array of integers with a length of 1 or 2 specifying the desired data.
[options]Object
{}
[options.channels]number
Array.<number>
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]The MIDI channel number (between 1 and 16) or an array of channel numbers to use. If no channel is specified, all channels will be used.
[options.time]number
string
(now)If time is a string prefixed with "+" and followed by a number, the message will be delayed by that many milliseconds. If the value is a positive number (DOMHighResTimeStamp), the operation will be scheduled for that time. The current time can be retrieved with WebMidi.time. If options.time is omitted, or in the past, the operation will be carried out as soon as possible.

Return Value

Returns: Output

Returns the Output object so methods can be chained.

Throws:

  • RangeError : The control value must be between 0 and 127.
  • RangeError : The msb value must be between 0 and 127

.sendOmniMode(...)

Since: 3.0.0

Sets OMNI mode to on or off for the specified channel(s). MIDI's OMNI mode causes the instrument to respond to messages from all channels.

It should be noted that support for OMNI mode is not as common as it used to be.

Parameters

Signature: sendOmniMode([state], [options])

ParameterType(s)DefaultDescription
[state]boolean
Whether to activate OMNI mode (true) or not (false).
[options]Object
{}
[options.channels]number
Array.<number>
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]The MIDI channel number (between 1 and 16) or an array of channel numbers to use. If no channel is specified, all channels will be used.
[options.time]number
string
(now)If time is a string prefixed with "+" and followed by a number, the message will be delayed by that many milliseconds. If the value is a positive number (DOMHighResTimeStamp), the operation will be scheduled for that time. The current time can be retrieved with WebMidi.time. If options.time is omitted, or in the past, the operation will be carried out as soon as possible.

Return Value

Returns: Output

Returns the Output object so methods can be chained.

Throws:

  • TypeError : Invalid channel mode message name.
  • RangeError : Channel mode controller numbers must be between 120 and 127.
  • RangeError : Value must be an integer between 0 and 127.

.sendPitchBend(...)

Since: 3.0.0

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

The resulting bend is relative to the pitch bend range that has been defined. The range can be set with sendPitchBendRange(). So, for example, if the pitch bend range has been set to 12 semitones, using a bend value of -1 will bend the note 1 octave below its nominal value.

Parameters

Signature: sendPitchBend(value, [options])

ParameterType(s)DefaultDescription
valuenumber
Array.<number>
The intensity of the bend (between -1.0 and 1.0). A value of 0 means no bend. If an invalid value is specified, the nearest valid value will be used instead. If the rawValue option is set to true, the intensity of the bend can be defined by either using a single integer between 0 and 127 (MSB) or an array of two integers between 0 and 127 representing, respectively, the MSB (most significant byte) and the LSB (least significant byte). The MSB is expressed in semitones with 64 meaning no bend. A value lower than 64 bends downwards while a value higher than 64 bends upwards. The LSB is expressed in cents (1/100 of a semitone). An LSB of 64 also means no bend.
[options]object
{}
[options.channels]number
Array.<number>
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]The MIDI channel number (between 1 and 16) or an array of channel numbers to use. If no channel is specified, all channels will be used.
[options.rawValue]boolean
falseA boolean indicating whether the value should be considered as a float between -1.0 and 1.0 (default) or as raw integer between 0 and 127` (or an array of 2 integers if using both MSB and LSB).
[options.time]number
string
(now)If time is a string prefixed with "+" and followed by a number, the message will be delayed by that many milliseconds. If the value is a positive number (DOMHighResTimeStamp), the operation will be scheduled for that time. The current time can be retrieved with WebMidi.time. If options.time is omitted, or in the past, the operation will be carried out as soon as possible.

Return Value

Returns: Output

Returns the Output object so methods can be chained.

.sendPitchBendRange(...)

Since: 3.0.0

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 is specified by using the semitones and cents parameters. For example, setting the semitones parameter to 12 means that the pitch bend range will be 12 semitones above and below the nominal pitch.

Parameters

Signature: sendPitchBendRange([semitones], [cents], [options])

ParameterType(s)DefaultDescription
[semitones]number
0The desired adjustment value in semitones (between 0 and 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]number
0The desired adjustment value in cents (integer between 0 and 127).
[options]object
{}
[options.channels]number
Array.<number>
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]The MIDI channel number (between 1 and 16) or an array of channel numbers to use. If no channel is specified, all channels will be used.
[options.time]number
string
(now)If time is a string prefixed with "+" and followed by a number, the message will be delayed by that many milliseconds. If the value is a positive number (DOMHighResTimeStamp), the operation will be scheduled for that time. The current time can be retrieved with WebMidi.time. If options.time is omitted, or in the past, the operation will be carried out as soon as possible.

Return Value

Returns: Output

Returns the Output object so methods can be chained.

Throws:

  • RangeError : The msb value must be between 0 and 127.
  • RangeError : The lsb value must be between 0 and 127.

.sendPolyphonicMode(...)

Since: 3.0.0

Sets the polyphonic mode. In poly mode (usually the default), multiple notes can be played and heard at the same time. In mono mode, only one note will be heard at once even if multiple notes are being played.

Parameters

Signature: sendPolyphonicMode(mode, [options])

ParameterType(s)DefaultDescription
modestring
The mode to use: mono or poly.
[options]Object
{}
[options.channels]number
Array.<number>
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]The MIDI channel number (between 1 and 16) or an array of channel numbers to use. If no channel is specified, all channels will be used.
[options.time]number
string
(now)If time is a string prefixed with "+" and followed by a number, the message will be delayed by that many milliseconds. If the value is a positive number (DOMHighResTimeStamp), the operation will be scheduled for that time. The current time can be retrieved with WebMidi.time. If options.time is omitted, or in the past, the operation will be carried out as soon as possible.

Return Value

Returns: Output

Returns the Output object so methods can be chained.

.sendProgramChange(...)

Since: 3.0.0

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

Parameters

Signature: sendProgramChange([program], [options])

ParameterType(s)DefaultDescription
[program]number
0The MIDI patch (program) number (integer between 0 and 127).
[options]Object
{}
[options.channels]number
Array.<number>
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]The MIDI channel number (between 1 and 16) or an array of channel numbers to use. If no channel is specified, all channels will be used.
[options.time]number
string
(now)If time is a string prefixed with "+" and followed by a number, the message will be delayed by that many milliseconds. If the value is a positive number (DOMHighResTimeStamp), the operation will be scheduled for that time. The current time can be retrieved with WebMidi.time. If options.time is omitted, or in the past, the operation will be carried out as soon as possible.

Return Value

Returns: Output

Returns the Output object so methods can be chained.

Throws:

  • TypeError : Failed to execute 'send' on 'MIDIOutput': The value at index 1 is greater than 0xFF.

.sendReset(...)

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

Parameters

Signature: sendReset([options])

ParameterType(s)DefaultDescription
[options]object
{}
[options.time]number
string
(now)If time is a string prefixed with "+" and followed by a number, the message will be delayed by that many milliseconds. If the value is a positive number (DOMHighResTimeStamp), the operation will be scheduled for that time. The current time can be retrieved with WebMidi.time. If options.time is omitted, or in the past, the operation will be carried out as soon as possible.

Return Value

Returns: Output

Returns the Output object so methods can be chained.

.sendResetAllControllers(...)

Sends a reset all controllers channel mode message. This resets all controllers, such as the pitch bend, to their default value.

Parameters

Signature: sendResetAllControllers([options])

ParameterType(s)DefaultDescription
[options]Object
{}
[options.channels]number
Array.<number>
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]The MIDI channel number (between 1 and 16) or an array of channel numbers to use. If no channel is specified, all channels will be used.
[options.time]number
string
(now)If time is a string prefixed with "+" and followed by a number, the message will be delayed by that many milliseconds. If the value is a positive number (DOMHighResTimeStamp), the operation will be scheduled for that time. The current time can be retrieved with WebMidi.time. If options.time is omitted, or in the past, the operation will be carried out as soon as possible.

Return Value

Returns: Output

.sendRpnDecrement(...)

Decrements the specified MIDI registered parameter by 1. Here is the full list of parameter names that can be used with this method:

  • 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

Signature: sendRpnDecrement(parameter, [options])

ParameterType(s)DefaultDescription
parameterString
Array.<number>
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.
[options]Object
{}
[options.channels]number
Array.<number>
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]The MIDI channel number (between 1 and 16) or an array of channel numbers to use. If no channel is specified, all channels will be used.
[options.time]number
string
(now)If time is a string prefixed with "+" and followed by a number, the message will be delayed by that many milliseconds. If the value is a positive number (DOMHighResTimeStamp), the operation will be scheduled for that time. The current time can be retrieved with WebMidi.time. If options.time is omitted, or in the past, the operation will be carried out as soon as possible.

Return Value

Returns: Output

Returns the Output object so methods can be chained.

Throws:

  • TypeError The specified parameter is not available.

.sendRpnIncrement(...)

Increments the specified MIDI registered parameter by 1. Here is the full list of parameter names that can be used with this method:

  • 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

Signature: sendRpnIncrement(parameter, [options])

ParameterType(s)DefaultDescription
parameterString
Array.<number>
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.
[options]Object
{}
[options.channels]number
Array.<number>
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]The MIDI channel number (between 1 and 16) or an array of channel numbers to use. If no channel is specified, all channels will be used.
[options.time]number
string
(now)If time is a string prefixed with "+" and followed by a number, the message will be delayed by that many milliseconds. If the value is a positive number (DOMHighResTimeStamp), the operation will be scheduled for that time. The current time can be retrieved with WebMidi.time. If options.time is omitted, or in the past, the operation will be carried out as soon as possible.

Return Value

Returns: Output

Returns the Output object so methods can be chained.

.sendRpnValue(...)

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

MIDI registered parameters extend the original list of control change messages. The MIDI 1.0 specification lists only a limited number of them:

NumbersFunction
(0x00, 0x00)pitchbendrange
(0x00, 0x01)channelfinetuning
(0x00, 0x02)channelcoarsetuning
(0x00, 0x03)tuningprogram
(0x00, 0x04)tuningbank
(0x00, 0x05)modulationrange
(0x3D, 0x00)azimuthangle
(0x3D, 0x01)elevationangle
(0x3D, 0x02)gain
(0x3D, 0x03)distanceratio
(0x3D, 0x04)maximumdistance
(0x3D, 0x05)maximumdistancegain
(0x3D, 0x06)referencedistanceratio
(0x3D, 0x07)panspreadangle
(0x3D, 0x08)rollangle

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

Parameters

Signature: sendRpnValue(parameter, [data], [options])

ParameterType(s)DefaultDescription
parameterstring
Array.<number>
A string identifying the parameter's name (see above) or a two-position array specifying the two control bytes (e.g. [0x65, 0x64]) that identify the registered parameter.
[data]number
Array.<number>
[]A single integer or an array of integers with a maximum length of 2 specifying the desired data.
[options]object
{}
[options.channels]number
Array.<number>
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]The MIDI channel number (between 1 and 16) or an array of channel numbers to use. If no channel is specified, all channels will be used.
[options.time]number
string
(now)If time is a string prefixed with "+" and followed by a number, the message will be delayed by that many milliseconds. If the value is a positive number (DOMHighResTimeStamp), the operation will be scheduled for that time. The current time can be retrieved with WebMidi.time. If options.time is omitted, or in the past, the operation will be carried out as soon as possible.

Return Value

Returns: Output

Returns the Output object so methods can be chained.

.sendSongPosition(...)

Since: 3.0.0

Sends a song position MIDI message. 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

Signature: sendSongPosition([value], [options])

ParameterType(s)DefaultDescription
[value]number
0The MIDI beat to cue to (integer between 0 and 16383).
[options]object
{}
[options.time]number
string
(now)If time is a string prefixed with "+" and followed by a number, the message will be delayed by that many milliseconds. If the value is a positive number (DOMHighResTimeStamp), the operation will be scheduled for that time. The current time can be retrieved with WebMidi.time. If options.time is omitted, or in the past, the operation will be carried out as soon as possible.

Return Value

Returns: Output

Returns the Output object so methods can be chained.

.sendSongSelect(...)

Since: 3.0.0

Sends a song select MIDI message.

Parameters

Signature: sendSongSelect([value], [options])

ParameterType(s)DefaultDescription
[value]number
0The number of the song to select (integer between 0 and 127).
[options]object
{}
[options.time]number
string
(now)If time is a string prefixed with "+" and followed by a number, the message will be delayed by that many milliseconds. If the value is a positive number (DOMHighResTimeStamp), the operation will be scheduled for that time. The current time can be retrieved with WebMidi.time. If options.time is omitted, or in the past, the operation will be carried out as soon as possible.

Return Value

Returns: Output

Returns the Output object so methods can be chained.

Throws:

  • The song number must be between 0 and 127.

.sendStart(...)

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

Parameters

Signature: sendStart([options])

ParameterType(s)DefaultDescription
[options]object
{}
[options.time]number
string
(now)If time is a string prefixed with "+" and followed by a number, the message will be delayed by that many milliseconds. If the value is a positive number (DOMHighResTimeStamp), the operation will be scheduled for that time. The current time can be retrieved with WebMidi.time. If options.time is omitted, or in the past, the operation will be carried out as soon as possible.

Return Value

Returns: Output

Returns the Output object so methods can be chained.

.sendStop(...)

Sends a stop real-time message. This tells the device connected to this output to stop playback immediately (or at the scheduled time, if specified).

Parameters

Signature: sendStop([options])

ParameterType(s)DefaultDescription
[options]object
{}
[options.time]number
string
(now)If time is a string prefixed with "+" and followed by a number, the message will be delayed by that many milliseconds. If the value is a positive number (DOMHighResTimeStamp), the operation will be scheduled for that time. The current time can be retrieved with WebMidi.time. If options.time is omitted, or in the past, the operation will be carried out as soon as possible.

Return Value

Returns: Output

Returns the Output object so methods can be chained.

.sendSysex(...)

Sends a MIDI system exclusive (sysex) message. There are two categories of system exclusive messages: manufacturer-specific messages and universal messages. Universal messages are further divided into three subtypes:

  • Universal non-commercial (for research and testing): 0x7D
  • Universal non-realtime: 0x7E
  • Universal realtime: 0x7F

The method's first parameter (identification) identifies the type of message. If the value of identification is 0x7D (125), 0x7E (126) or 0x7F (127), the message will be identified as a universal non-commercial, universal non-realtime or universal realtime message (respectively).

If the identification value is an array or an integer between 0 and 124, it will be used to identify the manufacturer targeted by the message. The MIDI Manufacturers Association maintains a full list of Manufacturer ID Numbers.

The data parameter should only contain the data of the message. When sending out the actual MIDI message, WEBMIDI.js will automatically prepend the data with the sysex byte (0xF0) and the identification byte(s). It will also automatically terminate the message with the sysex end byte (0xF7).

To use the sendSysex() method, system exclusive message support must have been enabled. To do so, you must set the sysex option to true when calling WebMidi.enable():

WebMidi.enable({sysex: true})
.then(() => console.log("System exclusive messages are enabled");
Examples of manufacturer-specific system exclusive messages

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]);

In this case 0x42 is the ID of the manufacturer (Korg) and [0x1, 0x2, 0x3, 0x4, 0x5] is the data being sent.

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

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

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.

Example of universal system exclusive message

If you want to send a universal sysex message, simply assign the correct identification number in the first parameter. Number 0x7D (125) is for non-commercial, 0x7E (126) is for non-realtime and 0x7F (127) is for realtime.

So, for example, if you wanted to send an identity request non-realtime message (0x7E), you could use the following:

WebMidi.outputs[0].sendSysex(0x7E, [0x7F, 0x06, 0x01]);

For more details on the format of universal messages, consult the list of universal sysex messages.

Parameters

Signature: sendSysex(identification, [data], [options])

ParameterType(s)DefaultDescription
identificationnumber
Array.<number>
An unsigned integer or an array of three unsigned integers between 0 and 127 that either identify the manufacturer or sets the message to be a universal non-commercial message (0x7D), a universal non-realtime message (0x7E) or a universal realtime message (0x7F). The MIDI Manufacturers Association maintains a full list of Manufacturer ID Numbers.
[data]Array.<number>
Uint8Array
A Uint8Array or an array of unsigned integers between 0 and 127. This is the data you wish to transfer.
[options]object
{}
[options.time]number
string
(now)If time is a string prefixed with "+" and followed by a number, the message will be delayed by that many milliseconds. If the value is a positive number (DOMHighResTimeStamp), the operation will be scheduled for that time. The current time can be retrieved with WebMidi.time. If options.time is omitted, or in the past, the operation will be carried out as soon as possible.

Return Value

Returns: Output

Returns the Output object so methods can be chained.

Throws:

  • DOMException : Failed to execute 'send' on 'MIDIOutput': System exclusive message is not allowed.
  • TypeError : Failed to execute 'send' on 'MIDIOutput': The value at index x is greater than 0xFF.

.sendTimecodeQuarterFrame(...)

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

Signature: sendTimecodeQuarterFrame(value, [options])

ParameterType(s)DefaultDescription
valuenumber
The quarter frame message content (integer between 0 and 127).
[options]object
{}
[options.time]number
string
(now)If time is a string prefixed with "+" and followed by a number, the message will be delayed by that many milliseconds. If the value is a positive number (DOMHighResTimeStamp), the operation will be scheduled for that time. The current time can be retrieved with WebMidi.time. If options.time is omitted, or in the past, the operation will be carried out as soon as possible.

Return Value

Returns: Output

Returns the Output object so methods can be chained.

.sendTuneRequest(...)

Since: 3.0.0

Sends a MIDI tune request real-time message.

Parameters

Signature: sendTuneRequest([options])

ParameterType(s)DefaultDescription
[options]object
{}
[options.time]number
string
(now)If time is a string prefixed with "+" and followed by a number, the message will be delayed by that many milliseconds. If the value is a positive number (DOMHighResTimeStamp), the operation will be scheduled for that time. The current time can be retrieved with WebMidi.time. If options.time is omitted, or in the past, the operation will be carried out as soon as possible.

Return Value

Returns: Output

Returns the Output object so methods can be chained.

.sendTuningBank(...)

Since: 3.0.0

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

Signature: sendTuningBank([value], [options])

ParameterType(s)DefaultDescription
[value]number
0The desired tuning bank (integer between 0 and 127).
[options]Object
{}
[options.channels]number
Array.<number>
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]The MIDI channel number (between 1 and 16) or an array of channel numbers to use. If no channel is specified, all channels will be used.
[options.time]number
string
(now)If time is a string prefixed with "+" and followed by a number, the message will be delayed by that many milliseconds. If the value is a positive number (DOMHighResTimeStamp), the operation will be scheduled for that time. The current time can be retrieved with WebMidi.time. If options.time is omitted, or in the past, the operation will be carried out as soon as possible.

Return Value

Returns: Output

Returns the Output object so methods can be chained.

Throws:

  • RangeError : The bank value must be between 0 and 127.

.sendTuningProgram(...)

Since: 3.0.0

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

Signature: sendTuningProgram(value, [options])

ParameterType(s)DefaultDescription
valuenumber
The desired tuning program (integer between 0 and 127).
[options]Object
{}
[options.channels]number
Array.<number>
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]The MIDI channel number (between 1 and 16) or an array of channel numbers to use. If no channel is specified, all channels will be used.
[options.time]number
string
(now)If time is a string prefixed with "+" and followed by a number, the message will be delayed by that many milliseconds. If the value is a positive number (DOMHighResTimeStamp), the operation will be scheduled for that time. The current time can be retrieved with WebMidi.time. If options.time is omitted, or in the past, the operation will be carried out as soon as possible.

Return Value

Returns: Output

Returns the Output object so methods can be chained.

Throws:

  • RangeError : The program value must be between 0 and 127.

.stopNote(...)

Sends a note off message for the specified MIDI note number on the specified channel(s). The first parameter is the note to stop. It can be a single value or an array of the following valid values:

  • A MIDI note number (integer between 0 and 127)
  • A note identifier (e.g. "C3", "G#4", "F-1", "Db7")
  • A Note object

The execution of the note off command can be delayed by using the time property of the options parameter.

Parameters

Signature: stopNote(note, [options])

ParameterType(s)DefaultDescription
notenumber
Note
string
Array.<number>
Array.<Note>
Array.<string>
The note(s) to stop. The notes can be specified by using a MIDI note number (0 - 127), a note identifier (e.g. C3, G#4, F-1, Db7) or an array of the previous types. When using a note identifier, octave range must be between -1 and 9. The lowest note is C-1 (MIDI note number 0) and the highest note is G9 (MIDI note number 127).
[options]Object
{}
[options.channels]number
Array.<number>
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]The MIDI channel number (between 1 and 16) or an array of channel numbers to use. If no channel is specified, all channels will be used.
[options.release]number
0.5The velocity at which to release the note (between 0 and 1). If the rawRelease option is also defined, rawRelease will have priority. An invalid velocity value will silently trigger the default of 0.5.
[options.rawRelease]number
64The velocity at which to release the note (between 0 and 127). If the release option is also defined, rawRelease will have priority. An invalid velocity value will silently trigger the default of 64.
[options.time]number
string
(now)If time is a string prefixed with "+" and followed by a number, the message will be delayed by that many milliseconds. If the value is a positive number (DOMHighResTimeStamp), the operation will be scheduled for that time. The current time can be retrieved with WebMidi.time. If options.time is omitted, or in the past, the operation will be carried out as soon as possible.

Return Value

Returns: Output

Returns the Output object so methods can be chained.

.suspendEvent(...)

Suspends execution of all callbacks functions registered for the specified event type.

You can suspend execution of callbacks registered with EventEmitter.ANY_EVENT by passing EventEmitter.ANY_EVENT to suspendEvent(). Beware that this will not suspend all callbacks but only those registered with EventEmitter.ANY_EVENT. While this may seem counter-intuitive at first glance, it allows the selective suspension of global listeners while leaving other listeners alone. If you truly want to suspends all callbacks for a specific EventEmitter, simply set its eventsSuspended property to true.

Parameters

Signature: suspendEvent(event)

ParameterType(s)DefaultDescription
eventstring
Symbol
The event name (or EventEmitter.ANY_EVENT) for which to suspend execution of all callback functions.

.unsuspendEvent(...)

Resumes execution of all suspended callback functions registered for the specified event type.

You can resume execution of callbacks registered with EventEmitter.ANY_EVENT by passing EventEmitter.ANY_EVENT to unsuspendEvent(). Beware that this will not resume all callbacks but only those registered with EventEmitter.ANY_EVENT. While this may seem counter-intuitive, it allows the selective unsuspension of global listeners while leaving other callbacks alone.

Parameters

Signature: unsuspendEvent(event)

ParameterType(s)DefaultDescription
eventstring
Symbol
The event name (or EventEmitter.ANY_EVENT) for which to resume execution of all callback functions.

.waitFor(...)

Attributes: async

The waitFor() method is an async function which returns a promise. The promise is fulfilled when the specified event occurs. The event can be a regular event or EventEmitter.ANY_EVENT (if you want to resolve as soon as any event is emitted).

If the duration option is set, the promise will only be fulfilled if the event is emitted within the specified duration. If the event has not been fulfilled after the specified duration, the promise is rejected. This makes it super easy to wait for an event and timeout after a certain time if the event is not triggered.

Parameters

Signature: waitFor(event, [options])

ParameterType(s)DefaultDescription
eventstring
Symbol
The event to wait for
[options]Object
{}
[options.duration]number
InfinityThe number of milliseconds to wait before the promise is automatically rejected.

Events

closed

Event emitted when the Output has been closed by calling the close() method.

Event Properties

PropertyTypeDescription
timestampnumberThe moment (DOMHighResTimeStamp) when the event occurred (in milliseconds since the navigation start of the document).
typestring"closed"
targetOutputThe object to which the listener was originally added (Output).
portOutputThe port that was closed

disconnected

Event emitted when the Output becomes unavailable. This event is typically fired when the MIDI device is unplugged.

Event Properties

PropertyTypeDescription
timestampnumberThe moment (DOMHighResTimeStamp0 when the event occurred (in milliseconds since the navigation start of the document).
typestring"disconnected"
targetOutputThe object to which the listener was originally added (Output).
portobjectObject with properties describing the Output that was disconnected. This is not the actual Output as it is no longer available.

opened

Event emitted when the Output has been opened by calling the open() method.

Event Properties

PropertyTypeDescription
timestampnumberThe moment (DOMHighResTimeStamp) when the event occurred (in milliseconds since the navigation start of the document).
typestring"opened"
targetOutputThe object to which the listener was originally added (Output).
portOutputThe port that was opened