API Docs for: 2.2.0
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

_onInterfaceStateChange

() protected static

Defined in src/webmidi.js:1112

_resetInterfaceUserHandlers

() protected static

Defined in src/webmidi.js:1179

_updateInputs

() protected static

Defined in src/webmidi.js:1016

_updateInputsAndOutputs

() protected static

Defined in src/webmidi.js:1006

_updateOutputs

() protected static

Defined in src/webmidi.js:1064

addListener

(
  • type
  • listener
)
WebMidi static chainable

Defined in src/webmidi.js:591

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

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

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

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

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.

getOctave

(
  • number
)
Number static

Defined in src/webmidi.js:871

Available since 2.0.0-rc.6

Returns the octave number for the specified MIDI note number (0-127). By default, the value is based on middle C (note number 60) being placed on the 4th octave (C4). However, by using the octaveOffset property, you can offset the result as much as you want.

Parameters:

  • number Number

    An integer representing a valid MIDI note number (between 0 and 127).

Returns:

Number:

The octave (as a signed integer) or undefined.

getOutputById

(
  • id
)
Output | False static

Defined in src/webmidi.js:805

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

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

Returns a valid MIDI note number (0-127) given the specified input. The input usually is a note name (C3, F#4, D-2, G8, etc.). If an integer between 0 and 127, it will simply be returned as is.

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 input value

hasListener

(
  • type
  • listener
)
Boolean static

Defined in src/webmidi.js:637

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

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. The name can also optionally include a sharp (#), a double sharp (##), a flat (b) or a double flat (bb) symbol: C5, G4, D#-1, F0, Gb7, Eb-1, Abb4, B##6, etc.

Note that, in converting note names to numbers, C4 is considered to be middle C (MIDI note number 60) as per the scientific pitch notation standard.

Also note that the resulting note number is offset by the octaveOffset value (if not zero). For example, if you pass in "C4" and the octaveOffset value is 2 the resulting MIDI note number will be 36.

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.

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

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.

toMIDIChannels

(
  • [channel]
)
Array protected

Defined in src/webmidi.js:734

Converts an input value (which should be an integer, an array of integers, "all" or undefined) to an array of valid MIDI channel numbers. Passing "all" or undefined to this function results in all channels being returned (1-16).

Elements in the array that cannot successfully be parsed to integers between 1 and 16 (using parseInt()) are silently removed.

Parameters:

  • [channel] Uint | Array optional

Returns:

Properties

enabled

Boolean static

Defined in src/webmidi.js:356

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

inputs

Array static

Defined in src/webmidi.js:371

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

MIDI_CHANNEL_MESSAGES

Object static

Defined in src/webmidi.js:146

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

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

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

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

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.

octaveOffset

Number static

Defined in src/webmidi.js:312

Available since 2.1

An integer to offset the octave both in inbound and outbound messages. By default, middle C (MIDI note number 60) is placed on the 4th octave (C4).

If, for example, octaveOffset is set to 2, MIDI note number 60 will be reported as C6. If octaveOffset is set to -1, MIDI note number 60 will be reported as C3.

outputs

Array static

Defined in src/webmidi.js:385

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

supported

Boolean static

Defined in src/webmidi.js:337

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

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

time

DOMHighResTimeStamp static

Defined in src/webmidi.js:414

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

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.

    • port String

      The actual Input or Output object associated to the event.

disconnected

Defined in src/webmidi.js:1134

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.

    • port String

      An generic object containing details about the port that triggered the event.