Input

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

Type

Array.<InputChannel>

Source

Input.js, line 59

---

<readonly> connection :string

Description

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

Details

Type

string

Source

Input.js, line 899

---

<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

Type

string

Source

Input.js, line 889

---

<readonly> manufacturer :string

Description

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

Details

Type

string

Source

Input.js, line 909

---

<readonly> name :string

Description

Name of the MIDI input

Details

Type

string

Source

Input.js, line 877

---

<readonly> state :string

Description

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

Details

Type

string

Source

Input.js, line 919

---

<readonly> type :string

Description

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

Details

Type

string

Source

Input.js, line 929

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)

   • 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
   • keyaftertouch
   • noteoff
   • noteon
   • nrpn
   • pitchbend
   • programchange

6. Channel Mode Events (channel-specific)

   • channelmode
   • To be completed...

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

Array.<Listener>

An array of all Listener objects that were created.

Throws

Error

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

Details

Source

Input.js, line 601

---

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)

   • 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
   • keyaftertouch
   • noteoff
   • noteon
   • nrpn
   • pitchbend
   • programchange

6. Channel Mode Events (channel-specific)

   • channelmode
   • To be completed...

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

Array.<Listener>

An array of all Listener objects that were created.

Throws

Error

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

Details

Source

Input.js, line 742

---

<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

Promise.<(void|*)>

Details

Source

Input.js, line 470

---

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

Description

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

Returns

Promise.<void>

Details

Source

Input.js, line 74

---

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

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

Source

Input.js, line 777

---

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

Description

Opens the input for usage.

Returns

Promise.<Input>

The promise is fulfilled with the Input

Details

Source

Input.js, line 449

---

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

Source

Input.js, line 833

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

Type

Object

Source

Input.js, line 391

---

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

Type

Object

Source

Input.js, line 327

---

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

Type

Object

Source

Input.js, line 115

---

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

Type

Object

Source

Input.js, line 359

---

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

Type

Object

Source

Input.js, line 131

---

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

Type

Object

Since

2.1

Source

Input.js, line 179

---

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

Type

Object

Source

Input.js, line 99

---

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

Type

Object

Source

Input.js, line 407

---

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

Type

Object

Source

Input.js, line 277

---

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

Type

Object

Source

Input.js, line 293

---

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

Type

Object

Source

Input.js, line 343

---

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

Type

Object

Source

Input.js, line 375

---

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

Type

Object

Source

Input.js, line 236

---

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

Type

Object

Source

Input.js, line 260

---

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

Type

Object

Source

Input.js, line 311

---

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

Type

Object

Source

Input.js, line 423