API Docs for: 2.2.0
Show:

Input Class

Defined in: src/webmidi.js:1192

The Input object represents a MIDI input port on the host system. This object is created by the MIDI subsystem and cannot be instantiated directly.

You will find all available Input objects in the WebMidi.inputs array.

Methods

_initializeUserHandlers

() protected

Defined in src/webmidi.js:1565

_onMidiMessage

() protected

Defined in src/webmidi.js:1585

_parseChannelEvent

(
  • e
)
protected

Defined in src/webmidi.js:1629

Parameters:

_parseSystemEvent

() protected

Defined in src/webmidi.js:1947

addListener

(
  • type
  • channel
  • listener
)
WebMidi chainable

Defined in src/webmidi.js:1300

Adds an event listener to the Input that will trigger a function callback when the specified event happens. The events that are dispatched can be channel-specific or Input-wide.

Here is a list of events that are dispatched by Input objects and that can be listened to.

Channel-specific MIDI events:

Input-wide MIDI events:

For device-wide events, the channel parameter will be silently ignored. You can simply use undefined in that case.

If you want to view all incoming MIDI traffic, you can listen to the input-wide midimessage event. This event is dispatched for every single message that is received on that input.

Parameters:

  • type String

    The type of the event.

  • channel Number | Array | String

    The MIDI channel to listen on (integer between 1 and 16). You can also specify an array of channel numbers or the value 'all' (or leave it undefined for input-wide events).

  • 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 specified event type is not supported.

getCcNameByNumber

(
  • number
)
String | Undefined

Defined in src/webmidi.js:1877

Available since 2.0.0

Returns the name of a control change message matching the specified number. If no match is found, the function returns undefined.

Parameters:

  • number Number

    The number of the control change message.

Returns:

String | Undefined:

The matching control change name or undefined.

Throws:

RangeError The control change number must be between 0 and 119.

getChannelModeByNumber

(
  • number
)
String | Undefined

Defined in src/webmidi.js:1913

Available since 2.0.0

Returns the channel mode name matching the specified number. If no match is found, the function returns undefined.

Parameters:

  • number Number

    The number of the channel mode message.

Returns:

String | Undefined:

The matching channel mode message's name or undefined;

Throws:

RangeError The channel mode number must be between 120 and 127.

hasListener

(
  • type
  • channel
  • listener
)
Boolean

Defined in src/webmidi.js:1421

Checks if the specified event type is already defined to trigger the listener function on the specified channel(s). If more than one channel is specified, the function will return true only if all channels have the listener defined.

For device-wide events (sysex, start, etc.), the channel parameter is silently ignored. We suggest you use undefined in such cases.

Parameters:

  • type String

    The type of the event.

  • channel Number | Array | String

    The MIDI channel to check on (between 1 and 16). You can also specify an array of channel numbers or the string 'all'.

  • listener Function

    The callback function to check for.

Returns:

Boolean:

Boolean value indicating whether or not the channel(s) already have this listener defined.

Throws:

TypeError:

The 'listener' parameter must be a function.

on

()

Defined in src/webmidi.js:1412

Available since 2.0.0

This is an alias to the Input.addListener() function.

removeListener

(
  • [type]
  • [channel]
  • [listener]
)
Input chainable

Defined in src/webmidi.js:1480

Removes the specified listener from the specified channel(s). If the listener parameter is left undefined, all listeners for the specified type will be removed from all channels. If the channel is also omitted, all listeners of the specified type will be removed from all channels. If no parameters are defined, all listeners attached to any channel of the Input will be removed.

For device-wide events (sysex, start, etc.), the channel parameter is silently ignored. You can use undefined in such cases.

Parameters:

  • [type] String optional

    The type of the event.

  • [channel] Number | String | Array optional

    The MIDI channel(s) to check on. It can be a uint (between 1 and 16) an array of channel numbers or the special value "all".

  • [listener] Function optional

    The callback function to check for.

Returns:

Input:

The Input object for easy method chaining.

Throws:

TypeError:

The 'listener' parameter must be a function..

Properties

connection

String

Defined in src/webmidi.js:1213

[read-only] Status of the MIDI port's connection (pending, open or closed)

id

String

Defined in src/webmidi.js:1226

[read-only] ID string of the MIDI port. The ID is host-specific. Do not expect the same ID on different platforms. For example, Google Chrome and the Jazz-Plugin report completely different IDs for the same port.

manufacturer

String

Defined in src/webmidi.js:1241

[read-only] Name of the manufacturer of the device that makes this port available.

name

String

Defined in src/webmidi.js:1254

[read-only] Name of the MIDI port

state

String

Defined in src/webmidi.js:1267

[read-only] State of the MIDI port (connected or disconnected)

type

String

Defined in src/webmidi.js:1280

[read-only] Type of the MIDI port (input)

Events

activesensing

Defined in src/webmidi.js:2123

Event emitted when a system active sensing MIDI message has been received.

