Input

The Input class represents a single MIDI input port. This object is automatically instantiated by the library according to the host's MIDI subsystem and does not need to be directly instantiated. Instead, you can access all Input objects by referring to the WebMidi.inputs array. You can also retrieve inputs by using methods such as WebMidi.getInputByName() and WebMidi.getInputById().

Note that a single MIDI device may expose several inputs and/or outputs.

Important: the Input class does not directly fire channel-specific MIDI messages (such as noteon or controlchange, etc.). The InputChannel object does that. However, you can still use the Input.addListener() method to listen to channel-specific events on multiple InputChannel objects at once.

Extends: EventEmitter

Fires: activesensing, clock, closed, continue, disconnected, midimessage, opened, reset, songposition, songselect, start, stop, sysex, timecode, tunerequest, unknownmidimessage

Constructor

Creates an Input object.

Parameters

new Input(midiInput)

Parameter	Type	Default	Description
midiInput	MIDIInput		MIDIInput object as provided by the MIDI subsystem (Web MIDI API).

---

Properties

.channels

Type: Array.<InputChannel>

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

.connection

Type: string
Attributes: read-only

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

.eventCount

Type: number
Attributes: read-only

The number of unique events that have registered listeners.

Note: this excludes global events registered with EventEmitter.ANY_EVENT because they are not tied to a specific event.

.eventMap

Type: Object
Attributes: read-only

An object containing a property for each event with at least one registered listener. Each event property contains an array of all the Listener objects registered for the event.

.eventNames

Type: Array.<string>
Attributes: read-only

An array of all the unique event names for which the emitter has at least one registered listener.

Note: this excludes global events registered with EventEmitter.ANY_EVENT because they are not tied to a specific event.

.eventsSuspended

Type: boolean

Whether or not the execution of callbacks is currently suspended for this emitter.

.id

Type: string
Attributes: 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

Type: string
Attributes: read-only

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

.name

Type: string
Attributes: read-only

Name of the MIDI input.

.octaveOffset

Since: 3.0
Type: number

An integer to offset the reported octave of incoming notes. 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.

Note that this value is combined with the global offset value defined in the WebMidi.octaveOffset property (if any).

.state

Type: string
Attributes: read-only

State of the input port: connected or disconnected.

.type

Type: string
Attributes: read-only

The port type. In the case of the Input object, this is always: input.

---

Methods

.addForwarder(...)

Adds a forwarder that will forward all incoming MIDI messages matching the criteria to the specified Output destination(s). This is akin to the hardware MIDI THRU port, with the added benefit of being able to filter which data is forwarded.

Parameters

Signature: addForwarder(output, [options])

Parameter	Type(s)	Default	Description
output	Output Array.<Output>		An Output object, or an array of such objects, to forward messages to.
[options]	object	{}
[options.types]	string Array.<string>	(all messages)	A message type, or an array of such types (noteon, controlchange, etc.), that the message type must match in order to be forwarded. If this option is not specified, all types of messages will be forwarded. Valid messages are the ones found in either MIDI_SYSTEM_MESSAGES or MIDI_CHANNEL_MESSAGES.
[options.channels]	number Array.<number>	[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]	A MIDI channel number or an array of channel numbers that the message must match in order to be forwarded. By default all MIDI channels are included (1 to 16).

Return Value

Returns: Forwarder

The Forwarder object created to handle the forwarding. This is useful if you wish to manipulate or remove the Forwarder later on.

.addListener(...)

Adds an event listener that will trigger a function callback when the specified event is dispatched. The event usually is input-wide but can also be channel-specific.

Input-wide events do not target a specific MIDI channel so it makes sense to listen for them at the Input level and not at the InputChannel level. Channel-specific events target a specific channel. Usually, in this case, you would add the listener to the InputChannel object. However, as a convenience, you can also listen to channel-specific events directly on an Input. This allows you to react to a channel-specific event no matter which channel it actually came through.

When listening for an event, you simply need to specify the event name and the function to execute:

const listener = WebMidi.inputs[0].addListener("midimessage", e => {
  console.log(e);
});

