Generated: Tuesday, August 19, 2008, 09:16:11 Copyright © 2008 , Kurt Nrmark The local LAML software home page

Midi Function Library

Kurt Nrmark © 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. Midi message predicates. 6. Midi region functions. 11. Generation of guitar beats.
2. Midi message accessor. 7. Single midi message abstractions. 12. Style Splitting.
3. Message List functions. 8. Channel replication, (copying) joining, and selection. 13. Auxiliary functions.
4. Generation of Scaling Functions. 9. Midi transformations on given bars.
5. Examples of Concrete Scaling Functions. 10. Midi transformations on sections.

Alphabetic index:
Meta? (Meta? x [type]) Is x a Meta midi message of type.
NoteOn? (NoteOn? x) Is x a NoteOn midi message?
abs-merge (abs-merge other-message-list . messages) Merge the current selection with another a list of messages.
add-to-velocity (add-to-velocity channel amount . messages) Add amount to velocity of a given channel.
add-two-scaling-functions (add-two-scaling-functions sf1 sf2) Add two scaling functions with each other
beat (beat direction stretch base-velocity total-length velocity-scaling-fn delta-time-scaling-fn [transposition ch base-duration time-note-list]) Return a guitar beat chord in channel ch with a number notes, with an enforced total length (duration) of total-length.
channel-message? (channel-message? x) Is x a midi message ast with a channel attribute? Returns #f is x is not an AST.
channel-volume-flow (channel-volume-flow channel channel-volume-from channel-volume-to . messages) Gradually channel-volume a given channel from channel-volume-from to channel-volume-to.
chord-complement (chord-complement chord-str-list) Returns the complement of chord-str-list, relative to the possible note names.
chord-meta (chord-meta root [chord-type]) Create a Yamaha Tyros Meta event (with deltaTiming, value 0) that encodes a given root and chord-type.
delete-channel (delete-channel channel . messages) Delete those messages from message-list which belong to the given channel.
delete-channel-abs-time (delete-channel channel . messages) Delete those messages from message-list which belong to the given channel.
delta-merge (delta-merge other-message-list . messages) Merge the current selection with another a list of messages.
distribute-even (distribute-even channel . messages) Distribute all NoteOn in the given channel evenly.
drum-NoteOn? (drum-NoteOn? x) Is x a NoteOn drum midi message? In the context of this predicate, a drum midi message uses channel 9 or channel 10.
duration-to-next (duration-to-next default-duration) Return an duration attribute value pair (a list of two elements) of the deltaTime length from the hosting NoteOn to the next NoteOn with same channel and the same note value.
eliminate-control-change (eliminate-control-change channel control . messages) Eliminate ControlChange message in a given channel and with a given control number.
eliminate-events (eliminate-events predicate . messages) Eliminate events that matches the predicate.
eliminate-midi-null-events (eliminate-midi-null-events . messages) Eliminate midi null events in all channels.
eliminate-program-change (eliminate-program-change channel . messages) Eliminate ProgramChange message in a given channel.
enforce-minimum-message-length (enforce-minimum-message-length min-length message-list) Enforce that message-list will have a mini length of min-length.
envelope-sections-by-bar (envelope-section-by-bar section-list . message-list) Envelope sections of the midi message-list with pieces from section-list.
fade-out (fade-out . messages) Fade out linearly all channels in message-list.
fade-out-channels (fade-out . messages) Fade out linearly channelels in channel-list in message-list.
filter-messages (filter-messages pred-fn . messages) Keep those messages in the message list that satisfy the predicate pred-fn.
from-percent-points (from-percent-points point-lst) Return a list of points useful for make-scale-function-by-xy-points.
from-permille-points (from-permille-points point-lst) Return a list of points useful for make-scale-function-by-xy-points.
generate-mega-voice-function (generate-mega-voice-function mega-voice-map) Generates a mega-voice-function from a given mega voice map.
icon (icon name) Return an icon name, which serve as the 'middle name' of a style file.
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 to channel ch-to.
keep-beat (keep-beat n [displacement ppqn]) Generates a useful absTime predicate for thin-out-messages-abs-time.
lyrics (lyrics txt) Create a lyrics meta event with the given text.
make-pitch-bend-change-list (make-pitch-bend-change-list ch n duration scale-fn [first-delta-time]) Return a list of n deltaTimed PitchBendChange midi events for channel ch with a total duration.
make-scale-fn-pol-one-pol (make-scale-fn-pol-one-pol shape-start shape-end c d) Generates a positive, continuous scaling function which is constant one 'in the middle' and a second degree polynomial 'in the ends'.
make-scale-fn-pol-one-pol-general (make-scale-fn-pol-one-pol-general shape-start shape-end cs ds ce de) A generalization of f-identity-symmetric which uses separate parameters of the second degree polynomials at the start of the interval and at the end of the interval.
make-scale-function-by-xy-points (make-scale-function-by-xy-points xy-list) Return a scaling function composed by linear functions on subintervals of [0,1].
make-tempo-change-list (make-tempo-change-list n duration base-tempo scale-fn [last-tempo]) Return a list of n deltaTimed tempo Meta events with a total length of duration.
marker-channel (marker-channel channel . messages) Use the given channel as a marker channel.
midi (midi attribute-name mes) Return the attribute value of the attribute named attribute-name of mes.
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-marker (midi-marker marker-txt) Return a deltaTime meta event of type 6 - a marker event.
midi-null-event (midi-null-event delta-time [info-text]) A deltaTime midi null event inserted at delta-time.
midi-null-event-abs-time (midi-null-event-abs-time abs-time [info-text]) An absTime midi null event, inserted at abs-time.
midi-null-event-delta-time (midi-null-event-delta-time delta-time [info-text]) A deltaTime midi null event inserted at delta-time.
midi-null-event-message? (midi-null-event-message? x) Is x a midi null event AST? In fact, this predicate catches all Meta type 1 events (because the textual contents of midi null events have been given free).
midi-null-event-text midi-null-event-text The default midi null event info text.
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.
multiply-scaling-function (multiply-scaling-function factor sf) Multiply a scaling function sc my a factor, and return the new, scaled scaling function.
multiply-two-scaling-functions (multiply-two-scaling-functions sf1 sf2) Multiply two scaling functions with each other
no-sustain (no-sustain channel . message-list) Eliminate all sustain ControlChange messages on the given channel in message-list.
non-channel-message? (non-channel-message? x) Is x a midi message ast without a channel attribute? Returns #f is x is not an AST.
note-complement (note-complement note-str-list) Returns the complement of note-str-list, relative to the possible note names.
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.
pitch-bend-range (pitch-bend-range channel range . optional-parameter-list) Emit four control change messages which control the pitch-bend-range, in half tones and cents, for the given channel.
pitch-bend-scale (pitch-bend-scale factor) A higher-order function that returns a numeric pitch-bend scaling function that takes into consideration that the mid-point pitch-bend value is 8192 (and not 0 as in the simple case of scaling).
play-chord (play-chord root chord-type start-octave number-of-octaves time-delta duration [channel velocity]) Play a given chord progression as a (maybe long) number of NoteOn messages, mostly for chord demo purposes.
quantize (quantize channel q pulses-per-quarter-note . messages) Quantize channel to q.
quantize-channels (quantize channel-list q pulses-per-quarter-note . messages) Quantize a number of channels to q.
repeat-messages (repeat-messages n . messages) Repeat messages n times.
repeat-messages-enforce-periode-length (repeat-messages-enforce-periode-length n min-period-length . messages) Repeat messages n times, and enforce that each repetition has length of at least min-period-length.
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.
same-time-transform (same-time-transform channels transformer . messages) Transform consecutive midi NoteOn messages (two or more) that belong to channels, and which occur at the same time.
scale-attribute (scale-attribute attribute-name scaling-function . messages) Context-dependent scaling of an attribute with use of a scaling function.
scale-attribute-by-factor (scale-attribute-by-factor ast-predicate attribute-name factor . messages) Scale the value of attribute-name with factor.
scale-velocity-of-sections-by-bar (scale-velocity-of-sections-by-bar channels section-list . message-list) Scale the velocity of NoteOn messages, in selected channels, in given bars.
scale-velocity-of-sections-by-time (scale-velocity-of-sections-by-time channels section-list . message-list) Scale the velocity of NoteOn messages, in selected channels, in given regions of time.
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.
sf1 sf1 A scaling function
sf2 sf2 A scaling function
sf3 sf3 A scaling function
sf4 sf4 A scaling function
sf5 sf5 A scaling function
sf6 sf6 A scaling function
split-and-process-all-style-directory-refined (split-and-process-all-style-directory-refined meta-file-path input-dir-path output-dir-path mode) Split each style file in each directory of input-dir-path in midi pieces, and organize the midi pieces in output-dir-path.
split-and-process-all-styles (split-and-process-all-styles input-dir-path output-dir-path mode channel-selection) A bulk processing variant of split-and-process-style.
split-and-process-all-styles-refined (split-and-process-all-styles-refined meta-file-path input-dir-path output-dir-path mode) Split each style file in input-dir-path in midi pieces, and organize the midi pieces in output-dir-path.
split-and-process-style (split-and-process-style style-file-path output-dir-path mode channel-selection) Split a given style file in midi pieces, and generate (up to) 15 different midi files of the parts.
split-and-process-style-one-channel-refined (split-and-process-style-one-channel-refined style-file-path output-dir-path mode channel) A much refined version of split-and-process-style.
split-and-process-style-refined (split-and-process-style-refined meta-file-path style-file-path output-dir-path mode) Split all channels in a style file into midi pieces.
steel-guitar-megavoice-map steel-guitar-megavoice-map The mega voice map of a steel guitar (tyros 1).
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 channels section-list . message-list) Substitute sections of the midi message-list with sections from section-list.
substitute-section-by-time (substitute-section-by-time channel section-list . message-list) Substitute sections of the midi message-list with sections from section-list.
subtract-two-scaling-functions (subtract-two-scaling-functions sf1 sf2) Subtract two scaling functions with each other
tempo (tempo bpm) Return a tempo Meta event, for tempo bpm, at deltaTime 0.
thin-out-messages-abs-time (thin-out-messages-abs-time channel-list abs-time-pred . messages) Thin out messages based on their absolute timing.
thin-out-messages-delta-time (thin-out-messages-delta-time channel-list abs-time-pred start-time . messages) Thin out messages based on their absolute timing, where the absolute timing is calculated from start-time and the deltaTime attributes.
thin-out-section-by-bar (thin-out-section-by-bar channel section-list . message-list) Thin out sections of the midi message-list by means of abs-time predicates.
time-adapt-to (time-adapt-to new-length . messages) Adapt the time of the midi messages to new-length time units in total.
time-displace (time-displace displacement . messages) Time displace with amount (adds displacement to the absolute time of the event).
time-displace-channels (time-displace-channels channel-list displacement . messages) As time-displace, but only affecting channels in channel-list
time-displace-channels-with-scaling (time-displace-channels-with-scaling channel-list displacement scaling-fn . messages) As time-displace-channels, but with a scaling of the amount of displacement.
time-of-marker (time-of-marker marker-name [message-list]) Find the absTime of marker with name marker-name, such as "M-1", in message-list.
time-stretch (time-stretch factor . messages) Stretch the time and duration of message-list with a factor.
total-length-of-message-list (total-length-of-message-list message-list) Calculate the total length of message-list.
transform-attribute (transform-attribute ast-predicate attribute-name trasformation-fn . messages) Transform the value of attribute-name with with a given numeric transformation function.
transform-messages (transform-messages filter-fn transformation-fn . messages) If filter-fn holds (returns true) on a given midi message, transform this message with transformation-fn.
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 Midi message predicates.

