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

_resetInterfaceUserHandlers

() protected static

Defined in src/webmidi.js:1260

_updateInputs

() protected static

Defined in src/webmidi.js:1097

_updateInputsAndOutputs

() protected static

Defined in src/webmidi.js:1087

_updateOutputs

() protected static

Defined in src/webmidi.js:1145

addListener

(
  • type
  • listener
)
WebMidi static chainable

Defined in src/webmidi.js:655

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

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 WebMidi or Input objects will be destroyed.

enable

(
  • [callback]
  • [sysex=false]
)
static

Defined in src/webmidi.js:496

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.

Warning: starting with Chrome v77, the Web MIDI API must be hosted on a secure origin (https://, localhost or file:///) and the user will always be prompted to authorize the operation (no matter if sysex is requested or not).

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

Available since 2.0.0

Returns the Input object that matches the specified ID string or false if no matching input is found. As per the Web MIDI API specification, IDs are strings (not integers). Please note that IDs change from one host to another. For example, Chrome does not use the same kind of IDs as Jazz-Plugin.

Parameters:

  • id String

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

Returns:

Input | False:

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

Throws:

Error WebMidi is not enabled.

getInputByName

(
  • name
)
Input | False static

Defined in src/webmidi.js:918

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

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

Available since 2.0.0

Returns the Output object that matches the specified ID string or false if no matching output is found. As per the Web MIDI API specification, IDs are strings (not integers).

Please note that IDs change from one host to another. For example, Chrome does not use the same kind of IDs as Jazz-Plugin.

Parameters:

  • id String

    The ID string of the port. IDs can be viewed by looking at the WebMidi.outputs array.

Returns:

Output | False:

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

Throws:

Error WebMidi is not enabled.

getOutputByName

(
  • name
)
Output | False static

Defined in src/webmidi.js:975

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

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

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

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

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="all"]
)
Array static

Defined in src/webmidi.js:798

Returns a sanitized array of valid MIDI channel numbers (1-16). The parameter should be one of the following:

  • a single integer
  • an array of integers
  • the special value "all"
  • the special value "none"

Passing "all" or undefined as a parameter to this function results in all channels being returned (1-16). Passing "none" results in no channel being returned (as an empty array).

Note: parameters that cannot successfully be parsed to integers between 1 and 16 are silently ignored.

Parameters:

  • [channel="all"] Number | Array | "all" | "none" optional

Returns:

Array:

An array of 0 or more valid MIDI channel numbers

Properties

enabled

Boolean static

Defined in src/webmidi.js:379

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

inputs

Array static

Defined in src/webmidi.js:394

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

MIDI_CHANNEL_MESSAGES

Object static

Defined in src/webmidi.js:144

Available since 2.0.0

[read-only] An object containing properties for each MIDI channel messages and their associated hexadecimal value.

MIDI_CHANNEL_MODE_MESSAGES

Object static

Defined in src/webmidi.js:309

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

Available since 2.0.0

[read-only] An object containing properties for each MIDI control change messages (a.k.a. CC messages) and their associated hexadecimal value.

MIDI_NRPN_MESSAGES

Object static

Defined in src/webmidi.js:284

Available since 2.0.0

[read-only] An object containing properties for MIDI control change messages that make up NRPN messages

MIDI_REGISTERED_PARAMETER

Object static

Defined in src/webmidi.js:171

Available since 2.0.0

[read-only] An object containing properties for each registered parameters and their associated pair of hexadecimal values. MIDI registered parameters extend the original list of control change messages (a.k.a. CC 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.

nrpnTypes

Array static

Defined in src/webmidi.js:459

[read-only] NRPN message types

octaveOffset

Number static

Defined in src/webmidi.js:335

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

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

supported

Boolean static

Defined in src/webmidi.js:360

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

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

time

DOMHighResTimeStamp static

Defined in src/webmidi.js:473

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

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

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.