Calling the function with an input-wide event (such as "midimessage"), will return the Listener object that was created.

If you call the function with a channel-specific event (such as "noteon"), it will return an array of all Listener objects that were created (one for each channel):

const listeners = WebMidi.inputs[0].addListener("noteon", someFunction);

You can also specify which channels you want to add the listener to:

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

In this case, listeners is an array containing 3 Listener objects.

Note that, when adding channel-specific listeners, it is the InputChannel instance that actually gets a listener added and not the Input instance. You can check that by calling InputChannel.hasListener().

There are 8 families of events you can listen to:

1. MIDI System Common Events (input-wide)

   • songposition
   • songselect
   • sysex
   • timecode
   • tunerequest

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

   • clock
   • start
   • continue
   • stop
   • activesensing
   • reset

3. State Change Events (input-wide)

   • opened
   • closed
   • disconnected

4. Catch-All Events (input-wide)

   • midimessage
   • unknownmidimessage

5. Channel Voice Events (channel-specific)

   • channelaftertouch
   • controlchange
     • controlchange-controller0
     • controlchange-controller1
     • controlchange-controller2
     • (...)
     • controlchange-controller127
   • keyaftertouch
   • noteoff
   • noteon
   • pitchbend
   • programchange

   Note: you can listen for a specific control change message by using an event name like this: controlchange-controller23, controlchange-controller99, controlchange-controller122, etc.

6. Channel Mode Events (channel-specific)

   • allnotesoff
   • allsoundoff
   • localcontrol
   • monomode
   • omnimode
   • resetallcontrollers

7. NRPN Events (channel-specific)

   • nrpn
   • nrpn-dataentrycoarse
   • nrpn-dataentryfine
   • nrpn-databuttonincrement
   • nrpn-databuttondecrement

8. RPN Events (channel-specific)

   • rpn
   • rpn-dataentrycoarse
   • rpn-dataentryfine
   • rpn-databuttonincrement
   • rpn-databuttondecrement

Parameters

Signature: addListener(event, listener, [options])

Parameter	Type(s)	Default	Description
event	string EventEmitter.ANY_EVENT		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	{}
[options.arguments]	array		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.
[options.channels]	number Array.<number>	[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]	An integer between 1 and 16 or an array of such integers representing the MIDI channel(s) to listen on. If no channel is specified, all channels will be used. This parameter is ignored for input-wide events.
[options.context]	object	this	The value of this in the callback function.
[options.duration]	number	Infinity	The number of milliseconds before the listener automatically expires.
[options.prepend]	boolean	false	Whether the listener should be added at the beginning of the listeners array and thus be triggered before others.
[options.remaining]	number	Infinity	The number of times after which the callback should automatically be removed.

Return Value

Returns: Listener or Array.<Listener>

If the event is input-wide, a single Listener object is returned. If the event is channel-specific, an array of all the Listener objects is returned (one for each channel).

.addOneTimeListener(...)

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.

Calling the function with an input-wide event (such as "midimessage"), will return the Listener object that was created.

If you call the function with a channel-specific event (such as "noteon"), it will return an array of all Listener objects that were created (one for each channel):

const listeners = WebMidi.inputs[0].addOneTimeListener("noteon", someFunction);

You can also specify which channels you want to add the listener to:

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

In this case, the listeners variable contains an array of 3 Listener objects.

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 8 families of events you can listen to:

1. MIDI System Common Events (input-wide)

   • songposition
   • songselect
   • sysex
   • timecode
   • tunerequest

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

   • clock
   • start
   • continue
   • stop
   • activesensing
   • reset

3. State Change Events (input-wide)

   • opened
   • closed
   • disconnected

4. Catch-All Events (input-wide)

   • midimessage
   • unknownmidimessage

5. Channel Voice Events (channel-specific)

   • channelaftertouch
   • controlchange
     • controlchange-controller0
     • controlchange-controller1
     • controlchange-controller2
     • (...)
     • controlchange-controller127
   • keyaftertouch
   • noteoff
   • noteon
   • pitchbend
   • programchange

   Note: you can listen for a specific control change message by using an event name like this: controlchange-controller23, controlchange-controller99, controlchange-controller122, etc.

