Generated: Sunday, June 3, 2007, 22:57:19 Copyright © 2007 , Kurt Nørmark The local LAML software home page

Midi Function Library

Kurt Nørmark © normark@cs.aau.dk Department of Computer Science, Aalborg University, Denmark.

LAML Source file: styles/xml-in-laml/midi/midi-laml-processing-lib.scm

This is a library of common MIDI manipulation functions. It must be loaded together with the MIDI LAML mirror library.

Table of Contents:
1. Message List functions. 3. Single midi message abstractions. 5. Overall processing utilities.
2. Midi region functions. 4. Channel replication, (copying) joining, and selection.

Alphabetic index:
add-to-velocity (add-to-velocity channel amount . messages) Add amount to velocity of a given channel.
chord-meta (chord-meta root [chord-type])
distribute-even (distribute-even channel . messages) Distribute all NoteOn in the given channel evenly.
eliminate-control-change (eliminate-control-change channel control . messages) Eliminate ControlChange message in a given channel and with a given control number.
fade-out (fade-out . messages) Fade out linearly through message-list.
interpolate (interpolate channel . messages) Put an interpolation note in between every note on the given channel.
join-channels (join-channels channel-list ch-to . messages) Join (remove) messages in channel-list, and instead assign these too channel ch-to.
lyrics (lyrics txt) Create a lyris meta event with the given text.
midi-comment (midi-comment . text-strings) Return a deltaTime meta event which can act as a comment in the midi file.
midi-context (midi-context continuation-name . messages) Establish a context in which a smaller selection can be made.
midi-null-event (midi-null-event delta-time) A deltaTime midi null event.
midi-region (midi-region . midi-messages) Marks a region of midi messages, with the purpose of adding additional structure to a MIDI LAML file (much like span and div in HTML).
midi-region-do (midi-region-do contextual-continuation . messages) Marks a region of midi messages.
no-sustain (no-sustain channel . messages) Eliminate all sustain ControlChange messages on the given channel in message-list.
octave (octave channel n . messages) Change octave on channel ch with n.
pan (pan c value) Set the PAN of channel c to value.
pan-flow (pan-flow channel pan-from pan-to . messages) Gradually pan a given channel from pan-from to pan-to.
quantize (quantize channel q pulses-per-quarter-note . messages) Quantize channel to q.
replicate (replicate n . messages) Replicate the events (in all channels) in message-list n times.
replicate-channel (replicate-channel ch-from ch-to . messages) Replicate each message of a given channel in message-list.
select-channel (select-channel channel . messages) Return only those messages from message-list which belong to the given channel.
select-channels (select-channels channel-list . messages) Select (project) to only those channels of channel-list.
split-and-process-all-styles (split-and-process-all-styles input-dir-path output-dir-path mode channel-selection) Spilt each style file in input-dir-path in midi pieces, and generate (up to) 15 different in output-dir-path.
split-and-process-style (split-and-process-style style-file-path output-dir-path mode channel-selection) Spilt a given style file in midi pieces, and generate (up to) 15 different midi files of the parts.
strum-1 (strum-1 length root chord-type . messages) Add strum (a sequence of chord adapted notes) to all matching notes in messages.
strum-2 (strum-2 . messages) Add strum (a sequence of chord adapted notes) to all matching notes in messages.
strum-3 (strum-3 channel . messages) Add strum (a sequence of chord adapted notes) to all matching notes in messages which belong to channel.
substitute-section-by-bar substitute-section-by-bar Substitute sections of the midi message-list with sections from section-list.
time-displace (time-displace displacement . messages) Time displace with amount.
time-displace-channels (time-displace-channels channel-list displacement . messages) As time-displace, but only affecting channels in channel-list
time-stretch (time-stretch factor . messages) Stretch the time of message-list with a factor.
transpose (transpose amount . messages) Transpose all channels with amount.
transpose-channels (transpose-channels channel-list amount . messages) Transpose channels in channel-list with amount.
voice (voice channel msb lsb program-number) Emit two channel change messages (msb/lsb) and a program change message.


1 Message List functions.
This section contains function that can be applied to lists of midi messages.

fade-out
Form (fade-out . messages)
Description Fade out linearly through message-list. Works in both absTime and deltaTime mode.
Parameters messages A list of midi messages (such as NoteOn messages)
See also Scheme source file fade-out

time-stretch
Form (time-stretch factor . messages)
Description Stretch the time of message-list with a factor. Works in both absTime and deltaTime mode.
Parameters messages A list of midi messages (such as NoteOn messages)
factor A factor with wich to stretch the timing of the messages. A factor 1 is neutral with respect to timing.
See also Scheme source file time-stretch

