Jazz-Soft.net

We make it sound!

Home » Documentation » JZZ.js » JZZ.MIDI

JZZ.MIDI

All midi messages are internally handled as JZZ.MIDI objects. This type inherits from the JavaScript Array, and therefore allows all array operations on it.

Construction

JZZ.MIDI() works with or without the new keyword.

It accepts an array or a comma-separated list of the message bytes or another JZZ.MIDI object.

String names for the notes are allowed where appropriate (in the note on / note off / aftertouch messages).

Note name consists of the pitch class (from A to G), accidentals (#, ##, b, bb, or none), and the octave (from 0 to 10), and is case-insensitive.

German notation fans can use H and Bb for Si and Si-flat.

e.g. C#5, c#5, Db5, db5, DB5, dB5, B##4, b##4, H##4, h##4 will all have value of 61.

MIDI note range spans from C0 (0) to G10 (127), and the Middle-C is C5 (60).

Example

All following statements will produce the same result:

msg = new JZZ.MIDI([0x90, 63, 127]);
msg = new JZZ.MIDI(0x90, 63, 127);
msg = JZZ.MIDI(0x90, 63, 127);
msg = JZZ.MIDI([0x90, 'Eb5', 127]);
msg = JZZ.MIDI.noteOn(0, 'D#5', 127);                    // see below...

Timestamp

Timestamps will be available in the future releases.

toString()

toString() convert MIDI message to human-readable string.

NOTE: in most JavaScript realizations, console.log() does not automatically call this function.

Example

console.log(JZZ.MIDI.noteOn(0, 'D#5', 127).toString());  // or
console.log('Playing note: ' + JZZ.MIDI.noteOn(0, 'D#5', 127));

Helpers

It is not uncommon for JavaScript developer to forget which MIDI message stands for Dumper piano pedal off.

Therefore, some helper functions might be helpful.

In the following list c will stand for the channel, nn - for the note, vv - for velocity, mm - for the most significant byte (MSB), ll - for the least significant byte (LSB), b - for the boolean On/Off, xx and yy for other paraneters.

noteOn(c, nn, vv) - note on; returns 9c nn vv. If omitted, default velocity value is 7F (127).

noteOff(c, nn, vv) - note off; returns 8c nn vv. In most cases, velocity can be omitted.

aftertouch(c, nn, xx) - aftertouch; returns Ac nn xx.

program(c, xx) - program change; returns Cc xx.

pressure(c, xx) - pressure (channel aftertouch); returns Dc xx.

pitchBend(c, xx) - pitch bender; returns Ec ll mm.

control(c, xx, yy) - other control; returns Bc xx yy; some controls have their own dedicated helpers below.

bankMSB(c, mm) - bank select, MSB; returns Bc 00 mm.

bankLSB(c, ll) - bank select, LSB; returns Bc 20 ll.

modMSB(c, mm) - modulation wheel, MSB; returns Bc 01 mm.

modLSB(c, ll) - modulation wheel, LSB; returns Bc 21 ll.

breathMSB(c, mm) - breath controller, MSB; returns Bc 02 mm.

breathLSB(c, ll) - breath controller, LSB; returns Bc 22 ll.

footMSB(c, mm) - foot controller, MSB; returns Bc 04 mm.

footLSB(c, ll) - foot controller, LSB; returns Bc 24 ll.

portamentoMSB(c, mm) - portamento time, MSB; returns Bc 05 mm.

portamentoLSB(c, ll) - portamento time, LSB; returns Bc 25 ll.

volumeMSB(c, mm) - channel volume, MSB; returns Bc 07 mm.

volumeLSB(c, ll) - channel volume, LSB; returns Bc 27 ll.

balanceMSB(c, mm) - stereo balance, MSB; returns Bc 08 mm.

balanceLSB(c, ll) - stereo balance, LSB; returns Bc 28 ll.

panMSB(c, mm) - stereo pan, MSB; returns Bc 0A mm.

panLSB(c, ll) - stereo pan, LSB; returns Bc 2A mm.

expressionMSB(c, mm) - expression controller, MSB; returns Bc 0B mm.

expressionLSB(c, ll) - expression controller, LSB; returns Bc 2B mm.

damper(c, b) - damper pedal on/off; returns Bc 40 7f/00.

portamento(c, b) - portamento on/off; returns Bc 41 7f/00.

sostenuto(c, b) - sostenuto pedal on/off; returns Bc 42 7f/00.

soft(c, b) - soft pedal on/off; returns Bc 43 7f/00.

allSoundOff(c) - all sound off; returns Bc 78 00.

allNotesOff(c) - all notes off; returns Bc 7B 00.

mtc(smpte) - MIDI time code (SMPTE quarter-frame); returns F1 xx.

songPosition(xx) - song position pointer; returns F2 ll mm.

songSelect(xx) - song select; returns F3 xx.

tune() - tune request; returns F6.

clock() - timing clock; returns F8.

start() - start; returns FA.

continue() - continue; returns FB.

stop() - stop; returns FC.

active() - active sensing; returns FE.

reset() - reset; returns FF.

Some common SysEx messages:

sxIdRequest() - device ID request; returns F0 7E 7F 06 01 F7. (see also: gearInfo())

sxFullFrame(smpte) - SMPTE full-frame; returns F0 7F 7F 01 01 xx xx xx xx F7.

All helpers above (and some more) can be directly used with MIDI-Out port and MTrk objects.

SMF helpers

Technically, Standard MIDI File Meta Event is NOT a MIDI message.
However, these can pass through regular JZZ MIDI pipelines, and be used in MIDI files.

In the following list len is the length of the subsequent data, data - the string of bytes, str and text - a (possibly, wide character-) String and its representation as the sequence of bytes.

smf(xx, data) - meta event of an arbitrary type xx; returns FFxx len data.

smfSeqNumber(ssss) - sequence number; returns FF00 02 ssss, where ssss is a 16-bit integer.

smfText(str) - text event; returns FF01 len text. This is the event used in karaoke files.

smfCopyright(str) - copyright notice; returns FF02 len text.

smfSeqName(str) - sequence/track name; returns FF03 len text.

smfInstrName(str) - instrument name; returns FF04 len text.

smfLyric(str) - lyric; returns FF05 len text.

smfMarker(str) - marker; returns FF06 len text.

smfCuePoint(str) - cue point; returns FF07 len text.

smfProgName(str) - program name; returns FF08 len text.

smfDevName(str) - device name; returns FF09 len text.

smfChannelPrefix(cc) - channel prefix; returns FF20 01 cc.

smfEndOfTrack() - end of track; returns FF2F 00.

smfTempo(tttttt) - set tempo in microseconds per quarter note; returns FF51 03 tttttt, where tttttt is a 24-bit integer.

smfBPM(bpm) - set tempo in beats per minute; calculates tttttt and returns smfTempo(tttttt).

smfSMPTE(smpte) or smfSMPTE([hh, mm, ss, fr, ff]) or smfSMPTE(hh, mm, ss, fr, ff) - SMPTE offset; returns FF54 05 hh mm ss fr ff, where hh / mm / ss / fr are hours / minutes / seconds / frames, and ff is the frame fraction, in hundredth's of a frame.

smfTimeSignature(nn, dd, cc, bb) - time signature; returns FF58 04 nn dd cc bb, where nn is a time signature numerator, dd - time signature numerator, where nn is a time signature denominator expressed as a power of 2 (e.g. nn=6, dd=3 would mean 6/8). Optional parameters: cc - number of MIDI clocks per metronome click (default: 24), bb - number of 1/32 notes per 24 MIDI clocks (default: 8) - most of the existing software ignores these.

smfKeySignature(key) - key signature; returns FF59 02 sf mi, where key is a key signature (e.g. 'Bb', 'F#m'), sf - a sharp/flat count (e.g. -7 for 7 flats, 7 for 7 sharps, 0 for C major / A minor), mi = 0/1 for major / minor.

smfMetaEvent(data) - sequencer specific meta event; returns FF7F len data.

All helpers above can be directly used with MIDI-Out port and MTrk objects.

Data access

isNoteOn() - return true for the Note On message (9x nn vv; vv > 0), or false otherwise.

isNoteOff() - return true for the Note Off message (8x nn vv or 9x nn 00), or false otherwise.

isSysEx() - return true if the message starts with F0, or false otherwise.

isFullSysEx() - return true if the message starts with F0 and ends with F7, or false otherwise.

isSysEx() - return true if the first byte of the message is F0, or false otherwise.

isSMF() - return true if the message is an SMF Meta Event, or false otherwise.

getChannel() - return the channel number if the message is channel-related, or undefined otherwise.

setChannel(cc) - set the channel number to cc where it makes sense.

getNote() - return the note MIDI value for Note On / Note Off / Aftertouch messages, or undefined for others.

setNote(nn) - set the note to nn where it makes sense; nn can be a MIDI value or a note name.

getVelocity() - return the velocity for Note On / Note Off messages, or undefined for others.

setVelocity(vv) - set velocity for Note On / Note Off messages.

getSysExChannel() - return the SysEx channel if the message is a SysEx, or undefined otherwise.

setSysExChannel(cc) - set the SysEx channel in the SysEx message.

The following functions are applied only to SMF messages:

getData() - return a String containing the message binary data.

setData(data) - set the SysEx channel in the SysEx message.

getText() - return the message text. If the message data is valid UTF8, it is converted to a wide character string.

setText(str) - set the message text. The input may be converted to UTF8. If you don't want UTF8 conversion, use setData() instead.

Example

// transpose msg an octave up:
var note = msg.getNote();
if (note !== undefined) msg.setNote(note + 12);

freq()

JZZ.MIDI.freq(nn) or JZZ.MIDI.freq(nn, a5) - return the note frequency in HZ.

nn - note name or MIDI value.

a5 - frequency of the A5 note, default 440.

See also