new Input( midiInput )

Description

The Input class represents a single MIDI input port. This object is derived from the host's MIDI subsystem and cannot be instantiated directly.

You can find a list of all currently available Input objects in the WebMidi#inputs array.

The Input class extends the EventEmitter class from the djipevents module. This means it also includes methods such as getListeners(), emit(), suspendEvent() and several others.

Parameters
Name Type Description
midiInput MIDIInput

MIDIInput object as provided by the MIDI subsystem (Web MIDI API).

Details

Classes


new Input( midiInput )

Members


channels :Array.<InputChannel>

Description

Array containing the 16 InputChannel objects available for this Input. The channels are numbered 1 through 16.

Details
Array.<InputChannel>

<readonly> connection :string

Description

Input port's connection state: "pending", "open" or "closed".

Details
string

<readonly> id :string

Description

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.

Details
string

<readonly> manufacturer :string

Description

Name of the manufacturer of the device that makes this input port available.

Details
string

<readonly> name :string

Description

Name of the MIDI input

Details
string

<readonly> state :string

Description

State of the input port: "connected" or "disconnected".

Details
string

<readonly> type :string

Description

Port type. In the case of Input, this is always: "input".

Details
string

Methods


addListener( event, listener [, options ] ) → {Array.<Listener>}

Description

Adds an event listener that will trigger a function callback when the specified event happens. The event can be channel-bound or input-wide. Channel-bound events are dispatched by InputChannel objects and are tied to a specific MIDI channel while input-wide events are dispatched by the Input object itself and are not tied to a specific channel.

When listening for an input-wide event, you must specify the event to listen for and the callback function to trigger when the event happens:

WebMidi.inputs[0].addListener("midimessage", someFunction);
			

To listen for a channel-bound event, you must also specify the event to listen for and the function to trigger but you have to add the channels you wish to listen on in the options parameter:

WebMidi.inputs[0].addListener("noteon", someFunction, {channels: [1, 2, 3]});
			

The code above will add a listener for the "noteon" event and call someFunction when the event is triggered on MIDI channels 1, 2 or 3.

Note that, when adding events to channels, it is the InputChannel instance that actually gets a listener added and not the `Input instance.

Note: if you want to add a listener to a single MIDI channel you should probably do so directly on the InputChannel object itself.

There are 6 families of events you can listen to:

  1. MIDI System Common Events (input-wide)

  2. MIDI System Real-Time Events (input-wide)

  3. State Change Events (input-wide)

  4. Catch-All Events (input-wide)

  5. Channel Voice Events (channel-specific)

  6. Channel Mode Events (channel-specific)

Parameters
Name Type Attributes Default Description
event 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).

options Object <optional>
{}
Name Type Attributes Default Description
arguments array <optional>

An array of arguments which will be passed separately to the callback function. This array is stored in the arguments property of the Listener object and can be retrieved or modified as desired.

channels number | Array.<number> <optional>

An integer between 1 and 16 or an array of such integers representing the MIDI channel(s) to listen on. This parameter is ignored for input-wide events.

context Object <optional>
this

The value of this in the callback function.

duration number <optional>
Infinity

The number of milliseconds before the listener automatically expires.

prepend boolean <optional>
false

Whether the listener should be added at the beginning of the listeners array.

remaining boolean <optional>
Infinity

The number of times after which the callback should automatically be removed.

Returns

An array of all Listener objects that were created.

Throws

For channel-specific events, 'options.channels' must be defined.

Details

addOneTimeListener( event, listener [, options ] ) → {Array.<Listener>}

Description

Adds a one-time event listener that will trigger a function callback when the specified event happens. The event can be channel-bound or input-wide. Channel-bound events are dispatched by InputChannel objects and are tied to a specific MIDI channel while input-wide events are dispatched by the Input object itself and are not tied to a specific channel.

When listening for an input-wide event, you must specify the event to listen for and the callback function to trigger when the event happens:

WebMidi.inputs[0].addListener("midimessage", someFunction);
			

To listen for a channel-bound event, you must also specify the event to listen for and the function to trigger but you have to add the channels you wish to listen on in the options parameter:

WebMidi.inputs[0].addListener("noteon", someFunction, {channels: [1, 2, 3]});
			

The code above will add a listener for the "noteon" event and call someFunction when the event is triggered on MIDI channels 1, 2 or 3.

Note that, when adding events to channels, it is the InputChannel instance that actually gets a listener added and not the `Input instance.

Note: if you want to add a listener to a single MIDI channel you should probably do so directly on the InputChannel object itself.

There are 6 families of events you can listen to:

  1. MIDI System Common Events (input-wide)

  2. MIDI System Real-Time Events (input-wide)

  3. State Change Events (input-wide)

  4. Catch-All Events (input-wide)

  5. Channel Voice Events (channel-specific)

  6. Channel Mode Events (channel-specific)

Parameters
Name Type Attributes Default Description
event 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).

options Object <optional>
{}
Name Type Attributes Default Description
arguments array <optional>

