Introduction to Web MIDI

“A tutorial about Web MIDI? In 2016? You’re kidding, right?”

No! It’s not what you think! For those of us who have used the web since the 1990s, the phrase “Web MIDI” usually induces flashbacks to a time when websites automatically played a lo-fi bloopy version of The Final Countdown while you signed the webmaster’s guestbook. However, in 2016, Web MIDI—and specifically the Web MIDI API—has a lot more potential.

MIDI standards for Musical Instrument Digital Interface. It’s a protocol that allows electronic musical instruments, computers and other devices to talk to each other. It works by sending small messages from device to device saying things like "note 12 was just pressed" or "note 62 isn't being pressed anymore", but in a digital shorthand.

The Web MIDI API uses this protocol and allows you to take a MIDI-enabled instrument such as a keyboard, connect it to your computer and have information sent from the keyboard to your browser.

Currently, the Web MIDI API is only supported in Chrome and Opera, but you can follow its progress in Firefox by visiting this bug. 

So why would we want to connect a keyboard to a web browser? Well, not many musicians know their way around a QWERTY keyboard as much as they do a musical one. Also, the range of musical devices that support MIDI is huge. By connecting a MIDI-enabled input device to our browser, along with using the Web Audio API, we're able to create musical instruments on the web. 

Want to play a piano? Just connect your keyboard and visit a web page that uses these technologies to replicate the sound of a piano. Want a different sound? Simply visit a different site.

Hopefully you can see the benefit of this API, but how does it actually work?

Accessing a MIDI Device

First we want to check if our browser supports the Web MIDI API. We do this by seeing if the navigator.requestMIDIAccess method exists. This method is only implemented in browsers that support the API.

if (navigator.requestMIDIAccess) {
    console.log('Browser supports MIDI!');
}

Now that we know the method exists, let's call it to request access to any MIDI input that comes the browser's way.

if (navigator.requestMIDIAccess) {
    navigator.requestMIDIAccess()
        .then(success, failure);
}

navigator.requestMIDIAccess() returns a promise, meaning that it will either call a success function or a failure function depending on the outcome of it requesting MIDI access. Here we've given it the names of two functions we're going to create next.

function success (midi) {
    console.log('Got midi!', midi);
}

function failure () {
    console.error('No access to your midi devices.')
}

As you can see, our success function takes a MIDI parameter in the form of a MIDIAccess object. The MIDIAccess object is the key to receiving midi data. The object itself provides an interface to any MIDI devices you have attached. Inputs represent any MIDI devices you have connected to your computer. I have a single MIDI keyboard attached, so if I were to log midi.inputs.size, it would output "1".

In order to get the input data from our device, we first create a variable and assign it midi.inputs.values() like so.

var inputs = midi.inputs.values();

An important thing to note is that the value assigned to inputs is an iterator. An iterator is an object that knows how to access its properties one at a time, while keeping track of the current position in the iteration sequence. It provides a next() method to allow you to get the next item in the sequence. It also has a done property to let us know if we've iterated over all properties of the object. This means we can write fancy for loops like this:

for (var input = inputs.next();
     input && !input.done;
     input = inputs.next()) {
    // each time there is a midi message call the onMIDIMessage function
    input.value.onmidimessage = onMIDIMessage;
}

What this for loop is saying is:

1. Create a variable called input and assign the next input to it. Because we've not iterated over any inputs yet, this will return the first of our inputs.


2. If we have an input and the input iterator's done value doesn't equal true, then carry on with the loop.


3. Set input to the next input in our iterator object.

You'll also note that inside this for loop we're assigning a function to the input's onmidimessage listener. This function will be called any time a MIDI event is received from the device represented by that input. Let's create that function:

function onMIDIMessage (message) {
    console.log(message.data);
}

Decoding MIDI Data

The part of the MIDI message we're interested in is its data; what type of MIDI event was sent? Which key on the keyboard was pressed? 

If you're following along with this tutorial, you'll see that when you press a key on your keyboard, the browser will log something like [144, 61, 95] to the console. And when you take your finger off the key, the browser will again log something slightly different, like [128, 61, 0].