NoteOn?
Form (NoteOn? x)
Description Is x a NoteOn midi message?
See also Scheme source file NoteOn?

Meta?
Form (Meta? x [type])
Description Is x a Meta midi message of type.
Parameters x Any data, but typically some midi AST.
type A meta type attribute (an integer). If not provided, the type does not matter.
See also Scheme source file Meta?

drum-NoteOn?
Form (drum-NoteOn? x)
Description Is x a NoteOn drum midi message? In the context of this predicate, a drum midi message uses channel 9 or channel 10.
See also Scheme source file drum-NoteOn?

midi-null-event-message?
Form (midi-null-event-message? x)
Description Is x a midi null event AST? In fact, this predicate catches all Meta type 1 events (because the textual contents of midi null events have been given free).
See also Scheme source file midi-null-event-message?
Generator midi-null-event

channel-message?
Form (channel-message? x)
Description Is x a midi message ast with a channel attribute? Returns #f is x is not an AST.
See also Scheme source file channel-message?

non-channel-message?
Form (non-channel-message? x)
Description Is x a midi message ast without a channel attribute? Returns #f is x is not an AST.
See also Scheme source file non-channel-message?


2 Midi message accessor.
Convenient accessor of Midi Asts. Can be used instead of the general purpose accessors of LAML asts.

midi
Form (midi attribute-name mes)
Description Return the attribute value of the attribute named attribute-name of mes. Numeric attributes are automatically returned as numbers. If mes is a non-ast, or an ast without an attribute named attribute-name, return #f.
Precondition True
Parameters attribute-name The name of the attribute. A symbol. (A string also works).
mes A midi message ast. (Any other value my also be passed, in which case the function just returns #f).
Returns The attribute value of mes, converted to a number for the following attribute-names: channel, note, velocity, duration, value, number, pressure, and strum-length.
See also Scheme source file midi
Note Can always be called. The precondition is as weak as possible.


3 Message List functions.
This section contains function that can be applied on lists of midi messages. As such, this is the important 'bread and butter' functions of this library. Most functions come in two flavors. The main function, f, can be applied in this way (f m1 m2 ... mk) on k midi messages m1 ... mk. The other flavor, always named f-1, is applied as (f-1 (list m1 m2 ... mk)). In many cases there will be a few positional and required parameters before the first message. Thus, if there are two such required parameters p1 and p2, the calling forms are (f p1 p2 m1 m2 ... mk) and (f-1 p1 p2 (list m1 m2 ... mk)) respectively. Notice that the f-1 flavor of the functions are not explicitly documented below. If necessary, consult the Scheme source file to see f-1 via the provided links under 'See also'.

fade-out
Form (fade-out . messages)
Mode Both deltaTime and absTime
Description Fade out linearly all channels in 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

fade-out-channels
Form (fade-out . messages)
Mode Both deltaTime and absTime
Description Fade out linearly channelels in channel-list in message-list. Works in both absTime and deltaTime mode.
Parameters channel-list A list of channels. (A list of integers in the interval 1..16).
messages A list of midi messages (such as NoteOn messages)
See also Scheme source file fade-out-channels

time-stretch
Form (time-stretch factor . messages)
Mode Both deltaTime and absTime. Also in absTime mode with interleaving deltaTime events.
Description Stretch the time and duration of message-list with a factor. Affects all messages (not only noteOn messages). 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 real number). A factor 1.0 is neutral with respect to timing.
See also Scheme source file time-stretch
Examples Midi LAML examples