An array of arguments which will be passed separately to the callback function. This array is stored in the arguments property of the Listener object and can be retrieved or modified as desired.

channels number | Array.<number> <optional>

An integer between 1 and 16 or an array of such integers representing the MIDI channel(s) to listen on. This parameter is ignored for input-wide events.

context Object <optional>
this

The value of this in the callback function.

duration number <optional>
Infinity

The number of milliseconds before the listener automatically expires.

prepend boolean <optional>
false

Whether the listener should be added at the beginning of the listeners array.

Returns

An array of all Listener objects that were created.

Throws

For channel-specific events, 'options.channels' must be defined.

Details

<async> close() → {Promise.<(void|*)>}

Description

Closes the input. When an input is closed, it cannot be used to listen to MIDI messages until the input is opened again by calling Input.open().

Returns
Details

<async> destroy() → {Promise.<void>}

Description

Destroys the Input by remove all listeners, emptying the channels array and unlinking the MIDI subsystem.

Returns
Details

hasListener( event, listener [, options ] ) → {Boolean}

Description

Checks if the specified event type is already defined to trigger the listener function. For channel-specific events, the function will return true only if all channels have the listener defined.

Parameters
Name Type Attributes Default Description
event string

The type of the event.

listener function

The callback function to check for.

options Object <optional>
{}
Name Type Attributes Description
channels number | Array.<number> <optional>

An integer between 1 and 16 or an array of such integers representing the MIDI channel(s) to check. This parameter is ignored for input-wide events.

Returns

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

Throws

Error For channel-specific events, 'options.channels' must be defined.

Details

<async> open() → {Promise.<Input>}

Description

Opens the input for usage.

Returns

The promise is fulfilled with the Input

Details

removeListener( [ type [, listener [, options ] ] ] )

Description

Removes the specified listener for the specified event. If no listener is specified, all listeners for the specified event will be removed. If no event is specified, all listeners for the Input as well as all listeners for all InputChannels will be removed.

By default, channel-specific listeners will be removed from all channels unless the options.channel narrows it down.

Parameters
Name Type Attributes Default Description
type String <optional>

The type of the event.

listener function <optional>

The callback function to check for.

options Object <optional>
{}
Name Type Attributes Description
channels number | Array.<number> <optional>

An integer between 1 and 16 or an array of such integers representing the MIDI channel(s) to match. This parameter is ignored for input-wide events.

context * <optional>

Only remove the listeners that have this exact context.

remaining number <optional>

Only remove the listener if it has exactly that many remaining times to be executed.

Details

Events


activesensing

Description

Input-wide (system) event emitted when an active sensing message has been received.

Properties
Name Type Description
target InputChannel

The Input that triggered the event.

event.data Array

The MIDI message as an array of 8 bit values.

event.rawData Uint8Array

The raw MIDI message as a Uint8Array.

timestamp number

The moment (DOMHighResTimeStamp) when the event occurred (in milliseconds since the navigation start of the document).

type string

"activesensing"

Details
Object

clock

Description

Input-wide (system) event emitted when a timing clock message has been received.

Properties
Name Type Description
target InputChannel

The Input that triggered the event.

event.data Array

The MIDI message as an array of 8 bit values.

event.rawData Uint8Array

The raw MIDI message as a Uint8Array.

timestamp number

The moment (DOMHighResTimeStamp) when the event occurred (in milliseconds since the navigation start of the document).

type string

"clock"

Details
Object

closed

Description

Event emitted when the Input has been closed by calling the Input#close method.

Properties
Name Type Description
timestamp number

The moment (DOMHighResTimeStamp) when the event occurred (in milliseconds since the navigation start of the document).

type string

"closed"

target Input

The object that triggered the event

Details
Object

continue

Description

Input-wide (system) event emitted when a continue message has been received.

Properties
Name Type Description
target InputChannel

The Input that triggered the event.

event.data Array

The MIDI message as an array of 8 bit values.

event.rawData Uint8Array

The raw MIDI message as a Uint8Array.

timestamp number

The moment (DOMHighResTimeStamp) when the event occurred (in milliseconds since the navigation start of the document).

type string

"continue"

Details
Object

disconnected

Description

Event emitted when the Input becomes unavailable. This event is typically fired when the MIDI device is unplugged.

Properties
Name Type Description
timestamp number

The moment (DOMHighResTimeStamp) when the event occurred (in milliseconds since the navigation start of the document).

type string

"disconnected"

target Object

Object with properties describing the Input that triggered the event. This is not the actual Input as it is no longer available.

Name Type Description
connection string

"closed"

id string

ID of the input

manufacturer string

Manufacturer of the device that provided the input

name string

Name of the device that provided the input

state string

"disconnected"

type string

"input"

Details
Object

midimessage

Description

Event emitted when a MIDI message is received on the Input

Properties
Name Type Attributes Description
target Input

The Input that triggered the event.

event.data Array

The MIDI message as an array of 8 bit values.

event.rawData Uint8Array

The raw MIDI message as a Uint8Array.