This array can be broken down like so. The first element is the type of MIDI event. MIDI messages can contain a fairly small number of events, and each event has a corresponding number. In our case, 144 maps to a noteOn message, indicating that a key has been pressed, while 128 is a noteOff message, telling us the key is no longer being pressed. For a full list of possible MIDI event types, check out the message list in the MIDI specification.

The second value in the array represents which key on the keyboard was pressed. Each note on a keyboard is given a number from 0 to 127. In the above example, I pressed key 61, which by using this look-up table we can see was a C#.

The third and final value in the array represents velocity, basically the speed the key was hit. This can be used to mimic playing a piano where keys can be played softly or struck quick and hard.

Now that we know which key number is being pressed or released, let's turn it into something useful. Let's hook the Web MIDI API up to the Web Audio API. If you aren't familiar with the Web Audio API, check out my series of tutorials on that very topic.

Creating a Web Instrument

Let's turn our browser into a mini synthesizer. We'll want to create an oscillator that generates the frequency of the note pressed, so we'll need to convert the MIDI note number to its relevant frequency. Luckily our good friend Wikipedia gives us a little algorithm to do just this. Here's what it looks like in JavaScript form:

function midiNoteToFrequency (note) {
    return Math.pow(2, ((note - 69) / 12)) * 440;
}

Give it a note and get the frequency back. Let's use this in our onMIDIMessage function.

function onMIDIMessage (message) {
    var frequency = midiNoteToFrequency(message.data[1]);
}

Next we want to play a note of this frequency if the MIDI message is a noteOn message.

if (message.data[0] === 144 && message.data[2] > 0) {
    playNote(frequency);
}

You'll probably understand the first part of this if statement quite easily. We're checking that the message type is 144 which is the noteOn message.

But what about the second part? Well, some MIDI devices, instead of sending a noteOff message, will send a noteOn message with zero velocity, so we're checking the message has a velocity that's greater than zero. 

Now that we have noteOn covered, we'll write something similar for noteOff. NoteOff's message value is 128, so we need to check not only for that value but also whether its velocity was zero in order to cover the situation I just mentioned.

if (message.data[0] === 128 || message.data[2] === 0) {
    stopNote(frequency);
}

All we have to do now is fill out the startNote and stopNote functions. This is the job of the Web Audio API, and is therefore sadly outside the scope of this tutorial, but if you know the API then the complete code below should be fairly self-explanatory. 

If not, check out my series on the Web Audio API, which includes how to build a synthesizer. The code in that tutorial is similar to what I've done here, so would be the perfect place to apply what you've learned here.

var context = new AudioContext(),
    oscillators = {};

if (navigator.requestMIDIAccess) {
    navigator.requestMIDIAccess()
        .then(success, failure);
}

function success (midi) {
    var inputs = midi.inputs.values();
    // inputs is an Iterator

    for (var input = inputs.next(); input && !input.done; input = inputs.next()) {
        // each time there is a midi message call the onMIDIMessage function
        input.value.onmidimessage = onMIDIMessage;
    }
}

function failure () {
    console.error('No access to your midi devices.')
}

function onMIDIMessage (message) {
    var frequency = midiNoteToFrequency(message.data[1]);

    if (message.data[0] === 144 && message.data[2] > 0) {
        playNote(frequency);
    }

    if (message.data[0] === 128 || message.data[2] === 0) {
        stopNote(frequency);
    }
}

function midiNoteToFrequency (note) {
    return Math.pow(2, ((note - 69) / 12)) * 440;
}

function playNote (frequency) {
    oscillators[frequency] = context.createOscillator();
    oscillators[frequency].frequency.value = frequency;
    oscillators[frequency].connect(context.destination);
    oscillators[frequency].start(context.currentTime);
}

function stopNote (frequency) {
    oscillators[frequency].stop(context.currentTime);
    oscillators[frequency].disconnect();
}

What Next?

Remember, noteOn and noteOff are just two of the message types available to us, and a MIDI keyboard is just one of the many, many types of MIDI devices. You don't even have to use MIDI to make something musical. An HTML5 game you play using a MIDI trumpet? Sounds like just my thing.