An Introduction to Web MIDI

MIDI is everywhere, from game consoles to audio hardware and music production software, and now it is available in JavaScript. This tutorial will get you up and running with Web MIDI.

This tutorial assumes you have experience with JavaScript programming and a basic understanding of MIDI, but it will cover some of the basics nonetheless.

What is MIDI?

MIDI, or Music Instrument Digital Interface, is a standard protocol that describes the way all MIDI compatible hardware and software communicates. In other words, it is the digital language that all MIDI compatible hardware and software uses to communicate.

The language is very expressive, it allows a lot of information to be packed into a small amount of space. The information can include everything from musical notes, key velocities and sustain pedal activity, through to stereo positioning and ADSR envelope data.

What is Web MIDI?

Web MIDI, a standard JavaScript API specified by the W3C, allows JavaScript to communicate with MIDI compatible devices that are connected to a user's computer.

When combined with Web Audio, these APIs provide a powerful set of tools that can be used to create a wide range of audio and music applications for the web.

The Basics

We are now going to take a look at the Web MIDI API and begin to construct the code that will allow us to send and receive some simple MIDI messages.

Detecting Browser Support

The first thing we need to do is make sure the web browser that is running our JavaScript code supports the standard Web MIDI API. This can be done easily enough by checking for the existence of the requestMIDIAccess function.

if (navigator.requestMIDIAccess !== undefined) {
  // Web MIDI is available.
} else {
  // Web MIDI is not available.
}

If the requestMIDIAccess function exists then Web MIDI is available for us to use, and we can ask the browser for access to the user's MIDI devices.

Requesting MIDI Access

Due to the nature of Web MIDI, some users may choose to deny JavaScript access to any MIDI devices that are connected to their computers, for privacy reasons. Because of that we must first request access to the MIDI devices and then handle the response appropriately.

if (navigator.requestMIDIAccess !== undefined) {
  navigator.requestMIDIAccess()
    .then(handleAccess, handleAccessError);
} else {
  console.warn("Web MIDI is not available");
}

/**
 * @param MIDIAccess access
 */
function handleAccess(access) {}

/**
 * @param Error error
 */
function handleAccessError(error) {
  console.warn("Web MIDI access was denied");
}

The requestMIDIAccess function returns a Promise that will succeed if MIDI access is permitted, and fail if MIDI access is denied. If the request is successful we will be provided with a MIDIAccess object that gives us access to any MIDI compatible devices connected to the user's computer.

MIDI Input and Output

MIDI devices are made available to our code in two flavors, input devices and output devices. Input devices may send our code MIDI messages, and our code may send MIDI messages to output devices. If a device can send and receive MIDI messages, it will be presented as an input device and an output device.

The MIDIAccess object exposes maps containing the available devices.

/**
 * @param MIDIAccess access
 */
function handleAccess(access) {
  printInputs(access.inputs);
  printOutputs(access.outputs);
}

/**
 * @param MIDIInputMap inputs
 */
function printInputs(inputs) {
  console.group("MIDI Input Devices");
  
  var i = 0;
  var n = inputs.size;
  
  while (i < n) {
    /** @type MIDIInput */
    var device = inputs.get(i);

    console.info(device.name);
    i ++;
  }
  
  console.groupEnd();
}

/**
 * @param MIDIOutputMap outputs
 */
function printOutputs(outputs) {
  console.group("MIDI Output Devices");
  
  var i = 0;
  var n = outputs.size;
  
  while (i < n) {
    /** @type MIDIOutput */
    var device = outputs.get(i);

    console.info(device.name);
    i ++;
  }
  
  console.groupEnd();
}

Each MIDIInput and MIDIOutput object represents a physical MIDI device, and provide information about the devices including the device name and the device manufacturer. That information could be used within a web application to present a list of usable devices to the user.

Receiving MIDI Messages

A MIDIInput object will dispatch a MIDIMessageEvent object whenever a MIDI message is sent from the physical device represented by the MIDIInput object. To receive MIDI messages from a device we simply add an event listener to the relevant MIDIInput object.

The following code will listen for MIDI messages sent from all input devices.

/**
 * @param MIDIAccess access
 */
function handleAccess(access) {
  addListeners(access.inputs);
}

/**
 * @param MIDIInputMap inputs
 */
function addListeners(inputs) {
  var i = 0;
  var n = inputs.size;
  
  while (i < n) {
    inputs.get(i).onmidimessage = handleMessage;
    i ++;
  }
}

/**
 * @param MIDIMessageEvent event
 */
function handleMessage(event) {}

A MIDIMessageEvent object has a data property that is a Uint8Array object containing three values. Those values are the three bytes that form the raw MIDI message, and we need to read the MIDI message information from those bytes.

/**
 * @param MIDIMessageEvent event
 */
function handleMessage(event) {
  /** @type Uint8Array */
  var bytes = event.data;
  
  // The MIDI channel
  var channel = bytes[0] & 0x0F;

  // The MIDI event type
  var type = bytes[0] & 0xF0;
  
  if (type === 0x90) {
    handleNoteOn(bytes[1], bytes[2]);
  } else if (type === 0x80) {
    handleNoteOff(bytes[1], bytes[2]);
  }
}