time-displace
Form (time-displace displacement . messages)
Description Time displace with amount. Affects all channels as well as system messages. Displacement can be positive or negative. As of now, it works only in absTime mode.
Parameters messages A list of midi messages (such as NoteOn messages)
displacement The displacement of messages in time units, as described by the pulsesPerQuarterNote attribute of MidiHeader. Can be positive or negative.
See also Scheme source file time-displace

time-displace-channels
Form (time-displace-channels channel-list displacement . messages)
Description As time-displace, but only affecting channels in channel-list
Parameters messages A list of midi messages (such as NoteOn messages)
displacement The displacement of messages in time units, as described by the pulsesPerQuarterNote attribute of MidiHeader. Can be positive or negative.
channel-list A list of channels. (A list of integers in the interval 1..16).
See also Scheme source file time-displace-channels

add-to-velocity
Form (add-to-velocity channel amount . messages)
Description Add amount to velocity of a given channel. If the volicity exceeds the limits (0..127) it is enforced to the lower/upper limit. Works in both absTime and deltaTime mode.
Parameters messages A list of midi messages (such as NoteOn messages)
amount An amount to add to the velocity. Positive or negative.
See also Scheme source file add-to-velocity

replicate
Form (replicate n . messages)
Description Replicate the events (in all channels) in message-list n times. Most useful in deltaTime mode. Is typically used to play n verses of a song.
Parameters messages A list of midi messages (such as NoteOn messages)
n The number of replications. Must be a non-negative integer.
See also Scheme source file replicate

octave
Form (octave channel n . messages)
Description Change octave on channel ch with n. Works in both absTime and deltaTime mode.
Parameters messages A list of midi messages (such as NoteOn messages)
n Relative octave number. n can be positive or negative. The amount 0 is neutral.
See also Scheme source file octave

interpolate
Form (interpolate channel . messages)
Description Put an interpolation note in between every note on the given channel. Works only in absTime mode.
Parameters messages A list of midi messages (such as NoteOn messages)
channel A channel number in the interval 1..16.
See also Scheme source file interpolate

quantize
Form (quantize channel q pulses-per-quarter-note . messages)
Description Quantize channel to q. Only in absTime mode.
Parameters messages A list of midi messages (such as NoteOn messages)
pulses-per-quarter-note Must (redundantly) be similar to the pulsesPerQuarterNote attribute of MidiHeader.
q One of the integer values 1, 2, 4, 8, 16, 32, 64 and 128. 4 means a quater note quantification.
See also Scheme source file quantize

distribute-even
Form (distribute-even channel . messages)
Description Distribute all NoteOn in the given channel evenly. Does only work in absTime mode.
Parameters messages A list of midi messages (such as NoteOn messages)
channel A channel number in the interval 1..16.
See also Scheme source file distribute-even

transpose
Form (transpose amount . messages)
Description Transpose all channels with amount. amount can be negative, 0 (for no transposition), or positive. Works for both deltaTime and absTime.
Parameters messages A list of midi messages (such as NoteOn messages)
amount A relative number of half note values (positive or negative). The amount 0 is neutral.
See also Scheme source file transpose

transpose-channels
Form (transpose-channels channel-list amount . messages)
Description Transpose channels in channel-list with amount. amount can be negative, 0 (for no transposition), or positive. Works for both deltaTime and absTime.
Parameters messages A list of midi messages (such as NoteOn messages)
amount A relative number of half note values (positive or negative). The amount 0 is neutral.
channel-list A list of channels. (A list of integers in the interval 1..16).
See also Scheme source file transpose-channels

pan-flow
Form (pan-flow channel pan-from pan-to . messages)
Description Gradually pan a given channel from pan-from to pan-to. Works for both deltaTime and absTime. The limits of pan-from and pan-to are 1..127. If exceeded, automatic cut off to min/max value is provided.
Parameters messages A list of midi messages (such as NoteOn messages)
channel A channel number in the interval 1..16.
pan-from The initial pan value. 64 is neutral, 0 is hard left, and 127 is hard right.
pan-to The final pan value. 64 is neutral, 0 is hard left, and 127 is hard right.
See also Scheme source file pan-flow

no-sustain
Form (no-sustain channel . messages)
Description Eliminate all sustain ControlChange messages on the given channel in message-list.
Parameters channel A channel number in the interval 1..16.
messages A list of midi messages (such as NoteOn messages)
See also Scheme source file no-sustain

eliminate-control-change
Form (eliminate-control-change channel control . messages)
Description Eliminate ControlChange message in a given channel and with a given control number.
Parameters channel A channel number in the interval 1..16.
control A control number in the interval 0 ..127
messages A list of midi messages.
See also Scheme source file eliminate-control-change


2 Midi region functions.
This section contains function that establish regions around a list of midi messages.