transform-attribute
Form (transform-attribute ast-predicate attribute-name trasformation-fn . messages)
Description Transform the value of attribute-name with with a given numeric transformation function. Only messages that satisfy the ast predicate ast-pred are affected. Non-affected messages, or messages that to not have an attribtute named attribute-name, are passed without modification.
Parameters ast-predicate A predicate, guarantied to be applied on an AST (midi-message).
messages A list of midi messages
See also Scheme source file transform-attribute
Specialized function scale-attribute-by-factor
Pitch-bend scaling function pitch-bend-scale
Note The function-generator pitch-bend-scale produces functions that can be used as transformation functions in case we transform the value attribute of PitchBendChange midi messages.

scale-attribute-by-factor
Form (scale-attribute-by-factor ast-predicate attribute-name factor . messages)
Description Scale the value of attribute-name with factor. Only messages that satisfy the ast predicate ast-pred are affected. Non-affected messages, or messages that to not have an attribtute named attribute-name, are passed without modification.
Parameters ast-predicate A predicate, guarantied to be applied on an AST (midi-message)
messages A list of midi messages
See also Scheme source file scale-attribute-by-factor
Generalized function transform-attribute
Context-dependent scaling function scale-attribute
Note Notice that this function is a specialization of the more general function transform-attribute.