/**
 * @param Number note
 * @param Number velocity
 */
function handleNoteOn(note, velocity) {
  console.info("NoteOn %s %s", note, velocity);
}

/**
 * @param Number note
 * @param Number velocity
 */
function handleNoteOff(note, velocity) {
  console.info("NoteOff %s %s", note, velocity);
}

The channel is the MIDI channel identifier which the MIDI message is associated with.

The type is the MIDI event type, which could be anything from a key being pressed through to the frequency of a filter being changed. For now we are only interested in two event types, note-on (0x90) which indicates a key has been pressed, and note-off (0x80) which indicates a key has been released.

The note passed to the handleNoteOn and handleNoteOff functions is the MIDI note, and the velocity is the speed at which the key was pressed or released. The velocity can be any integer in the range 0 to 127, inclusive.

So there you have it, our code is now receiving note information from physical MIDI devices. What you do with the incoming note information is entirely up to you, you could use it to play sounds with Web Audio or go crazy and use it to splat pixels into a canvas. You could also send the note information directly to one of the available MIDI output devices.

Sending MIDI Messages

A MIDIOutput object has a send function that can be used to send a MIDI message to a physical MIDI device. This process can actually get quite complex due to the expressiveness of the MIDI language, but we are going to keep things simple here and only deal with the sending of note-on and note-off information.

We will use three functions here, one for sending note-on messages, one for sending note-off messages, and one for building and sending the MIDI messages.

/**
 * @param Number note
 * @param Number velocity
 * @param MIDIOutput output
 */
function sendNoteOn(note, velocity, output) {}

/**
 * @param Number note
 * @param Number velocity
 * @param MIDIOutput output
 */
function sendNoteOff(note, velocity, output) {}

/**
 * @param Number type
 * @param Number data1
 * @param Number data2
 * @param MIDIOutput output
 */
function sendMessage(type, data1, data2, output) {}

The sendNoteOn and sendNoteOff functions will contain the same code, the only difference will be the MIDI event type that they pass to the sendMessage function.

/**
 * @param Number note
 * @param Number velocity
 * @param MIDIOutput output
 */
function sendNoteOn(note, velocity, output) {
  sendMessage(0x90, note, velocity, output);
}

/**
 * @param Number note
 * @param Number velocity
 * @param MIDIOutput output
 */
function sendNoteOff(note, velocity, output) {
  sendMessage(0x80, note, velocity, output);
}

The sendMessage function will construct the raw MIDI message and send it immediately to the MIDI device. For simplicity, all of the messages will be sent on MIDI channel 0.

// Reusable Uint8Array
var messageData = new Uint8Array(3);

/**
 * @param Number type
 * @param Number data1
 * @param Number data2
 * @param MIDIOutput output
 */
function sendMessage(type, data1, data2, output) {
  messageData[0] = type;
  messageData[1] = data1;
  messageData[2] = data2;
  
  // Send the MIDI message immediately
  output.send(messageData);
}

Now we can receive and send MIDI note information, and that alone presents us with a lot of possibilities for audio based web applications.

MIDI Connections and Disconnections

It is possible that a MIDI device could be connected to, or disconnected from, a user's computer while an application is running in the browser. If that happens we need a way to detect it so we can update the state of the application accordingly.

Luckily, the MIDIAccess object allows us to listen for state changes, which basically means it allows us to detect when MIDI devices are connected and disconnected.

Rolling back to the handleAccess function, we can add an event listener to the MIDIAccess object and respond to any state changes.

/**
 * @param MIDIAccess access
 */
function handleAccess(access) {
  access.onstatechange = handleStateChange;
  addListeners(access.inputs);
}

/**
 * @param MIDIConnectionEvent event
 */
function handleStateChange(event) {}

The MIDIConnectionEvent object has a port property that will either be a MIDIInput or MIDIOutput object, the state of which has changed.

/**
 * @param MIDIConnectionEvent event
 */
function handleStateChange(event) {
  /** @type (MIDIInput|MIDIOutput) */
  var device = event.port;
  
  if (device.state === "connected") {
      // Handle the connection
      if (device.type === "input") {
        device.onmidimessage = handleMessage;
      }
  } else if (device.state === "disconnected") {
      // Handle the disconnection
      if (device.type === "input") {
        device.onmidimessage = null;
      }
  }
}

Depending on the complexity of your web application, you may also want to update device lists or switch the active output device when a state change is detected.

Live Demonstration

The following demonstration is based on the code in this tutorial. It indicates if it has successfully gained access to a MIDIAccess object, and if it has, any note-on and note-off MIDI messages it receives from any MIDIInput object will be displayed.

The repository for the demonstration is available at GitHub if you are interested in looking at the source code.

Additional Resources

• MIDI - Wikipedia


• General MIDI - Wikipedia


• Summary of MIDI Messages