midi-context
Form (midi-context continuation-name . messages)
Description Establish a context in which a smaller selection can be made. Defined as a macro. The context can be substituted by the selection inside it. Underlying, a continuation named select is captured.
Parameters continuation-name The formal name of the continuation that controls the emitted MIDI messages.
messages A list of midi messages (such as NoteOn messages)
Examples (midi-context select ... (midi-region-do select ...) ...)
See also Scheme source file midi-context

midi-region-do
Form (midi-region-do contextual-continuation . messages)
Description Marks a region of midi messages. Pass them through to contextual-continuation and, if in absTime mode, time displace them to time 0. midi-region-do is used to select and play a selected part of a MIDI LAML file.
Parameters messages A list of midi messages (such as NoteOn messages)
contextual-continuation The continuation to which messages are passed. This is normally the continuation established by the midi-context form.
See also Scheme source file midi-region-do

midi-region
Form (midi-region . midi-messages)
Description Marks a region of midi messages, with the purpose of adding additional structure to a MIDI LAML file (much like span and div in HTML). Pass them through to caller. Mark the region in the binary midi file with midi-comments.
Parameters messages A list of midi messages (such as NoteOn messages)
Attributes
Required: *
name The name of the midi region
drop A boolean attribute which allows for elimination of the region.
See also Scheme source file midi-region


3 Single midi message abstractions.
Abstractions that generate a single, or a few midi messages.

midi-null-event
Form (midi-null-event delta-time)
Description A deltaTime midi null event. The midi null event is neutral with respec to the midi sound. Implemented as a Meta event of type 1.
See also Scheme source file midi-null-event

midi-comment
Form (midi-comment . text-strings)
Description Return a deltaTime meta event which can act as a comment in the midi file.
Parameters text-strings Textual contents, in term of zero, one or several strings.
See also Scheme source file midi-comment

pan
Form (pan c value)
Description Set the PAN of channel c to value. Returns a single MIDI ControlChange event.
Parameters c A channel number between 1 and 16.
value The pan value. 64 is neutral, 0 is hard left, and 127 is hard right.
See also Scheme source file pan

voice
Form (voice channel msb lsb program-number)
Description Emit two channel change messages (msb/lsb) and a program change message. You should look up msb/lsb bank number and program number in a midi reference sheet. The program number is according to the general midi specification.
Parameters channel A channel number (between 1 and 16)
msb Most significant byte of bank number. An integer between 0 and 127.
lsb Least significant byte of bank number. An integer between 0 and 127.
program-number. The Standard MIDI program number.
See also Scheme source file voice

chord-meta
Form (chord-meta root [chord-type])
Description
Parameters root The name of the root note. One of "C" "C#" "D" "D#" "E" "F" "F#" "G" "G#" "A" "A#" "B" (a string).
chord-type The name of a chord type. One of "1+8" "1+5" "M" "6" "M7" "M7b5" "M7(#11)" "9" "M7_9" "6_9" "b5" "aug" "7aug" "M7aug" "m" "m6" "m7" "m7b5" "m(9)" "m7(9)" "m7(11)" "mM7b5" "mM7" "mM7(9)" "dim" "dim7" "7" "7sus4" "7(9)" "7(#11)" "7(13)" "7b5" "7(b9)" "7(b13)" "7(#9)" "sus4" "sus2" (a string).
See also Scheme source file chord-meta
Note Please notice that upper/lower case is important in the chord-type parameter (but not in the root parameter).

lyrics
Form (lyrics txt)
Description Create a lyris meta event with the given text.
Parameters txt A lyrics contribution (a text string).
See also Scheme source file lyrics
Note Yamaha Tyros observation: Do not use the Danish Ø, ø, Æ, and æ in the text. The Danish å and Å are OK.

strum-1
Form (strum-1 length root chord-type . messages)
Description Add strum (a sequence of chord adapted notes) to all matching notes in messages. Similar to strum-2, but this version takes explicit, positional chord root, chord type and strum length parameters. A given notes matches a chord and a root if the note is present in the chord sequence made by root and chord-type. If the chord does not match a note, just return the note. Else return a longer chord adapted list ending with note-on-ast. Should only be used on absTime (?). The parameters lgt, root, chord-type, delta-time, duration, channel and velocity is as for noteon-sequence-ending-at.
Parameters length The number notes produced in case of a match (a non-negative integer)
root The name of the root note. One of "C" "C#" "D" "D#" "E" "F" "F#" "G" "G#" "A" "A#" "B" (a string).
chord-type The name of a chord type. One of "1+8" "1+5" "M" "6" "M7" "M7b5" "M7(#11)" "9" "M7_9" "6_9" "b5" "aug" "7aug" "M7aug" "m" "m6" "m7" "m7b5" "m(9)" "m7(9)" "m7(11)" "mM7b5" "mM7" "mM7(9)" "dim" "dim7" "7" "7sus4" "7(9)" "7(#11)" "7(13)" "7b5" "7(b9)" "7(b13)" "7(#9)" "sus4" "sus2" (a string).
See also Scheme source file strum-1