time-adapt-to
Form (time-adapt-to new-length . messages)
Description Adapt the time of the midi messages to new-length time units in total. The durations of the individual messages are adapted proportionally. Implemented by use of time-stretch. Can be used in both absTime mode and deltaTime mode, but it is most obvious to use this function in deltaTime mode.
Parameters messages A list of midi messages
new-length The desired length of messages including the first message to and including the last message (but excluding the sucessor's delta). An integer.
See also Scheme source file time-adapt-to

time-displace
Form (time-displace displacement . messages)
Mode absTime mode - with possible interleaved deltaTime elements
Description Time displace with amount (adds displacement to the absolute time of the event). Affects all channels as well as system messages. Displacement can be positive or negative. This function works only in absTime mode, including absTime mode where there appears deltaTime contributions. (It is trivial to achieve time displacement in deltaTime mode by just adjusting the value of a single deltaTime attribute).
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
Similar function time-displace-channels

time-displace-channels
Form (time-displace-channels channel-list displacement . messages)
Mode absTime mode - with possible interleaved deltaTime elements
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
Similar function time-displace

time-displace-channels-with-scaling
Form (time-displace-channels-with-scaling channel-list displacement scaling-fn . messages)
Mode absTime mode.
Description As time-displace-channels, but with a scaling of the amount of displacement.
Parameters channel-list A list of channels. (A list of integers in the interval 1..16).
displacement The basis amount of displacement of messages in time units, as described by the pulsesPerQuarterNote attribute of MidiHeader. Can be positive or negative. Scaled with scaling-fn before addition.
scaling-fn A scaling function.
messages A list of midi messages (such as NoteOn messages)
See also Scheme source file time-displace-channels-with-scaling
Similar function 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. Works in both absTime mode and deltaTime mode. Affects all messages with channel attributes. In deltaTime mode the first deltaTime is taken to be 0 (independent of its actual value). deltaTime mode is somewhat experimental.
Parameters q One of the integer values 1, 2, 4, 8, 16, 32, 64 and 128. As an example, 4 means a quarter note quantification.
pulses-per-quarter-note Must (redundantly) be similar to the pulsesPerQuarterNote attribute of MidiHeader.
messages A list of midi messages (such as NoteOn messages)
See also Scheme source file quantize

quantize-channels
Form (quantize channel-list q pulses-per-quarter-note . messages)
Description Quantize a number of channels to q. Works in both absTime mode and in deltaTime mode. Affects all messages with channel attributes. In deltaTime mode the first deltaTime is taken to be 0 (independent of its actual value). deltaTime mode is somewhat experimental.
Parameters q One of the integer values 1, 2, 4, 8, 16, 32, 64 and 128. As an example, 4 means a quarter note quantification.
pulses-per-quarter-note Must (redundantly) be similar to the pulsesPerQuarterNote attribute of MidiHeader.
messages A list of midi messages (such as NoteOn messages)
See also Scheme source file quantize-channels

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

channel-volume-flow
Form (channel-volume-flow channel channel-volume-from channel-volume-to . messages)
Description Gradually channel-volume a given channel from channel-volume-from to channel-volume-to. Works for both deltaTime and absTime. The limits of channel-volume-from and channel-volume-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.
channel-volume-from The initial channel-volume value. 64 is neutral, 0 is hard left, and 127 is hard right.
channel-volume-to The final channel-volume value. 64 is neutral, 0 is hard left, and 127 is hard right.
See also Scheme source file channel-volume-flow

no-sustain
Form (no-sustain channel . message-list)
Description Eliminate all sustain ControlChange messages on the given channel in message-list.
Parameters channel A channel number in the interval 1..16, or #t as a wildchard for any channel.
message-list 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. Works in both deltaTime and absTime mode.
Parameters channel A channel number in the interval 1..16. The value #t serves as a wilchard for any channel.
control A control number in the interval 0 ..127. The value #t serves as a wildchard for any control number.
messages A list of midi messages.
See also Scheme source file eliminate-control-change

eliminate-program-change
Form (eliminate-program-change channel . messages)
Description Eliminate ProgramChange message in a given channel. Works in both deltaTime and absTime mode.
Parameters channel A channel number in the interval 1..16. The value #t serves as a wilchard for any channel.
messages A list of midi messages.
See also Scheme source file eliminate-program-change

delta-merge
Form (delta-merge other-message-list . messages)
Description Merge the current selection with another a list of messages. Both the current selection and the other message list must consist of deltaTime messages (and only deltaTime messages). The sibling function (delta-merge-two-lists message-list-1 message-list-2) accepts two lists.
Precondition There are deltaTime messages (and only deltaTime messages) in both involved message lists.
Parameters other-message-list A list of deltaTime messages.
Returns a list of merged messages that preserves the timing of both input lists.
See also Scheme source file delta-merge
Note It is trivial to do the merging if one of the inputs contain absTime messages. This is because, per design, deltaTime messages can be inserted in between absTime messages.

abs-merge
Form (abs-merge other-message-list . messages)
Description Merge the current selection with another a list of messages. Both the current selection and the other message list must consist of absTime messages (and only absTime messages). The sibling function (abs-merge-two-lists message-list-1 message-list-2) accepts two lists. absTime merging, as implemented in this function, is easier to deal with.
Precondition There are absTime messages (and only absTime messages) in both involved message lists.
Parameters other-message-list A list of absTime messages.
Returns A list of merged messages (absTime)
See also Scheme source file abs-merge
Note It is trivial to do the merging if one of the inputs contain absTime messages. deltaTime merging, as implemented in delta-merge, is a little tricky - but doable.

transform-messages
Form (transform-messages filter-fn transformation-fn . messages)
Description If filter-fn holds (returns true) on a given midi message, transform this message with transformation-fn. If not, pass the midi message untransformed.
Parameters filter-fn A boolean midi-message function. Is always applied on an AST.
transformation-fn a single midi-message transformation function. Is always applied on an AST.
messages A list of midi messages (such as NoteOn messages)
Returns a list of transformed messages
See also Scheme source file transform-messages

filter-messages
Form (filter-messages pred-fn . messages)
Description Keep those messages in the message list that satisfy the predicate pred-fn. Messages that do not satify the predicate are removed. As a consequence, this function is most likely to be useful in absTime mode.
Parameters pred-fn A boolean midi-message predicate function. Will applied on an AST. If pred-fn returns true on an-ast, keep it.
messages A list of midi messages (such as NoteOn messages)
Returns a list of messages
See also Scheme source file filter-messages

thin-out-messages-abs-time
Form (thin-out-messages-abs-time channel-list abs-time-pred . messages)
Mode pure absTime
Description Thin out messages based on their absolute timing. For messages in channel-list, keep only those those message whose absTime attribute satisfy abs-time-pred. Keep messages in channels which do not belong to channel-list, and keep messages without a channel. This function is (implemented as) a specialized application of filter-messages. The higher-order function keep-beat generates useful predicates that can be used as actual parameters to abs-time-pred
Parameters channel-list A list of channel numbers (an integer list).
abs-time-pred A boolean function (lambda (abs-time) ...). Keep those message who's absTime attribute satsify the predicate. abs-time is an integer.
See also Scheme source file thin-out-messages-abs-time
Examples Midi LAML examples
Predicate generator keep-beat
More general function filter-messages
By bar variant thin-out-section-by-bar

thin-out-messages-delta-time
Form (thin-out-messages-delta-time channel-list abs-time-pred start-time . messages)
Mode deltaTime
Description Thin out messages based on their absolute timing, where the absolute timing is calculated from start-time and the deltaTime attributes. For messages in channel-list, keep only those those message whose calculated absolute time satisfy abs-time-pred. Keep messages in channels which do not belong to channel-list, and keep messages without a channel. This function is (implemented as) a specialized application of filter-messages. The higher-order function keep-beat generates useful predicates that can be used as actual parameters to abs-time-pred
Parameters channel-list A list of channel numbers (an integer list).
abs-time-pred A boolean function (lambda (abs-time) ...). Keep those message who's absTime attribute satsify the predicate. abs-time is an integer.
start-time The start-time which is used as the basis for calculating absolute times. Typically 0, but no default is available.
See also Scheme source file thin-out-messages-delta-time
Examples Midi LAML examples
Predicate generator keep-beat
More general function filter-messages
By bar variant thin-out-section-by-bar

keep-beat
Form (keep-beat n [displacement ppqn])
Description Generates a useful absTime predicate for thin-out-messages-abs-time. The absolute time is displaced with displacement (displacement is subtracted from the absolute time) before fed to the predicate. Returns a function that keeps all messages for 1/n notes, where n is 1, 2, 4, 8, ... (a power of 2, power >= 1).
Parameters n defines which notes to keep.
displacement Allows identification of notes that are systematically displace. Defaults to 0.
ppqn Pulse per quarter notes. Defaults to 1920.
Returns An abs-time predicate (lambda (abs-time) ...)
See also Scheme source file keep-beat
Use context thin-out-messages-abs-time thin-out-section-by-bar
Note (keep-beat 4) returns a predicate that keeps all quarter notes.

scale-attribute
Form (scale-attribute attribute-name scaling-function . messages)
Description Context-dependent scaling of an attribute with use of a scaling function. Scale the value of the attribute attribute-name in all NoteOn messages in messages. Non-NoteOn events (and NoteOn events which does not have an attribute named attribute-name) are not affected. The scaling is done by multiplying each attribute value with a factor returned by the scaling function. The factor depends on the position of the NoteOn message relative to the contextual NoteOn messages. scaling-function is a real-valued function (lambda (x) ...) where x belongs to the interval [0,1].
Parameters attribute-name The name of the attribute to scale. A string or symbol.
scaling-function A function from [0,1] to Real.
messages A list of midi messages (such as NoteOn messages)
See also Scheme source file scale-attribute
Examples Midi LAML examples
Non-context dependent scaling scale-attribute-by-factor
Scaling functions scaling-function-generation

marker-channel
Form (marker-channel channel . messages)
Description Use the given channel as a marker channel. Convert NoteOn messages in the given channel to markers with consequtive numbering "M-1", "M-2", etc. The note attribute is used as the level of the marker. C is level 0, D is level 1, E is level 2, etc. We only use white keys for leveling. Eliminate all other ControlChange and ProgramChange messages relating to the channel.
Parameters channel A channel number in the interval 1..16.
messages A list of midi messages (such as NoteOn messages). Cannot be empty.
See also Scheme source file marker-channel

repeat-messages
Form (repeat-messages n . messages)
Mode deltaTime
Description Repeat messages n times.
Parameters n The number of times to repeat messages. An integer.
messages A list of midi messages (such as NoteOn messages). May also be a nested list of such messages according to LAML conventions.
See also Scheme source file repeat-messages
Variant with period length repeat-messages

repeat-messages-enforce-periode-length
Form (repeat-messages-enforce-periode-length n min-period-length . messages)
Mode deltaTime
Description Repeat messages n times, and enforce that each repetition has length of at least min-period-length. (If the length of message-list is less than min-period-length, an appropriate deltaTime message is appended to each repetition.
Parameters n The number of times to repeat messages. An integer.
min-period-length The mini period length, measured in pulses (an integer).
messages A list of midi messages (such as NoteOn messages). May also be a nested list of such messages according to LAML conventions.
See also Scheme source file repeat-messages-enforce-periode-length
More basic variant repeat-messages

same-time-transform
Form (same-time-transform channels transformer . messages)
Mode absTime
Description Transform consecutive midi NoteOn messages (two or more) that belong to channels, and which occur at the same time. The tranformer can do whatever calculation necessary on these 'same time messages'. The transformer must return a list of messages (maybe empty). All other messages are not affected. All messages passed to transformer are guarantied to take place at the same time. \ The order or the messages passed to transformer is unknown.\ The transformer must return a list of midi message asts (maybe an empty list), typically (but necessarily) NoteOn messages.
Parameters channels A list of channel numbers in the interval 1..16.
transformer A function from a list of at least two NoteOn messages to a list of messages. It is guarantied that this function is called with at least two messages, which both are NoteOn messages in absTime mode.
messages A list of midi messages.
See also Scheme source file same-time-transform
Example Midi LAML examples
Note You can use this function to repair multiple track which must play in parallel. In a typical scenario you have manually corrected note values in one of the channels, and you now wish to enforce another channel to introduce the samme note corrections.


4 Generation of Scaling Functions.
Scaling functions are used for smooth scaling of attributes such as deltaTime, duration, and velocity. A scaling function has the simple signature [0,1] -> Real. The functions in this section generate such scaling functions. The next section contains concrete scaling functions. The most useful - and the most versatile - generator is make-scale-function-by-xy-points.

make-scale-fn-pol-one-pol
Form (make-scale-fn-pol-one-pol shape-start shape-end c d)
Description Generates a positive, continuous scaling function which is constant one 'in the middle' and a second degree polynomial 'in the ends'. Given 0 <= d < 0.5: Generate and return a function f for which (f d) = 1 and (f (- 1 d)) = 1. For d < x < (- 1 d): f(x) = 1. For 0 < x < d: f(x) is polynomial or constant (depending on shape-start) For (- 1 d) < x < 1: f(x) is polynomial or constant (depending on shape-end) shape-start and shape-end is either the symbol up, flat or down.
Parameters shape-start One of the symbols up, flat, or down.
shape-end One of the symbols up, flat, or down.
c The factor of the second degree term of the polynomial.
d An x-value between 0 and 0.5. The generated function is constant 1 in the interval [d, 1-d].
Returns A positive, real-valued function (lambda (x) ...) where x is in the interval [0,1].
See also Scheme source file make-scale-fn-pol-one-pol

make-scale-fn-pol-one-pol-general
Form (make-scale-fn-pol-one-pol-general shape-start shape-end cs ds ce de)
Description A generalization of f-identity-symmetric which uses separate parameters of the second degree polynomials at the start of the interval and at the end of the interval.
Parameters shape-start One of the symbols up, flat, or down.
shape-end One of the symbols up, flat, or down.
cs The factor of the second degree term of the polynomial used in the interval [0,ds].
ce The factor of the second degree term of the polynomial used in the interval [1-de, 1].
ds An x-value between 0 and 1. The generated function is constant 1 in the interval [ds, 1-de].
de An x-value between 0 and 1. The generated function is constant 1 in the interval [ds, 1-de].
Returns A positive, real-valued function (lambda (x) ...) where x is in the interval [0,1].
See also Scheme source file make-scale-fn-pol-one-pol-general

make-scale-function-by-xy-points
Form (make-scale-function-by-xy-points xy-list)
Description Return a scaling function composed by linear functions on subintervals of [0,1]. The functions from-percent-points and from-permille-points are helpful for creation of the xy-list parameter.
Parameters xy-list a list of (x,y) cons pairs which must contain at least (0, y0) and (1, y1) for some y0 and y1.
Returns A real-value function (lambda (x) ...) where x is in the interval [0,1]. Not necessarily positive valued.
See also Scheme source file make-scale-function-by-xy-points
Helper functions from-percent-points from-permille-points

multiply-scaling-function
Form (multiply-scaling-function factor sf)
Description Multiply a scaling function sc my a factor, and return the new, scaled scaling function.
Parameters sf A real-value function.
factor A real-valued number.
Returns A modified (scaled) real-valued scaling function.
See also Scheme source file multiply-scaling-function

add-two-scaling-functions
Form (add-two-scaling-functions sf1 sf2)
Description Add two scaling functions with each other
See also Scheme source file add-two-scaling-functions

subtract-two-scaling-functions
Form (subtract-two-scaling-functions sf1 sf2)
Description Subtract two scaling functions with each other
See also Scheme source file subtract-two-scaling-functions

multiply-two-scaling-functions
Form (multiply-two-scaling-functions sf1 sf2)
Description Multiply two scaling functions with each other
See also Scheme source file multiply-two-scaling-functions

from-percent-points
Form (from-percent-points point-lst)
Description Return a list of points useful for make-scale-function-by-xy-points. Both x and y parameters are percentage values. They will therefore both be divided by 100.
Parameters point-lst A list of points. Each point is of the form (n m).
Returns A list of cons pairs of the form (n/100 . m/100) suitable for input to make-scale-function-by-xy-points.
See also Scheme source file from-percent-points
Use context make-scale-function-by-xy-points

from-permille-points
Form (from-permille-points point-lst)
Description Return a list of points useful for make-scale-function-by-xy-points. Both x and y parameters are permillage values. They will therefore both be divided by 1000.
Parameters point-lst A list of points. Each point is of the form (n m).
Returns A list of cons pairs of the form (n/1000 . m/1000) suitable for input to make-scale-function-by-xy-points.
See also Scheme source file from-permille-points
Use context make-scale-function-by-xy-points


5 Examples of Concrete Scaling Functions.
This section contains concrete scaling functions, as generated by the functions in the previous section. These scaling functions may serve as inspiration when new scaling functions are needed. As already mentioned above, a scaling function has the simple signature [0,1] -> Real. We link to SVG illustrations of the graphs of the scaling functions. When a new scaling function is developed it can be tried out in man/scaling-functions/try.laml and visualized in man/scaling-functions/try.svg . Consult the Scheme source to access the source form of the scaling function.

sf1
Form sf1
Description A scaling function
See also Scheme source file sf1
Graphical illustration SVG

sf2
Form sf2
Description A scaling function
See also Scheme source file sf2
Graphical illustration SVG

sf3
Form sf3
Description A scaling function
See also Scheme source file sf3
Graphical illustration SVG

sf4
Form sf4
Description A scaling function
See also Scheme source file sf4
Graphical illustration SVG

sf5
Form sf5
Description A scaling function
See also Scheme source file sf5
Graphical illustration SVG

sf6
Form sf6
Description A scaling function
See also Scheme source file sf6
Graphical illustration SVG


6 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)
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


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

midi-null-event-text
Form midi-null-event-text
Description The default midi null event info text.
See also Scheme source file midi-null-event-text

midi-null-event
Form (midi-null-event delta-time [info-text])
Description A deltaTime midi null event inserted at delta-time. The midi null event is neutral with respect to the midi sound. Implemented as a Meta event of type 1.
Parameters delta-time The deltaTime of the midi-null-event. A non-negative integer.
info-text The text of the midi null event. Defaults to the value of the global variable midi-null-event-text.
See also Scheme source file midi-null-event
Similar Predicate midi-null-event-message?
Alias midi-null-event-delta-time
Similar function midi-null-event-abs-time
Note Deprecated. Use midi-null-event-delta-time instead.

midi-null-event-delta-time
Form (midi-null-event-delta-time delta-time [info-text])
Description A deltaTime midi null event inserted at delta-time. The midi null event is neutral with respect to the midi sound. Implemented as a Meta event of type 1.
Parameters delta-time The deltaTime of the midi-null-event. A non-negative integer.
info-text The text of the midi null event. Defaults to the value of the global variable midi-null-event-text.
See also Scheme source file midi-null-event-delta-time
Similar Predicate midi-null-event-message?
Alias of midi-null-event

midi-null-event-abs-time
Form (midi-null-event-abs-time abs-time [info-text])
Description An absTime midi null event, inserted at abs-time. The midi null event is neutral with respect to the midi sound. Implemented as a Meta event of type 1.
Parameters abs-time The absTime of the midi-null-event. A non-negative integer.
info-text The text of the midi null event. Defaults to the value of the global variable midi-null-event-text.
See also Scheme source file midi-null-event-abs-time

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

midi-marker
Form (midi-marker marker-txt)
Description Return a deltaTime meta event of type 6 - a marker event. Inserted at deltaTime 0.
Parameters marker-txt The text of the marker. (A string).
See also Scheme source file midi-marker

pan
Form (pan c value)
Description Set the PAN of channel c to value. Returns a single MIDI ControlChange event. Inserted at deltaTime 0.
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. All events are inserted at deltaTime 0.
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

tempo
Form (tempo bpm)
Description Return a tempo Meta event, for tempo bpm, at deltaTime 0.
See also Scheme source file tempo

pitch-bend-range
Form (pitch-bend-range channel range . optional-parameter-list)
Description Emit four control change messages which control the pitch-bend-range, in half tones and cents, for the given channel. All events are inserted at deltaTime 0.
Parameters channel A channel number (between 1 and 16)
range An integer between 1 and 12 (half tones). Typical range: 2.
cents An integer between 0 and 100, for fine adjustments. Defaults to 0.
See also Scheme source file pitch-bend-range
Pitch bend constructor make-pitch-bend-change-list

chord-meta
Form (chord-meta root [chord-type])
Description Create a Yamaha Tyros Meta event (with deltaTiming, value 0) that encodes a given root and chord-type. The chord-type is optional, and it defaults to "M" (for major).
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, the default of which is "M". 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
Examples Midi LAML examples
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 lyrics meta event with the given text. The lyrics meta event is inserted at deltaTime 0.
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.

play-chord
Form (play-chord root chord-type start-octave number-of-octaves time-delta duration [channel velocity])
Description Play a given chord progression as a (maybe long) number of NoteOn messages, mostly for chord demo purposes. The progression is allways ended by the root note. A list of deltaTime NoteOn messages are created. Each note has deltaTime time-delta. Each played note will last duration time units There will be time-delta between notes in the played chord (meassured in basic type units, 1920 pr. quarter note on tyros).
Parameters root The name of the root. 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).
start-octave an octave number. Octave number 3 contains the middle C (note 60) - according the yamaha convention. Within the interval [-2..8]. (An integer).
number-of-octaves The number of octaves the play the cord. A positive integer.
time-delta The delta-time of each generated NoteOn message.
duration The durationof each generated NoteOn message.
channel The channel of the generated NoteOn messages. Defaults to channel 1.
velocity The velocity of the generated NoteOn messages. Defaults to channel 80.
See also Scheme source file play-chord
Examples Midi LAML examples

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