timestamp number

The moment (DOMHighResTimeStamp) when the event occurred (in milliseconds since the navigation start of the document).

type string

"midimessage"

event.statusByte number

The message's status byte.

event.dataBytes Array.<number> <nullable>

The message's data bytes as an array of 0, 1 or 2 integers. This will be null for sysex messages.

Details
Object

2.1


opened

Description

Event emitted when the Input has been opened by calling the Input#open method.

Properties
Name Type Description
timestamp number

The moment (DOMHighResTimeStamp) when the event occurred (in milliseconds since the navigation start of the document).

type string

"opened"

target Input

The object that triggered the event

Details
Object

reset

Description

Input-wide (system) event emitted when a reset message has been received.

Properties
Name Type Description
target InputChannel

The Input that triggered the event.

event.data Array

The MIDI message as an array of 8 bit values.

event.rawData Uint8Array

The raw MIDI message as a Uint8Array.

timestamp number

The moment (DOMHighResTimeStamp) when the event occurred (in milliseconds since the navigation start of the document).

type string

"reset"

Details
Object

songposition

Description

Input-wide (system) event emitted when a song position message has been received.

Properties
Name Type Description
target InputChannel

The Input that triggered the event.

event.data Array

The MIDI message as an array of 8 bit values.

event.rawData Uint8Array

The raw MIDI message as a Uint8Array.

timestamp number

The moment (DOMHighResTimeStamp) when the event occurred (in milliseconds since the navigation start of the document).

type string

"songposition"

Details
Object

songselect

Description

Input-wide (system) event emitted when a song select message has been received.

Properties
Name Type Description
target InputChannel

The Input that triggered the event.

event.data Array

The MIDI message as an array of 8 bit values.

event.rawData Uint8Array

The raw MIDI message as a Uint8Array.

timestamp number

The moment (DOMHighResTimeStamp) when the event occurred (in milliseconds since the navigation start of the document).

type string

"songselect"

song string

Song (or sequence) number to select (1-128)

Details
Object

start

Description

Input-wide (system) event emitted when a start message has been received.

Properties
Name Type Description
target InputChannel

The Input that triggered the event.

event.data Array

The MIDI message as an array of 8 bit values.

event.rawData Uint8Array

The raw MIDI message as a Uint8Array.

timestamp number

The moment (DOMHighResTimeStamp) when the event occurred (in milliseconds since the navigation start of the document).

type string

"start"

Details
Object

stop

Description

Input-wide (system) event emitted when a stop message has been received.

Properties
Name Type Description
target InputChannel

The Input that triggered the event.

event.data Array

The MIDI message as an array of 8 bit values.

event.rawData Uint8Array

The raw MIDI message as a Uint8Array.

timestamp number

The moment (DOMHighResTimeStamp) when the event occurred (in milliseconds since the navigation start of the document).

type string

"stop"

Details
Object

sysex

Description

Input-wide (system) event emitted when a system exclusive message has been received. You should note that, to receive sysex events, you must call the WebMidi.enable() method with the sysex option set to true:

WebMidi.enable({sysex: true})
			 .then(() => console.log("WebMidi has been enabled with sysex support."))
			 .catch(err => console.log("WebMidi could not be enabled."))
			
Properties
Name Type Description
target InputChannel

The Input that triggered the event.

event.data Array

The MIDI message as an array of 8 bit values.

event.rawData Uint8Array

The raw MIDI message as a Uint8Array.

timestamp number

The moment (DOMHighResTimeStamp) when the event occurred (in milliseconds since the navigation start of the document).

type string

"sysex"

Details
Object

timecode

Description

Input-wide (system) event emitted when a time code quarter frame message has been received.

Properties
Name Type Description
target InputChannel

The Input that triggered the event.

event.data Array

The MIDI message as an array of 8 bit values.

event.rawData Uint8Array

The raw MIDI message as a Uint8Array.

timestamp number

The moment (DOMHighResTimeStamp) when the event occurred (in milliseconds since the navigation start of the document).

type string

"sysextimecode"

Details
Object

tunerequest

Description

Input-wide (system) event emitted when a tune request message has been received.

Properties
Name Type Description
target InputChannel

The Input that triggered the event.

event.data Array

The MIDI message as an array of 8 bit values.

event.rawData Uint8Array

The raw MIDI message as a Uint8Array.

timestamp number

The moment (DOMHighResTimeStamp) when the event occurred (in milliseconds since the navigation start of the document).

type string

"tunerequest"

Details
Object

unknownmidimessage

Description

Input-wide (system) event emitted when an unknown MIDI message has been received. It could be, for example, one of the undefined/reserved messages.

Properties
Name Type Description
target InputChannel

The Input that triggered the event.

event.data Array

The MIDI message as an array of 8 bit values.

event.rawData Uint8Array

The raw MIDI message as a Uint8Array.

timestamp number

The moment (DOMHighResTimeStamp) when the event occurred (in milliseconds since the navigation start of the document).

type string

"unknownmidimessage"

Details
Object