API Docs for: 2.0.0-rc.5
Show:

WebMidi Class

Defined in: src/webmidi.js:5

The WebMidi object makes it easier to work with the Web MIDI API. Basically, it simplifies two things: sending 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!

Methods

_createInput

() protected static

Defined in src/webmidi.js:991

_createOutput

() protected static

Defined in src/webmidi.js:1002

_onInterfaceStateChange

() protected static

Defined in src/webmidi.js:1013

_processStateChange

() protected static

Defined in src/webmidi.js:1036

_resetInterfaceUserHandlers

() protected static

Defined in src/webmidi.js:1104

_updateInputs

() protected static

Defined in src/webmidi.js:897

_updateInputsAndOutputs

() protected static

Defined in src/webmidi.js:887

_updateOutputs

() protected static

Defined in src/webmidi.js:944

addListener

(
  • type
  • listener
)
WebMidi static chainable

Defined in src/webmidi.js:538

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:

  • type String

    The type of the event.

  • listener Function

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

Returns:

WebMidi:

Returns the WebMidi object so methods can be chained.

Throws:

TypeError:

The 'listener' parameter must be a function.

disable

() static

Defined in src/webmidi.js:515

Available since 2.0.0

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

Defined in src/webmidi.js:412

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:

  • [callback] Function optional

    A function to execute upon success. This function will receive an Error object upon failure to enable the Web MIDI API.

  • [sysex=false] Boolean optional

    Whether to enable MIDI system exclusive messages or not.

Throws:

Error Jazz-Plugin must be installed to use WebMIDIAPIShim.

getInputById

(
  • id
)
Input | False static

Defined in src/webmidi.js:681

Available since 2.0.0

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 String

    The id of the port. IDs can be viewed by looking at the WebMidi.inputs array.

Returns:

Input | False:

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

getInputByName

(
  • name
)
Input | False static

Defined in src/webmidi.js:745

Available since 2.0.0

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 String

    The name of a MIDI input port such as those visible in the WebMidi.inputs array.

Returns:

Input | False:

The Input that was found or false if no input matched the specified name.

Throws:

TypeError The name must be a string.

getOutputById

(
  • id
)
Output | False static

Defined in src/webmidi.js:713

Available since 2.0.0

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 String

    The id of the port. Ids can be viewed by looking at the WebMidi.outputs array.

Returns:

Output | False:

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

getOutputByName

(
  • name
)
Output | False static

Defined in src/webmidi.js:779

Available since 2.0.0

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 String

    The name of a MIDI output port such as those visible in the WebMidi.outputs array.

Returns:

Output | False:

The Output that was found or false if no output matched the specified name.

Throws:

Error WebMidi is not enabled.

guessNoteNumber

(
  • input
)
Number static

Defined in src/webmidi.js:812

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:

  • input Number | String

    A string to extract the note number from. An integer can also be used, in which case it will simply be returned (if between 0 and 127).

Returns:

Number:

A valid MIDI note number (0-127).

Throws:

Error:

Invalid note number.

hasListener

(
  • type
  • listener
)
Boolean static

Defined in src/webmidi.js:584

Checks if the specified event type is already defined to trigger the specified listener function.

Parameters:

  • type String

    The type of the event.

  • listener Function

    The callback function to check for.

Returns:

Boolean:

Boolean value indicating whether or not a callback is already defined for this event type.

Throws:

TypeError:

The specified event type is not supported.

noteNameToNumber

(
  • name
)
Number static

Defined in src/webmidi.js:844

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

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

Parameters:

  • name String

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

Returns:

Number:

The MIDI note number (between 0 and 127)

Throws:

RangeError:

Invalid note name or note outside valid range.

removeListener

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

Defined in src/webmidi.js:627

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:

  • [type] String optional

    The type of the event.

  • [listener] Function optional

    The callback function to check for.

Returns:

WebMidi:

The WebMidi object for easy method chaining.

Throws:

TypeError:

The specified event type is not supported.

Properties

enabled

Boolean static

Defined in src/webmidi.js:331

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

inputs

Array static

Defined in src/webmidi.js:346

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

MIDI_CHANNEL_MESSAGES

Object static

Defined in src/webmidi.js:141

Available since 2.0.0

[read-only] List of valid MIDI channel messages and matching hexadecimal values.

MIDI_CHANNEL_MODE_MESSAGES

Object static

Defined in src/webmidi.js:281

Available since 2.0.0

[read-only] List of MIDI channel mode messages as defined in the official MIDI specification.

MIDI_CONTROL_CHANGE_MESSAGES

Object static

Defined in src/webmidi.js:201

Available since 2.0.0

[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

Defined in src/webmidi.js:166

Available since 2.0.0

[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

Defined in src/webmidi.js:103

Available since 2.0.0

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

outputs

Array static

Defined in src/webmidi.js:360

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

supported

Boolean static

Defined in src/webmidi.js:312

[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

Defined in src/webmidi.js:374

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

time

DOMHighResTimeStamp static

Defined in src/webmidi.js:389

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

Events

connected

Defined in src/webmidi.js:1049

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 Number

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

    • type String

      The type of event that occurred.

    • id String

      The ID of the device that triggered the event.

    • manufacturer String

      The manufacturer of the device that triggered the event.

    • name String

      The name of the device that triggered the event.

    • output String

      The Input or Output object that triggered the event.

disconnected

Defined in src/webmidi.js:1065

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 Number

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

    • type String

      The type of event that occurred.

    • id String

      The ID of the device that triggered the event.

    • manufacturer String

      The manufacturer of the device that triggered the event.

    • name String

      The name of the device that triggered the event.

    • output String

      The Input or Output object that triggered the event.