make-pitch-bend-change-list
Form (make-pitch-bend-change-list ch n duration scale-fn [first-delta-time])
Description Return a list of n deltaTimed PitchBendChange midi events for channel ch with a total duration. The list returned is a flat list of deltaTime PitchBendChange events. The value of the PitchBendChange events are scaled by a standard scaling function, scale-fn. Scaling functions are functions from [0,1] -> Real. Per convention of this function, the scaling value 0 corresponds to 8192 (pitch bend neutral). Scaling value 1 corresponds to 16383, and scaling value -1 correponds to 0.
Parameters ch Channel number (between 1 and 16).
n The number of PitchBendChange messages to produce. Minimum value: 2
duration The total duration of the list of PitchBendChange messages. Only accurate if the first-delta-time is the default value.
scale-fn The scaling function: [0,1] -> [-1, 1].
first-delta-time The delta time of the first PichBendChange message. Defaults to the calculated deltaTime of all PitchBendChange messages.
See also Scheme source file make-pitch-bend-change-list
Scaling functions scaling-function-generation
Pitch bend calibration pitch-bend-range

make-tempo-change-list
Form (make-tempo-change-list n duration base-tempo scale-fn [last-tempo])
Description Return a list of n deltaTimed tempo Meta events with a total length of duration. Scales the base tempo with scale-fn.
Parameters n The number of Meta tempo messages to produce. At least one.
duration The total duration of the list of Meta tempo messages (in time ticks).
base-tempo The base tempo, which is scaled throughout the the of generated Meta tempo events. A real number.
scale-fn The scaling function: [0,1] -> Positive Real Number.
last-tempo If provided, the last Meta tempo event is forced to be last-tempo. A real number.
See also Scheme source file make-tempo-change-list
Scaling functions scaling-function-generation


