WebMidi Class
The WebMidi
object makes it easier to work with the Web MIDI API. Basically, it simplifies
two things: sending outgoing MIDI messages and reacting to incoming MIDI messages.
Sending MIDI messages is done via an Output
object. All available outputs can be accessed in
the WebMidi.outputs
array. There is one Output
object for each output port available on
your system. Similarly, reacting to MIDI messages as they are coming in is simply a matter of
adding a listener to an Input
object. Similarly, all inputs can be found in the
WebMidi.inputs
array.
Please note that a single hardware device might create more than one input and/or output ports.
Sending messages
To send MIDI messages, you simply need to call the desired method (playNote()
,
sendPitchBend()
, stopNote()
, etc.) from an Output
object and pass in the appropriate
parameters. All the native MIDI communication will be handled for you. The only additional
thing that needs to be done is to first enable WebMidi
. Here is an example:
WebMidi.enable(function(err) {
if (err) console.log("An error occurred", err);
WebMidi.outputs[0].playNote("C3");
});
The code above, calls the WebMidi.enable()
method. Upon success, this method executes the
callback function specified as a parameter. In this case, the callback calls the playnote()
function to play a 3rd octave C on the first available output port.
Receiving messages
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, here's how to listen for pitch bend events on the first input port:
WebMidi.enable(function(err) {
if (err) console.log("An error occurred", err);
WebMidi.inputs[0].addListener('pitchbend', "all", function(e) {
console.log("Pitch value: " + e.value);
});
});
As you can see, this library is much easier to use than the native Web MIDI API. No need to manually craft or decode binary MIDI messages anymore!
Item Index
Methods
- _createInput static
- _createOutput static
- _onInterfaceStateChange static
- _processStateChange static
- _resetInterfaceUserHandlers static
- _updateInputs static
- _updateInputsAndOutputs static
- _updateOutputs static
- addListener static
- disable static
- enable static
- getInputById static
- getInputByName static
- getOutputById static
- getOutputByName static
- guessNoteNumber static
- hasListener static
- noteNameToNumber static
- removeListener static
Properties
- enabled static
- inputs static
- MIDI_CHANNEL_MESSAGES static
- MIDI_CHANNEL_MODE_MESSAGES static
- MIDI_CONTROL_CHANGE_MESSAGES static
- MIDI_REGISTERED_PARAMETER static
- MIDI_SYSTEM_MESSAGES static
- outputs static
- supported static
- sysexEnabled static
- time static
Events
Methods
_createInput
()
protected
static
_createOutput
()
protected
static
_onInterfaceStateChange
()
protected
static
_processStateChange
()
protected
static
_resetInterfaceUserHandlers
()
protected
static
_updateInputs
()
protected
static
_updateInputsAndOutputs
()
protected
static
_updateOutputs
()
protected
static
addListener
-
type
-
listener
Adds an event listener on the WebMidi
object that will trigger a function callback when the
specified event happens.
WebMidi must be enabled before adding event listeners.
Currently, only one event is being dispatched by the WebMidi
object:
- WebMidi/statechange:event
Parameters:
Returns:
Returns the WebMidi
object so methods can be chained.
Throws:
The 'listener' parameter must be a function.
disable
()
static
Completely disables WebMidi
by unlinking the MIDI subsystem's interface and destroying all
Input
and Output
objects that may be available. This also means that any listener that may
have been defined on Input
or Output
objects will be destroyed.
enable
-
[callback]
-
[sysex=false]
Checks if the Web MIDI API is available and then tries to connect to the host's MIDI subsystem.
This is an asynchronous operation. When it's done, the specified handler callback will be
executed. If an error occurred, the callback function will receive an Error
object as its
sole parameter.
To enable the use of system exclusive messages, the sysex
parameter should be set to true.
However, under some environments (e.g. Jazz-Plugin), the sysex parameter is ignored and sysex
is always enabled.
Parameters:
Throws:
Error Jazz-Plugin must be installed to use WebMIDIAPIShim.
getInputById
-
id
Returns an Input
object representing the input port with the specified id.
Please note that the IDs change from one host to another. For example, Chrome does not use the
same kind of IDs as the Jazz-Plugin.
Parameters:
-
id
StringThe id of the port. IDs can be viewed by looking at the
WebMidi.inputs
array.
Returns:
A MIDIInput port matching the specified id. If no matching port
can be found, the method returns false
.
getInputByName
-
name
Returns the first MIDI Input
whose name contains the specified string.
Please note that the port names change from one host to another. For example, Chrome does not report port names in the same way as the Jazz-Plugin does.
Parameters:
-
name
StringThe name of a MIDI input port such as those visible in the
WebMidi.inputs
array.
Returns:
The Input
that was found or false
if no input matched the specified
name.
Throws:
TypeError The name must be a string.
getOutputById
-
id
Returns an Output
object representing the output port matching the specified id.
Please note that the IDs change from one host to another. For example, Chrome does not use the
same kind of IDs as the Jazz-Plugin.
Parameters:
-
id
StringThe id of the port. Ids can be viewed by looking at the
WebMidi.outputs
array.
Returns:
A MIDIOutput port matching the specified id. If no matching
port can be found, the method returns false
.
getOutputByName
-
name
Returns the first MIDI Output
that matches the specified name.
Please note that the port names change from one host to another. For example, Chrome does not report port names in the same way as the Jazz-Plugin does.
Parameters:
-
name
StringThe name of a MIDI output port such as those visible in the
WebMidi.outputs
array.
Returns:
The Output
that was found or false
if no output matched the
specified name.
Throws:
Error WebMidi is not enabled.
guessNoteNumber
-
input
Returns a valid MIDI note number given the specified input. The input can be a note name (C3, F#4, D-2, G8, etc.) or an int between 0 and 127.
Parameters:
Returns:
A valid MIDI note number (0-127).
Throws:
Invalid note number.
hasListener
-
type
-
listener
Checks if the specified event type is already defined to trigger the specified listener function.
Parameters:
Returns:
Boolean value indicating whether or not a callback is already defined for this event type.
Throws:
The specified event type is not supported.
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 8. The name can also optionally include a sharp "#" or double sharp "##" symbol and a flat "b" or double flat "bb" symbol: C5, G4, D#-1, F0, Gb7, Eb-1, Abb4, B##6, etc.
The lowest note is C-2 (MIDI note number 0) and the highest note is G8 (MIDI note number 127).
Parameters:
-
name
StringThe name of the note in the form of a letter, followed by an optional "#", "##", "b" or "bb" followed by the octave number (between -2 and 8).
Returns:
The MIDI note number (between 0 and 127)
Throws:
Invalid note name or note outside valid range.
removeListener
-
[type]
-
[listener]
Removes the specified listener(s). If the listener
parameter is left undefined, all listeners
for the specified type
will be removed. If both the listener
and the type
parameters are
omitted, all listeners attached to the WebMidi
object will be removed.
Parameters:
Returns:
The WebMidi
object for easy method chaining.
Throws:
The specified event type is not supported.
Properties
enabled
Boolean
static
[read-only] Indicates whether the interface to the host's MIDI subsystem is currently enabled.
MIDI_CHANNEL_MESSAGES
Object
static
[read-only] List of valid MIDI channel messages and matching hexadecimal values.
MIDI_CHANNEL_MODE_MESSAGES
Object
static
[read-only] List of MIDI channel mode messages as defined in the official MIDI specification.
MIDI_CONTROL_CHANGE_MESSAGES
Object
static
[read-only] List of MIDI control change messages
valid MIDI registered parameterS and their matching pair of hexadecimal values. MIDI registered parameters extend the original list of control change messages. Currently, there are only a limited number of them.
MIDI_REGISTERED_PARAMETER
Object
static
[read-only] List of valid MIDI registered parameters and their matching pair of hexadecimal values. MIDI registered parameters extend the original list of control change messages. Currently, there are only a limited number of them.
MIDI_SYSTEM_MESSAGES
Object
static
[read-only] List of valid MIDI system messages and matching hexadecimal values.
Note: values 249 and 253 are actually dispatched by the Web MIDI API but I do not know what they are used for. They are not part of the online MIDI 1.0 spec.
supported
Boolean
static
[read-only] Indicates whether the environment supports the Web MIDI API or not.
Note: in environments that do not offer built-in MIDI support, this will report true if the
navigator.requestMIDIAccess
function is available. For example, if you have installed
WebMIDIAPIShim but no plugin, this property will be true even though actual support might
not be there.
sysexEnabled
Boolean
static
[read-only] Indicates whether the interface to the host's MIDI subsystem is currently active.
time
DOMHighResTimeStamp
static
[read-only] Current MIDI performance time in milliseconds. This can be used to queue events in the future.
Events
connected
Event emitted when a MIDI port becomes available. This event is typically fired whenever a MIDI device is plugged in. Please note that it may fire several times if a device possesses multiple input/output ports.
Event Payload:
-
event
Object-
timestamp
NumberThe timestamp when the event occurred (in milliseconds since the epoch).
-
type
StringThe type of event that occurred.
-
id
StringThe ID of the device that triggered the event.
-
manufacturer
StringThe manufacturer of the device that triggered the event.
-
name
StringThe name of the device that triggered the event.
-
output
StringThe
Input
orOutput
object that triggered the event.
-
disconnected
Event emitted when a MIDI port becomes unavailable. This event is typically fired whenever a MIDI device is unplugged. Please note that it may fire several times if a device possesses multiple input/output ports.
Event Payload:
-
event
Object-
timestamp
NumberThe timestamp when the event occurred (in milliseconds since the epoch).
-
type
StringThe type of event that occurred.
-
id
StringThe ID of the device that triggered the event.
-
manufacturer
StringThe manufacturer of the device that triggered the event.
-
name
StringThe name of the device that triggered the event.
-
output
StringThe
Input
orOutput
object that triggered the event.
-