6. Channel Mode Events (channel-specific)

   • allnotesoff
   • allsoundoff
   • localcontrol
   • monomode
   • omnimode
   • resetallcontrollers

7. NRPN Events (channel-specific)

   • nrpn
   • nrpn-dataentrycoarse
   • nrpn-dataentryfine
   • nrpn-databuttonincrement
   • nrpn-databuttondecrement

8. RPN Events (channel-specific)

   • rpn
   • rpn-dataentrycoarse
   • rpn-dataentryfine
   • rpn-databuttonincrement
   • rpn-databuttondecrement

Parameters

Signature: addOneTimeListener(event, listener, [options])

Parameter	Type(s)	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	{}
[options.arguments]	array		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.
[options.channels]	number Array.<number>		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.
[options.context]	object	this	The value of this in the callback function.
[options.duration]	number	Infinity	The number of milliseconds before the listener automatically expires.
[options.prepend]	boolean	false	Whether the listener should be added at the beginning of the listeners array and thus be triggered before others.

Return Value

Returns: Array.<Listener>

An array of all Listener objects that were created.

.close()

Attributes: async

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().

Note: if what you want to do is stop events from being dispatched, you should use eventsSuspended instead.

Return Value

Returns: Promise.<Input>

The promise is fulfilled with the Input object

.destroy()

Attributes: async

Destroys the Input by removing all listeners, emptying the channels array and unlinking the MIDI subsystem. This is mostly for internal use.

Return Value

Returns: Promise.<void>

.emit(...)

Executes the callback function of all the Listener objects registered for a given event. The callback functions are passed the additional arguments passed to emit() (if any) followed by the arguments present in the arguments property of the Listener object (if any).

If the eventsSuspended property is true or the Listener.suspended property is true, the callback functions will not be executed.

This function returns an array containing the return values of each of the callbacks.

It should be noted that the regular listeners are triggered first followed by the global listeners (those added with EventEmitter.ANY_EVENT).

Parameters

Signature: emit(event, ...args)

Parameter	Type(s)	Default	Description
event	string		The event
args	*		Arbitrary number of arguments to pass along to the callback functions

Return Value

Returns: Array

An array containing the return value of each of the executed listener functions.

Throws:

• TypeError : The event parameter must be a string.

.getListenerCount(...)

Returns the number of listeners registered for a specific event.

Please note that global events (those added with EventEmitter.ANY_EVENT) do not count towards the remaining number for a "regular" event. To get the number of global listeners, specifically use EventEmitter.ANY_EVENT as the parameter.

Parameters

Signature: getListenerCount(event)

Parameter	Type(s)	Default	Description
event	string Symbol		The event which is usually a string but can also be the special EventEmitter.ANY_EVENT symbol.

Return Value

Returns: number

An integer representing the number of listeners registered for the specified event.

.getListeners(...)

Returns an array of all the Listener objects that have been registered for a specific event.

Please note that global events (those added with EventEmitter.ANY_EVENT) are not returned for "regular" events. To get the list of global listeners, specifically use EventEmitter.ANY_EVENT as the parameter.

Parameters

Signature: getListeners(event)

Parameter	Type(s)	Default	Description
event	string Symbol		The event to get listeners for.

Return Value

Returns: Array.<Listener>

An array of Listener objects.

.hasForwarder(...)

Checks whether the specified Forwarder object has already been attached to this input.

Parameters

Signature: hasForwarder(forwarder)

