Previous Section | Next Section | Table of Contents | Index | Title Page

## MIDI, Adagio, and Sequences

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 `demos/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 `demos/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.

### The SEQ Type

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 `demos/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. It must be closed after `seq-write-smf` returns.
`seq-insert-note(seq, time, line, voice, pitch, dur, loud` [SAL]
`(seq-insert_note seq time line voice pitch dur loud)` [LISP]
  Inserts a new note into the SEQ object seq. The note will be at time (a FIXNUM in milliseconds), with voice (channel) given by a FIXNUM starting at 1, 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.
`seq-midi-sal(seq, note-fn, ctrl: ctrl-fn, bend: bend-fn, touch: touch-fn, prgm: prgm-fn)` [SAL]
  Converts a SEQ data object seq into a sound. All -fn parameters are function names, typically passed by writing something like `quote(my-note-fn`). The note-fn takes channel, pitch, and velocity as parameters. The ctrl-fn takes channel, control number, and control value as parameters. All other functions take two parameters: channel and value. The note-fn must return a sound. It will be called for each MIDI note in an environment that conveys the starting time and duration.
`(seq-midi seq (note (chan pitch vel) filter-expr behavior-expression) (ctrl (chan control value) (...)) (bend (chan value) (...)) (touch (chan value) (...)) (prgm (chan value) (...)))` [LISP]
  Converts a SEQ data object seq into a sound. The filter-expr is an expression that must evaluate to true for the note to be synthesized, and behavior-expression returns a sound. Both filter-expr and behavior-expression can be written in terms of chan, pitch, and vel, which are the channel, pitch, and velocity of the note in the MIDI file.

### Adagio Score Language

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.

### Specifying Attributes

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 (100th's), but this can be changed to a millisecond (1000th'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.

#### Time

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

#### Pitch

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 `P`n, 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

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

Note that `E` is a pitch, so eighth-notes use the duration code `I`. The default tempo is 100 beats per minute (see Section "Tempo"). These codes may be followed by a `T` (triplet), indicating a duration of 2/3 the normal. A dot (`.`) after a duration code extends it by half to 3/2 the normal. An integer after a note multiplies its duration by the indicated value (the result is still just one note). Finally, a slash followed by an integer divides the duration by the integer. Like all attributes, duration attributes may not have embedded spaces. Examples:

> `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

A duration may be noted by `U`n, where n is an integer indicating 100th's of a second (or 1000th's), see Section "Time Units and Resolution". For example, `U25` is twenty-five time units.

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

#### Next Time

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".

#### Rest

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

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.

Be aware that overlapping notes on the same pitch can be a problem for some synthesizers. The following example illustrates this potential problem:

    !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?

At one beat per second (tempo 60), these three notes will start at times 0, 1, and 1.5 seconds, respectively. Since these notes have an articulation of 160, each will be on 160% of its nominal duration, so the first note (C) will remain on until 1.6 seconds. But the third note (another C) will start at time 1.5 seconds. Thus, the second C will be started before the first one ends. Depending on the synthesizer, this may cancel the first C or play a second C in unison. In either case, a note-off message will be sent at time 1.6 seconds. If this cancels the second C, its actual duration will be 0.1 rather than 1.6 seconds as intended. A final note-off will be sent at time 3.1 seconds.

#### Loudness

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

#### Voice

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.

There is a limit to how many notes can be played at the same time on a given voice (MIDI channel). Since the limit depends upon the synthesizer, Adagio cannot tell you when you exceed the limit. Similarly, Adagio cannot tell whether your synthesizer is set up to respond to a given channel, so there is no guarantee that what you write will actually be heard.

#### Timbre (MIDI Program)

A MIDI program (synthesizer preset) can be selected using the attribute `Z`n, 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.

For many synthesizers, you will not be able to change programs at the start of a note or during a note. Change the program during a rest instead. For example:

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

Check how your synthesizer interprets program numbers. For example, the cartridge programs on a DX7 can be accessed by adding 32 to the cartridge program number. Cartridge program number 10 is specified by `Z42`.

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.

#### Tempo

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.

#### Rate

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").

### Default Attributes

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`

Control changes (including timbre or MIDI program, specified by `Z`) have no default value and are only sent as specified in the score.

Important: the rules for determining when a command will play a note are as follows (and this has changed slightly from previous versions):

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.

Another way to say this is "Special commands and commands with rests (`R`) do not play notes. Otherwise, play a note if a pitch is specified or if no control is specified."

### Examples

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

The next example is the same piece expressed in a different manner, illustrating the interaction between the `!TEMPO` command and the time attribute. Recall that the time attribute is measured relative to the time of the last `!TEMPO` command:

    *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.

### Advanced Features

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

#### Time Units and Resolution

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

> `!CSEC` |  | centisecond time units = 100th
> `!MSEC` |  | millisecond time units = 1000th

The time unit remains in effect until the next `!CSEC` or `!MSEC` command.

#### Multiple Notes Per Line

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

#### Control Change Commands

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

The letter listed beside each control function is the Adagio command letter. For example, `M23` is the command for setting the modulation wheel to 23. Except for pitch bend, the portamento switch, and MIDI Program Change, all values range from 0 to 127. Pitch bend is "off" or centered at 128, and has a range from 0 to 255 (MIDI allows for more precision, but Adagio does not). Turn on portamento with `K127` and off with `K0`. Programs are numbered 1 to 128 to correspond to synthesizer displays.

About volume: Midi volume is just a control, and the Midi standard does not say what it means. Typically it does what the volume pedal does; that is, it scales the amplitude in a continuously changeable fashion. In contrast, Midi velocity, which is controlled by the `L` (loudness) attribute, is part of a Midi note-on command and is fixed for the duration of the note. Typically, these two ways of controlling loudness and amplitude operate independently. In some low-cost synthesizers the numbers seem to be added together internally and volume changes are ignored after the note starts.

About pitch bend: Midi pitch bend is a number from 0 to 16383, where 8192 is the center position. To convert to Midi, Adagio simply multiplies your number by 64, giving values from 0 to 16320. Note that `Y128` translates exactly to 8192. The meaning of pitch bend depends upon your synthesizer and its setting. Most synthesizers let you specify a "pitch bend range." A range of one semitone means that `Y255` will produce a bend of approximately one semitone up, and `Y0` will bend one semitone down. If the range is 12 semitones, then the same `Y255` will bend an octave. Typically, pitch bend is exponential, so each increment in the pitch bend value will bend an equal number of cents in pitch.

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.

#### Multiple Tempi

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.

Clock commands and thus tempo changes can take place at arbitrary times. It is assumed that tempo changes on an exact 24th of a beat subdivision (for example, exactly on a beat). If not, the tempo change will take place on the nearest exact 24th of a beat subdivision. This may be earlier or later than the requested time.

#### System Exclusive Messages

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

#### Control Ramps

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

A rather curious and extreme use of macros and ramps is illustrated in the following example. The `noteon` macro starts a note, and `noteoff` ends it. Ramps can now be used to emit a series of notes with changing pitches or velocities. Since Adagio has no idea that these macros are turning on notes, it is up to the programmer to turn them off!

    !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 !End Command

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

#### Calling C Routines

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`.

#### Setting C Variables

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.

Previous Section | Next Section | Table of Contents | Index | Title Page