8 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 to channel ch-to. Existing messages in ch-to are not affected. It is allowed to use source/target channels outside the interval [1..16], which are discared upon midi generation. (If you use channels outside the interval [1..16] it may affect the timing of the remaining events. Therefore it is recommended to stay inside the interval [1.16]). ch-to is allowed to be 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

delete-channel
Form (delete-channel channel . messages)
Description Delete those messages from message-list which belong to the given channel. 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 delete-channel

delete-channel-abs-time
Form (delete-channel channel . messages)
Description Delete those messages from message-list which belong to the given channel. The messages disappear entirely. Works in absTime 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 delete-channel-abs-time

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) or #t in the meaning of all channels.
channel-list A list of channel numbers (an integer list).
See also Scheme source file select-channels

eliminate-midi-null-events
Form (eliminate-midi-null-events . messages)
Description Eliminate midi null events in all channels. Works in both absTime and deltaTime mode.
Parameters messages A list of midi messages (such as NoteOn messages)
See also Scheme source file eliminate-midi-null-events

eliminate-events
Form (eliminate-events predicate . messages)
Description Eliminate events that matches the predicate. The elimination is done independent of channel. Works in both absTime and deltaTime mode.
Parameters messages A list of midi messages (such as NoteOn messages)
predicate An predicate which is guarantied to be called on an AST.
See also Scheme source file eliminate-events


9 Midi transformations on given bars.

substitute-section-by-bar
Form (substitute-section-by-bar channels section-list . message-list)
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).
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).
message-list A list of midi messages.
See also Scheme source file substitute-section-by-bar
Similar abstime function substitute-section-by-time

thin-out-section-by-bar
Form (thin-out-section-by-bar channel section-list . message-list)
Description Thin out sections of the midi message-list by means of abs-time predicates. The midi message-list must be in absTime mode. The affected sections in the midi message-list are identified by bar. Only messages in the given channels are thinned out.
Parameters channels A list of channels (a list of integers)
section-list A list of sections to be thinned out. Each section is itself a list, which has the form (bar-number number-of-bars abs-time-keep-predicate).
message-list A list of midi messages.
See also Scheme source file thin-out-section-by-bar
Examples Midi LAML examples
Predicate generator keep-beat
Simpler variant thin-out-messages-abs-time

scale-velocity-of-sections-by-bar
Form (scale-velocity-of-sections-by-bar channels section-list . message-list)
Description Scale the velocity of NoteOn messages, in selected channels, in given bars. The midi message-list must be in absTime mode (not checked). The affected sections in the midi message-list are identified by bar. Only messages in the given channels are affected
Parameters channels A list of channels (a list of integers)
section-list A list of sections in which to scale the velocity. Each section is itself a list, which has the form (bar-number number-of-bars scaling-function).
message-list A list of midi messages.
Attributes
Required: *
min-velocity The smallest possible velocity. Defaults to 0. Serves as a lower limit cut off value.
max-velocity The largest possible velocity. Defaults to 127. Serves as an upper limit cut off value.
See also Scheme source file scale-velocity-of-sections-by-bar
Examples Midi LAML examples
Similar time function scale-velocity-of-sections-by-time

