Nyquist includes facilities to read and write MIDI files as well as an ASCII text-based score representation language, Adagio. XLISP and Nyquist can be used to generate MIDI files using compositional algorithms. (See also Section Xmusic and Algorithmic Composition.) A tutorial on using the Adadio representation and MIDI can be found in nyquist/lib/midi/midi_tutorial.htm. The Adagio language is described below. Adagio was originally developed as part of the CMU MIDI Toolkit, which included a program to record and play MIDI using the Adagio representation. Some of the MIDI features of Adagio may not be useful within Nyquist.

Nyquist offers a number of different score representations, and you may find this confusing. In general, MIDI files are a common way to exchange music performance data, especially with sequencers and score notation systems. The nyquist/lib/midi/midi_tutorial.htm examples show how to get the most precise control when generating MIDI data. Adagio is most useful as a text-based score entry language, and it is certainly more compact than Lisp expressions for MIDI-like data. The Xmusic library (Chapter Xmusic and Algorithmic Composition) is best for algorithmic generation of music and score manipulation. There are functions to convert between the Adagio, MIDI sequence data, and Xmusic score representations.

Nyquist has a special data type to store MIDI data called a SEQ (short for "sequence"). You can create an empty SEQ object, read data into it from a MIDI or Adagio file, write a SEQ as MIDI or Adagio, and insert notes into a SEQ object. You can also convert SEQ objects into sound by providing functions to handle different MIDI messages. Further discussion and examples can be found in lib/midi/midi_tutorial.htm.

seq-create() [SAL]
(seq-create) [LISP]

Creates a SEQ data object.

seq-read(seq, file) [SAL]
(seq-read seq file) [LISP]

Reads into a SEQ data object from an ASCII text file in Adagio format. The first parameter is the SEQ object to read. The file is a file opened for reading. It must be closed after seq-read returns.

seq-read-smf(seq, midi-file) [SAL]
(seq-read seq midi-file) [LISP]

Reads into a SEQ data object from a Standard MIDI File. The first parameter is the SEQ object to read. The midi-file is a binary file opened in binary mode for reading. It must be closed after seq-read-smf returns.

seq-write(seq, file, absolute) [SAL]
(seq-write seq file absolute) [LISP]

Writes a SEQ data object to an ASCII text file in Adagio format. The first parameter is the SEQ object to write. The file is a file opened for writing. It must be closed after seq-read returns. The absolute parameter should be true to write absolute times of events and false (NIL) to write relative times.

seq-write-smf(seq, midi-file) [SAL]
(seq-write-smf seq midi-file) [LISP]

Writes a SEQ data object to a binary file in Standard MIDI File format. The first parameter is the SEQ object to write. The midi-file is a binary file opened for writing. The file is closed by seq-write-smf.

