Input Class
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.
Item Index
Methods
Properties
Methods
_initializeUserHandlers
()
protected
_onMidiMessage
()
protected
_parseNrpnEvent
-
e
Parses channel events and constructs NRPN message parts in valid sequences. Keeps a separate NRPN buffer for each channel. Emits an event after it receives the final CC parts msb 127 lsb 127. If a message is incomplete and other messages are received before the final 127 bytes, the incomplete message is cleared.
Parameters:
-
e
ObjectEvent
_parseSystemEvent
()
protected
addListener
-
type
-
channel
-
listener
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:
- sysex
- timecode
- songposition
- songselect
- tuningrequest
- clock
- start
- continue
- stop
- activesensing
- reset
- midimessage
- unknownsystemmessage
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
StringThe type of the event.
-
channel
Number | Array | StringThe 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
FunctionA 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:
Returns the WebMidi
object so methods can be chained.
Throws:
The specified event type is not supported.
getCcNameByNumber
-
number
Returns the name of a control change message matching the specified number. If no match is
found, the function returns undefined
.
Parameters:
-
number
NumberThe number of the control change message.
Returns:
The matching control change name or undefined
.
Throws:
RangeError The control change number must be between 0 and 119.
getChannelModeByNumber
-
number
Returns the channel mode name matching the specified number. If no match is found, the function
returns undefined
.
Parameters:
-
number
NumberThe number of the channel mode message.
Returns:
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
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:
Returns:
Boolean value indicating whether or not the channel(s) already have this listener defined.
Throws:
The "listener" parameter must be a function.
removeListener
-
[type]
-
[channel]
-
[listener]
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:
Returns:
The Input
object for easy method chaining.
Throws:
The "listener" parameter must be a function..
Properties
id
String
[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
[read-only] Name of the manufacturer of the device that makes this port available.
Events
activesensing
Event emitted when a system active sensing MIDI message has been received.
Event Payload:
-
event
Object-
target
InputThe
Input
that triggered the event. -
data
Uint8ArrayThe raw MIDI message as an array of 8 bit values.
-
timestamp
NumberThe time when the event occurred (in milliseconds)
-
type
StringThe type of event that occurred.
-
channelaftertouch
Event emitted when a channel-wide aftertouch MIDI message has been received on a specific device and channel.
Event Payload:
-
event
Object-
target
InputThe
Input
that triggered the event. -
data
Uint8ArrayThe raw MIDI message as an array of 8 bit values.
-
timestamp
NumberThe time when the event occurred (in milliseconds)
-
channel
UintThe channel where the event occurred (between 1 and 16).
-
type
StringThe type of event that occurred.
-
value
NumberThe aftertouch value received (between 0 and 1).
-
channelmode
Event emitted when a channel mode MIDI message has been received on a specific device and channel.
Event Payload:
-
event
Object-
target
InputThe
Input
that triggered the event. -
data
Uint8ArrayThe raw MIDI message as an array of 8 bit values.
-
timestamp
NumberThe time when the event occurred (in milliseconds)
-
channel
UintThe channel where the event occurred (between 1 and 16).
-
type
StringThe type of event that occurred.
-
controller
Object-
number
UintThe number of the controller. -
name
StringThe usual name or function of the controller.
-
-
value
UintThe value received (between 0 and 127).
-
clock
Event emitted when a system timing clock MIDI message has been received.
Event Payload:
-
event
Object-
target
InputThe
Input
that triggered the event. -
data
Uint8ArrayThe raw MIDI message as an array of 8 bit values.
-
timestamp
NumberThe time when the event occurred (in milliseconds)
-
type
StringThe type of event that occurred.
-
continue
Event emitted when a system continue MIDI message has been received.
Event Payload:
-
event
Object-
target
InputThe
Input
that triggered the event. -
data
Uint8ArrayThe raw MIDI message as an array of 8 bit values.
-
timestamp
NumberThe time when the event occurred (in milliseconds)
-
type
StringThe type of event that occurred.
-
controlchange
Event emitted when a control change MIDI message has been received on a specific device and channel.
Event Payload:
-
event
Object-
target
InputThe
Input
that triggered the event. -
data
Uint8ArrayThe raw MIDI message as an array of 8 bit values.
-
timestamp
NumberThe time when the event occurred (in milliseconds)
-
channel
UintThe channel where the event occurred (between 1 and 16).
-
type
StringThe type of event that occurred.
-
controller
Object-
number
UintThe number of the controller. -
name
StringThe usual name or function of the controller.
-
-
value
UintThe value received (between 0 and 127).
-
keyaftertouch
Event emitted when a key-specific aftertouch MIDI message has been received on a specific device and channel.
Event Payload:
-
event
Object-
target
InputThe
Input
that triggered the event. -
data
Uint8ArrayThe raw MIDI message as an array of 8 bit values.
-
timestamp
NumberThe time when the event occurred (in milliseconds)
-
channel
UintThe channel where the event occurred (between 1 and 16).
-
type
StringThe type of event that occurred.
-
note
Object-
number
UintThe MIDI note number. -
name
StringThe usual note name (C, C#, D, D#, etc.). -
octave
UintThe octave (between -2 and 8).
-
-
value
NumberThe aftertouch amount (between 0 and 1).
-
midimessage
Event emitted when a MIDI message is received. This should be used primarily for debugging purposes.
Event Payload:
-
event
Object-
target
InputThe
Input
that triggered the event. -
data
Uint8ArrayThe raw MIDI message as an array of 8 bit values.
-
timestamp
UintThe timestamp when the event occurred (in milliseconds since the Unix Epoch).
-
type
StringThe type of event that occurred.
-
noteoff
Event emitted when a note off MIDI message has been received on a specific device and channel.
Event Payload:
-
event
Object-
target
InputThe
Input
that triggered the event. -
data
Uint8ArrayThe raw MIDI message as an array of 8 bit values.
-
timestamp
NumberThe time when the event occurred (in milliseconds)
-
channel
UintThe channel where the event occurred (between 1 and 16).
-
type
StringThe type of event that occurred.
-
note
Object-
number
UintThe MIDI note number. -
name
StringThe usual note name (C, C#, D, D#, etc.). -
octave
UintThe octave (between -2 and 8).
-
-
velocity
NumberThe release velocity (between 0 and 1).
-
rawVelocity
NumberThe attack velocity expressed as a 7-bit integer (between 0 and 127).
-
noteon
Event emitted when a note on MIDI message has been received on a specific device and channel.
Event Payload:
-
event
Object-
target
InputThe
Input
that triggered the event. -
data
Uint8ArrayThe raw MIDI message as an array of 8 bit values.
-
timestamp
NumberThe time when the event occurred (in milliseconds)
-
channel
UintThe channel where the event occurred (between 1 and 16).
-
type
StringThe type of event that occurred.
-
note
Object-
number
UintThe MIDI note number. -
name
StringThe usual note name (C, C#, D, D#, etc.). -
octave
UintThe octave (between -2 and 8).
-
-
velocity
NumberThe attack velocity (between 0 and 1).
-
rawVelocity
NumberThe attack velocity expressed as a 7-bit integer (between 0 and 127).
-
pitchbend
Event emitted when a pitch bend MIDI message has been received on a specific device and channel.
Event Payload:
-
event
Object-
target
InputThe
Input
that triggered the event. -
data
Uint8ArrayThe raw MIDI message as an array of 8 bit values.
-
timestamp
NumberThe time when the event occurred (in milliseconds)
-
channel
UintThe channel where the event occurred (between 1 and 16).
-
type
StringThe type of event that occurred.
-
value
NumberThe pitch bend value received (between -1 and 1).
-
programchange
Event emitted when a program change MIDI message has been received on a specific device and channel.
Event Payload:
-
event
Object-
target
InputThe
Input
that triggered the event. -
data
Uint8ArrayThe raw MIDI message as an array of 8 bit values.
-
timestamp
NumberThe time when the event occurred (in milliseconds)
-
channel
UintThe channel where the event occurred (between 1 and 16).
-
type
StringThe type of event that occurred.
-
value
UintThe value received (between 0 and 127).
-
reset
Event emitted when a system reset MIDI message has been received.
Event Payload:
-
event
Object-
target
InputThe
Input
that triggered the event. -
data
Uint8ArrayThe raw MIDI message as an array of 8 bit values.
-
timestamp
NumberThe time when the event occurred (in milliseconds)
-
type
StringThe type of event that occurred.
-
songposition
Event emitted when a system song position pointer MIDI message has been received.
Event Payload:
-
event
Object-
target
InputThe
Input
that triggered the event. -
data
Uint8ArrayThe raw MIDI message as an array of 8 bit values.
-
timestamp
NumberThe time when the event occurred (in milliseconds)
-
type
StringThe type of event that occurred.
-
songselect
Event emitted when a system song select MIDI message has been received.
Event Payload:
start
Event emitted when a system start MIDI message has been received.
Event Payload:
-
event
Object-
target
InputThe
Input
that triggered the event. -
data
Uint8ArrayThe raw MIDI message as an array of 8 bit values.
-
timestamp
NumberThe time when the event occurred (in milliseconds)
-
type
StringThe type of event that occurred.
-
stop
Event emitted when a system stop MIDI message has been received.
Event Payload:
-
event
Object-
target
InputThe
Input
that triggered the event. -
data
Uint8ArrayThe raw MIDI message as an array of 8 bit values.
-
timestamp
NumberThe time when the event occurred (in milliseconds)
-
type
StringThe type of event that occurred.
-
sysex
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
InputThe
Input
that triggered the event. -
data
Uint8ArrayThe raw MIDI message as an array of 8 bit values.
-
timestamp
NumberThe time when the event occurred (in milliseconds)
-
type
StringThe type of event that occurred.
-
timecode
Event emitted when a system MIDI time code quarter frame message has been received.
Event Payload:
-
event
Object-
target
InputThe
Input
that triggered the event. -
data
Uint8ArrayThe raw MIDI message as an array of 8 bit values.
-
timestamp
NumberThe time when the event occurred (in milliseconds)
-
type
StringThe type of event that occurred.
-
tuningrequest
Event emitted when a system tune request MIDI message has been received.
Event Payload:
-
event
Object-
target
InputThe
Input
that triggered the event. -
data
Uint8ArrayThe raw MIDI message as an array of 8 bit values.
-
timestamp
NumberThe time when the event occurred (in milliseconds)
-
type
StringThe type of event that occurred.
-
unknownsystemmessage
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
InputThe
Input
that triggered the event. -
data
Uint8ArrayThe raw MIDI message as an array of 8 bit values.
-
timestamp
NumberThe time when the event occurred (in milliseconds)
-
type
StringThe type of event that occurred.
-