envelope-sections-by-bar
Form (envelope-section-by-bar section-list . message-list)
Description Envelope sections of the midi message-list with pieces from section-list. The midi message-list must be in absTime mode and pieces from the section-list must be in deltaTime mode. (This is not checked). The affected sections in the midi message-list are identified by bar.
Parameters section-list A list of sections to be inserted. Each section is itself a list, which has the form (bar-number number-of-bars pre-envelope-list post-envelope-list). The deltaTime messages in pre-envelope-list is inserted at the beginning of the section. The deltaTime messages in post-envelope-list is inserted at the beginning of the section. .parameter message-list A list of midi messages.
See also Scheme source file envelope-sections-by-bar


10 Midi transformations on sections.
The functions in this section are similar to the functions in the previous sections. The main difference is that the functions in this section work on sections, identified by absolute time ticks, not bar numbers. The function time-of-marker allows for identification of sections by markers.

substitute-section-by-time
Form (substitute-section-by-time channel section-list . message-list)
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 time. Only messages in the given channels are substituted. The inserted sections are stretched to fill the requested number of bars. In addition it stretches the replacement-list to fit the given time interval [start-time - end-time]. It does not replicate the replacement list.
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 (time-start time-end replacement-list).
message-list A list of midi messages.
See also Scheme source file substitute-section-by-time
Similar bar function substitute-section-by-bar
Note Compared with substitute-section-by-bar this function identifies regions with absolute times, not bar number and bar length.

scale-velocity-of-sections-by-time
Form (scale-velocity-of-sections-by-time channels section-list . message-list)
Description Scale the velocity of NoteOn messages, in selected channels, in given regions of time. The midi message-list must be in absTime mode (not checked). The affected sections in the midi message-list are identified by time intervals. Only messages in the given channels are affected.
Parameters channels A list of channels (a list of integers)
section-list A list of sections in which to scale the velocity. Each section is itself a list, which has the form (start-time end-time scaling-function).
message-list A list of midi messages.
Attributes
Required: *
min-velocity The smallest possible velocity. Defaults to 0. Serves as a lower limit cut off value.
max-velocity The largest possible velocity. Defaults to 127. Serves as an upper limit cut off value.
See also Scheme source file scale-velocity-of-sections-by-time
Examples Midi LAML examples
Similar bar function scale-velocity-of-sections-by-bar

time-of-marker
Form (time-of-marker marker-name [message-list])
Description Find the absTime of marker with name marker-name, such as "M-1", in message-list. message-list defaults to the value of the global variable contextual-message-list assigned by substitute-section-by-time. The problem is, however, that contextual-message-list is not assigned before it typically is used. This problem has not been settled yet. Assume, as a precondition, that message-list is in absTime mode.
Parameters marker-name The name of a meta marker (a string). Example: "M-1".
message-list A list of midi messages. Defaults to the value of the global variable contextual-message-list.
Returns The absTime of the located meta midi message, of #f if the marker cannot be located in the message list.
See also Scheme source file time-of-marker


11 Generation of guitar beats.
The function beat generates (typically, but not necessarily) guitar beats. The instrument definition is outside the context of the beat function. The generated beats are affected by a large number of parameters. The function duration-to-next is a function which makes it possible to express the duration contextually. LAML technically, duration-to-next, is an attribute-returning delayed procedural content item function.

beat
Form (beat direction stretch base-velocity total-length velocity-scaling-fn delta-time-scaling-fn [transposition ch base-duration time-note-list])
Description Return a guitar beat chord in channel ch with a number notes, with an enforced total length (duration) of total-length. Direction is one of up or down (symbols or strings). The notes and their deltaTimes is per default fixed to a C-Major chord of six notes, but it can be customized to an arbitrary sequence via the parameter time-note-list. Each NoteOn sounds until it is activated later on in the contextual sequence, or with a duration of base-duration if it is last in the contextual sequence. Transpose with the value of transpose. Stretch with a factor of stretch (normally between 0 and 1). The velocity of each NoteOn event is, in the starting point, base-velocity (scaling is pending). The deltaTime of all but the first NoteOn event is base-delta-time (scaling is pending). The deltaTime of the first NoteOn is 0. Scale velocities with velocity-scaling-fn. Scale delta-times with delta-time-scaling-fn. noteValue may also the the symbol -, in which case the note is skipped (in the sense that the note is substituted by a mill-null-event). time-note-list defaults to a C-major chord sequence of six notes. The first deltaTime is forced to be 0, independent of its given value.
Parameters direction Either up or down (symbol or strings). If down, time-note-list is reversed.
stretch Stretch-factor (typically, but not necessarity, a real number between 0 and 1).
base-velocity The initial velocity before scaling with velocity-scaling-fn. An integer between 0 and 127.
total-length The enforced total-length of the beat. An non-negative integer.
velocity-scaling-fn A scaling function which is used to scale the base-velocity throughout the six notes.
delta-time-scaling-fn A scaling function which is used to scale the base-delta-time throughout the six notes.
transposition A transposition of the notes in the beat. A integer (positive or negative). Defaults to 0.
ch The channel in which to which the NoteOn in the beat belongs. Defaults to channel 1. An integer between 1 and 16.
base-duration The duration of all NoteOn which are not followed by a similar NoteOn in the same channel and with the same note value attribute. Defaults to 960.
time-note-list A list of deltaTime noteValue pairs which defines the basis beat of the chord. Each entry is of the form (deltaTime noteValue base-velocity) where deltaTime is non-negative integer and noteValue is a note number, or a symbol or string which can be transformed to a note number by the function note-name-to-note-number. base-velocity is optional, and if present it overrides the base-velocity (the third parameter of the function).
See also Scheme source file beat
Examples Midi LAML examples

duration-to-next
Form (duration-to-next default-duration)
Description Return an duration attribute value pair (a list of two elements) of the deltaTime length from the hosting NoteOn to the next NoteOn with same channel and the same note value. Serves as a delayed procedural content item of a NoteOn midi event.
See also Scheme source file duration-to-next

generate-mega-voice-function
Form (generate-mega-voice-function mega-voice-map)
Description Generates a mega-voice-function from a given mega voice map. A mega voice function maps a note-name (with special conventions), a mega voice section name, and a normal velocity to the note value and the mega-voice-specific velocity.
See also Scheme source file generate-mega-voice-function

steel-guitar-megavoice-map
Form steel-guitar-megavoice-map
Description The mega voice map of a steel guitar (tyros 1).
See also Scheme source file steel-guitar-megavoice-map


12 Style Splitting.
The functions in this section split a style file in its midi path. In this context, a style file is a Yamaha Keyboard style file which control the automatic accompaniment. The first functions are older versions. The refined functions are more advanced. The refined functions are able to extract meta information about the midi contents of the pieces. Some levels of bulk processing is provided.