Event Payload:

  • event Object
    • target Input

      The Input that triggered the event.

    • data Uint8Array

      The raw MIDI message as an array of 8 bit values.

    • timestamp Number

      The time when the event occurred (in milliseconds)

    • type String

      The type of event that occurred.

channelaftertouch

Defined in src/webmidi.js:1825

Event emitted when a channel-wide aftertouch MIDI message has been received on a specific device and channel.

Event Payload:

  • event Object
    • target Input

      The Input that triggered the event.

    • data Uint8Array

      The raw MIDI message as an array of 8 bit values.

    • timestamp Number

      The time when the event occurred (in milliseconds)

    • channel Uint

      The channel where the event occurred (between 1 and 16).

    • type String

      The type of event that occurred.

    • value Number

      The aftertouch value received (between 0 and 1).

channelmode

Defined in src/webmidi.js:1780

Event emitted when a channel mode MIDI message has been received on a specific device and channel.

Event Payload:

  • event Object
    • target Input

      The Input that triggered the event.

    • data Uint8Array

      The raw MIDI message as an array of 8 bit values.

    • timestamp Number

      The time when the event occurred (in milliseconds)

    • channel Uint

      The channel where the event occurred (between 1 and 16).

    • type String

      The type of event that occurred.

    • controller Object
      • number Uint
        The number of the controller.
      • name String
        The usual name or function of the controller.
    • value Uint

      The value received (between 0 and 127).

clock

Defined in src/webmidi.js:2059

Event emitted when a system timing clock MIDI message has been received.

Event Payload:

  • event Object
    • target Input

      The Input that triggered the event.

    • data Uint8Array

      The raw MIDI message as an array of 8 bit values.

    • timestamp Number

      The time when the event occurred (in milliseconds)

    • type String

      The type of event that occurred.

continue

Defined in src/webmidi.js:2091

Event emitted when a system continue MIDI message has been received.

Event Payload:

  • event Object
    • target Input

      The Input that triggered the event.

    • data Uint8Array

      The raw MIDI message as an array of 8 bit values.

    • timestamp Number

      The time when the event occurred (in milliseconds)

    • type String

      The type of event that occurred.

controlchange

Defined in src/webmidi.js:1751

Event emitted when a control change MIDI message has been received on a specific device and channel.

Event Payload:

  • event Object
    • target Input

      The Input that triggered the event.

    • data Uint8Array

      The raw MIDI message as an array of 8 bit values.

    • timestamp Number

      The time when the event occurred (in milliseconds)

    • channel Uint

      The channel where the event occurred (between 1 and 16).

    • type String

      The type of event that occurred.

    • controller Object
      • number Uint
        The number of the controller.
      • name String
        The usual name or function of the controller.
    • value Uint

      The value received (between 0 and 127).

keyaftertouch

Defined in src/webmidi.js:1720

Event emitted when a key-specific aftertouch MIDI message has been received on a specific device and channel.

