Technology Applications Download Documentation Community about the developer...

Home » Documentation » JZZ.js » JZZ engine

JZZ engine

JZZ()

JZZ() is the first function you are going to call in your MIDI application.

On the first call, the function checks it's arguments, creates the singleton engine object and tries to initialize it.

On all successive calls, it returns the same object and ignores the arguments.

Engine is considered successfully initialized if there is at least one MIDI-Out or MIDI-In port that can be opened.

If the engine fails to initialize, it will execute its first or call (if there is one), and ignore all further calls.

Argument can be either empty or an object(map) with the following keys:

engine : implementation name, or a vector of the names in the order of priority.
Can be 'none', or contain 'etc'.
e.g. JZZ({engine:['extension','etc','webmidi']}) tries extension first, webmidi last, and other implementations in default order in between.
sysex : if true, Web MIDI API will be called with the {sysex:true} option.
Other MIDI implementations are not as paranoic about the sysex messages and ignore this key.
NOTE: In Chrome v.43 and later, sysex is always disabled if the page is opened via the http:// protocol.
The prompt for enabling sysex shows up only on pages opened via the secure https://.
degrade : if both sysex and degrade are true, Web MIDI API will graciously degrade to non-sysex operation if the sysex mode is unavailable or refused by user.
Other MIDI implementations ignore this key.

info()

engine.info() - return an info object with the following keys:

name : 'JZZ.jz'
ver : script version
engine : implementation string
version : engine version
sysex : true if sysex messages allowed, false otherwise.
inputs : an array of info objects for available input ports
outputs : an array of info objects for available output ports

Currently, implementation can be one of the following:

'node' - jazz-midi module in Node.js
'plugin' - ActiveX object in MS Internet Explorer or NPAPI plugin in supported browsers (requires Jazz-Plugin)
'extension' - Web-extension: see Chrome Web Store for Chrome / Opera, or Mozilla Add-ons for Firefox.
'webmidi' - Web MIDI API
'webaudio' - Web Audio API - may be available in the future versions
'none' - if none of the above available

refresh()

engine.refresh() - refresh the list of available input/output ports.

For the case if a device was disconnected or a new device connected during the session.

openMidiIn()

engine.openMidiIn() - open MIDI-In port. See more details here.

openMidiOut()

engine.openMidiOut() - open MIDI-Out port. See more details here.

close()

engine.close() - close all ports.

No other calls except the common calls can be chained to the closed engine.

This call is optional in HTML, but may be required in Node.js if there are any MIDI-In ports remaining open.

Other calls

engine.or(), engine.and(), engine.wait()

Example

JZZ({sysex:true}).or('Cannot start MIDI engine!')
    .and(function(){ console.log(this.info()); })
    .wait(10000).refresh()
    .and(function(){ console.log(this.info()); })
    .and('Thank you!');

onChange()

engine.onChange(handler) - get the watcher object.

An optional handler parameter is a handler function that will be called each time when an external MIDI device is connected or disconnected.

The function will be given an argument in the form:

{ inputs: { added: [...], removed: [...] }, outputs: { added: [...], removed: [...] } },

where the arrays are filled with the info objects for each connected/disconnected device.

onChange().connect()

watcher.connect(handler) - add handler to the watcher.

handler - same as above. There can be any number of handlers chained to the watcher.

onChange().disconnect()

watcher.diconnect(handler) - remove handler from the watcher.

handler - a handler to remove.

If called without arguments, removes all handlers. This is the only way to remuve anonymous handlers.

onChange().*

Other engine functions can be chained after the watcher. They will execute on the engine object, rather than on the watcher.