split-and-process-style
Form (split-and-process-style style-file-path output-dir-path mode channel-selection)
Description Split 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. Only output channels in channel-selection (a list of integers).
Parameters style-file-path The full file path to a style file.
output-dir-path The full file path to a an existiing output directory.
mode Midi processing mode. A symbol. Must be deltaTime.
channel-selection A list of channel numbers, in the interval 1..16. A list of integers.
See also Scheme source file split-and-process-style
Bulk version split-and-process-all-styles
Refined version split-and-process-style-one-channel-refined
Note Older version. Use the newer and refined variant. Does probably not work correctly any more.

split-and-process-all-styles
Form (split-and-process-all-styles input-dir-path output-dir-path mode channel-selection)
Description A bulk processing variant of split-and-process-style. Spilt each style file in input-dir-path in midi pieces, and generate (up to) 15 different in output-dir-path. Apply mode (deltaTime or absTime) and select channels in channel-selection (a list of integers).
Parameters input-dir-path The absolute and complete path to an existing directory that contains style files.
output-dir-path The full file path to a an existiing output directory.
mode Midi processing mode. A symbol. Must be deltaTime.
channel-selection A list of channel numbers, in the interval 1..16. A list of integers.
See also Scheme source file split-and-process-all-styles
Bulk version split-and-process-all-styles
Refined version split-and-process-all-styles-refined
Note Older version. Use the newer and refined variant

split-and-process-style-one-channel-refined
Form (split-and-process-style-one-channel-refined style-file-path output-dir-path mode channel)
Description A much refined version of split-and-process-style. Split a given style file in midi pieces, and generate (up to) 15 different midi files of the parts. Place the midi pieces in subdirectories of output-dir-path. Apply mode (deltaTime or absTime) - a symbol - when parsing the style file. Only output data in the given channel. Do not store meta information. (If you want meta information stored, use split-and-process-style-one-channel-given-ast-refined instead of this function).
Parameters style-file-path The absolute and complete path to a style file.
output-dir-path The absolute path to a directory. All but last directory path must be existing.
mode Either absTime or deltaTime (a symbol). MUST be deltaTime
channel A single channel - an integer number between 1 and 16.
See also Scheme source file split-and-process-style-one-channel-refined
Bulk version split-and-process-all-styles

split-and-process-style-refined
Form (split-and-process-style-refined meta-file-path style-file-path output-dir-path mode)
Description Split all channels in a style file into midi pieces. Save meta information about the midi pieces in meta-file-path. If meta-file-path is #f, do not store meta information. Mode must be deltaTime.
Parameters meta-file-path The absolute and complete path to a meta file, or #f. An empty meta file is created automatically if it does not exist.
style-file-path The absolute and complete path to a style file.
output-dir-path The absolute path to a directory. All but last directory path must be existing.
mode Either absTime or deltaTime (a symbol). MUST be deltaTime
See also Scheme source file split-and-process-style-refined
Directory bulk version split-and-process-all-styles-refined

split-and-process-all-styles-refined
Form (split-and-process-all-styles-refined meta-file-path input-dir-path output-dir-path mode)
Description Split each style file in input-dir-path in midi pieces, and organize the midi pieces in output-dir-path. Only the styles in input-dir-path - and not subdirectories - are processed. Create the meta information in the file addressed by meta-file-path. Create the last directory in output-dir-path if necessary. A bulk processing variant of split-and-process-style-refined. Apply mode (deltaTime or absTime) and select channels in channel-selection (a list of integers). Mode must be deltaTime.
Parameters meta-file-path The absolute and complete path to a meta file, or #f. An empty meta file is created automatically if it does not exist.
input-dir-path The absolute and complete path to an existing directory that contains style files.
output-dir-path The absolute path to a directory. All but the last directory path must be existing.
mode Either absTime or deltaTime (a symbol). MUST be deltaTime
See also Scheme source file split-and-process-all-styles-refined
Directory bulk version split-and-process-all-style-directory-refined

split-and-process-all-style-directory-refined
Form (split-and-process-all-style-directory-refined meta-file-path input-dir-path output-dir-path mode)
Description Split each style file in each directory of input-dir-path in midi pieces, and organize the midi pieces in output-dir-path. At the top level, the directory structure is replicated. This is just another bluk version on top of split-and-process-all-styles-refined. No recusive processing is involved. Only a directory of directories of style files. Create the meta information in the file addressed by meta-file-path. Create the last directory in output-dir-path if necessary. Apply mode (deltaTime or absTime) and select channels in channel-selection (a list of integers). Mode must be deltaTime.
Parameters meta-file-path The absolute and complete path to a meta file, or #f. An empty meta file is created automatically if it does not exist.
input-dir-path The absolute and complete path to an existing directory that contains directories with style files.
output-dir-path The absolute path to a directory. The leave directory of output-dir-path is created if necessary. The parent part must exists.
mode Either absTime or deltaTime (a symbol). MUST be deltaTime
See also Scheme source file split-and-process-all-style-directory-refined


13 Auxiliary functions.
Miscellaneous function that are not naturally contained in the categories from above.

pitch-bend-scale
Form (pitch-bend-scale factor)
Description A higher-order function that returns a numeric pitch-bend scaling function that takes into consideration that the mid-point pitch-bend value is 8192 (and not 0 as in the simple case of scaling).
Returns A function suitable as transformation function in transform-attribute on the value attribute in PitchBendChange messages.
See also Scheme source file pitch-bend-scale
Possible use context transform-attribute

total-length-of-message-list
Form (total-length-of-message-list message-list)
Description Calculate the total length of message-list. Works in both absTime and deltaTime mode.
See also Scheme source file total-length-of-message-list

enforce-minimum-message-length
Form (enforce-minimum-message-length min-length message-list)
Mode deltaTime
Description Enforce that message-list will have a mini length of min-length. Works only in deltaTime mode.
See also Scheme source file enforce-minimum-message-length

icon
Form (icon name)
Description Return an icon name, which serve as the 'middle name' of a style file.
Parameters name A symbolic name of an icon. The currently supported names are: "penguin", "butterfly", "candle", "banana", "orange", "lighting".
See also Scheme source file icon

note-complement
Form (note-complement note-str-list)
Description Returns the complement of note-str-list, relative to the possible note names.
Parameters note-str-list A comma-separated list of notes names belonging to C CS D Eb E F FS G GS A Bb and B.
Returns The comma-separated list of notes not in note-str-list.
See also Scheme source file note-complement

chord-complement
Form (chord-complement chord-str-list)
Description Returns the complement of chord-str-list, relative to the possible note names.
Parameters chord-str-list A comma-separated list of chord names belonging to maj maj6 maj7 maj7s11 maj9 maj7-9 maj6-9 aug min min6 min7 min7b5 min-9 min7-9 min7-11 min-maj7 min-maj7-9 dim dim7 7th 7sus4 7b5 7-9 7s11 7-13 7-b9 7-b13 7-s9 maj7aug 7aug 1-plus-8 1-plus-5 sus4 1-plus-2-plus-5 and cancel.
Returns The comma-separated list of chords not in chord-str-list.
See also Scheme source file chord-complement

Generated: Tuesday, August 19, 2008, 09:16:12
Generated by LAML SchemeDoc using LAML Version 33.0 (August 19, 2008, full)