OverviewClamps PackagesCM DictionaryClamps DictionaryFomus

Topic

MIDI

Common Music uses MIDI stream to support reading and writing MIDI data to to MIDI files, Portmidi and Midishare. Two levels of MIDI support are provided:

  • A high level interface provides Lisp classes and methods for generating music to MIDI streams in non-real time mode.
  • A low level interface implements "conless" midi messages that can be sent to, and received from an open Midiport or Midishare connection in real time without adding garbage to the Lisp heap.

High level MIDI support

High level MIDI support consists of class definitions of MIDI scores and events and functions that operate on them in non-real time. Note that non-real does not imply slower than real time -- the high level interface generates output many times faster than real time. High level support is documented by main entries in the Common Music dictionary, the following topic list provides links to this documentation:

MIDI event classes

MIDI score classes

MIDI functions

Low level MIDI support

Low level MIDI support provides functions for working with specially formatted unsigned fixnum values called midi messages. Common Music supports all of the message types defined in the MIDI 1.0 specification as well as those described in the MIDI Time Code and Cueing supplement.

MIDI Messages

A MIDI message is a specially formatted fixnum (28-30 bits) containing up to three 7-bit bytes of information. Each MIDI message is implemented by a constructor function, a predicate, and one or more field accessors. Some message types, such as System Exclusive and Meta messages, are implemented as composite data. Constructors for these types return two values: a message and a vector of message data bytes.

Message Utility Functions

[Function]
(midi-copy-message msg {keyword value}*)

Returns a copy of msg with fields altered according to keyword arguments.

midi-copy-message supports the following keyword arguments:

:opcode byte
An optional new status opcode for the copied message.
:channel byte
An optional new channel value for the copied message.
:data1 byte
An optional new value for upper data byte the copied message.
:data2 byte
An optional new value for lower data byte the copied message.

Examples

;; Copying MIDI messages.
(define m1 (make-note-on 0 20 90))

(define m2 (midi-copy-message m1 :data1 73))

(midi-print-message m2)
#<Note-On 0 73 90>
⇒ 156890

