Members
-
<readonly> enabled :boolean
-
Description
Indicates whether access to the host's MIDI subsystem is active or not.
Details
-
<readonly> inputs :Array
-
Description
An array of all currently available MIDI inputs.
Details
-
<readonly, nullable> interface :MIDIAccess
-
Description
The
MIDIAccess
instance used to talk to the Web MIDI API. This should not be used directly unless you know what you are doing.Details
-
isBrowser :boolean
-
Description
Indicates whether the current environment is a browser environment or not. If you need to check if we are in Node.js, use isNode. In certain environments (such as Electron and NW.js) isNode and isBrowser can both be true at the same time.
Details
-
isNode :boolean
-
Description
Indicates whether the current environment is Node.js or not. If you need to check if we are in browser, use isBrowser. In certain environments (such as Electron and NW.js) isNode and isBrowser can both be true at the same time.
Details
-
<readonly> MIDI_CHANNEL_MESSAGES :Object.<string, number>
-
Description
Enum of all MIDI channel voice messages and their associated numerical value. Note that it has been deprecated since v3.0. You should now use MIDI_CHANNEL_VOICE_MESSAGES.
Details
-
<readonly> MIDI_CHANNEL_MODE_MESSAGES :Object.<string, number>
-
Description
Enum of all channel mode messages and their associated numerical value:
allsoundoff
: 120resetallcontrollers
: 121localcontrol
: 122allnotesoff
: 123omnimodeoff
: 124omnimodeon
: 125monomodeon
: 126polymodeon
: 127
Details
-
<readonly> MIDI_CHANNEL_VOICE_MESSAGES :Object.<string, number>
-
Description
Enum of all MIDI channel voice messages and their associated numerical value:
noteoff
: 0x8 (8)noteon
: 0x9 (9)keyaftertouch
: 0xA (10)controlchange
: 0xB (11)channelmode
: 0xB (11)nrpn
: 0xB (11)programchange
: 0xC (12)channelaftertouch
: 0xD (13)pitchbend
: 0xE (14)
Details
-
<readonly> MIDI_CONTROL_CHANGE_MESSAGES :Object.<string, number>
-
Description
Enum of all control change messages and their associated numerical value:
bankselectcoarse
: 0modulationwheelcoarse
: 1breathcontrollercoarse
: 2footcontrollercoarse
: 4portamentotimecoarse
: 5dataentrycoarse
: 6volumecoarse
: 7balancecoarse
: 8pancoarse
: 10expressioncoarse
: 11effectcontrol1coarse
: 12effectcontrol2coarse
: 13generalpurposeslider1
: 16generalpurposeslider2
: 17generalpurposeslider3
: 18generalpurposeslider4
: 19bankselectfine
: 32modulationwheelfine
: 33breathcontrollerfine
: 34footcontrollerfine
: 36portamentotimefine
: 37dataentryfine
: 38volumefine
: 39balancefine
: 40panfine
: 42expressionfine
: 43effectcontrol1fine
: 44effectcontrol2fine
: 45holdpedal
: 64portamento
: 65sustenutopedal
: 66softpedal
: 67legatopedal
: 68hold2pedal
: 69soundvariation
: 70resonance
: 71soundreleasetime
: 72soundattacktime
: 73brightness
: 74soundcontrol6
: 75soundcontrol7
: 76soundcontrol8
:`77soundcontrol9
: 78soundcontrol10
: 79generalpurposebutton1
: 80generalpurposebutton2
: 81generalpurposebutton3
: 82generalpurposebutton4
: 83reverblevel
: 91tremololevel
: 92choruslevel
: 93celestelevel
: 94phaserlevel
: 95databuttonincrement
: 96databuttondecrement
: 97nonregisteredparametercoarse
: 98nonregisteredparameterfine
: 99registeredparametercoarse
: 100registeredparameterfine
: 101
Details
-
<readonly> MIDI_INTERFACE_EVENTS :Array.<string>
-
Description
Array of valid events triggered at the interface level.
Details
-
<readonly> MIDI_NRPN_MESSAGES :Object.<string, number>
-
Description
Enum of all control change messages that are used to create NRPN messages and their associated numerical value:
entrymsb
: 6entrylsb
: 38increment
: 96decrement
: 97paramlsb
: 98parammsb
: 99nullactiveparameter
: 127
Details
-
<readonly> MIDI_REGISTERED_PARAMETER :Object.<string, number>
-
Description
Enum of all registered parameters and their associated pair of numerical values. MIDI registered parameters extend the original list of control change messages. Currently, there are only a limited number of them:
pitchbendrange
: [0x00, 0x00]channelfinetuning
: [0x00, 0x01]channelcoarsetuning
: [0x00, 0x02]tuningprogram
: [0x00, 0x03]tuningbank
: [0x00, 0x04]modulationrange
: [0x00, 0x05]azimuthangle
: [0x3D, 0x00]elevationangle
: [0x3D, 0x01]gain
: [0x3D, 0x02]distanceratio
: [0x3D, 0x03]maximumdistance
: [0x3D, 0x04]maximumdistancegain
: [0x3D, 0x05]referencedistanceratio
: [0x3D, 0x06]panspreadangle
: [0x3D, 0x07]rollangle
: [0x3D, 0x08]
Details
-
<readonly> MIDI_SYSTEM_MESSAGES :Object.<string, number>
-
Description
Enum of all valid MIDI system messages and matching numerical values. WebMidi.js also uses two custom messages.
System common messages
sysex
: 0xF0 (240)timecode
: 0xF1 (241)songposition
: 0xF2 (242)songselect
: 0xF3 (243)tunerequest
: 0xF6 (246)sysexend
: 0xF7 (247)
The
sysexend
message is never actually received. It simply ends a sysex stream.System real-time messages
clock
: 0xF8 (248)start
: 0xFA (250)continue
: 0xFB (251)stop
: 0xFC (252)activesensing
: 0xFE (254)reset
: 0xFF (255)
Values 249 and 253 are actually relayed by the Web MIDI API but they do not serve a specific purpose. The MIDI 1.0 spec simply states that they are undefined/reserved.
Custom WebMidi.js messages
midimessage
: 0unknownsystemmessage
: -1
Details
-
<readonly> NOTES :Array.<string>
-
Description
Array of standard note names
Details
-
octaveOffset :number
-
Description
An integer to offset the octave both in inbound and outbound messages. 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. IfoctaveOffset
is set to -1, MIDI note number 60 will be reported as C3.Details
-
<readonly> outputs :Array
-
Description
An array of all currently available MIDI outputs.
Details
-
<readonly> supported :boolean
-
Description
Indicates whether the environment provides support for the Web MIDI API or not.
Note: in environments that do not offer built-in MIDI support, this will report
true
if thenavigator.requestMIDIAccess
function is available. For example, if you have installed WebMIDIAPIShim.js but no plugin, this property will betrue
even though actual support might not be there.Details
-
<readonly> sysexEnabled :Boolean
-
Description
Indicates whether MIDI system exclusive messages have been activated when WebMidi.js was enabled via the
enable()
method.Details
-
<readonly> time :DOMHighResTimeStamp
-
Description
The elapsed time, in milliseconds, since the time origin. Said simply, it is the number of milliseconds that passed since the page was loaded. Being a floating-point number, it has sub-millisecond accuracy. According to the documentation, the time should be accurate to 5 µs (microseconds). However, due to various constraints, the browser might only be accurate to one millisecond.
Details
-
validation :boolean
-
Description
Indicates whether argument validation and backwards-compatibility checks are performed throughout the WebMidi.js library for object methods and property setters.
This is an advanced setting that should be used carefully. Setting
validation
tofalse
improves performance but should only be done once the project has been thoroughly tested with validation turned on.Details
Methods
-
convertToTimestamp( [ time ] ) → {number}
-
Description
Returns a valid timestamp, relative to the navigation start of the document, derived from the
time
parameter. If the parameter is a string starting with the "+" sign and followed by a number, the resulting timestamp will be the sum of the current timestamp plus that number. If the parameter is a positive number, it will be returned as is. Otherwise, false will be returned.Parameters
Name Type Attributes Description time
number | string <optional> The time string (e.g.
"+2000"
) or number to parseReturns
Details
-
<async> disable() → {Promise.<void>}
-
<async> enable( [ options ] ) → {Promise.<Object>}
-
Description
Checks if the Web MIDI API is available in the current environment and then tries to connect to the host's MIDI subsystem. This is an asynchronous operation and it causes a security prompt to be displayed to the user.
To enable the use of MIDI system exclusive messages, the
sysex
option should be set totrue
. However, under some environments (e.g. Jazz-Plugin), thesysex
option is ignored and system exclusive messages are always enabled. You can check the sysexEnabled property to confirm.To enable access to software synthesizers available on the host, you would set the
software
option totrue
. However, this option is only there to future-proof the library as support for software synths has not yet been implemented in any browser (as of April 2020).There are 3 ways to execute code after
WebMidi
has been enabled:- Pass a callback function in the options
- Listen to the
enabled
event - Wait for the promise to resolve
In order, this is what happens towards the end of the enabling process:
- callback is executed
enabled
event is triggeredconnected
events from available inputs and outputs are triggered- promise is resolved
The promise is fulfilled with an object containing two properties (
inputs
andoutputs
) that contain arrays of available inputs and outputs, respectively.Important note: starting with Chrome v77, a page using Web MIDI API must be hosted on a secure origin (
https://
,localhost
orfile:///
) and the user will always be prompted to authorize the operation (no matter if thesysex
option istrue
or not).Examples
// Enabling WebMidi and using the promise WebMidi.enable().then(ports => { console.log("WebMidi.js has been enabled!"); console.log("Inputs: ", ports.inputs); console.log("Outputs: ", ports.outputs); })
// Enabling WebMidi and listening to 'enabled' event WebMidi.addListener("enabled", e => { console.log("WebMidi.js has been enabled!"); }); WebMidi.enable();
// Enabling WebMidi and using callback function WebMidi.enable({callback: e => { console.log("WebMidi.js has been enabled!"); });
Parameters
Name Type Attributes Description options
Object <optional> Name Type Attributes Default Description callback
function <optional> A function to execute once the operation completes. This function will receive an
Error
object if enabling the Web MIDI API failed.sysex
boolean <optional> false Whether to enable MIDI system exclusive messages or not.
validation
boolean <optional> true Whether to enable library-wide validation of method arguments and setter values. This is an advanced setting that should be used carefully. Setting
validation
tofalse
improves performance but should only be done once the project has been thoroughly tested with validation turned on.software
boolean <optional> false Whether to request access to software synthesizers on the host system. This is part of the spec but has not yet been implemented by most browsers as of April 2020.
Returns
Throws
Details
-
getInputById( id ) → {Input|false}
-
Description
Returns the Input object that matches the specified ID string or
false
if no matching input is found. As per the Web MIDI API specification, IDs are strings (not integers).Please note that IDs change from one host to another. For example, Chrome does not use the same kind of IDs as Jazz-Plugin.
Parameters
Name Type Description id
string The ID string of the input. IDs can be viewed by looking at the inputs array. Even though they sometimes look like integers, IDs are strings.
Returns
Throws
Details
-
getInputByName( name ) → {Input|false}
-
Description
Returns the first Input object whose name contains the specified string. Note that the port names change from one environment to another. For example, Chrome does not report input names in the same way as the Jazz-Plugin does.
Parameters
Name Type Description name
string The non-empty string to look for within the name of MIDI inputs (such as those visible in the inputs array).
Returns
Throws
Details
-
getNoteNumberByName( name ) → {number|false}
-
Description
Returns a MIDI note number matching the note name passed in the form of a string parameter. The note name must include the octave number. The name can also optionally include a sharp (#), a double sharp (##), a flat (b) or a double flat (bb) symbol. For example, these are all valid names: C5, G4, D#-1, F0, Gb7, Eb-1, Abb4, B##6, etc.
When converting note names to numbers, C4 is considered to be middle C (MIDI note number 60) as per the scientific pitch notation standard.
The resulting note number is offset by the octaveOffset value (if not zero). For example, if you pass in "C4" and the octaveOffset value is 2, the resulting MIDI note number will be 36.
Note: since v3.x, this function returns
false
instead of throwing an error when it cannot parse the name to a number.Parameters
Name Type Description name
string The name of the note in the form of a letter, followed by an optional "#", "##", "b" or "bb" followed by the octave number.
Returns
Details
-
getNoteObject( [ notes [, options ] ] ) → {Note}
-
Description
Converts the
note
parameter to a valid Note object. The input usually is an unsigned integer (0-127) or a note name ("C4"
,"G#5"
, etc.). If the input is a Note object, it will be returned as is.If the input is a note number or name, it is possible to specify options by providing the optional
options
parameter.An error is thrown for invalid input.
Parameters
Name Type Attributes Default Description notes
number | string | Note <optional> options
Object <optional> {} Name Type Attributes Default Description duration
number <optional> Infinity The number of milliseconds before the note should be explicitly stopped.
attack
number <optional> 0.5 The note's attack velocity as a decimal number between 0 and 1.
release
number <optional> 0.5 The note's release velocity as a decimal number between 0 and 1.
rawAttack
number <optional> 64 The note's attack velocity as an integer between 0 and 127.
rawRelease
number <optional> 64 The note's release velocity as an integer between 0 and 127.
Returns
Throws
Details
-
getOctave( number ) → {number|false}
-
Description
Returns the octave number for the specified MIDI note number (0-127). By default, the value is based on middle C (note number 60) being placed on the 4th octave (C4). However, by using the octaveOffset property, you can offset the result as desired.
Note: since v3.x, this method returns
false
instead ofundefined
when the value cannot be parsed to a valid octave.Parameters
Name Type Description number
number An integer representing a valid MIDI note number (between 0 and 127).
Returns
Details
-
getOutputById( id ) → {Output|false}
-
Description
Returns the Output object that matches the specified ID string or
false
if no matching output is found. As per the Web MIDI API specification, IDs are strings (not integers).Please note that IDs change from one host to another. For example, Chrome does not use the same kind of IDs as Jazz-Plugin.
Parameters
Name Type Description id
string The ID string of the port. IDs can be viewed by looking at the outputs array.
Returns
Throws
Details
-
getOutputByName( name ) → {Output|false}
-
Description
Returns the first Output object whose name contains the specified string. Note that the port names change from one environment to another. For example, Chrome does not report input names in the same way as the Jazz-Plugin does.
Parameters
Name Type Description name
string The non-empty string to look for within the name of MIDI inputs (such as those visible in the outputs array).
Returns
Throws
Details
-
getValidNoteArray( [ notes [, options ] ] ) → {Array.<Note>}
-
Description
Converts an input value, which can be an unsigned integer (0-127), a note name, a Note object or an array of the previous types, to an array of Note objects.
Note objects are returned as is. For note numbers and names, a Note object is created with the options specified. An error will be thrown when encountering invalid input.
Parameters
Name Type Attributes Default Description notes
number | string | Note | Array.<number> | Array.<string> | Array.<Note> <optional> options
Object <optional> {} Name Type Attributes Default Description duration
number <optional> Infinity The number of milliseconds before the note should be explicitly stopped.
attack
number <optional> 0.5 The note's attack velocity as a decimal number between 0 and 1.
release
number <optional> 0.5 The note's release velocity as a decimal number between 0 and 1.
rawAttack
number <optional> 64 The note's attack velocity as an integer between 0 and 127.
rawRelease
number <optional> 64 The note's release velocity as an integer between 0 and 127.
Returns
Throws
Details
-
guessNoteNumber( input ) → {number|false}
-
Description
Returns a valid MIDI note number (0-127) given the specified input. The parameter usually is a string containing a note name (
"C3"
,"F#4"
,"D-2"
,"G8"
, etc.). If an integer between 0 and 127 is passed, it will simply be returned as is (for convenience). Other strings will be parsed for integer, if possible.Note: since v3.x, this method returns
false
instead of throwing an error when the input is invalid.Parameters
Name Type Description input
string | number A string to extract the note number from. An integer can also be used, in this case it will simply be returned as is (if between 0 and 127).
Returns
Details
-
sanitizeChannels( [ channel ] ) → {Array}
-
Description
Returns a sanitized array of valid MIDI channel numbers (1-16). The parameter should be a single integer or an array of integers.
For backwards-compatibility, passing
undefined
as a parameter to this method results in all channels being returned (1-16). Otherwise, parameters that cannot successfully be parsed to integers between 1 and 16 are silently ignored.Parameters
Name Type Attributes Description channel
number | Array.<number> <optional> An integer or an array of integers to parse as channel numbers.
Returns
Details
Events
-
connected
-
disabled
-
Description
Event emitted once
WebMidi
has been successfully disabled.Properties
Name Type Description timestamp
DOMHighResTimeStamp The moment when the event occurred (in milliseconds since the navigation start of the document).
target
WebMidi The object that triggered the event
type
string disabled
Details
-
disconnected
-
Description
Properties
Name Type Description timestamp
DOMHighResTimeStamp The moment when the event occurred (in milliseconds since the navigation start of the document).
type
string disconnected
target
Object Object with properties describing the Input or {@Output} that triggered the event.
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
oroutput
Details
-
enabled
-
Description
Event emitted once
WebMidi
has been successfully enabled.Properties
Name Type Description timestamp
DOMHighResTimeStamp The moment when the event occurred (in milliseconds since the navigation start of the document).
target
WebMidi The object that triggered the event
type
string enabled
Details