| MIDI Messages | [Topic] |
A MIDI message is a formatted fixnum (typically 28-30 bit) containing up to three bytes of data. 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 are supported by MIDI message types and subtypes.
MIDI messages are usually not manipulated directly by the user. Instead, high level objects and command like midi-note, midi-channel-message, midi-message, import, open and receive, automatically transform MIDI compositional data to and from the lower level MIDI message representation documented here.
Each MIDI message type is implemented by a constructor function, a predicate, and one or more field accessors, if appropriate. The field accessors are functions, not macros, so they are suitable for use in mapping. Field accessors are also setf-able, that is, they may be used to both set and retrieve the contents of message data fields.
Some message types, such as System Exclusive ("Sysex") messages and MIDI file meta events, are implemented as composite messages. Constructors for composite messages return multiple values, the message created and an array with element type (unsigned-byte 7) (sysex) (unsigned-byte 8) (meta events) of message data.
midi-channel-message-p message
midi-system-message-p message
midi-meta-message-p message
midi-message-data1 message
midi-message-data2 message
Channel messages define the basic device operations in MIDI.
make-channel-message opcode logical-channel data1
&optional data2
channel-message-p message
channel-message-channel message
channel-message-opcode message
channel-message-data1 message
channel-message-data2 message
make-note-off logical-channel key velocity
note-off-p message
note-off-channel message
note-off-key message
note-off-velocity message
make-note-on logical-channel key velocity
note-on-p message
note-on-channel message
note-on-key message
note-on-velocity message
Note Off and Note On messages are sent when a note is released (ended) or depressed (started). By convention, a Note On message with velocity 0 is equivalent to a Note Off message. A velocity of 64 is standard.
make-key-pressure logical-channel key pressure
key-pressure-p message
key-pressure-channel message
key-pressure-key message
key-pressure-pressure message
This message, also known as Polyphonic Key Pressure or After-touch, indicates a pressure (velocity) change of a previously triggered note changes.
make-control-change logical-channel controller value
control-change-p message
control-change-channel message
control-change-controller message
control-change-value message
Various sliders, buttons, and knobs on MIDI keyboards are referred to as "controllers." On sound modules, some of the attributes which can be changed in real-time are called "controllers." Controllers are numbered from 0 to 121, and some of them have defined purposes. The values 122-127 are reserved in the controller-change message for special mode messages. See MIDI Controllers.
make-program-change logical-channel program
program-change-p message
program-change-channel message
program-change-program message
This message indicates a patch number change. Many synthesizers support more than 128 programmed sounds, organized in "Banks" a 128 patches. In order to switch to a patch in a different bank, "Bank Select" controllers may be used, followed by a program change message. See MIDI Controllers. for more information.
make-channel-pressure logical-channel pressure
channel-pressure-p message
channel-pressure-channel message
channel-pressure-pressure message
This message is sent when the channel pressure changes. Some velocity-sensing keyboards do not support polyphonic after-touch. Use this message to send the single greatest velocity (of all te current depressed keys).
make-pitch-bend logical-channel lsb msb
pitch-bend-p message
pitch-bend-channel message
pitch-bend-lsb message
pitch-bend-msb message
This message is sent to indicate a change in the pitch wheel. The pitch wheel is measured by a 14-bit value. Center (no pitch change) is #x2000. The exact range of the pitch bend is specific to the synthesizer.
System messages are sent to the device (or each device in a daisy-chain), as opposed to a specific channel.
make-system-message type route
&optional data1 data2
system-message-p message
system-message-route message
system-message-status message
system-message-data1 message
system-message-data2 message
make-sysex route data
sysex-p message
sysex-route message
make-sysex returns two values, a message bitfield indicating a system exclusive message and an array of system exclusive data. data must be either an array of type
(simple-array (unsigned-byte 7) (*))containing a full system exclusive message enclosed within FO and F7 tags or a polymorphous list of numbers, characters, strings, lists, vectors, or sequences of these, which will be used to construct the system exclusive message array (see make-sysex-data).
A System Exclusive message, or "SysEx," is a message that is vendor, or synthesizer, specific and makes up for all that MIDI doesn't support. 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. See MIDI Sysex Messages.
make-mtc-quarter-frame route tag nibble
mtc-quarter-frame-p message
mtc-quarter-frame-route message
mtc-quarter-frame-tag message
mtc-quarter-frame-nibble message
Quarter Frame Messages send one nibble of a full 4-byte SMPTE time code frame at a time, four times per SMPTE frame, or one full frame every two SMPTE frames. The most-significant nibble of the hour byte is used to indicate the time code type (24, 25, 30 drop, or 30 fps). See SMPTE for a cursory explanation of SMPTE time code.
make-song-position route lsb msb
song-position-p message
song-position-route message
song-position-lsb message
song-position-msb message
This is an internal 14-bit register that holds the number of MIDI beats (1 beat = six MIDI clocks) since the start of the song.
make-song-select route song
song-select-p message
song-select-route message
song-select-song message
The Song Select specifies which sequence or song is to be played.
make-cable-select route cable
cable-select-p message
cable-select-route message
cable-select-cable message
Though officially undefined, some MIDI interfaces use this message to control cable access. A single data byte that follows designates the cable number on which subsequent MIDI messages are routed.
make-tune-request route
tune-request-p message
tune-request-route message
Upon receiving a Tune Request, all analog sythesizers should tune their oscillators. Possibly obsolete in the age of digital synthesizers...
make-eox route
eox-p message
eox-route message
Used to terminate a System Exclusive message.
NOTE: This message type is not used by Common Music and provided for convenience only.
make-timing-clock route
timing-clock-p message
timing-clock-route message
Sent 24 times per quarter note when synchronization is required.
make-timing-tick route
timing-tick-p message
timing-tick-route message
Tells all sequencers on the MIDI bus to advance by a single "tick."
make-start route
start-p message
start-route message
make-continue route
continue-p message
continue-route message
make-stop route
stop-p message
stop-route message
A Start message starts the current sequence playing. (This message will be followed by Timing Clocks). A Continue message continues at the point the sequence was stopped. A Stop message stops the current sequence.
make-active-sensing route
active-sensing-p message
active-sensing-route message
If a MIDI device receives an Active Sensing message, then it should enter "active sensing mode." In that mode, if no messages are received for 300 milliseconds, then it should silence all sound output. The Active Sensing byte itself is a valid message to inhibit this silencing. This helps make sure that a "hung" MIDI system automatically silences itself.
make-system-reset route
system-reset-p message
system-reset-route message
Reset all receivers in the system to power-up status. This should be used sparingly, preferably under manual control. In particular, it should not be sent on power-up.
Meta messages (or Meta Events) store various sorts of non-event information in MIDI tracks. Similar to system exclusive messages, meta-message constructors return two values, a message of type meta-message and an array of type
(simple-array (unsigned-byte 8) (*))containing the message data. Meta messages are only valid within MIDI files, hence their constructors do not accept a route argument.
NOTE: Unlike System Exclusive Messages, Meta Messages do contain full 8-bit data bytes.
make-meta-message type
meta-message-p message
meta-message-type message
make-sequence-number num
sequence-number-p message
This optional event which must occur at the beginning of a track (ie, before any non-zero delta-times and before any midi events) specifies the number of a sequence. The two data bytes ss ss, are that number which corresponds to the MIDI Cue message. In a format 2 MIDI file, this number identifies each "pattern" (ie, Mtrk) so that a "song" sequence can use the MIDI Cue message to refer to patterns. If the ss ss numbers are omitted (ie, Length byte = 0 instead of 2), then the track's location in the file is used (ie, the first MTrk chunk is the first pattern). In format 0 or 1, which contain only one "pattern" (even though format 1 contains several tracks), this event is placed in only the first track. So, a group of format 1 files with different sequence numbers can comprise a "song collection".
There can be only one of these events per MTrk chunk in a Format 2. There can be only one of these events in a Format 0 or 1, and it must be in the first track.
make-text-event string &optional type
text-event-p message
make-copyright-note string
copyright-note-p message
make-sequence/track-name string
sequence/track-name-p message
make-instrument-name string
instrument-name-p message
make-lyric string
lyric-p message
make-marker string
marker-p message
make-cue-point string
cue-point-p message
A Text Event stores any amount of text. Although this text could be used for any purpose, the specialized Copyright Note, Sequence/Track Name, Instrument Name, Lyric, Marker and Cue Point messages should be used whereever applicable. Lyric messages indicate a song lyric (ie, text) which occurs on a given beat. A single Lyric MetaEvent should contain only one syllable or an empty string, indicating a melisma. Marker events might be used to denote a loop start and loop end, etc. Cue Points might be used to indicate the start of sample, with the sound file's name in string.
Text messages, Copyright Notes, Sequence/Track Names and Instrument Names are best put at the beginning of a track.
make-midi-channel channel
midi-channel-p message
This optional event which normally occurs at the beginning of an track (ie, before any non-zero delta-times and before any MetaEvents except Sequence Number) specifies to which MIDI Channel any subsequent MetaEvent or System Exclusive events are associated. It is acceptable to have more than one MIDI channel event in a given track, if that track needs to associate various events with various channels.
make-midi-port port
midi-port-p message
This optional event which normally occurs at the beginning of an track (ie, before any non-zero delta-times and before any midi events) specifies through which MIDI Port (or bus) the track events should be sent. It is legal to have more than one Port event in a given track, if that track needs to output to another port at some point in the track.
make-eot ()
eot-p message
This event is not optional. It must be the last event in every track.
make-tempo-change tempo
tempo-change-p message
Indicates a tempo change, where tempo is expressed in microseconds per MIDI quarter note.
make-smpte-offset
hours mins secs frames fractional-frames
smpte-offset-p message
Designates the SMPTE start time of the track and should therefore at the beginning of the track. In a format 1 file, the SMPTE Offset must be stored with the tempo map (ie, the first track), and has no meaning in any other track. fractional-frames is in 100ths of a frame, even in SMPTE-based MTrks which specify a different frame subdivision for delta-times (ie, different from the subframe setting in the file header). The hour should not be encoded with the SMPTE format as it is in MIDI Time Code.
make-time-signature numerator denominator
&optional (clocks 24)
(32nds 8)
time-signature-p message
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.
In a format 0 file, the tempo and time signature changes are scattered throughout the one track. In format 1, the very first track should consist of just the tempo and time signature events so that it could be read by some device capable of generating a "tempo map". In format 2, each track should begin with at least one initial tempo and time signature event. If there are no tempo and time signature events in a MIDI file, a tempo of 120 bpm and 4/4 meter is assumed.
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.
make-key-signature key &optional (mode
:major)
key-signature-p message
Indicates a change of key. key is a number between -7 and 7 denoting the number of flats (negative) or sharps (positive) in the signature. mode is either :major or :minor and defaults to :major.
In a format 0 file, key signatures are scattered throughout the one track. In format 1, the very first track only should contain key signature events so that it could be read by some device capable of generating a gloabl "key map". In format 2, each track should begin with a key signature event. If there is no key signature in a MIDI file, a key of C Major is assumed.
make-sequencer-event &rest data
sequencer-event-p message
- message
Also known as Proprietary Event. It can be used by a program to store proprietary data. The first byte(s) should be a unique ID of some sort so that a program can identity whether the event belongs to it, or to some other program. A 4 character (ie, ascii) ID is recommended for such.
midi-note, midi-channel-message, midi-message, import, open, receive, make-sysex-data, MIDI Sysex Messages, SMPTE, MIDI Controllers, General MIDI