seq-insert-note(seq, time, line, chan, pitch, dur, loud [SAL]
(seq-insert_note seq time line chan pitch dur loud) [LISP]

Inserts a new note into the SEQ object seq. The note will be at time (a FIXNUM in milliseconds), with chan (MIDI channel) given by a FIXNUM starting at 0, duration given by dur (a FIXNUM in milliseconds), pitch (a FIXNUM with MIDI key number), and MIDI velocity given by loud, a FIXNUM from 1 to 127. The line field is intended as a source code line number for Adagio files and can be any FIXNUM.

seq-insert-ctrl(seq, time, line, ctrltype, chan, ctrlnum, value [SAL]
(seq-insert-ctrl seq time line ctrltype chan ctrlnum value) [LISP]

Inserts a new control into the SEQ object seq. Here, “control” refers to a variety of MIDI messages, including program change, pitch bend, and aftertouch in addition to control changes. The control will be at time (a FIXNUM in milliseconds). The ctrltype (FIXNUM) uses MIDI status bytes for convenience: seq-ctrl-tag (11) for a MIDI control change, seq-prgm-tag (12) for a MIDI program change, seq-cpress-tag (13) for a MIDI channel pressure change, or seq-bend-tag (14) for a MIDI pitch bend change. The chan (MIDI channel) is given by a FIXNUM starting at 0. If ctrltype is 11 (control change), then ctrlnum is the MIDI controller number, otherwise this parameter is ignored. The value is the MIDI data value (FIXNUM from 0 to 127). In the case of pitch bend, this value is a FIXNUM from 0 to 255 representing the upper 8 bits of the unsigned 14-bit MIDI pitch bend value. (To convert from a scale of -1 to 1, use round(x * 127 + 128).) This gives about 10-cent resolution on pitch bends of plus or minus one octave, which is normally good enough, but should be better. The line field is intended as a source code line number for Adagio files and can be any FIXNUM.

To read data from a sequence, you normally begin by making a shallow copy, but you can probably just call seq-reset to initialize the iterator. Then call seq-get to get the current event, and seq-next to advance to the next event:

seq-copy(seq) [SAL]
(seq-copy seq) [LISP]

Returns a shallow copy of seq. Each copy of a sequence contains an independent iterator providing sequential access to the events in the sequence.

seq-reset(seq) [SAL]
(seq-reset seq) [LISP]

Reset the sequence iterator to the beginning of the sequence.

seq-get(seq) [SAL]
(seq-get seq) [LISP]

Get the current event in the sequence. The returned value is a list of FIXNUMs in the form (eventtype time line chan value1 value2 dur) as follows:

• eventtype - The type of event: seq-done-tag (0) indicates end of sequence, seq-other-tag (1) indicates the event is not supported in Nyquist, seq-note-tag (2) indicates the event is a note, seq-ctrl-tag (11) indicates a MIDI control change, seq-prgm-tag (12) indicates a MIDI program change, seq-cpress-tag (13) indicates a MIDI channel pressure change, and seq-bend-tag (14) indicates a MIDI pitch bend change.
• seq-ctrl-tag (3) indicates the event is a MIDI control change
• time - Time of the event in milliseconds.
• line - The Adagio file line number for the event (may not be defined when data is imported from a MIDI file or elsewhere.
• chan - The MIDI channel (zero-based).
• value1 - The note pitch or controller number, depending upon the event type, or zero for program change, channel pressure or pitch bend. This value is zero-based, e.g. the first controller number is 0.
• value2 - The note velocity, program number, controller value, channel pressure, or pitch bend (see seq-insert-ctrl above for details on pitch bend values.) Program numbers are zero based.
• dur - The duration in milliseconds for notes.

Functions to access events returned by seq-get are defined in runtime/seqfnint.lsp.

seq-next(seq) [SAL]
(seq-next seq) [LISP]

Advance the sequence iterator to the next event in the sequence unless the iterator is at the last (seq-done-tag) event.

Adagio is an easy-to-use, non-procedural notation for scores. In Adagio, text commands are used to specify each note. If you are new to Adagio, you may want to glance at the examples in Section Examples starting on page Examples before reading any further.

A note is described in Adagio by a set of attributes, and any attribute not specified is “inherited” from the previous line. Attributes may appear in any order and must be separated by one or more blanks. An attribute may not contain any blanks. The attributes are: time, pitch, loudness, voice number, duration, and articulation.

Adagio has been used to program a variety of hardware and software synthesizers, and the Adagio compiler can be easily adapted to new environments. Although not originally intended for MIDI, Adagio works quite well as a representation for MIDI scores. Adagio has been extended to allow MIDI controller data such as modulation wheels, pitch bend, and volume, MIDI program commands to change timbre, and System Exclusive messages.

A note command in Adagio must be separated from other notes. Usually, notes are distinguished by writing each one on a separate line. Notes can also be separated by using a comma or semicolon as will be described below.

Besides notes, there are several other types of commands:

1. An asterisk (*) in column one (or immediately after a comma, semicolon, or space) indicates that the rest of the line is a comment. The line is ignored by Adagio, and is therefore a good way to insert text to be read by people. Here are some examples:

   * This is a comment.
   T150 G4  * This is a comment too!
   T150 G4  ;* So is this.
   

2. An empty command (a blank line, for example) is ignored as if it were a comment (Footnote 5) .
3. An exclamation point (!) in column one (or immediately after a comma or semicolon) indicates a special command. A special command does not generate a note. Special commands follow the “!” with no intervening spaces and extend to the end of the line, for example:

   !TEMPO 100
   

4. Control change commands are used to control parameters like pitch bend, modulation, and program (timbre). Control change commands can be specified along with notes or by themselves. A command that specifies control changes without specifying a pitch will not produce a note.

Adagio is insensitive to case, thus “A” is equivalent to “a”, and you can mix upper and lower case letters freely.

A note is indicated by a set of attributes. Attributes are indicated by a string of characters with no intervening spaces because spaces separate attributes. The attributes are described below.

The default unit of time is a centisecond (100^th's), but this can be changed to a millisecond (1000^th's) using the !MSEC command and reset to centiseconds with !CSEC (see Section Time Units and Resolution). In the descriptions below, the term “time unit” will be used to mean whichever convention is currently in effect.

The time attribute specifies when to start the note. A time is specified by a “T” followed by a number representing time units or by a duration (durations are described below). Examples:

T150	** 1.5 sec (or .15 sec)
TQ3	** 3 quarter note's duration

If no time is specified, the default time is the sum of the time and duration attributes of the previous note. (But see Section Next Time.) Time is measured relative to the time of the most recent Tempo or Rate command. (See the examples in Section Examples for some clarification of this point.)

The pitch attribute specifies what frequency to produce. Standard scale pitches are named by name, using S for sharp, F for flat, and (optionally) N for natural. For example, C and CN represent the same pitch, as do FS and GF (F sharp and G flat). Note that there are no bar lines, and accidentals to not carry forward to any other notes as in common practice notation.

Octaves are specified by number. C4 is middle C, and B3 is a half step lower. F5 is the top line of the treble clef, etc. (Adagio octave numbering follows the ISO standard, but note that this is not universal. In particular, Yamaha refers to middle C as C3.) Accidentals can go before or after the octave number, so FS3 and F3S have the same meaning.

An alternate notation for pitch is Pn, where n is an integer representing the pitch. Middle C (C4) is equivalent to P60, CS4 is P61, etc.

If you do not specify an octave, Adagio will choose one for you. This is done by picking the octave that will make the current pitch as close to the previous pitch as possible. In the case of augmented fourths or diminished fifths, there are two equally good choices. Adagio chooses the lower octave.

Duration is specified by a letter indicating a number of beats, followed by one or several modifiers. The basic duration codes are:

W   (whole, 4 beats),
H   (half, 2 beats),
Q   (quarter, 1 beat),
I   (eighth, 1/2 beat),
S   (sixteenth, 1/4 beat),
%   (thirtysecond, 1/8 beat), and
^   (sixtyfourth, 1/16 beat).

Q		1 beat (quarter note)
QT		2/3 beat (quarter triplet)
W.		6 beats(dotted whole note)
ST6		1 beat (6 sixteenth triplets)
H5		10 beats(5 half notes)
Q3/7		3/7 beats

Durations may be combined using a plus sign:

Q+IT        ** a quarter tied to an eighth triplet
Q/7+W+Q2/7  ** a 7th beat tied to a whole tied to 2/7th beat
Q+U10       ** a quarter plus 10 time units

The time of the next command (the next command in the Adagio program text) is normally the time of the current note command plus the duration of the current note. This can be overridden by a field consisting of the letter N followed by a number indicating time units, or followed by a duration as described above. The next note will then start at the time of the current note plus the duration specified after N. If the next note has an explicit time attribute (T), then the specified time will override the one based on the previous note. Examples:

N0	** start the next note at the same time as this one
N50	** start the next note 0.5 seconds after this one
NQT	** start the next note 2/3 beat after the current one
NU10+Q  ** start after 0.1 seconds plus a quarter

A comma has an effect similar to N0 and is explained in Section Multiple Notes Per Line. Articulation effects such as staccato can be produced using N, but it is more convenient to use the articulation attribute described in Section Articulation.

Rests are obtained by including the field R in a note command. The effect of an R field is to omit the note that would otherwise occur as the result of the current note command. In all other respects, the command is processed just like any other line. This means that attributes such as duration, loudness, and pitch can be specified, and anything specified will be inherited by the note in the next command. Normally, a rest will include just R and a duration. The fact that a note command specifies a rest is not inherited. For example:

R H	** a half (two beat) rest
RH	** illegal, R must be separated from H by space(s)

Because some synthesizers (e.g. a DX7) cannot change programs (presets) rapidly, it may be desirable to change programs in a rest so that the synthesizer will be ready to play by the end of the rest. See Section Timbre (MIDI Program) for an example.

Articulation in Adagio refers to the percentage of time a note is on relative to the indicated duration. For example, to play a note staccato, you would normally play the note about half of its indicated duration. In Adagio, articulation is indicated by # followed by an integer number indicating a percentage. The articulation attribute does not affect the time of the next command. This example plays two staccato quarter notes:

C Q #50
D

To produce overlapping notes, the articulation may be greater than 100.

!TEMPO 60
C Q #160   * starts at time 0,   ends at 1.6 sec
D I        * starts at time 1,   ends at 1.8 sec
C Q        * starts at time 1.5, ends at 3.1 sec?

Loudness is indicated by an L followed by a dynamic marking from the following: PPP, PP, P, MP, MF, F, FF, FFF. Alternatively, a number from 1 to 127 may be used. The loudness attribute is the MIDI note velocity. (Note that a MIDI velocity of 0 means “note-off,” so the minimum loudness is 1.) The dynamic markings are translated into numbers as follows:

Lppp		20		Lmf		58
Lpp		26		Lf		75
Lp		34		Lff		98
Lmp		44		Lfff		127

The voice attribute tells which of the 16 MIDI channels to use for the note. The voice attribute consists of a V followed by an integer from 1 (the default) to 16.

A MIDI program (synthesizer preset) can be selected using the attribute Zn, where n is the program number (from 1 to 128). Notice that in MIDI, changing the program on a given channel will affect all notes on that channel and possibly others. Adagio treats MIDI program changes as a form of control change.

R I Z23 V4	** change MIDI channel 4 to program 23 during rest
A4		** play a note on channel 4

As in MIDI, the Adagio timbre is a property of the voice (MIDI channel), so the timbre will not be inherited by notes on a different channel; to change the timbre on multiple voices (channels), you must explicitly notate each change.

The length of a beat may be changed using a Tempo command:

!TEMPO n

where n indicates beats per minute. The exclamation mark tells Adagio that this is a special command line rather than a note definition. A special command takes the place of a note specification. No other attributes should be written on a line with a special command. The !TEMPO command is associated with a time, computed as if the !TEMPO command were a note. The time attribute (T) of all succeeding notes is now measured relative to the time of the !TEMPO command. The new tempo starts at the !TEMPO command time and affects all succeeding notes. Durations specified in time units (for example U58, N15) are not affected by the !TEMPO command, and numerical times (for example T851) are computed relative to the time of the last !TEMPO command.

The !TEMPO command is fairly clever about default durations. If the last duration specified before the !TEMPO command is symbolic (using one of ^, %, S, I, Q, H, or W ), then the default duration for the node after the !TEMPO command will be modified according to the tempo change. Consider the following tempo change:

!TEMPO 60
A4 H
!TEMPO 120
G

In this example, the first note will last 2 seconds (2 beats at 60 beats per minute). The second note inherits the duration (H) from the first note, but at 120 beats per minute, the second note will last only 1 second. If the duration had been specified U200 (also a duration of 2 seconds), the second note would also last 2 seconds because the !TEMPO command does not affect times or durations specified numerically in time units. If the duration is the sum of a symbolic and a numeric specification, the inherited duration after a !TEMPO command is undefined.

The !RATE command scales all times including those specified in hundredths of seconds. A rate of 100 means no change, 200 means twice as fast, and 50 means half as fast. For example, to make a piece play 10% faster, you can add the following command at the beginning of the score:

!RATE 110

!RATE and !TEMPO commands combine, so

!RATE 200
!TEMPO 70

will play 70 beats per minute at double the normal speed, or 140 beats per minute. Like !TEMPO, the time of the !RATE command is added to the time attribute of all following notes up to the next !TEMPO or !RATE command.

Two !RATE commands do not combine, so a !RATE command only affects the rate until the next !RATE command.

Although !TEMPO and !RATE can occur in the middle of a note (using N, T, etc.) they do not affect a note already specified. This property allows multiple tempi to exist simultaneously (see Section Multiple Tempi).

If an attribute is omitted, the previous one is used by default (with the exception of the time attribute). The default values for the first note, which are inherited by succeeding notes until something else is specified, are given below in Adagio notation:

Time		T0
Pitch		C4
Duration		Q
Articulation		#100
Loudness		LFFF
Voice		V1
Tempo		!TEMPO 100
Rate		!RATE 100

1. If a special (!) command or nothing is specified, e.g. a blank line, do not play a note.
2. If R (for “rest”) is specified, do not play a note.
3. Otherwise, if a pitch is specified, do play a note.
4. Otherwise, if no control changes (or program changes) are specified (so this is a command with non-pitch attributes and no control changes), do play a note.

The following plays the first two bars of “Happy Birthday”. Note that Adagio knows nothing of bar lines, so the fact that the first note occurs on beat 3 or that the meter is three-four is of no consequence:

*Example 1 ** Happy Birthday tune (C major)
!TEMPO 120
G4 I. LF
G4 S
A4 Q
G4
C5
B4 H

The time attribute for the first note is zero (0). The second note will occur a dotted eighth later, etc. Notice that no timbre or rate was specified. Adagio will provide reasonable default values of 1 and 100, respectively.

The following example plays the first four bars of an exercise from Bartok's Mikrokosmos (Vol. 1, No. 12). An extra quarter note is inserted at the beginning of each voice in order to allow time to change MIDI programs. The right hand part is played on voice (MIDI channel) 1 and the left hand part on voice 2. Notice the specification of the time attribute to indicate that voice 2 starts at time 0. Also, default octaves are used to reduce typing.

*Example 2 ** Bartok
*voice 1, right hand
R Q Z10 V1   ** extra rest for program change
A4 H
B Q
C
D H
C
D Q
C
B
A
B
C
D
R

*voice 2, left hand
T0 R Q Z15 V2   ** extra rest for program change
G3 H
F Q
E
D H
E
D Q
E
F
G
F
E
D
R

*Example 3 ** 4 measures in 2 sections
!Tempo 100
*Voice 1, Measures 1 & 2
R Q Z10 V1
A4 H
B Q
C
D H
C

*Voice 2, Measures 1 & 2
T0 R Q Z15 V2
G3 H
F Q
E
D H
E H

!TEMPO 100
*Voice 1, Measures 3 & 4
* note that Z10 is still in effect for V1
V1 D4 Q
C
B
A
B
C
D
R

*Voice 2, Measures 3 & 4
T0 V2 D3 Q
E
F
G
F
E
D
R

The piece is written in 4 sections. The first plays a rest followed by two measures, starting at time 0. The next section changes the time back to zero and plays two measures of the left hand part (voice 2). The next command (!TEMPO 100) sets the tempo to 100 (it already is) and sets the reference time to be two measures into the piece. Therefore, the next note (D4) will begin measure 3. The D3 that begins the last group of notes has a T0 attribute, so it will also start at measure 3. Notice how the !TEMPO command can serve to divide a piece into sections.

The last example will show yet another way to express the same piece of music using the “Next” attribute. Only the first bar of music is given.

*Example 4 ** use of the Next attribute
!Tempo 100
R Q Z10 V1 N0
R Q Z15 V2

A4 H V1 N0
G3   V2

B4 Q V1 N0
F3   V2

C4 Q V1 N0
E3   V2

Here, each pair of lines represents two simultaneous notes. The N0 attribute forces the second line to start at the same time as the first line of each pair. Because of the large intervals, octave numbers (3 and 4) are necessary to override the default octave for these pitches.

Beyond the simple notation described above, Adagio supports a number of features. (See also the next chapter.)

The default time unit is 10ms (ten milliseconds or one centisecond or 100^th of a second), but it is possible to change the basic unit to 1ms, or 1000^th of a second. The time unit can be specified by:

!CSEC		centisecond time units = 100th
!MSEC		millisecond time units = 1000th

Notes can be separated by commas or semicolons as well as by starting a new line. A comma is equivalent to typing N0 and starting a new line. In other words, the next note after a comma will start at the same time as the note before the comma. In general, use commas to separate the notes of a chord.

A semicolon is equivalent to starting a new line. In general, use semicolons to group notes in a melody. Here is yet another rendition of the Bartok:

*Example 5 ** use of semicolons
!Tempo 100
R Q Z10 V1
A4 H; B Q; C; D H; C; D Q; C; B; A; B; C; D; R

T0 R Q Z15 V2
G3 H; F Q; E; D H; E; D Q; E; F; G; F; E; D; R

This example is similar to Example 2, except semicolons are used. Note how semicolons make the two lines of music stand out. The next example is similar to Example 4, except commas are used and four bars are notated. The music below is treated as a sequence of 2-note chords, with each chord on a separate line:

*Example 6 ** use of commas
!Tempo 100
R Q Z10 V1, R Q Z15 V2
A4 H V1, G3 V2
B4 Q V1, F3 V2
C4   V1, E3 V2
D4 H V1, D3 V2
C4   V1, E3 V2
D4 Q V1, D3 V2
C4   V1, E3 V2
B4   V1, F3 V2
A4   V1, G3 V2
B4   V1, F3 V2
C4   V1, E3 V2
D4   V1, D3 V2
R

Any control change can be specified using the syntax “~n(v)”, where n is the controller number (0 - 127), and v is the value. In addition, Adagio has some special syntax for some of the commonly used control changes (note that Pitch bend, Aftertouch, and MIDI Program Change are technically not MIDI control changes but have their own special message format and status bytes):

K		Portamento switch
M		Modulation wheel
O		Aftertouch
X		Volume
Y		Pitch bend
Z		Program Change

Control changes can be part of a note specification or independent. In the following example, a middle C is played with a modulation wheel setting of 50 and a pitch bend of 120. Then, at 10 unit intervals, the pitch bend is decreased by 10. The last line sets the portamento time (controller 5) to 80:

*Example 7
C4 LMF M50 Y120 U100 N10
Y110 N10; Y100 N10; Y90 N10; Y80 N10
Y70 N10; Y60 N10; Y50 N10
~5(80)

See Section Default Attributes on page Default Attributes for rules on whether or not a command will play a note.

Writing a piece with multiple tempi requires no new commands; you just have to be clever in the use of Tempo and Time. The following plays a 7 note diatonic scale on voice 1, and a 12 note chromatic scale on voice 2:

*Example 8 ** multiple tempi
!TEMPO 70
V1 C4; D; E; F; G; A; B
T0 R N0

!TEMPO 120
V2 C4; CS; D; DS; E; F; FS; G; GS; A; AS; B

!TEMPO 100
V1 C5, V2 C5

The third line plays the 7-note diatonic scale on voice 1. The next line contains the tricky part: notice that the time is set back to zero, there is a rest, and a next (N) attribute is used to specify that the next default time will be at the same time as the current one. This is tricky because a !TEMPO command cannot have a time (T0) attribute, and a T0 by itself would create a note with a duration. T0 R N0 says: “go to time 0, do not play a note, and do not advance the time before the next command”. Thus, the time of the !TEMPO 120 command is zero. After the 12 note scale, the tempo is changed to 100 and a final note is played on each voice. A little arithmetic will show that 7 notes at tempo 70 and 12 notes at tempo 120 each take 6 seconds, so the final notes (C5) of each scale will happen at the same time.

MIDI Synchronization

The Adagio program (but not Nyquist) can synchronize with external devices using MIDI real time messages. Thus, Adagio has a !CLOCK command. This command is currently of no use to Nyquist users but is documented here for completeness (it's part of the language syntax even if it does not do anything).

Since Adagio supports multiple tempi, and Midi clock is based on beats, it is necessary to be explicit in the score about where the clock should start and what is the duration of a quarter note. The !CLOCK command in Adagio turns on a 24 pulse-per-quarter (PPQ) clock at the current tempo and time:

!TEMPO 100
!CLOCK

A !CLOCK command must also be inserted for each tempo change that is to be reflected in the Midi clock. Typically, each !TEMPO command will be followed by a !CLOCK command.

Adagio has a definition facility that makes it possible to send system exclusive parameters. Often, there are parameters on Midi synthesizers that can only be controlled by system exclusive messages. Examples include the FM ratio and LFO rate on a DX7 synthesizer. The following example defines a macro for the DX7 LFO rate and then shows how the macro is used to set the LFO rate for a B-flat whole note in the score. The macro definition is given in hexadecimal, except v is replaced by the channel (voice) and %1 is replaced by the first parameter. A macro is invoked by writing “~” followed by the macro name and a list of parameters:

!DEF LFO F0 43 0v 01 09 %1 F7
Bf5 W ~LFO(25)

In general, the !DEF command can define any single MIDI message including a system exclusive message. The message must be complete (including the status byte), and each !DEF must correspond to just one message. The symbol following !DEF can be any name consisting of alphanumeric characters. Following the name is a hexadecimal string (with optional spaces), all on one line. Embedded in the string may be the following special characters:

v

Insert the 4-bit voice (MIDI channel) number. If v occurs in the place of a high-order hexadecimal digit, replace v with 0v so that the channel number is always placed in the low-order 4 bits of a data byte. In other words, v is padded if necessary to fall into the low-order bits.

%n

Insert a data byte with the low-order 7 bits of parameter number n. Parameters are numbered 1 through 9. If the parameter value is greater than 127, the high-order bits are discarded.

^n

Insert a data byte with bits 7 through 13 of parameter number n. In other words, shift the value right 7 places then clear all but the first 7 bits. Note that 14-bit numbers can be encoded by referencing the same parameter twice; for example, %4^4 will insert the low-order followed by the high-order parts of parameter 4 into two successive data bytes.

Parameters are separated by commas, but there may be no spaces. The maximum number of parameters allowed is 9. Here is an example of definitions to send a full-resolution pitch bend command and to send a system exclusive command to change a DX7 parameter (Footnote 6) .

* Define macro for pitch bend commands:
!DEF bend Ev %1 ^1

A ~bend(8192)  ** 8192 is "pitch bend off"

* Change the LFO SPEED:
*  SYSEX = F0, Yamaha = 43, Substatus/Channel = 1v, 
*  Group# = 01, Parameter# = 9, Data = 0-99, EOX = F7
!DEF lfospeed F0 43 1v 01 09 %1 F7

* now use the definitions:
G4 ~bend(7567) N40
~lfospeed(30) N35

The !RAMP command can specify a smooth control change from one value to another. It consists of a specification of the starting and ending values of some control change, a duration specifying how often to send a new value, and a duration specifying the total length of the ramp.

!RAMP X10 X100 Q W2
!RAMP ~23(10) ~23(50) U20 W
!RAMP ~lfo(15) ~lfo(35) U10

The first line says to ramp the volume control (controller number 7) from 10 to 100, changing at each quarter note for the duration of two whole notes. The second line says to ramp controller number 23 from value 10 to value 50, sending a new control change message every 20 time units. The overall duration of the ramp should be equivalent to a whole note (W). As shown in the third line, even system exclusive messages controlled by parameters can be specified. If the system exclusive message has more than one parameter, only one parameter may be “ramped”; the others must remain the same. For example, the following would ramp the second parameter:

!RAMP ~mysysex(4,23,75) ~mysysex(4,100,75) U10 W

!DEF noteon 9v %1 %2
!DEF noteoff 8v %1 %2
~noteon(48,125)
~noteoff(48,126)
* turn on some notes
!RAMP ~noteon(36,125) ~noteon(60,125) Q W NW
* turn them off
!RAMP ~noteoff(60,50) ~noteoff(36,50) Q W NW

The special command !END marks the end of a score. Everything beyond that is ignored, for example:

* this is a score
C; D; E; F; G W
!END
since the score has ended, this text will be ignored

It is possible to call C routines from within Adagio scores when using specially linked versions, but this feature is disabled in Nyquist. The syntax is described here for completeness.

The !CALL command calls a C routine that can in turn invoke a complex sequence of operations. Below is a call to a trill routine, which is a standard routine in Adagio. The parameters are the base pitch of the trill, the total duration of the trill, the interval in semitones, the duration of each note of the trill, and the loudness. Notice that both numbers and Adagio notation can be used as parameters:

!CALL trill(A5,W,2,S,Lmf)  T278 V1

The parameter list should have no spaces, and parameters are separated by commas. Following the close parenthesis, you may specify other attributes such as the starting time and voice as shown in the example above.

A parameter may be an Adagio pitch specification, an Adagio duration, an Adagio loudness, a number, or an ASCII character within single quotes, e.g. 'a' is equivalent to 97 because 97 is the decimal encoding of “a” in ASCII.

The !CALL may be followed by a limited set of attributes. These are time (T), voice (V), and next time (N). The !CALL is made at the current time if no time is specified, and the time of the next adagio command is the time of the !CALL unless a next time is specified. In other words, the default is N0.

In addition to calling C routines, there is another way in which scores can communicate with C. As with !CALL, specific C code must be linked before these commands can be used, and this is not supported in Nyquist. The !SETI command sets an integer variable to a value, and the !SETV command sets an element of an integer array. For example, the next line sets the variable delay to 200 and sets transposition[5] to -4 at time 200:

!SETI delay 200
!SETV transposition 5 -4  T200

As with the !CALL command, these commands perform their operations at particular times according to their place in the Adagio score. This makes it very easy to implement time-varying parameters that control various aspects of an interactive music system.