strum-2
Form (strum-2 . messages)
Description Add strum (a sequence of chord adapted notes) to all matching notes in messages. Similar to strum-1, but this version takes chord root, chord type and strum length from attributes of NoteOn. The strum-length attribute defaults to 4 in the context of this function. The chord-type defaults to major ("M"). This "C" and "C#" are legal chord attribute values of NoteOn elements. They are identical to "CM" and "C#M". A given notes matches a chord and a root if the note is present in the chord sequence made by root and chord-type. If the chord does not match a note, just return the note. Else return a longer chord adapted list ending with note-on-ast. Should only be used on absTime (?). The chord root, chord type, and strum length are taken from the chord and strum-length attributes of the NoteOn elements.
See also Scheme source file strum-2

strum-3
Form (strum-3 channel . messages)
Description Add strum (a sequence of chord adapted notes) to all matching notes in messages which belong to channel. Similar to strum-1, but this version takes chord root, chord type from Meta events, maybe and typically generated from the accompaniment of Keyboard. It may also take chord information from a chord attribute of NoteOn messages. As a distinctive feature of this version of strum, the chord information is carried through the messages. The strum-length attribute defaults to 4 in the context of this function, but it can change if a NoteOn messages carries a strum-length attribute. A given notes matches a chord and a root if the note is present in the chord sequence made by root and chord-type. If the chord does not match a note, just return the note. Else return a longer chord adapted list ending with note-on-ast. Should only be used on absTime (?).
See also Scheme source file strum-3


4 Channel replication, (copying) joining, and selection.

replicate-channel
Form (replicate-channel ch-from ch-to . messages)
Description Replicate each message of a given channel in message-list. Allocate each replicated message in channel ch-to. Existing messages in ch-to are not affected. It may be useful to use target channels outside the interval [1..16] for temporary purposes. Each message belonging to channel ch-to is immediately replicated. (This is a contrast to the function replicate, which serves as "verse replication").
Parameters ch-from A channel (an integer between 1 and 16)
ch-to A channel (an integer between 1 and 16)
messages A list of midi messages (such as NoteOn messages)
See also Scheme source file replicate-channel

join-channels
Form (join-channels channel-list ch-to . messages)
Description Join (remove) messages in channel-list, and instead assign these too channel ch-to. Existing messages in ch-to are not affected. It is allowed to use source/target channels outside the interval [1..16]. ch-to is allowed to one of the channels in channel-list.
Parameters channel-list A list of channel numbers (an integer list).
messages A list of midi messages (such as NoteOn messages)
See also Scheme source file join-channels

select-channel
Form (select-channel channel . messages)
Description Return only those messages from message-list which belong to the given channel. Also include messages without a channel assigned to them. Works in both absTime and deltaTime mode.
Parameters messages A list of midi messages (such as NoteOn messages)
channel A channel (an integer between 1 and 16)
See also Scheme source file select-channel

select-channels
Form (select-channels channel-list . messages)
Description Select (project) to only those channels of channel-list. Also include messages without a channel assigned to them.
Parameters messages A list of midi messages (such as NoteOn messages)
channel-list A list of channel numbers (an integer list).
See also Scheme source file select-channels


5 Overall processing utilities.

split-and-process-style
Form (split-and-process-style style-file-path output-dir-path mode channel-selection)
Description Spilt a given style file in midi pieces, and generate (up to) 15 different midi files of the parts. Place the midi pieces in a subdirectory of output-dir-path. Apply mode (deltaTime or absTime). Only output channels in channel-selection (a list of integers).
See also Scheme source file split-and-process-style

split-and-process-all-styles
Form (split-and-process-all-styles input-dir-path output-dir-path mode channel-selection)
Description Spilt each style file in input-dir-path in midi pieces, and generate (up to) 15 different in output-dir-path. A bulk processing variant of split-and-process-style. Apply mode (deltaTime or absTime) and select channels in channel-selection (a list of integers).
See also Scheme source file split-and-process-all-styles

substitute-section-by-bar
Form substitute-section-by-bar
Description Substitute sections of the midi message-list with sections from section-list. The midi message-list must be in absTime mode and the replacements must be in deltaTime mode. (This is not checked). The affected sections in the midi message-list are identified by bar. Only messages in the given channels are substituted. The inserted sections are replicated to fill the requested number of bars (but they are never divided). By giving empty insertion section-list, it is possible to remove given sections.
Parameters channels A list of channels (a list of integers)
section-list A list of sections to be inserted. Each section is itself a list, which has the form (bar-number number-of-bars replacement-list).
See also Scheme source file substitute-section-by-bar

Generated: Sunday, June 3, 2007, 22:57:19
Generated by LAML SchemeDoc using LAML Version 32.0 (March 9, 2007, full)