Parameter	Type(s)	Default	Description
forwarder	Forwarder		The Forwarder to check for (the Forwarder object is returned when calling addForwarder().

Return Value

Returns: boolean

.hasListener(...)

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

Parameters

Signature: hasListener(event, listener, [options])

Parameter	Type(s)	Default	Description
event	string Symbol		The type of the event.
listener	function		The callback function to check for.
[options]	object	{}
[options.channels]	number Array.<number>		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.

Return Value

Returns: boolean

Boolean value indicating whether or not the Input or InputChannel already has this listener defined.

.open()

Attributes: async

Opens the input for usage. This is usually unnecessary as the port is opened automatically when WebMidi is enabled.

Return Value

Returns: Promise.<Input>

The promise is fulfilled with the Input object.

.removeForwarder(...)

Removes the specified Forwarder object from the input.

Parameters

Signature: removeForwarder(forwarder)

Parameter	Type(s)	Default	Description
forwarder	Forwarder		The Forwarder to remove (the Forwarder object is returned when calling addForwarder().

.removeListener(...)

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 InputChannel objects will be removed.

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

Parameters

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

Parameter	Type(s)	Default	Description
[type]	string		The type of the event.
[listener]	function		The callback function to check for.
[options]	object	{}
[options.channels]	number Array.<number>		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.
[options.context]	*		Only remove the listeners that have this exact context.
[options.remaining]	number		Only remove the listener if it has exactly that many remaining times to be executed.

.suspendEvent(...)

Suspends execution of all callbacks functions registered for the specified event type.

You can suspend execution of callbacks registered with EventEmitter.ANY_EVENT by passing EventEmitter.ANY_EVENT to suspendEvent(). Beware that this will not suspend all callbacks but only those registered with EventEmitter.ANY_EVENT. While this may seem counter-intuitive at first glance, it allows the selective suspension of global listeners while leaving other listeners alone. If you truly want to suspends all callbacks for a specific EventEmitter, simply set its eventsSuspended property to true.

Parameters

Signature: suspendEvent(event)

Parameter	Type(s)	Default	Description
event	string Symbol		The event name (or EventEmitter.ANY_EVENT) for which to suspend execution of all callback functions.

.unsuspendEvent(...)

Resumes execution of all suspended callback functions registered for the specified event type.

You can resume execution of callbacks registered with EventEmitter.ANY_EVENT by passing EventEmitter.ANY_EVENT to unsuspendEvent(). Beware that this will not resume all callbacks but only those registered with EventEmitter.ANY_EVENT. While this may seem counter-intuitive, it allows the selective unsuspension of global listeners while leaving other callbacks alone.

Parameters

Signature: unsuspendEvent(event)

Parameter	Type(s)	Default	Description
event	string Symbol		The event name (or EventEmitter.ANY_EVENT) for which to resume execution of all callback functions.

.waitFor(...)

Attributes: async

The waitFor() method is an async function which returns a promise. The promise is fulfilled when the specified event occurs. The event can be a regular event or EventEmitter.ANY_EVENT (if you want to resolve as soon as any event is emitted).

If the duration option is set, the promise will only be fulfilled if the event is emitted within the specified duration. If the event has not been fulfilled after the specified duration, the promise is rejected. This makes it super easy to wait for an event and timeout after a certain time if the event is not triggered.

Parameters

Signature: waitFor(event, [options])

Parameter	Type(s)	Default	Description
event	string Symbol		The event to wait for
[options]	Object	{}
[options.duration]	number	Infinity	The number of milliseconds to wait before the promise is automatically rejected.

---

Events

activesensing

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

Since: 2.1

Event Properties

Property	Type	Description
port	Input	The Input that triggered the event.
target	Input	The object that dispatched the event.
message	Message	A Message object containing information about the incoming MIDI message.
timestamp	number	The moment (DOMHighResTimeStamp) when the event occurred (in milliseconds since the navigation start of the document).
type	string	activesensing

clock

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

Since: 2.1

Event Properties

Property	Type	Description
port	Input	The Input that triggered the event.
target	Input	The object that dispatched the event.
message	Message	A Message object containing information about the incoming MIDI message.
timestamp	number	The moment (DOMHighResTimeStamp) when the event occurred (in milliseconds since the navigation start of the document).
type	string	clock

closed

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

Event Properties

Property	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 dispatched the event.
port	Input	The Input that triggered the event.

continue

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

Since: 2.1

Event Properties

Property	Type	Description
port	Input	The Input that triggered the event.
target	Input	The object that dispatched the event.
message	Message	A Message object containing information about the incoming MIDI message.
timestamp	number	The moment (DOMHighResTimeStamp) when the event occurred (in milliseconds since the navigation start of the document).
type	string	continue

disconnected

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

Event Properties

Property	Type	Description
timestamp	number	The moment (DOMHighResTimeStamp) when the event occurred (in milliseconds since the navigation start of the document).
type	string	disconnected
port	Input	Object with properties describing the Input that was disconnected. This is not the actual Input as it is no longer available.
target	Input	The object that dispatched the event.

midimessage

Event emitted when any MIDI message is received on an Input.

Since: 2.1

Event Properties

Property	Type	Description
port	Input	The Input that triggered the event.
target	Input	The object that dispatched the event.
message	Message	A Message object containing information about the incoming MIDI message.
timestamp	number	The moment (DOMHighResTimeStamp) when the event occurred (in milliseconds since the navigation start of the document).
type	string	midimessage

opened

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

Event Properties

Property	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 dispatched the event.
port	Input	The Input that triggered the event.

reset

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

Since: 2.1

Event Properties

Property	Type	Description
port	Input	The Input that triggered the event.
target	Input	The object that dispatched the event.
message	Message	A Message object containing information about the incoming MIDI message.
timestamp	number	The moment (DOMHighResTimeStamp) when the event occurred (in milliseconds since the navigation start of the document).
type	string	reset

songposition

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

Since: 2.1

Event Properties

Property	Type	Description
port	Input	The Input that triggered the event.
target	Input	The object that dispatched the event.
message	Message	A Message object containing information about the incoming MIDI message.
timestamp	number	The moment (DOMHighResTimeStamp) when the event occurred (in milliseconds since the navigation start of the document).
type	string	songposition

songselect

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

Since: 2.1

Event Properties

Property	Type	Description
port	Input	The Input that triggered the event.
target	Input	The object that dispatched the event.
message	Message	A Message object containing information about the incoming MIDI message.
timestamp	number	The moment (DOMHighResTimeStamp) when the event occurred (in milliseconds since the navigation start of the document).
value	string	Song (or sequence) number to select (0-127)
rawValue	string	Song (or sequence) number to select (0-127)

start

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

Since: 2.1

Event Properties

Property	Type	Description
port	Input	The Input that triggered the event.
target	Input	The object that dispatched the event.
message	Message	A Message object containing information about the incoming MIDI message.
timestamp	number	The moment (DOMHighResTimeStamp) when the event occurred (in milliseconds since the navigation start of the document).
type	string	start

stop

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

Since: 2.1

Event Properties

Property	Type	Description
port	Input	The Input that triggered the event.
target	Input	The object that dispatched the event.
message	Message	A Message object containing information about the incoming MIDI message.
timestamp	number	The moment (DOMHighResTimeStamp) when the event occurred (in milliseconds since the navigation start of the document).
type	string	stop

sysex

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."))

Event Properties

Property	Type	Description
port	Input	The Input that triggered the event.
target	Input	The object that dispatched the event.
message	Message	A Message object containing information about the incoming MIDI message.
timestamp	number	The moment (DOMHighResTimeStamp) when the event occurred (in milliseconds since the navigation start of the document).
type	string	sysex

timecode

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

Since: 2.1

Event Properties

Property	Type	Description
port	Input	The Input that triggered the event.
target	Input	The object that dispatched the event.
message	Message	A Message object containing information about the incoming MIDI message.
timestamp	number	The moment (DOMHighResTimeStamp) when the event occurred (in milliseconds since the navigation start of the document).
type	string	timecode

tunerequest

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

Since: 2.1

Event Properties

Property	Type	Description
port	Input	The Input that triggered the event.
target	Input	The object that dispatched the event.
message	Message	A Message object containing information about the incoming MIDI message.
timestamp	number	The moment (DOMHighResTimeStamp) when the event occurred (in milliseconds since the navigation start of the document).
type	string	tunerequest

unknownmessage

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

Since: 2.1

Event Properties

Property	Type	Description
port	Input	The Input that triggered the event.
target	Input	The object that dispatched the event.
message	Message	A Message object containing information about the incoming MIDI message.
timestamp	number	The moment (DOMHighResTimeStamp) when the event occurred (in milliseconds since the navigation start of the document).
type	string	unknownmessage