Documentation for v2.5.3

caution

Version 2.5.3 will be the last version of the 2.x branch. This documentation and the 2.5.3 version will not be updated after 2021.

Browser Support

This library works in all browsers that natively support the Web MIDI API. Currently (2021), the following browsers have built-in support:

Chrome (macOS, GNU/Linux, Android & Windows)
Opera (macOS, GNU/Linux, Windows)
Android WebView component (KitKat and above)
Edge (Windows)

It is also possible to use this library in other browsers if you install version 1.4+ of Jazz-Plugin together with the WebMIDIAPIShim polyfill. This combination provides support for the following additional browsers:

Firefox v51 or less (Mac, GNU/Linux & Windows)
Safari (macOS)
Internet Explorer (Windows)

For details on how to use WebMidi.js with the Jazz-Plugin (and WebMIDIAPIShim, please skip ahead to the Using WebMidi.js with the Jazz-Plugin section.

For Firefox v52+ support, you need to install two extensions made by Jazz-Soft:

Jazz-MIDI extension v1.5.1+
Web MIDI API extension

Early tests show that WebMidi.js is working in Firefox when both these extensions installed. Further testing will need to be done but it looks very promising.

I invite you to communicate with the Firefox and Safari teams to let them know how having native Web MIDI support is important for you:

Safari: https://bugs.webkit.org/show_bug.cgi?id=107250
Firefox: https://bugzilla.mozilla.org/show_bug.cgi?id=836897

Note that, in 2020, Apple has announced that they would not implement the Web MIDI API (and a host of other APIs) in Safari over fingerprinting concerns.

Node.js Support

There is no official Node.js support in WebMidi.js 2.5.x. Version 3 and above offer full Node.js support.

TypeScript Support

TypeScript type definitions have been tentatively added to WebMidi.js with version 2.3 (thanks to mmmveggies) but it should be noted that TypeScript IS NOT officially supported in version 2.5.x. TypeScript is supported in version 3 and above.

Despite the absence of official suuport, this has been reported to work in v2.5.3:

import WebMidi from "webmidi";

WebMidi.enable(...);

Or (thanks to michaelcaterisano):

const WebMidi: import("webmidi").WebMidi = require("webmidi");

You can also import the types, if you need them:

import WebMidi, { InputEventNoteon, InputEventNoteoff } from "webmidi";

input.addListener("noteon", "all", (event: InputEventNoteon) => {
  ...
}) 

Installation

Depending on your needs and environment, you can install WebMidi.js in a variety of different ways.

CDN

The easiest way to get started is to link the WebMidi.js library from the jsDelivr CDN (content delivery network). To retrieve the latest version, just add this <script> tag to your HTML page:

<script src="https://cdn.jsdelivr.net/npm/webmidi@2.5.3"></script>

Manual Install

Obviously, you can also install WebMidi.js the old fashioned way by downloading the 2.5.3 release packaged as a zip file. Uncompress the package, grab the webmidi.min.js file and copy it to your project. Link to it from your HTML page as usual.

NPM Install

If it's more convenient, you can install WebMidi.js with NPM. Simply issue the following command to perform the actual install:

npm install webmidi

Then, just add a <script> tag to your HTML page and make it point to:

<script src="node_modules/webmidi/webmidi.min.js"></script>

Using with a Bundler

If you are using a bundler such as WebPack, you can import WebMidi.js in your project in this way:

import WebMidi from 'path/to/webmidi';

Insecure Origins

Starting with version 77, Chrome deprecates Web MIDI usage on insecure origins. This means that, going forward, the page will need to be hosted on a secure origin (e.g. https://, localhost: or file:///) and the user will need to explicitely authorize usage (no matter if sysex is used or not).

Quick Start

Getting started is easy. The first thing to do is to enable WebMidi.js. To do that, you call WebMidi.enable() and pass it a function to execute when done. This function will receive an Error object if enabling WebMidi failed:

WebMidi.enable(function (err) {

  if (err) {
    console.log("WebMidi could not be enabled.", err);
  } else {
    console.log("WebMidi enabled!");
  }
  
});

To send and receive MIDI messages, you will need to do so via the appropriate Output and Input device. To view all the available Input and Output ports, you can use the matching arrays:

WebMidi.enable(function (err) {
    console.log(WebMidi.inputs);
    console.log(WebMidi.outputs);
});

To send MIDI messages to a device, you simply need to grab that device and call one of its output method (playNote(), stopNote(), sendPitchBend(), etc.). To retrieve a device, you can use its position in the WebMidi.outputs array. For instance, to grab the first output device, you could use:

var output = WebMidi.outputs[0];

However, this is not very safe as the position of devices in the array could change. An alternative is to use the device's ID:

var output = WebMidi.getOutputById("1584982307");

Beware that device IDs are not the same across browsers and platforms. You could also use the device's name (as displayed in the WebMidi.outputs array):

var output = WebMidi.getOutputByName("Axiom Pro 25 Ext Out");

Then, you can call any of the output methods and all native MIDI communications will be handled for you. For example, to play a "C" on the 3rd octave, you simply do:

output.playNote("C3");

That's it.

Receiving messages works in a similar way: you retrieve the Input device you want to use, and then add a callback function to be triggered when a specific MIDI message is received. For example, to listen for pitch bend events on all channels of the device:

var input = WebMidi.getInputByName("Axiom Pro 25 USB A In");

input.addListener('pitchbend', "all", function(e) {
    console.log("Pitch value: " + e.value);
});

API Documentation

The API for WebMidi.js is fully documented. If you spot an error (even something minor) or think a topic should be made clearer, do not hesitate to file an issue or, better yet, send a PR.

Here is a link to the full API Reference.

More code examples

Here are various other examples to give you an idea of what is possible with WebMidi.js.

// Enable WebMidi.js
WebMidi.enable(function (err) {

  if (err) {
    console.log("WebMidi could not be enabled.", err);
  }

  // Viewing available inputs and outputs
  console.log(WebMidi.inputs);
  console.log(WebMidi.outputs);
  
  // Reacting when a new device becomes available
  WebMidi.addListener("connected", function(e) {
    console.log(e);
  });
  
  // Reacting when a device becomes unavailable
  WebMidi.addListener("disconnected", function(e) {
    console.log(e);
  });

  // Display the current time
  console.log(WebMidi.time);

  // Retrieving an output port/device using its id, name or index
  var output = WebMidi.getOutputById("123456789");
  output = WebMidi.getOutputByName("Axiom Pro 25 Ext Out");
  output = WebMidi.outputs[0];

  // Play a note on all channels of the selected output
  output.playNote("C3");

  // Play a note on channel 3
  output.playNote("Gb4", 3);

  // Play a chord on all available channels
  output.playNote(["C3", "D#3", "G3"]);

  // Play a chord on channel 7
  output.playNote(["C3", "D#3", "G3"], 7);

  // Play a note at full velocity on all channels)
  output.playNote("F#-1", "all", {velocity: 1});

  // Play a note on channel 16 in 2 seconds (relative time)
  output.playNote("F5", 16, {time: "+2000"});

  // Play a note on channel 1 at an absolute time in the future
  output.playNote("F5", 16, {time: WebMidi.time + 3000});

  // Play a note for a duration of 2 seconds (will send a note off message in 2 seconds). Also use
  // a low attack velocity
  output.playNote("Gb2", 10, {duration: 2000, velocity: 0.25});

  // Stop a playing note on all channels
  output.stopNote("C-1");

  // Stopping a playing note on channel 11
  output.stopNote("F3", 11);

  // Stop a playing note on channel 11 and use a high release velocity
  output.stopNote("G8", 11, {velocity: 0.9});

  // Stopping a playing note in 2.5 seconds
  output.stopNote("Bb2", 11, {time: "+2500"});

  // Send polyphonic aftertouch message to channel 8
  output.sendKeyAftertouch("C#3", 8, 0.25);

  // Send pitch bend (between -1 and 1) to channel 12
  output.sendPitchBend(-1, 12);

  // You can chain most method calls
  output.playNote("G5", 12)
    .sendPitchBend(-0.5, 12, {time: 400}) // After 400 ms.
    .sendPitchBend(0.5, 12, {time: 800})  // After 800 ms.
    .stopNote("G5", 12, {time: 1200});    // After 1.2 s.

  // Retrieve an input by name, id or index
  var input = WebMidi.getInputByName("nanoKEY2 KEYBOARD");
  input = WebMidi.getInputById("1809568182");
  input = WebMidi.inputs[0];

  // Listen for a 'note on' message on all channels
  input.addListener('noteon', "all",
    function (e) {
      console.log("Received 'noteon' message (" + e.note.name + e.note.octave + ").");
    }
  );

  // Listen to pitch bend message on channel 3
  input.addListener('pitchbend', 3,
    function (e) {
      console.log("Received 'pitchbend' message.", e);
    }
  );

  // Listen to control change message on all channels
  input.addListener('controlchange', "all",
    function (e) {
      console.log("Received 'controlchange' message.", e);
    }
  );
  
  // Listen to NRPN message on all channels
  input.addListener('nrpn', "all",
    function (e) {
      if(e.controller.type === 'entry') {
        console.log("Received 'nrpn' 'entry' message.", e);
      }
      if(e.controller.type === 'decrement') {
        console.log("Received 'nrpn' 'decrement' message.", e);
      }
      if(e.controller.type === 'increment') {
        console.log("Received 'nrpn' 'increment' message.", e);
      }
      console.log("message value: " + e.controller.value + ".", e);
    }
  );

  // Check for the presence of an event listener (in such cases, you cannot use anonymous functions).
  function test(e) { console.log(e); }
  input.addListener('programchange', 12, test);
  console.log("Has event listener: ", input.hasListener('programchange', 12, test));

  // Remove a specific listener
  input.removeListener('programchange', 12, test);
  console.log("Has event listener: ", input.hasListener('programchange', 12, test));

  // Remove all listeners of a specific type on a specific channel
  input.removeListener('noteoff', 12);

  // Remove all listeners for 'noteoff' on all channels
  input.removeListener('noteoff');

  // Remove all listeners on the input
  input.removeListener();

});

About Sysex Support

Per the Web MIDI API specification, system exclusive (sysex) support is disabled by default. If you need to use sysex messages, you will need to pass true as the second parameter to WebMidi.enable():

WebMidi.enable(function (err) {
  if (err) {
    console.warn(err);
  } else {
    console.log("Sysex is enabled!");
  }
}, true);

Important: depending on the browser, version and platform, it may also be necessary to serve the page over https if you want to enable sysex support.

Migration Notes

If you are upgrading from version 1.x to 2.x, you should know that v2.x is not backwards compatible. Some important changes were made to the API to make it easier to use, more versatile and to better future-proof it.

Here is a summary of the changes:

All the "output" functions (playNote(), sendPitchBend(), etc.) have been moved to the Output object. A list of all available Output objects is available in WebMidi.outputs (like before).
All the "input" functions (addListener, removeListener() and hasListener() have been moved to the Input object. A list of all available Input objects is available in WebMidi.inputs (also like before).

There might be a few other minor changes here and there but the refactoring mostly concerns the introduction of Input and Output objects.

Using WebMidi.js with the Jazz-Plugin

To use WebMidi.js on Safari, Firefox and Internet Explorer, you will first need to install Jazz-Plugin. Simply download the plugin and run the installer.

Users of Firefox v52+ are currently out of luck because Mozilla deactivated support for NPAPI plugins. There is an add-on version of Jazz-Midi but, unfortunately, the API is different and cannot be used as is. Firefox v52+ users will have to wait for native Web MIDI support to be finalized. Reading from the comments on Bug 836897, this might take a while...

Then, you will need to add the plugin to the page with the following HTML code:

<object id="Jazz1" classid="CLSID:1ACE1618-1C7D-4561-AEE1-34842AA85E90" class="hidden">
  <object id="Jazz2" type="audio/x-jazz" class="hidden">
    <p><a href=http://jazz-soft.net>Jazz-Plugin</a> required!</p>
  </object>
</object>

To support recent versions of Internet Explorer, you also need to add a meta tag to the <head> of the page:

<meta http-equiv="X-UA-Compatible" content="requiresActiveX=true"/>

Since Jazz-Plugin does not use the same syntax as the native Web MIDI API, it is necessary to also install the WebMIDIAPIShim polyfill. You can do that by including the following in your page:

<script src='https://cwilso.github.io/WebMIDIAPIShim/build/WebMIDIAPI.min.js'></script>

Obviously, you can also download a local copy and link to it.

Documentation for v2.5.3

Browser Support​

Node.js Support​

TypeScript Support​

Installation​

CDN​

Manual Install​

NPM Install​

Using with a Bundler​

Insecure Origins​

Quick Start​

API Documentation​

More code examples​

About Sysex Support​

Migration Notes​

Using WebMidi.js with the Jazz-Plugin​