(define m3 (midi-copy-message m2 :data1 73 :opcode #b1000 :data2 127))

(midi-print-message m3)
#<Note-Off 0 73 127>
⇒ 140543
[Function]
(midi-print-message msg [time])

Prints msg and an optional time value. Returns msg as its value.

Example

;; Printing MIDI messages.
(midi-print-message (make-note-on 0 60 90) )
#<Note-On 0 60 90>
⇒ 155226
(midi-print-message (make-note-off 9 60 90) 1000)
    1000 #<Note-Off P "hi-bongo" 90>
⇒ 2514522
(midi-print-message (make-program-change 2 45))
#<Program-Change 2 "pizzicato-strings">
⇒ 726656
(midi-print-message (make-control-change 0 +sustain+ 60))
#<Control-Change 0 "hold-1" 60>
⇒ 188476

Message Constructors, Predicates and Accessors

Channel Messages

Channel messages encode the performance information sent to particular instruments on the synthesizer.

All Channel Messages
[Function]
(make-channel-message opcode channel data1 . data2)
[Function]
(channel-message-p message)
[Function]
(channel-message-channel message)
[Function]
(channel-message-opcode message)
[Function]
(channel-message-data1 message)
[Function]
(channel-message-data2 message)
Note-On
[Function]
(make-note-on channel key velocity)
[Function]
(note-on-p message)
[Function]
(note-on-channel message)
[Function]
(note-on-key message)
[Function]
(note-on-velocity message)
Note-Off
[Function]
(make-note-off channel key velocity)
[Function]
(note-off-p message)
[Function]
(note-off-channel message)
[Function]
(note-off-key message)
[Function]
(note-off-velocity message

Key Pressure (Aftertouch)
[Function]
(make-key-pressure channel key pressure)
[Function]
(key-pressure-p message)
[Function]
(key-pressure-channel message)
[Function]
(key-pressure-key message)
[Function]
(key-pressure-pressure message)
Control Change
[Function]
(make-control-change channel controller value)
[Function]
(control-change-p message)
[Function]
(control-change-channel message)
[Function]
(control-change-controller message)
[Function]
(control-change-value message
Program Change
[Function]
(make-program-change channel program)
[Function]
(program-change-p message)
[Function]
(program-change-channel message)
[Function]
(program-change-program message)
Channel Pressure
[Function]
(make-channel-pressure channel pressure)
[Function]
(channel-pressure-p message)
[Function]
(channel-pressure-channel message)
[Function]
(channel-pressure-pressure message)
Pitch-Bend
[Function]
(make-pitch-bend channel lsb msb)
[Function]
(pitch-bend-p message)
[Function]
(pitch-bend-channel message)
[Function]
(pitch-bend-lsb message)
[Function]
(pitch-bend-msb message)

System Messages

System messages are sent to the device (or each device in a daisy-chain), as opposed to a specific channel.

All System Messages
[Function]
(make-system-message type route . data1 data2)
[Function]
(system-message-p message)
[Function]
(system-message-route message)
[Function]
(system-message-status message)
[Function]
(system-message-data1 message)
[Function]
(system-message-data2 message)
System Exclusive

A System Exclusive, or SysEx, message is a message that is specific to one vendor or synthesizer. The first one or three data bytes of the sysex specifies the vendor. The first one or three data bytes after the start tag F0 of the sysex specifies the vendor. If the synthesizer recognizes this Manufacturer's ID as its own, it will listen to the rest of the message. Otherwise, the message will be ignored. System Exclusive is used to send bulk dumps such as patch parameters and other non-spec data.

[Function]
(make-sysex route data)
[Function]
(sysex-p message)
[Function]
(sysex-route message

The make-sysex constructor returns two values, a message bitfield indicating a system exclusive message and an array of system exclusive data. data must be either:

  • A vector of unsigned bytes containing a full system exclusive message enclosed within FO and F7 tags
  • A polymorphous list of numbers, characters, strings, lists, vectors, or sequences of these, which will be used to construct the system exclusive message array.
MIDI Time Code Quarter Frame
[Function]
(make-mtc-quarter-frame route tag nibble)
[Function]
(mtc-quarter-frame-p message)
[Function]
(mtc-quarter-frame-route message)
[Function]
(mtc-quarter-frame-tag message)
[Function]
(mtc-quarter-frame-nibble message)
Song Position
[Function]
(make-song-position route lsb msb)
[Function]
(song-position-p message)
[Function]
(song-position-route message)
[Function]
(song-position-lsb message)
[Function]
(song-position-msb message)
Song Select
[Function]
(make-song-select route song)
[Function]
(song-select-p message)
[Function]
(song-select-route message)
[Function]
(song-select-song message)
Cable Select
[Function]
(make-cable-select route cable)
[Function]
(cable-select-p message)
[Function]
(cable-select-route message)
[Function]
(cable-select-cable message)
Tune Request
[Function]
(make-tune-request route)
[Function]
(tune-request-p message)
[Function]
(tune-request-route message)
End of Sysex
[Function]
(make-eox route)
[Function]
(eox-p message)
[Function]
(eox-route message)
Timing Clock
[Function]
(make-timing-clock route)
[Function]
(timing-clock-p message)
[Function]
(timing-clock-route message)
Timing Tick
[Function]
(make-timing-tick route)
[Function]
(timing-tick-p message)
[Function]
(timing-tick-route message)
Start, Continue and Stop
[Function]
(make-start route)
[Function]
(start-p message)
[Function]
(start-route message)
[Function]
(make-continue route)
[Function]
(continue-p message)
[Function]
(continue-route message)
[Function]
(make-stop route)
[Function]
(stop-p message)
[Function]
(stop-route message)
Active Sensing
[Function]
(make-active-sensing route)
[Function]
(active-sensing-p message)
[Function]
(active-sensing-route message)
System Reset
[Function]
(make-system-reset route)
[Function]
(system-reset-p message)
[Function]
(system-reset-route message)

Meta Messages

Meta messages store various sorts of non-event information for MIDI tracks and MIDI files. The meta message constructors return two values, a message and an array of unsigned bytes. Meta messages should not be sent to MIDI devices.

All Meta Messages
[Function]
(make-meta-message type)
[Function]
(meta-message-p message)
[Function]
(meta-message-type message)
Sequence Number
[Function]
(make-sequence-number num)
[Function]
(sequence-number-p message)
Text Event
[Function]
(make-text-event string . type)
[Function]
(text-event-p message)
[Function]
(make-sequence/track-name string)
[Function]
(sequence/track-name-p message)
[Function]
(make-instrument-name string)
[Function]
(instrument-name-p message)
[Function]
(make-lyric string)
[Function]
(lyric-p message)
[Function]
(make-marker string)
[Function]
(marker-p message)
[Function]
(make-cue-point string)
[Function]
(cue-point-p message)
MIDI Channel
[Function]
(make-midi-channel channel)
[Function]
(midi-channel-p message)
MIDI Port
[Function]
(make-midi-port port)
[Function]
(midi-port-p message)
End of Track
[Function]
(make-eot)
[Function]
(eot-p message)
Tempo Change
[Function]
(make-tempo-change usec)
[Function]
(tempo-change-p message)
SMPTE Offset
[Function]
(make-smpte-offset hours mins secs frames fractional-frames)
[Function]
(smpte-offset-p message)
Time Signature

Denominator is a negative power of 2. clocks expresses the number of MIDI clocks per metronome click and 32nds the number of notated 32nd notes in a MIDI quarter note (i.e., 24 MIDI clocks). This event allows a program to relate what MIDI thinks of as a quarter to any desired value.

[Function]
(make-time-signature numerator denominator . clocks 32nds)
[Function]
(time-signature-p message)
Key Signature

Key is either a number between -7 and 7 representing the number of flats (-) or sharps (+) in the key signature or a note symbol such as c, cf, cs etc. indicating the tonic. mode is either :major (the default) or :minor.

[Function]
(make-key-signature key mode)
[Function]
(key-signature-p message)
Sequencer Event
[Function]
(make-sequencer-event . data)
[Function]
(sequencer-event-p message)

MIDI Values

Common Music provides numerous constants and variables that symbolically encode common MIDI values such as program changes and controller values.

General MIDI (GM) Values

GM Program Changes

Piano (0-7)

+acoustic-grand-piano+ +bright-acoustic-piano+ +electric-grand-piano+ +honky-tonk-piano+ +electric-piano-1+ +electric-piano-2+ +harpsichord+ +clavi+

Chromatic Percussion (8-15)

+celesta+ +glockenspiel+ +music-box+ +vibraphone+ +marimba+ +xylophone+ +tubular-bells+ +dulcimer+

Organ (16-23)

+drawbar-organ+ +percussive-organ+ +rock-organ+ +church-organ+ +reed-organ+ +accordion+ +harmonica+ +tango-accordion+

Guitar (24-31)

+acoustic-guitar-nylon+ +acoustic-guitar-steel+ +electric-guitar-jazz+ +electric-guitar-clean+ +electric-guitar-muted+ +overdriven-guitar+ +distortion-guitar+ +guitar-harmonics+

Bass (32-39)

+acoustic-bass+ +electric-bass-finger+ +electric-bass-pick+ +fretless-bass+ +slap-bass-1+ +slap-bass-2+ +synth-bass-1+ +synth-bass-2+

Solo strings (40-47)

+violin+ +viola+ +cello+ +contrabass+ +tremolo-strings+ +pizzicato-strings+ +orchestral-strings+ +timpani+

Ensemble (48-55)

+string-ensemble-1+ +string-ensemble-2+ +synthstrings-1+ +synthstrings-2+ +choir-aahs+ +voice-oohs+ +synth-voice+ +orchestra-hit+

Brass (56-63)

+trumpet+ +trombone+ +tuba+ +muted-trumpet+ +french-horn+ +brass-section+ +synthbrass-1+ +synthbrass-2+

Reed (64-71)

+soprano-sax+ +alto-sax+ +tenor-sax+ +baritone-sax+ +oboe+ +english-horn+ +bassoon+ +clarinet+

Pipe (72-79)

+piccolo+ +flute+ +recorder+ +pan-flute+ +blown-bottle+ +skakuhachi+ +whistle+ +ocarina+

Synth Lead (80-87)

+lead-1-square+ +lead-2-sawtooth+ +lead-3-calliope+ +lead-4-chiff+ +lead-5-charang+ +lead-6-voice+ +lead-7-fifths+ +lead-8-bass+lead+

Synth Pad (88-95)

+pad-1-new-age+ +pad-2-warm+ +pad-3-polysynth+ +pad-4-choir+ +pad-5-bowed+ +pad-6-metallic+ +pad-7-halo+ +pad-8-sweep+

Synth Effects (96-103)

+fx-1-rain+ +fx-2-soundtrack+ +fx-3-crystal+ +fx-4-atmosphere+ +fx-5-brightness+ +fx-6-goblins+ +fx-7-echoes+ +fx-8-sci-fi+

Ethnic (104-111)

+sitar+ +banjo+ +shamisen+ +koto+ +kalimba+ +bagpipe+ +fiddle+ +shanai+

Percussive (112-119)

+tinkle-bell+ +agogo+ +steel-drums+ +woodblock+ +taiko-drum+ +melodic-tom+ +synth-drum+ +reverse-cymbal+

Sound Effects (120-127)

+guitar-fret-noise+ +breath-noise+ +seashore+ +bird-tweet+ +telephone-ring+ +helicopter+ +applause+ +gunshot+

GM Drum Map

The GM drum map on channel 9 (zero-based counting) maps key numbers 35-81 to the following sounds:

+acoustic-bass-drum+ +bass-drum-1+ +side-stick+ +acoustic-snare+ +hand-clap+ +electric-snare+ +low-floor-tom+ +closed-hi-hat+ +high-floor-tom+ +pedal-hi-hat+ +low-tom+ +open-hi-hat+ +low-mid-tom+ +hi-mid-tom+ +crash-cymbal-1+ +high-tom+ +ride-cymbal-1+ +chinese-cymbal+ +ride-bell+ +tambourine+ +splash-cymbal+ +cowbell+ +crash-cymbal-2+ +vibraslap+ +ride-cymbal-2+ +hi-bongo+ +low-bongo+ +mute-hi-conga+ +open-hi-conga+ +low-conga+ +high-timbale+ +low-timbale+ +high-agogo+ +low-agogo+ +cabasa+ +maracas+ +short-whistle+ +long-whistle+ +short-guiro+ +long-guiro+ +claves+ +hi-wood-block+ +low-wood-block+ +mute-cuica+ +open-cuica+ +mute-triangle+ +open-triangle+

Controller Values

The following standard controller and Registered Parameter Numbers (RPNs) are defined:

Specific Coarse Controllers

+bank-select+ +modulation-wheel+ +breath-control+ +foot-controller+ +portamento-time+ +data-entry+ +channel-volume+ +volume+ +balance+ +pan+ +expression-controller+ +effect-control-1+ +effect-control-2+ +general-purpose-controller-1+ +general-purpose-controller-2+ +general-purpose-controller-3+ +general-purpose-controller-4+

Specific Fine Controllers

+bank-select-fine+ +modulation-wheel-fine+ +breath-control-fine+ +foot-controller-fine+ +portamento-time-fine+ +data-entry-fine+ +channel-volume-fine+ +volume-fine+ +balance-fine+ +pan-fine+ +expression-controller-fine+ +effect-control-1-fine+ +effect-control-2-fine+ +general-purpose-controller-1-fine+ +general-purpose-controller-2-fine+ +general-purpose-controller-3-fine+ +general-purpose-controller-4-fine+

Common Switches

+sustain+ +portamento+ +sostenuto+ +soft-pedal+ +legato-footswitch+ +hold-2+

Sound Controllers

+sound-variation+ +sound-timbre+ +sound-release-time+ +sound-attack-time+ +sound-brightness+ +portamento-control+

Level Controller

+effects-level+ +tremolo-level+ +chorus-level+ +detune-level+ +phasor-level+

Data Entry Step Controllers

+data-entry-increment+ +data-entry-decrement+

Parameter Number Selection

+non-registered-parameter-number-fine+ +non-registered-parameter-number+ +registered-parameter-number-fine+ +registered-parameter-number+

Channel Mode Messages

+all-sound-off+ +reset-all-controllers+ +local-control+ +all-notes-off+ +omni-mode-off+ +omni-mode-on+ +poly-mode-on/off+ +poly-mode-on+

Registered Parameter Numbers

+rpn-pitch-bend-sensitivity+ +rpn-fine-tuning+ +rpn-coarse-tuning+ +rpn-reset+