Event Payload:

  • event Object
    • target Input

      The Input that triggered the event.

    • data Uint8Array

      The raw MIDI message as an array of 8 bit values.

    • timestamp Number

      The time when the event occurred (in milliseconds)

    • channel Uint

      The channel where the event occurred (between 1 and 16).

    • type String

      The type of event that occurred.

    • note Object
      • number Uint
        The MIDI note number.
      • name String
        The usual note name (C, C#, D, D#, etc.).
      • octave Uint
        The octave (between -2 and 8).
    • value Number

      The aftertouch amount (between 0 and 1).

midimessage

Defined in src/webmidi.js:1601

Available since 2.1

Event emitted when a MIDI message is received. This should be used primarily for debugging purposes.

Event Payload:

  • event Object
    • target Input

      The Input that triggered the event.

    • data Uint8Array

      The raw MIDI message as an array of 8 bit values.

    • timestamp Uint

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

    • type String

      The type of event that occurred.

noteoff

Defined in src/webmidi.js:1658

Event emitted when a note off MIDI message has been received on a specific device and channel.

Event Payload:

  • event Object
    • target Input

      The Input that triggered the event.

    • data Uint8Array

      The raw MIDI message as an array of 8 bit values.

    • timestamp Number

      The time when the event occurred (in milliseconds)

    • channel Uint

      The channel where the event occurred (between 1 and 16).

    • type String

      The type of event that occurred.

    • note Object
      • number Uint
        The MIDI note number.
      • name String
        The usual note name (C, C#, D, D#, etc.).
      • octave Uint
        The octave (between -2 and 8).
    • velocity Number

      The release velocity (between 0 and 1).

    • rawVelocity Number

      The attack velocity expressed as a 7-bit integer (between 0 and 127).

noteon

Defined in src/webmidi.js:1689

Event emitted when a note on MIDI message has been received on a specific device and channel.

Event Payload:

  • event Object
    • target Input

      The Input that triggered the event.

    • data Uint8Array

      The raw MIDI message as an array of 8 bit values.

    • timestamp Number

      The time when the event occurred (in milliseconds)

    • channel Uint

      The channel where the event occurred (between 1 and 16).

    • type String

      The type of event that occurred.

    • note Object
      • number Uint
        The MIDI note number.
      • name String
        The usual note name (C, C#, D, D#, etc.).
      • octave Uint
        The octave (between -2 and 8).
    • velocity Number

      The attack velocity (between 0 and 1).

    • rawVelocity Number

      The attack velocity expressed as a 7-bit integer (between 0 and 127).

pitchbend

Defined in src/webmidi.js:1844

Event emitted when a pitch bend MIDI message has been received on a specific device and channel.

Event Payload:

  • event Object
    • target Input

      The Input that triggered the event.

    • data Uint8Array

      The raw MIDI message as an array of 8 bit values.

    • timestamp Number

      The time when the event occurred (in milliseconds)

    • channel Uint

      The channel where the event occurred (between 1 and 16).

    • type String

      The type of event that occurred.

    • value Number

      The pitch bend value received (between -1 and 1).

programchange

Defined in src/webmidi.js:1806

Event emitted when a program change MIDI message has been received on a specific device and channel.

Event Payload:

  • event Object
    • target Input

      The Input that triggered the event.

    • data Uint8Array

      The raw MIDI message as an array of 8 bit values.

    • timestamp Number

      The time when the event occurred (in milliseconds)

    • channel Uint

      The channel where the event occurred (between 1 and 16).

    • type String

      The type of event that occurred.

    • value Uint

      The value received (between 0 and 127).

reset

Defined in src/webmidi.js:2138

Event emitted when a system reset MIDI message has been received.

Event Payload:

  • event Object
    • target Input

      The Input that triggered the event.

    • data Uint8Array

      The raw MIDI message as an array of 8 bit values.

    • timestamp Number

      The time when the event occurred (in milliseconds)

    • type String

      The type of event that occurred.

songposition

Defined in src/webmidi.js:2011

Event emitted when a system song position pointer MIDI message has been received.

Event Payload:

  • event Object
    • target Input

      The Input that triggered the event.

    • data Uint8Array

      The raw MIDI message as an array of 8 bit values.

    • timestamp Number

      The time when the event occurred (in milliseconds)

    • type String

      The type of event that occurred.

songselect

Defined in src/webmidi.js:2026

Event emitted when a system song select MIDI message has been received.

Event Payload:

  • event Object
    • target Input

      The Input that triggered the event.

    • data Uint8Array

      The raw MIDI message as an array of 8 bit values.

    • timestamp Number

      The time when the event occurred (in milliseconds)

    • type String

      The type of event that occurred.

    • song String

      Song (or sequence) number to select.

start

Defined in src/webmidi.js:2075

Event emitted when a system start MIDI message has been received.

Event Payload:

  • event Object
    • target Input

      The Input that triggered the event.

    • data Uint8Array

      The raw MIDI message as an array of 8 bit values.

    • timestamp Number

      The time when the event occurred (in milliseconds)

    • type String

      The type of event that occurred.

stop

Defined in src/webmidi.js:2107

Event emitted when a system stop MIDI message has been received.

Event Payload:

  • event Object
    • target Input

      The Input that triggered the event.

    • data Uint8Array

      The raw MIDI message as an array of 8 bit values.

    • timestamp Number

      The time when the event occurred (in milliseconds)

    • type String

      The type of event that occurred.

sysex

Defined in src/webmidi.js:1964

Event emitted when a system exclusive MIDI message has been received. You should note that, to receive sysex events, you must call the WebMidi.enable() method with a second parameter set to true:

WebMidi.enable(function(err) {
                    
                       if (err) {
                         console.log("WebMidi could not be enabled.");
                       }
                    
                       var input = WebMidi.inputs[0];
                    
                       input.addListener('sysex', "all", function (e) {
                         console.log(e);
                       });
                    
                    }, true);

Event Payload:

  • event Object
    • target Input

      The Input that triggered the event.

    • data Uint8Array

      The raw MIDI message as an array of 8 bit values.

    • timestamp Number

      The time when the event occurred (in milliseconds)

    • type String

      The type of event that occurred.

timecode

Defined in src/webmidi.js:1996

Event emitted when a system MIDI time code quarter frame message has been received.

Event Payload:

  • event Object
    • target Input

      The Input that triggered the event.

    • data Uint8Array

      The raw MIDI message as an array of 8 bit values.

    • timestamp Number

      The time when the event occurred (in milliseconds)

    • type String

      The type of event that occurred.

tuningrequest

Defined in src/webmidi.js:2043

Event emitted when a system tune request MIDI message has been received.

Event Payload:

  • event Object
    • target Input

      The Input that triggered the event.

    • data Uint8Array

      The raw MIDI message as an array of 8 bit values.

    • timestamp Number

      The time when the event occurred (in milliseconds)

    • type String

      The type of event that occurred.

unknownsystemmessage

Defined in src/webmidi.js:2153

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 Input

      The Input that triggered the event.

    • data Uint8Array

      The raw MIDI message as an array of 8 bit values.

    • timestamp Number

      The time when the event occurred (in milliseconds)

    • type String

      The type of event that occurred.