Please use JZZ to enable MIDI in browsers that do not support the WebMIDI API.
This javascript library is a prototype polyfill for the Web MIDI API of which Chris is a co-author.
It was originally designed to test usability of the API itself, but it is currently mainly used as a shim for Jazz-Soft's Jazz-Plugin to enable MIDI scenarios in browsers that don't yet support Web MIDI.
The library is actually a combination of a shim and a polyfill: as a polyfill it implements the WebMIDI API in browsers that don't support it natively, and as a shim it intercepts calls from and to the Jazz plugin. In this readme the terms polyfill and shim are used interchangeably.
Including this library means Web MIDI should work in all browsers that are supported by the Jazz plugin. The library also makes the Web MIDI API available in Node.js applications.
The shim will automatically check to see if the Web MIDI API is already implemented, and if not it will insert itself.
Multiple simultaneous inputs and outputs, and sending and receiving long messages (system exclusive) are supported. The shim also properly dispatches events. Timestamps on send and receive should be properly implemented now, although of course timing will not be very precise on either.
The library is very lightweight; the minified version is less than 17K in file-size.
At the moment Chrome, Opera and the Android WebView component (KitKat and above) support the Web MIDI API natively.
In other browsers you need to have version 1.4.4 or higher of the Jazz plugin installed in order for the shim to work properly.
Internet Explorer is supported from version 9 and up.
Note that Chrome and Opera for iOS do not have the Web MIDI API implemented and since there is no Jazz plugin for any iOS browser either, you cannot use Web MIDI on iOS devices.
The Web MIDI API shim works with Node.js applications as well. The shim creates a global variable navigator
that mimics the native navigator
object in browsers. The navigator
object has the method requestMIDIAccess
and this means that you can share your Web MIDI API related code seamlessly across browser and Node.js projects.
Instead of the Jazz plugin, the Node.js version uses the npm module jazz-midi to connect to the MIDI implementation of your operating system. A reference to jazz-midi
is added to the global navigator
object so you can query jazz-midi
for instance to get the version number:
// nodejs
console.log(navigator.jazzMidi.version); // 1.5.1
The jazz-midi
package can be seen as the Node.js version of the Jazz browser plugin and is maintained by Jazz Soft as well.
- Copy the file
WebMIDIAPI.min.js
from thebuild
folder into your project. - Optionally you can copy the source map file
WebMIDIAPI.min.js.map
as well - Add
<script src="/your/path/to/WebMIDIAPI.min.js"></script>
to your HTML page before the script tag(s) of your own code.
For debugging purposes you can use the uncompressed version; you can find it in the build
folder as well.
This method is suitable for both Node.js and browser projects, and for both commonjs and es-next code.
First install the package from npm:
npm i --save web-midi-api
or
yarn add web-midi-api
Then you can import the module into your code:
// commonjs
require('web-midi-api');
// es-next
import 'web-midi-api';
After you have added the shim using any of the methods described above, you can use the Web MIDI API as captured in the specification.
So, some sample usage:
// m = MIDIAccess object for you to make calls on
var m = null;
navigator.requestMIDIAccess().then(onSuccessCallback, onErrorCallback);
function onSuccessCallback(access) {
// If the browser supports WebMIDI, access is a native MIDIAccess
// object. If not, it is an instance of a custom class that mimics
// the behavior of MIDIAccess using Jazz.
m = access;
// Things you can do with the MIDIAccess object:
// inputs = MIDIInputMaps, you can retrieve the inputs with iterators
var inputs = m.inputs;
// outputs = MIDIOutputMaps, you can retrieve the outputs with iterators
var outputs = m.outputs;
// returns an iterator that loops over all inputs
var iteratorInputs = inputs.values()
// get the first input
var input = iteratorInputs.next().value
// onmidimessage(event), event.data & event.receivedTime are populated
input.onmidimessage = myMIDIMessagehandler;
// returns an iterator that loops over all outputs
var iteratorOutputs = outputs.values()
// grab first output device
var output = iteratorOutputs.next().value;
// full velocity note on A4 on channel zero
output.send([0x90, 0x45, 0x7f]);
// full velocity A4 note off in one second.
output.send([0x80, 0x45, 0x7f], window.performance.now() + 1000);
};
function onErrorCallback(err) {
console.log('uh-oh! Something went wrong! Error code: ' + err.code);
}
- list_devices simple listing of all available MIDI devices
- routing_1 example that lets you route MIDI inports to MIDI outports
- routing_2 same routing example with slightly different code
- node example that tests your MIDI in- and outports in Node.js
The polyfill is written in es-next so it needs to be transpiled to es5. You can find the es-next files in the src
folder. If you change something in the es-next files, you need to build the polyfill again. To do this, you need to have Node.js and npm installed.
First install the project dependencies using:
npm install
or
yarn install
This will install all necessary develop dependencies, a.o. browserify and babelify.
Optionally you can run a test script to check if everything has been installed correctly:
npm run test
During development you can start watchify which transpiles your code as soon as you save a changed file:
npm run watch
If you're satisfied with the new code, you can run a complete build:
npm run update
This compiles the files in the src
folder to commonjs files and puts them in the dist
folder. It also creates a browser bundle in es5 in the build
folder.
If you are new to npm and using npm packages in your project please visit the npm site. If you are new to bundling npm packages into an es5 web-bundle that can be used in the browser, consult the documentation one of these bundlers:
build
: contains the transpiled and bundled version of the Web MIDI API shim, this is the script that you add as a separate script to your HTML page.dist
: contains the transpiled commonjs code, this code is used if you import the Web MIDI API shim as a module.examples
: some usage examples for browser and Node.js, written in es5.gh-pages
: styles and scripts used by the github.io landing page, does not contain any library code.node
: contains the entry point for Node.js applications; this scripts combines the Web MIDI API shim with thejazz-midi
npm package. It also contains a Node.js test script that checks your MIDI in- and outports.src
: contains the actual code of this library, written in es-next, this code is by bundlers that support es-next (rollupjs).