TherequestMIDIAccess() method of theNavigator interface returns aPromise representing a request for access to MIDI devices on a user's system.This method is part of theWeb MIDI API, which provides a means for accessing, enumerating, and manipulating MIDI devices.

This method may prompt the user for access to MIDI devices available to their system, or it may use a previously established preference to grant or deny access.If permission is granted then thePromise resolves and aMIDIAccess object is returned.

Syntax

requestMIDIAccess()requestMIDIAccess(MIDIOptions)

Parameters

MIDIOptionsOptional

AnObject representing options to pass into the method. These options are:

sysex

ABoolean value that, if set totrue, allows the ability to send and receive system exclusive (sysex) messages. The default value isfalse.

software

ABoolean value that, if set totrue, allows the system to utilize any installed software synthesizers. The default value isfalse.

Return value

APromise that resolves with aMIDIAccess object.

Exceptions

AbortErrorDOMException

Thrown if the document or page is closed due to user navigation.

InvalidStateErrorDOMException

Thrown if the underlying system raises any errors.

NotSupportedErrorDOMException

Thrown if the feature or options are not supported by the system.

NotAllowedErrorDOMException

Thrown if the user or system denies the application from creating aMIDIAccess object with the requested options, or if the document is not allowed to use the feature (for example, because of aPermission Policy, or because the user previously denied a permission request).

Security requirements

Access to the API is subject to the following constraints:

• The method must be called in asecure context.
• Access may be gated by themidi HTTPPermission Policy.
• The user must explicitly grant permission to use the API though a user-agent specific mechanism, or have previously granted permission.Note that if access is denied by a permission policy it cannot be granted by a user permission.

The permission status can be queried using thePermissions API methodnavigator.permissions.query(), passing a permission descriptor with themidi permission and (optional)sysex property:

navigator.permissions.query({ name: "midi", sysex: true }).then((result) => {  if (result.state === "granted") {    // Access granted.  } else if (result.state === "prompt") {    // Using API will prompt for permission  }  // Permission was denied by user prompt or permission policy});

Examples

Request MIDI access

In the following example, theNavigator.requestMIDIAccess() method returns theMIDIAccess object, which gives access to information about the input and output MIDI ports.

navigator.requestMIDIAccess().then((access) => {  // Get lists of available MIDI controllers  const inputs = access.inputs.values();  const outputs = access.outputs.values();  // …});

Specifications

Browser compatibility

See also

• Web MIDI API
• Introduction to Web MIDI