Small JavaScript library providing an easy interface to working with Web MIDI
Clone or download

README.md

zMIDI

zMIDI is a small JavaScript "library" that provides an easy interface to transfer messages to and from the Web MIDI API (for those less in the know: this API provides a means to communicate with musical hardware through the web browser).

zMIDI is aimed to easily integrate musical messages without needing to translate these to weird hexadecimal numbers or do scary masking operations on incoming data values. Rather than having you translate MIDI commands, zMIDI does the job for you and provides you with enumerated types in an Event-driven model, which makes both more sense in a JavaScript environment and allows for easier development by providing an adequate abstraction layer.

Installation

You can install zMIDI via NPM:

npm install zmidi

Project integration

zMIDI is compatible with CommonJS, AMD/RequireJS or can be included in the browser via script tags:

CommonJS:

var zMIDILib   = require( "zmidi" ),
    zMIDI      = zMIDILib.zMIDI,
    zMIDIEvent = zMIDILib.zMIDIEvent,
    MIDINotes  = zMIDILib.MIDINotes;    

(you can subsequently use a tool like Browserify to build for the browser).

RequireJS:

require( [ "zMIDI", "zMIDIEvent", "MIDINotes" ], function( zMIDI, zMIDIEvent, MIDINotes )
{
    // do something...
});

Browser:

<script type="text/javascript" src="./src/SysexBuffer.js"></script>
<script type="text/javascript" src="./src/zMIDI.js"></script>
<script type="text/javascript" src="./src/zMIDIEvent.js"></script>
<script type="text/javascript" src="./src/MIDINotes.js"></script>

Note that the browser requires an additional include SysexBuffer.js.

Usage

Ensuring WebMIDI is available at the browser level

Those fortunate enough to have Google Chrome installed, can access this experimental feature (WebMIDI is still a W3C draft) by navigating to chrome://flags/ and enabling WebMIDI (directly via chrome://flags/#enable-web-midi). Note there is also an excellent WebMIDI shim available using the Jazz plugin, but this library is aimed at native support. Fingers crossed that its adaptation is coming and will be as widespread as the WebAudio API seems to be heading to ;) For now Chrome 37+ should support it on Windows, OS X, Linux, Chrome OS and Android.

Really making sure WebMIDI is available at the application level

Query the result of zMidi.isSupported() to really, really make sure it is available!

Really, really making sure MIDI devices are available at the real world level

Attach a MIDI device to your computer and activate it prior (!) to starting the browser. Note : some USB MIDI devices won't show up when connected directly to your computer, or they will show up, but won't transmit messages.

You're likely to be most successful using an audio interface with dedicated MIDI in/out channels.

For instance : an M-Audio keyboard controller wouldn't show up when connected directly via USB, but when connecting the keyboards MIDI-Out (via DIN cable) into the MIDI-In of a MOTU soundcard, all messages were transmitted clearly as the soundcard is now the broadcasting device.

Documentation / Wiki

You can view the online documentation here on Github :

https://github.com/igorski/zMIDI/wiki

Demos

To quickly see what zMIDI is capable of, you can try the following URL with a MIDI keyboard attached to your computer :

https://rawgit.com/igorski/zMIDI/master/examples/index.html

for a demo that packs some more punch, try the WebSID Chrome experiment for this experiment is using zMIDI ! :

http://www.igorski.nl/experiment/websid