WebMidi Class
The WebMidi
object makes it easier to work with the Web MIDI API. Basically, it
simplifies two things: sending and receiving MIDI messages.
To send MIDI messages, you simply need to pick the appropriate method 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(2, 76, 0.5);
});
The code above, calls the WebMidi.enable()
method. Upon success, this method
executes the handler specified as a parameter. IThe handler, in this case, sends a
'noteon' MIDI message to the device on channel 2 so it plays note number 76 at half
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.addEventListener('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!
Item Index
Methods
- addEventListener static
- enable static
- hasEventListener static
- noteNameToNumber static
- playNote static
- removeEventListener static
- send static
- sendChannelAftertouch static
- sendChannelMode static
- sendControlChange static
- sendKeyAftertouch static
- sendPitchBend static
- sendProgramChange static
- sendSystemMessage static
- sendSystemMessage static
- stopNote static
Methods
addEventListener
-
type
-
listener
-
[channel=all]
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) but this can be changed by passing one or more specific channel(s) as the 3rd parameter.
Here is a list of events that are dispatched by the WebMidi
object and that can be
listened to.
Channel-specific MIDI events:
- noteoff
- noteon
- keyaftertouch
- controlchange
- channelmode
- programchange
- channelaftertouch
- pitchbend
System-wide MIDI events:
- sysex
- timecode
- songposition
- songselect
- tuningrequest
- clock
- start
- continue
- stop
- activesensing
- reset
- unknownsystemmessage
Interface event:
- statechange
For system-wide events, the specified channel (if any) will be silently ignored. The value "all" will be used instead.
Parameters:
Returns:
Returns the WebMidi
object so methods can
be chained.
Throws:
The specified event type is not supported.
enable
-
successHandler
-
[errorHandler]
-
[sysex=false]
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.
Depending on the host environment, calling this method may prompt the user for authorization.
hasEventListener
-
type
-
listener
-
[channel=all]
Checks if the specified event type is already defined to trigger the listener
function on the specified channel. If the special value "all" is used for the
channel, the function will return true
only if all channels have the listener
defined.
For system-wide events (onstatechange
, sysex
, start
, etc.), the channel
parameter is silently ignored.
Parameters:
Returns:
Boolean value indicating whether or not the channel(s) already have this listener defined.
Throws:
WebMidi must be enabled before checking event listeners.
noteNameToNumber
-
name
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 5: C5, G4, D#-1, F0, etc.
Parameters:
-
name
StringThe name of the note in the form of a letter followed by an octave number (between -2 and 5).
Returns:
The MIDI note number.
playNote
-
channel
-
[note=60]
-
[velocity=0.5]
-
[duration=undefined]
-
[delay=0]
Requests the playback of a single note or multiple notes on the specified channel.
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:
-
channel
UintThe MIDI channel number (between 0 and 15). You can view available channels in the
WebMidi.outputs
array. -
[note=60]
Array | Uint | String optionalThe note to play or an array of notes to play. The notes can be specified in one of two ways. The first way is by using the MIDI note number (an integer between 0 and 127). The second way is by using the note name followed by the octave (C3, G#4, F-1). The octave range should be between -3 and 5.
-
[velocity=0.5]
Number optionalThe velocity at which to play the note (between 0 and 1).
-
[duration=undefined]
Int optionalThe number of milliseconds to wait before sending a matching note off event. If left undefined, only a note on is sent.
-
[delay=0]
Int optionalThe number of milliseconds to wait before actually sending the
note on
command (using a negative number or 0 will send the command immediately).
Returns:
Returns the WebMidi
object so methods can be
chained.
Throws:
The velocity must be a decimal number between 0 and 1.
removeEventListener
-
type
-
listener
-
[channel=all]
Removes the specified listener from the requested channel(s). If the special value "all" is used for the channel parameter, the function will remove the listener from all channels.
For system-wide events (onstatechange
, sysex
, start
, etc.), the channel
parameter is silently ignored.
Parameters:
Throws:
WebMidi must be enabled before removing event listeners.
send
-
channel
-
command
-
[data=[]]
-
[timestamp=0]
Sends a MIDI message to one or all channels at the specified timestamp. Unless, you
are familiar with the details of the MIDI message format, you should not use this
method directly. Instead, use one of the helper methods: playNote()
, stopNote()
,
sendControlChange()
, sendSystemMessage()
, etc.
Parameters:
-
channel
"all" | UintThe MIDI channel number (between 0 and 15) or the string "all". You can view the available channels in
WebMidi.outputs
. -
command
UintThe command number. Check out the constants in the WebMidi object for a list of available commands (0-255).
-
[data=[]]
Array optionalArray of data bytes. The number of data bytes varies depending on the command.
-
[timestamp=0]
DOMHighResTimeStamp optionalThe timestamp at which to schedule the event. You can use
WebMidi.time
to retrieve the current timestamp.
Returns:
Returns the WebMidi
object so methods can be
chained.
Throws:
The command must be an integer between 0 and 255.
sendChannelAftertouch
-
channel
-
[pressure=0]
-
[delay=0]
Sends a MIDI channel aftertouch
message to the specified channel. For key-specific
aftertouch, instead use sendKeyAftertouch()
.
Parameters:
-
channel
UintThe MIDI channel number (between 0 and 15). You can view available channels in the
WebMidi.outputs
array. -
[pressure=0]
Number optionalThe pressure level (between 0 and 1)
-
[delay=0]
Int optionalThe number of milliseconds to wait before actually sending the
key aftertouch
command (using a negative number or 0 will send the command immediately).
Returns:
Returns the WebMidi
object so methods can be chained.
Throws:
WebMidi must be enabled before sending messages.
sendChannelMode
-
channel
-
command
-
value
-
[delay=0]
Sends a MIDI channel mode
message to the specified channel.
Parameters:
-
channel
UintThe MIDI channel number (between 0 and 15). You can view available channels in the
WebMidi.outputs
array. -
command
UintThe MIDI channel mode command (120-127)
-
value
UintThe value to send (0-127)
-
[delay=0]
Int optionalThe number of milliseconds to wait before actually sending the
key aftertouch
command (using a negative number or 0 will send the command immediately).
Returns:
Returns the WebMidi
object so methods can be chained.
Throws:
Value must be between 0 and 127.
sendControlChange
-
channel
-
controller
-
value
-
[delay=0]
Sends a MIDI control change
message to the specified channel.
Parameters:
-
channel
UintThe MIDI channel number (between 0 and 15). You can view available channels in the
WebMidi.outputs
array. -
controller
UintThe MIDI controller number (0-119)
-
value
UintThe value to send (0-127).
-
[delay=0]
Int optionalThe number of milliseconds to wait before actually sending the
key aftertouch
command (using a negative number or 0 will send the command immediately).
Returns:
Returns the WebMidi
object so methods can be chained.
Throws:
Value must be between 0 and 127.
sendKeyAftertouch
-
channel
-
note
-
[pressure=0]
-
[delay=0]
Sends a MIDI key aftertouch
message to the specified channel. This is a
key-specific aftertouch. For a channel-wide aftertouch message, use
sendChannelAftertouch()
.
Parameters:
-
channel
UintThe MIDI channel number (between 0 and 15). You can view available channels in the
WebMidi.outputs
array. -
note
UintThe MIDI number of the note whose pressure data is being sent (0-127).
-
[pressure=0]
Number optionalThe pressure level to send (between 0 and 1)
-
[delay=0]
Int optionalThe number of milliseconds to wait before actually sending the
key aftertouch
command (using a negative number or 0 will send the command immediately).
Returns:
Returns the WebMidi
object so methods can be chained.
Throws:
The note number must be between 0 and 127.
sendPitchBend
-
channel
-
[level=-1]
-
[delay=0]
Sends a MIDI pitch bend
message to the specified channel.
Parameters:
-
channel
UintThe MIDI channel number (between 0 and 15). You can view available channels in the
WebMidi.outputs
array. -
[level=-1]
Number optionalThe intensity level of the bend (between -1 and 1)
-
[delay=0]
Int optionalThe number of milliseconds to wait before actually sending the
key aftertouch
command (using a negative number or 0 will send the command immediately).
Returns:
Returns the WebMidi
object so methods can be chained.
Throws:
Pitch bend value must be between -1 and 1.
sendProgramChange
-
channel
-
program
-
[delay=0]
Sends a MIDI program change
message to the specified channel.
Parameters:
-
channel
UintThe MIDI channel number (between 0 and 15). You can view available channels in the
WebMidi.outputs
array. -
program
UintThe MIDI patch (program) number (0-127)
-
[delay=0]
Int optionalThe number of milliseconds to wait before actually sending the
key aftertouch
command (using a negative number or 0 will send the command immediately).
Returns:
Returns the WebMidi
object so methods can be chained.
Throws:
Program numbers must be between 0 and 127.
sendSystemMessage
-
manufacturer
-
[data=[]]
-
[delay=0]
Sends a system exclusive message to all connected devices. The message will automatically be properly terminated. It is generally suggested to keep system exclusive messages to 64Kb or less.
Parameters:
-
manufacturer
Uint | ArrayA uint or an array of three uints between 0 and 127 that identifies the targeted manufacturer.
-
[data=[]]
Array optionalAn array of uints between 0 and 127. This is the data you wish to transfer.
-
[delay=0]
Uint optionalThe number of milliseconds to wait before actually sending the command (using 0 will send the command immediately).
Returns:
Returns the WebMidi
object so methods can be
chained.
Throws:
WebMidi must be enabled sending messages.
sendSystemMessage
-
command
-
[data=[]]
-
[delay=0]
Sends a MIDI real-time or common system message to all available outputs. The available messages are as follows:
System common messages:
sysex timecode songposition songselect tuningrequest sysexend
System real-time messages:
clock start continue stop activesensing reset
Parameters:
-
command
StringA string representing the command to send. The available system commands are: sysex, timecode, songposition, songselect, tuningrequest, sysexend, clock, start, continue, stop, activesensing and reset.
-
[data=[]]
Array optionalAn array of data bytes to insert in the message. The number of data bytes varies depending on the command.
-
[delay=0]
Uint optionalThe number of milliseconds to wait before actually sending the command (using 0 will send the command immediately).
Returns:
Returns the WebMidi
object so methods can be chained.
Throws:
The requested system command is not supported.
stopNote
-
channel
-
[note=60]
-
[velocity=0.5]
-
[delay=0]
Sends a MIDI note off
message to the specified channel for a single note or
multiple notes. You can delay the execution of the note off
command by using the
delay
parameter (milliseconds).
Parameters:
-
channel
UintThe MIDI channel number (between 0 and 15). You can view available channels in the
WebMidi.outputs
array. -
[note=60]
Array | Uint | String optionalThe note or an array of notes to stop. The notes can be specified in one of two ways. The first way is by using the MIDI note number (an integer between 0 and 127). The second way is by using the note name followed by the octave (C3, G#4, F-1). The octave range should be between -3 and 5.
-
[velocity=0.5]
Number optionalThe velocity at which to release the note (between 0 and 1).
-
[delay=0]
Int optionalThe number of milliseconds to wait before actually sending the
note off
message (using a negative number or 0 will stop the note immediately).
Returns:
Returns the WebMidi
object so methods can be
chained.
Throws:
The release velocity must be a decimal number between 0 and 1.
Properties
connected
Boolean
static
[read-only] Indicates whether the interface to the host's MIDI subsystem is still active.
inputs
MIDIOutput
static
[read-only] An array of all currently available MIDI outputs.
supported
Boolean
static
[read-only] Indicates whether the browser supports the Web MIDI API or not.
time
DOMHighResTimeStamp
static
[read-only] Current MIDI performance time in milliseconds. This can be used to queue events in the future.
Events
activesensing
Event emitted when a system active sensing MIDI message has been received.
Event Payload:
-
event
Object-
target
MIDIInputThe target MIDI input where the event occurred.
-
data
Uint8ArrayThe raw MIDI message as an array of 8 bit values.
-
receivedTime
NumberThe time when the event occurred (in milliseconds since start).
-
timeStamp
UintThe timestamp when the event occurred (in milliseconds since the epoch).
-
type
StringThe type of event that occurred.
-
channelaftertouch
Event emitted when a channel-wide aftertouch MIDI message has been received on a specific channel.
Event Payload:
-
event
Object-
target
MIDIInputThe target MIDI input where the event occurred.
-
data
Uint8ArrayThe raw MIDI message as an array of 8 bit values.
-
receivedTime
NumberThe time when the event occurred (in milliseconds since start).
-
timeStamp
UintThe timestamp when the event occurred (in milliseconds since the epoch).
-
channel
UintThe channel where the event occurred (between 0 and 15).
-
type
StringThe type of event that occurred.
-
value
NumberThe aftertouch value received (between 0 and 1).
-
channelmode
Event emitted when a channel mode MIDI message has been received on a specific channel.
Event Payload:
-
event
Object-
target
MIDIInputThe target MIDI input where the event occurred.
-
data
Uint8ArrayThe raw MIDI message as an array of 8 bit values.
-
receivedTime
NumberThe time when the event occurred (in milliseconds since start).
-
timeStamp
UintThe timestamp when the event occurred (in milliseconds since the epoch).
-
channel
UintThe channel where the event occurred (between 0 and 15).
-
type
StringThe type of event that occurred.
-
controller
Object-
number
UintThe number of the controller. -
name
StringThe number of the controller.
-
-
value
UintThe value received (between 0 and 127).
-
clock
Event emitted when a system timing clock MIDI message has been received.
Event Payload:
-
event
Object-
target
MIDIInputThe target MIDI input where the event occurred.
-
data
Uint8ArrayThe raw MIDI message as an array of 8 bit values.
-
receivedTime
NumberThe time when the event occurred (in milliseconds since start).
-
timeStamp
UintThe timestamp when the event occurred (in milliseconds since the epoch).
-
type
StringThe type of event that occurred.
-
continue
Event emitted when a system continue MIDI message has been received.
Event Payload:
-
event
Object-
target
MIDIInputThe target MIDI input where the event occurred.
-
data
Uint8ArrayThe raw MIDI message as an array of 8 bit values.
-
receivedTime
NumberThe time when the event occurred (in milliseconds since start).
-
timeStamp
UintThe timestamp when the event occurred (in milliseconds since the epoch).
-
type
StringThe type of event that occurred.
-
controlchange
Event emitted when a control change MIDI message has been received on a specific channel.
Event Payload:
-
event
Object-
target
MIDIInputThe target MIDI input where the event occurred.
-
data
Uint8ArrayThe raw MIDI message as an array of 8 bit values.
-
receivedTime
NumberThe time when the event occurred (in milliseconds since start).
-
timeStamp
UintThe timestamp when the event occurred (in milliseconds since the epoch).
-
channel
UintThe channel where the event occurred (between 0 and 15).
-
type
StringThe type of event that occurred.
-
controller
Object-
number
UintThe number of the controller. -
name
StringThe number of the controller.
-
-
value
UintThe value received (between 0 and 127).
-
keyaftertouch
Event emitted when a key-specific aftertouch MIDI message has been received on a specific channel.
Event Payload:
-
event
Object-
target
MIDIInputThe target MIDI input where the event occurred.
-
data
Uint8ArrayThe raw MIDI message as an array of 8 bit values.
-
receivedTime
NumberThe time when the event occurred (in milliseconds since start).
-
timeStamp
UintThe timestamp when the event occurred (in milliseconds since the epoch).
-
channel
UintThe channel where the event occurred (between 0 and 15).
-
type
StringThe type of event that occurred.
-
note
Object-
number
UintThe MIDI note number. -
name
StringThe usual note name (C, C#, D, D#, etc.). -
octave
UintThe octave (between -3 and 5).
-
-
value
NumberThe aftertouch amount (between 0 and 1).
-
noteoff
Event emitted when a note off MIDI message has been received on a specific channel.
Event Payload:
-
event
Object-
target
MIDIInputThe target MIDI input where the event occurred.
-
data
Uint8ArrayThe raw MIDI message as an array of 8 bit values.
-
receivedTime
NumberThe time when the event occurred (in milliseconds since start).
-
timeStamp
UintThe timestamp when the event occurred (in milliseconds since the epoch).
-
channel
UintThe channel where the event occurred (between 0 and 15).
-
type
StringThe type of event that occurred.
-
note
Object-
number
UintThe MIDI note number. -
name
StringThe usual note name (C, C#, D, D#, etc.). -
octave
UintThe octave (between -3 and 5).
-
-
velocity
NumberThe release velocity (between 0 and 1).
-
noteon
Event emitted when a note on MIDI message has been received on a specific channel.
Event Payload:
-
event
Object-
target
MIDIInputThe target MIDI input where the event occurred.
-
data
Uint8ArrayThe raw MIDI message as an array of 8 bit values.
-
receivedTime
NumberThe time when the event occurred (in milliseconds since start).
-
timeStamp
UintThe timestamp when the event occurred (in milliseconds since the epoch).
-
channel
UintThe channel where the event occurred (between 0 and 15).
-
type
StringThe type of event that occurred.
-
note
Object-
number
UintThe MIDI note number. -
name
StringThe usual note name (C, C#, D, D#, etc.). -
octave
UintThe octave (between -3 and 5).
-
-
velocity
NumberThe attack velocity (between 0 and 1).
-
pitchbend
Event emitted when a pitch bend MIDI message has been received on a specific channel.
Event Payload:
-
event
Object-
target
MIDIInputThe target MIDI input where the event occurred.
-
data
Uint8ArrayThe raw MIDI message as an array of 8 bit values.
-
receivedTime
NumberThe time when the event occurred (in milliseconds since start).
-
timeStamp
UintThe timestamp when the event occurred (in milliseconds since the epoch).
-
channel
UintThe channel where the event occurred (between 0 and 15).
-
type
StringThe type of event that occurred.
-
value
NumberThe pitch bend value received (between -1 and 1).
-
programchange
Event emitted when a program change MIDI message has been received on a specific channel.
Event Payload:
-
event
Object-
target
MIDIInputThe target MIDI input where the event occurred.
-
data
Uint8ArrayThe raw MIDI message as an array of 8 bit values.
-
receivedTime
NumberThe time when the event occurred (in milliseconds since start).
-
timeStamp
UintThe timestamp when the event occurred (in milliseconds since the epoch).
-
channel
UintThe channel where the event occurred (between 0 and 15).
-
type
StringThe type of event that occurred.
-
value
UintThe value received (between 0 and 127).
-
reset
Event emitted when a system reset MIDI message has been received.
Event Payload:
-
event
Object-
target
MIDIInputThe target MIDI input where the event occurred.
-
data
Uint8ArrayThe raw MIDI message as an array of 8 bit values.
-
receivedTime
NumberThe time when the event occurred (in milliseconds since start).
-
timeStamp
UintThe timestamp when the event occurred (in milliseconds since the epoch).
-
type
StringThe type of event that occurred.
-
songposition
Event emitted when a system song position pointer MIDI message has been received.
Event Payload:
-
event
Object-
target
MIDIInputThe target MIDI input where the event occurred.
-
data
Uint8ArrayThe raw MIDI message as an array of 8 bit values.
-
receivedTime
NumberThe time when the event occurred (in milliseconds since start).
-
timeStamp
UintThe timestamp when the event occurred (in milliseconds since the epoch).
-
type
StringThe type of event that occurred.
-
songselect
Event emitted when a system song select MIDI message has been received.
Event Payload:
-
event
Object-
target
MIDIInputThe target MIDI input where the event occurred.
-
data
Uint8ArrayThe raw MIDI message as an array of 8 bit values.
-
receivedTime
NumberThe time when the event occurred (in milliseconds since start).
-
timeStamp
UintThe timestamp when the event occurred (in milliseconds since the epoch).
-
type
StringThe type of event that occurred.
-
song
StringSong (or sequence) number to select.
-
start
Event emitted when a system start MIDI message has been received.
Event Payload:
-
event
Object-
target
MIDIInputThe target MIDI input where the event occurred.
-
data
Uint8ArrayThe raw MIDI message as an array of 8 bit values.
-
receivedTime
NumberThe time when the event occurred (in milliseconds since start).
-
timeStamp
UintThe timestamp when the event occurred (in milliseconds since the epoch).
-
type
StringThe type of event that occurred.
-
statechange
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 specific MIDI channel, it is intended to be interface-wide. If a channel is specified, it will be silently ignored.
stop
Event emitted when a system stop MIDI message has been received.
Event Payload:
-
event
Object-
target
MIDIInputThe target MIDI input where the event occurred.
-
data
Uint8ArrayThe raw MIDI message as an array of 8 bit values.
-
receivedTime
NumberThe time when the event occurred (in milliseconds since start).
-
timeStamp
UintThe timestamp when the event occurred (in milliseconds since the epoch).
-
type
StringThe type of event that occurred.
-
sysex
Event emitted when a system exclusive MIDI message has been received.
Event Payload:
-
event
Object-
target
MIDIInputThe target MIDI input where the event occurred.
-
data
Uint8ArrayThe raw MIDI message as an array of 8 bit values.
-
receivedTime
NumberThe time when the event occurred (in milliseconds since start).
-
timeStamp
UintThe timestamp when the event occurred (in milliseconds since the epoch).
-
type
StringThe type of event that occurred.
-
timecode
Event emitted when a system MIDI time code quarter frame message has been received.
Event Payload:
-
event
Object-
target
MIDIInputThe target MIDI input where the event occurred.
-
data
Uint8ArrayThe raw MIDI message as an array of 8 bit values.
-
receivedTime
NumberThe time when the event occurred (in milliseconds since start).
-
timeStamp
UintThe timestamp when the event occurred (in milliseconds since the epoch).
-
type
StringThe type of event that occurred.
-
tuningrequest
Event emitted when a system tune request MIDI message has been received.
Event Payload:
-
event
Object-
target
MIDIInputThe target MIDI input where the event occurred.
-
data
Uint8ArrayThe raw MIDI message as an array of 8 bit values.
-
receivedTime
NumberThe time when the event occurred (in milliseconds since start).
-
timeStamp
UintThe timestamp when the event occurred (in milliseconds since the epoch).
-
type
StringThe type of event that occurred.
-
unknownsystemmessage
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-
target
MIDIInputThe target MIDI input where the event occurred.
-
data
Uint8ArrayThe raw MIDI message as an array of 8 bit values.
-
receivedTime
NumberThe time when the event occurred (in milliseconds since start).
-
timeStamp
UintThe timestamp when the event occurred (in milliseconds since the epoch).
-
type
StringThe type of event that occurred.
-