File: part12.html

package info (click to toggle)
nyquist 3.24%2Bds-2
links: PTS, VCS
area: main
in suites: forky, sid
size: 58,156 kB
sloc: ansic: 74,757; lisp: 18,169; java: 10,942; cpp: 6,688; sh: 175; xml: 58; makefile: 40; python: 15
file content (1061 lines) | stat: -rw-r--r-- 52,439 bytes
parent folder | download | duplicates (2)
<!DOCTYPE html>
<html><head><title>MIDI, Adagio, and Sequences</title>
<link rel="stylesheet" type="text/css" href="nyquiststyle.css">
<link rel="icon" href="nyquist-icon.png" />
<link rel="shortcut icon" href="nyquist-icon.png" />
</head>
<body bgcolor="ffffff">
<a href = "part11.html">Previous Section</a> | <a href = "part13.html">Next Section</a> | <a href = "title.html#toc">Table of Contents</a> | <a href = "indx.html">Index</a> | <a href = "title.html">Title Page</a>
<hr>
<a name = "123"><h2>MIDI, Adagio, and Sequences</h2></a><a name="index953"></a><a name="index954"></a>
<p>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 <a href = "part15.html#157">Xmusic and Algorithmic Composition</a>.)  A tutorial on using
the Adadio representation and MIDI can be found in
<code>nyquist/lib/midi/midi_tutorial.htm</code><a name="index955"></a>. 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.</p>

<p>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 <code>nyquist/lib/midi/midi_tutorial.htm</code>
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 <a href = "part15.html#157">Xmusic and Algorithmic Composition</a>) 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.</p>
<a name = "124"><h3>The SEQ Type</h3></a>
<p>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
<code>lib/midi/midi_tutorial.htm</code><a name="index956"></a><a name="index957"></a>.</p>
<dl>
<dt>
<code>seq-create(<a name="index958"></a><a name="index959"></a><a name="index960"></a>)</code> [SAL]<br>

<code>(seq-create)</code> [LISP]</dt>
<dd>Creates a SEQ data object.<br><br>
<dt><code>seq-read(<a name="index961"></a><a name="index962"></a><a name="index963"></a><i>seq</i>,
<i>file</i>)</code> [SAL]<br>

<code>(seq-read <i>seq</i> <i>file</i>)</code> [LISP]</dt>
<dd>Reads into a SEQ data
object from an ASCII text file in Adagio format. The first parameter
is the SEQ object to read. The <i>file</i> is a file opened for
reading. It must be closed after <code>seq-read</code> returns.<br><br>
<dt><code>seq-read-smf(<a name="index964"></a><a name="index965"></a><a name="index966"></a><i>seq</i>,
<i>midi-file</i>)</code> [SAL]<br>

<code>(seq-read <i>seq</i> <i>midi-file</i>)</code> [LISP]</dt>
<dd>Reads into a SEQ data object from a Standard MIDI File. The first parameter is the SEQ object to read. The <i>midi-file</i> is a <i>binary</i> file opened <i>in binary mode</i> for reading. It must be closed after <code>seq-read-smf</code> returns.<br><br>
<dt><code>seq-write(<a name="index967"></a><a name="index968"></a><a name="index969"></a><i>seq</i>,
<i>file</i>, <i>absolute</i>)</code> [SAL]<br>

<code>(seq-write <i>seq</i> <i>file</i> <i>absolute</i>)</code> [LISP]</dt>
<dd>Writes a SEQ data object to an ASCII text file in Adagio format. The first parameter is the SEQ object to write. The <i>file</i> is a file opened for writing. It must be closed after <code>seq-read</code> returns. The <i>absolute</i> parameter should be true to write absolute times of events and false (NIL) to write relative times.<br><br>
<dt><code>seq-write-smf(<a name="index970"></a><a name="index971"></a><a name="index972"></a><i>seq</i>,
<i>midi-file</i>)</code> [SAL]<br>

<code>(seq-write-smf <i>seq</i> <i>midi-file</i>)</code> [LISP]</dt>
<dd>Writes a SEQ data object to a binary file in Standard MIDI File format. The first parameter is the SEQ object to write. The <i>midi-file</i> is a <i>binary</i> file opened for writing. The file is closed by <code>seq-write-smf</code>.<br><br>
<dt><code>seq-insert-note(<a name="index973"></a><i>seq</i>, 
 <i>time</i>, <i>line</i>, <i>chan</i>, <i>pitch</i>, <i>dur</i>, <i>loud</i></code> [SAL]<br>

<code>(seq-insert_note <i>seq</i> <i>time</i> <i>line</i> <i>chan</i> 
 <i>pitch</i> <i>dur</i> <i>loud</i>)</code> [LISP]</dt>
<dd>Inserts a new note into the SEQ 
object <i>seq</i>. The note will be at <i>time</i> (a FIXNUM in milliseconds), 
with <i>chan</i> (MIDI channel) given by a FIXNUM starting at 0, 
duration given 
by <i>dur</i> (a FIXNUM in milliseconds), <i>pitch</i> (a FIXNUM with MIDI key 
number), and MIDI velocity given by <i>loud</i>, a FIXNUM from 1 to 127. The
 <i>line</i> field is intended as a source code line number for Adagio files and
can be any FIXNUM.<br><br>
<dt><code>seq-insert-ctrl(<a name="index974"></a><i>seq</i>, <i>time</i>, 
  <i>line</i>, <i>ctrltype</i>, <i>chan</i>, <i>ctrlnum</i>, <i>value</i></code> [SAL]<br>

<code>(seq-insert-ctrl <i>seq</i> <i>time</i>
  <i>line</i> <i>ctrltype</i> <i>chan</i> <i>ctrlnum</i> <i>value</i>)</code> 
 [LISP]</dt>
<dd>Inserts
a new control into the SEQ object <i>seq</i>. Here, &ldquo;control&rdquo; refers to a 
variety of MIDI messages, including program change, pitch bend, and 
aftertouch in addition to control changes.
The control will be at <i>time</i> (a FIXNUM in 
milliseconds). The <i>ctrltype</i> (FIXNUM) uses MIDI status bytes for 
convenience: <code>seq-ctrl-tag</code> (11) for a MIDI control change, 
 <code>seq-prgm-tag</code> (12) for a MIDI program change,
 <code>seq-cpress-tag</code> (13) for a MIDI channel pressure change, or
 <code>seq-bend-tag</code> (14) for a MIDI pitch bend change.
The <i>chan</i> (MIDI channel) is given by a FIXNUM starting at 0.
If <i>ctrltype</i> is 11 (control change), then <i>ctrlnum</i> is the MIDI
controller number, otherwise this parameter is ignored. The <i>value</i> 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 <code>round(x * 127 + 128)</code>.)
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 <i>line</i> field is intended as a source code line number for Adagio files and
can be any FIXNUM.
</dd></dl>
<p>To read data from a sequence, you normally begin by making a shallow copy, but
you can probably just call <code>seq-reset</code> to initialize the iterator. Then
call <code>seq-get</code> to get the current event, and <code>seq-next</code> to advance
to the next event:</p>
<dl>
<dt>
<code>seq-copy(<a name="index975"></a><i>seq</i>)</code> [SAL]<br>

<code>(seq-copy <i>seq</i>)</code> [LISP]</dt>
<dd>Returns a shallow copy of <i>seq</i>. 
Each copy of a sequence contains an independent iterator providing sequential
access to the events in the sequence.<br><br>
<dt><code>seq-reset(<a name="index976"></a><i>seq</i>)</code> [SAL]<br>

<code>(seq-reset <i>seq</i>)</code> [LISP]</dt>
<dd>Reset the sequence iterator
to the beginning of the sequence.<br><br>
<dt><code>seq-get(<a name="index977"></a><i>seq</i>)</code> [SAL]<br>

<code>(seq-get <i>seq</i>)</code> [LISP]</dt>
<dd>Get the current event in the
sequence. The returned value is a list of FIXNUMs in the form
 (<i>eventtype</i> <i>time</i> <i>line</i> <i>chan</i> <i>value1</i> <i>value2</i> <i>dur</i>)
as follows:
<ul>
<li>
<i>eventtype</i> - The type of event: <code>seq-done-tag</code> (0) indicates
 end of sequence, <code>seq-other-tag</code> (1) indicates the event is not
 supported in Nyquist, <code>seq-note-tag</code> (2) indicates the event is a 
 note, <code>seq-ctrl-tag</code> (11) indicates a MIDI control change, 
 <code>seq-prgm-tag</code> (12) indicates a MIDI program change,
 <code>seq-cpress-tag</code> (13) indicates a MIDI channel pressure change, and
 <code>seq-bend-tag</code> (14) indicates a MIDI pitch bend change.</li>
<li><code>seq-ctrl-tag</code> (3) indicates the event is a MIDI control change</li>
<li><i>time</i> - Time of the event in milliseconds.</li>
<li><i>line</i> - The Adagio file line number for the event (may not be defined
when data is imported from a MIDI file or elsewhere.</li>
<li><i>chan</i> - The MIDI channel (zero-based).</li>
<li><i>value1</i> - 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. </li>
<li><i>value2</i> - The note velocity, program number, controller value,
channel pressure, or pitch bend (see <code>seq-insert-ctrl</code> above for
details on pitch bend values.) Program numbers are zero based.</li>
<li><i>dur</i> - The duration in milliseconds for notes.
</li></ul>
Functions to access events returned by <code>seq-get</code> are defined in
<code>runtime/seqfnint.lsp</code>.<br><br>
<dt><code>seq-next(<a name="index978"></a><i>seq</i>)</code> [SAL]<br>

<code>(seq-next <i>seq</i>)</code> [LISP]</dt>
<dd>Advance the sequence
iterator to the next event in the sequence unless the iterator is at
the last (<code>seq-done-tag</code>) event.

</dd></dl><a name = "125"><h3>Adagio Score Language</h3></a>
<p>Adagio <a name="index979"></a> 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 <a href = "#139">Examples</a> starting on page
<a href = "#139">Examples</a> before reading any further.</p>

<p>A note is described in Adagio by a set of attributes<a name="index980"></a>, and
any attribute not specified is &ldquo;inherited&rdquo; 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<a name="index981"></a>, pitch<a name="index982"></a>, loudness<a name="index983"></a>,
voice<a name="index984"></a> number, duration<a name="index985"></a>, and articulation<a name="index986"></a>.</p>

<p>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.</p>

<p>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.</p>

<p>Besides notes, there are several other types of commands:
<ol>
<li>
An asterisk<a name="index987"></a> (<code>*</code>) in column one (or immediately after a comma,
semicolon, or space) indicates that the rest of the line is a
comment<a name="index988"></a>.  The line is ignored by Adagio, and is therefore a
good way to insert text to be read by people.  Here are some examples:
</p>
<pre>
* This is a comment.
T150 G4  * This is a comment too!
T150 G4  ;* So is this.
</pre>

<p></li>
<li>An empty command (a blank<a name="index989"></a> line, for example) is ignored as if it
were a comment<a name="index990"></a> <a href = "foot.html#foot5">(Footnote 5)</a> .</li>
<li>An exclamation point<a name="index991"></a><a name="index992"></a> (!) in column one (or
immediately after a comma or semicolon) indicates a special
command<a name="index993"></a>.  A special command does not generate a note.
Special commands follow the &ldquo;!&rdquo; with no intervening spaces and extend to the end of the line, for example:
</p>
<pre>
!TEMPO 100
</pre>

<p></li>
<li>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.
</li></ol></p>

<p>Adagio is insensitive to case<a name="index994"></a>,
thus &ldquo;A&rdquo; is equivalent to &ldquo;a&rdquo;, and you
can mix upper and lower case letters freely.</p>
<a name = "126"><h3>Specifying Attributes</h3></a>
<p>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.</p>

<p>The default unit of time is  a centisecond
(100<sup T>th</sup>'s), but this can be changed to a millisecond (1000<sup T>th</sup>'s) using the <code>!MSEC</code> command and reset to centiseconds with <code>!CSEC</code>  (see Section <a href = "#141">Time Units and Resolution</a>).  In the descriptions below, the term &ldquo;time unit&rdquo; will be used to mean whichever convention is currently in effect.</p>
<a name = "127"><h4>Time</h4></a>
<p>The time<a name="index995"></a> attribute specifies when to start the note.  A time is
specified by a &ldquo;T<a name="index996"></a>&rdquo; followed by a number representing time units
 or by a duration (durations are described below).  Examples:
</p>
<pre>
T150	** 1.5 sec (or .15 sec)
TQ3	** 3 quarter note's duration
</pre>

<p>
If no time is specified, the default time<a name="index997"></a> is the sum of
the time and duration attributes of the previous note.  (But see Section
<a href = "#130">Next Time</a>.) Time is measured relative to the time of the
most recent Tempo<a name="index998"></a> or Rate<a name="index999"></a> command.  (See the
examples in Section
<a href = "#139">Examples</a> for some clarification of this point.)</p>
<a name = "128"><h4>Pitch</h4></a>
<p>The pitch<a name="index1000"></a> attribute specifies what frequency to produce.
Standard scale pitches are named by name, using <code>S</code> for sharp<a name="index1001"></a>,
 <code>F</code> for flat<a name="index1002"></a>,
and (optionally) <code>N</code> for natural<a name="index1003"></a>.
For example, <code>C</code> and <code>CN</code> represent the same pitch, as do <code>FS</code> and <code>GF</code> (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.</p>

<p>Octaves<a name="index1004"></a> are specified by
number. <code>C4</code> is middle C, and <code>B3</code> is a half step lower.  <code>F5</code> 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<a name="index1005"></a><a name="index1006"></a><a name="index1007"></a> can go before or after
the octave number, so  <code>FS3</code> and <code>F3S</code> have the same meaning.  </p>

<p>An alternate
notation for pitch is <code>P</code><i>n</i>, where <i>n</i> is an integer representing the pitch.<a name="index1008"></a>
Middle C<a name="index1009"></a> (C4) is equivalent to <code>P60</code>, <code>CS4</code> is <code>P61</code>, etc.  </p>

<p>If you do not specify an octave<a name="index1010"></a>,
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.</p>
<a name = "129"><h4>Duration</h4></a>
<p>Duration<a name="index1011"></a> is specified by a letter indicating a number of
beats, followed by one or several modifiers.  The basic duration codes are:
 
<blockquote>
<code>W</code><a name="index1012"></a>&emsp;&emsp;&emsp;(whole<a name="index1013"></a>, 4 beats), <br>

<code>H</code><a name="index1014"></a>&emsp;&emsp;&emsp;(half<a name="index1015"></a>, 2 beats), <br>

<code>Q</code><a name="index1016"></a>&emsp;&emsp;&emsp;(quarter<a name="index1017"></a>, 1 beat), <br>

<code>I</code><a name="index1018"></a>&emsp;&emsp;&emsp;(eighth<a name="index1019"></a>, 1/2 beat), <br>

<code>S</code><a name="index1020"></a>&emsp;&emsp;&emsp;(sixteenth<a name="index1021"></a>, 1/4 beat), <br>

<code>%</code><a name="index1022"></a>&emsp;&emsp;&emsp;(thirtysecond<a name="index1023"></a>, 1/8 beat), and<br>

<code>^</code><a name="index1024"></a>&emsp;&emsp;&emsp;(sixtyfourth<a name="index1025"></a>, 1/16 beat). </blockquote> 
Note that <code>E</code> is a pitch, so eighth-notes use the duration code <code>I</code>.
The default tempo is 100 beats per
minute (see Section <a href = "#136">Tempo</a>).  These codes may be followed by a  <code>T</code>
(triplet<a name="index1026"></a><a name="index1027"></a>), indicating a duration of 2/3 the normal.  A dot<a name="index1028"></a><a name="index1029"></a> (<code>.</code>) 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:

 
<blockquote>
<table>
<tr><td><code>Q</code></td><td>&nbsp;&nbsp;&nbsp;</td><td>1 beat (quarter note)</td></tr>
<tr><td><code>QT</code></td><td></td><td>2/3 beat (quarter triplet)</td></tr>
<tr><td><code>W.</code></td><td></td><td>6   beats(dotted whole note)</td></tr>
<tr><td><code>ST6</code></td><td></td><td>1   beat (6 sixteenth triplets) </td></tr>
<tr><td><code>H5</code></td><td></td><td>10  beats(5 half notes)</td></tr>
<tr><td><code>Q3/7</code></td><td></td><td>3/7 beats</td></tr></table>
</blockquote>

A duration may be noted by <code>U</code><i>n</i><a name="index1030"></a>, where <i>n</i> is an integer
indicating 100<sup T>th</sup>'s of a second 
(or 1000<sup T>th</sup>'s), see Section <a href = "#141">Time Units and Resolution</a>.
For example, <code>U25</code> is twenty-five time units.</p>

<p>Durations may be combined using a plus sign: 
</p>
<pre>
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
</pre>
 
<a name = "130"><h4>Next Time</h4></a>
<p>The time of the next<a name="index1031"></a><a name="index1032"></a> 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 <code>N</code>
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 <code>N</code>.  If the next note
has an explicit time attribute (<code>T</code>), then the specified time will override
the one based on the previous note.  Examples:
 </p>
<pre>
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
</pre>

<p>  
A comma has an effect similar to  <code>N0</code> and is explained in Section <a href = "#142">Multiple Notes Per Line</a>.  Articulation effects such as <i>staccato</i> can be produced using <code>N</code>, but it is more convenient to use the articulation attribute described in Section <a href = "#132">Articulation</a>.</p>
<a name = "131"><h4>Rest</h4></a>
<p>Rests<a name="index1033"></a><a name="index1034"></a> are obtained by including the field <code>R</code> in a
note command.  The effect of an <code>R</code> 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 <code>R</code> and a duration.  The fact that a
note command specifies a rest is not inherited.  For example:
 </p>
<pre>
R H	** a half (two beat) rest
RH	** illegal, R must be separated from H by space(s)
</pre>

<p>  </p>

<p>Because some synthesizers (e.g. a DX7<a name="index1035"></a>) cannot change programs
<a name="index1036"></a>
(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 <a href = "#135">Timbre (MIDI Program)</a> for an example.</p>
<a name = "132"><h4>Articulation</h4></a>
<p>Articulation<a name="index1037"></a><a name="index1038"></a><a name="index1039"></a> in Adagio refers to the
percentage of time a note is on relative to the indicated duration.  For
example, to play a note <i>staccato</i>, you would normally play the note about
half of its indicated duration.  In Adagio, articulation is indicated by
<code>#</code><a name="index1040"></a> followed by an integer number indicating a percentage.  The
articulation attribute does not affect the time of the next command.  This
example plays two <i>staccato</i> quarter notes:
</p>
<pre>
C Q #50
D
</pre>

<p>
To produce overlapping notes, the articulation may be greater than 100.  </p>
<small>
Be aware that overlapping notes on the same pitch can be a problem for some synthesizers.  The following example illustrates this potential problem:

<p></p>
<pre>
!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?
</pre>

<p>
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.
</p>
</small>
<a name = "133"><h4>Loudness</h4></a>
<p>Loudness<a name="index1041"></a><a name="index1042"></a> is indicated by an <code>L</code>
followed by a dynamic marking from the following: <code>PPP</code><a name="index1043"></a><a name="index1044"></a>,
<code>PP</code><a name="index1045"></a><a name="index1046"></a>, <code>P</code><a name="index1047"></a><a name="index1048"></a>, <code>MP</code><a name="index1049"></a><a name="index1050"></a>, <code>MF</code><a name="index1051"></a><a name="index1052"></a>, <code>F</code><a name="index1053"></a><a name="index1054"></a>,
<code>FF</code><a name="index1055"></a><a name="index1056"></a>, <code>FFF</code><a name="index1057"></a><a name="index1058"></a>.  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 &ldquo;note-off,&rdquo; so the minimum loudness is 1.)  The
dynamic<a name="index1059"></a>
markings are translated into numbers as follows:
  
<blockquote>
<table>
<tr><td><code>Lppp</code></td><td>&nbsp;&nbsp;</td><td>20</td>
<td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</td>
<td><code>Lmf</code></td><td>&nbsp</td><td>58</td></tr>
<tr><td><code>Lpp</code></td><td></td><td>26</td>
<td></td>
<td><code>Lf</code></td><td></td><td>75</td></tr>
<tr><td><code>Lp</code></td><td></td><td>34</td>
<td></td>
<td><code>Lff</code></td><td></td><td>98</td></tr>
<tr><td><code>Lmp</code></td><td></td><td>44</td>
<td></td>
<td><code>Lfff</code></td><td></td><td>127</td></tr>
</table>
</blockquote>
</p>
<a name = "134"><h4>Voice</h4></a>
<p>The voice<a name="index1060"></a><a name="index1061"></a> attribute tells which of the 16 MIDI channels to use
for the note.  The voice attribute consists of a <code>V</code> followed by
an integer from 1 (the default) to 16.  </p>
<small>
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.
</small>
<a name = "135"><h4>Timbre (MIDI Program)</h4></a>
<p>A MIDI program<a name="index1062"></a><a name="index1063"></a> (synthesizer preset<a name="index1064"></a>) can be
selected using the attribute <code>Z</code><i>n</i>, where <i>n</i>
is the program number (from 1 to 128).
Notice that in MIDI, changing the program on a given channel will affect
<i>all</i> notes on that channel and possibly others.  Adagio treats MIDI program changes as a form of control change.</p>
<small>
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:

<p></p>
<pre>
R I Z23 V4	** change MIDI channel 4 to program 23 during rest
A4		** play a note on channel 4
</pre>

<p>
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 <code>Z42</code>.
</p>
</small>

<p>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.</p>
<a name = "136"><h4>Tempo</h4></a>
<p>The length of a beat may be changed using a Tempo<a name="index1065"></a> command<a name="index1066"></a>:
</p>
<pre>
!TEMPO <i>n</i>
</pre>

<p>
where <i>n</i> 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 <code>!TEMPO</code> command is associated with a time, computed as if the <code>!TEMPO</code> command were a note.  The time<a name="index1067"></a> attribute (<code>T</code>) of all
succeeding notes is now measured relative to the time of the <code>!TEMPO</code> command.  The new tempo starts at the <code>!TEMPO</code> command time and
affects all succeeding notes.  
Durations specified in time units (for example <code>U58</code>, <code>N15</code>) are not affected by the <code>!TEMPO</code> command, and numerical times (for example  <code>T851</code>) are computed relative to the time of the last <code>!TEMPO</code> command.</p>

<p>The <code>!TEMPO</code> command is fairly clever about default durations<a name="index1068"></a>.  If the last duration specified before the <code>!TEMPO</code> command is
symbolic (using one of <code>^</code>, <code>%</code>, <code>S</code>, <code>I</code>, <code>Q</code>, <code>H</code>, or <code>W</code> ), then the default duration for the
node after the <code>!TEMPO</code> command will be modified according to the tempo change.
Consider the following tempo change:
</p>
<pre>
!TEMPO 60
A4 H
!TEMPO 120
G
</pre>

<p>
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 <code>U200</code> (also a
duration of 2 seconds), the second note would also last 2 seconds because the <code>!TEMPO</code> 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 <code>!TEMPO</code> command is undefined.</p>
<a name = "137"><h4>Rate</h4></a>
<p>The <code>!RATE</code><a name="index1069"></a><a name="index1070"></a> 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:
</p>
<pre>
!RATE 110
</pre>

<p>
<code>!RATE</code> and <code>!TEMPO</code> commands combine, so
</p>
<pre>
!RATE 200
!TEMPO 70
</pre>

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

<p>Two <code>!RATE</code> commands do not combine, so a <code>!RATE</code> command only affects the rate until the next <code>!RATE</code> command.</p>

<p>Although  <code>!TEMPO</code> and <code>!RATE</code> can occur in the middle of a note (using <code>N</code>, <code>T</code>, etc.) they do not affect a note already specified.   This property allows multiple tempi to exist simultaneously (see Section <a href = "#144">Multiple Tempi</a>).</p>
<a name = "138"><h3>Default Attributes</h3></a>
<p>If an attribute is omitted, the previous one is used by
default<a name="index1071"></a> (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:
  
<blockquote>
<table>
<tr><td>Time        </td><td>&nbsp;&nbsp;&nbsp;</td><td><code>T0  </code></td></tr>
<tr><td>Pitch       </td><td>                  </td><td><code>C4  </code></td></tr>
<tr><td>Duration    </td><td>                  </td><td><code>Q   </code></td></tr>
<tr><td>Articulation</td><td>                  </td><td><code>#100</code></td></tr>
<tr><td>Loudness    </td><td>                  </td><td><code>LFFF</code></td></tr>
<tr><td>Voice       </td><td>                  </td><td><code>V1  </code></td></tr>
<tr><td>Tempo       </td><td>                  </td><td><code>!TEMPO 100</code></td></tr>
<tr><td>Rate        </td><td>                  </td><td><code>!RATE 100</code></td></tr></table>
</blockquote>

Control changes (including timbre or MIDI program, specified by <code>Z</code>) have no default value and are only sent as specified in the score.</p>
<b><i>Important:</i></b> the rules for determining when a command will play a note are as follows (and this has changed slightly from previous versions):
<ol>
<li>
If a special (<code>!</code>) command or nothing is specified, e.g. a blank line, do <i>not</i> play a note.</li>
<li>If <code>R</code> (for &ldquo;rest&rdquo;) is specified, do <i>not</i> play a note.</li>
<li>Otherwise, if a pitch is specified, <i>do</i> play a note.</li>
<li>Otherwise, if no control changes (or program changes) are specified (so this is a command with non-pitch attributes and no control changes), <i>do</i> play a note.
</li></ol>
Another way to say this is &ldquo;Special commands and commands with rests (<code>R</code>) do not play notes.  Otherwise, play a note if a pitch is specified or if no control is specified.&rdquo;<a name = "139"><h3>Examples</h3></a>
<p>The following plays the first two bars of &ldquo;Happy Birthday&rdquo;.  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:
</p>
<pre>
*Example 1 ** Happy Birthday tune (C major)
!TEMPO 120
G4 I. LF
G4 S
A4 Q
G4
C5
B4 H
</pre>

<p>
The time attribute for the first note is zero (<code>0</code>).  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.</p>

<p>The following example plays the first four bars of  an exercise  from
Bartok<a name="index1072"></a>'s Mikrokosmos<a name="index1073"></a> (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.
</p>
<pre>
*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
</pre>

<p>
</p>
<pre>
*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
</pre>

<p></p>

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

<p></p>
<pre>
*Example 3 ** 4 measures in 2 sections
!Tempo 100
*Voice 1, Measures 1 &amp; 2
R Q Z10 V1
A4 H
B Q
C
D H
C
</pre>

<p>
</p>
<pre>
*Voice 2, Measures 1 &amp; 2
T0 R Q Z15 V2
G3 H
F Q
E
D H
E H
</pre>

<p>
</p>
<pre>
!TEMPO 100
*Voice 1, Measures 3 &amp; 4
* note that Z10 is still in effect for V1
V1 D4 Q
C
B
A
B
C
D
R
</pre>

<p>
</p>
<pre>
*Voice 2, Measures 3 &amp; 4
T0 V2 D3 Q
E
F
G
F
E
D
R
</pre>

<p></p>

<p>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)
<i>and</i> sets the reference time to
be two measures into the piece.  Therefore, the next note
<code>(D4</code>) will begin measure 3.  The <code>D3</code> that begins the last
group of notes has a <code>T0</code> attribute, so it will also start at measure
3.  Notice how the <code>!TEMPO</code> command can serve to divide a piece into
sections<a name="index1074"></a>.</p>

<p>The last example will show yet another way to express the same piece of
music using the &ldquo;Next&rdquo; attribute.  Only the first bar of music is
given.
</p>
<pre>
*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
</pre>

<p>
Here, each pair of 
lines represents two simultaneous notes.  The <code>N0</code> 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.</p>
<a name = "140"><h3>Advanced Features</h3></a>
<p>Beyond the simple notation described above, Adagio supports a number of 
features.  (See also the next chapter.)</p>
<a name = "141"><h4>Time Units and Resolution</h4></a><a name="index1075"></a><a name="index1076"></a>
<p>The default time unit is 10ms (ten milliseconds or one centisecond or
100<sup T>th</sup> of a second), but it is
possible to change the basic unit to 1ms, or 1000<sup T>th</sup> of a second.
The time unit can be specified by:
   <blockquote><a name="index1077"></a>
<a name="index1078"></a><table>
<tr><td><code>!CSEC</code></td><td>&nbsp;&nbsp;&nbsp;</td><td>centisecond time units = 100<sup T>th</sup></td></tr>
<tr><td><code>!MSEC</code></td><td></td><td>millisecond time units = 1000<sup T>th</sup></td></tr></table>
</blockquote>  
The time unit remains in effect until the next <code>!CSEC</code> or <code>!MSEC</code> command.</p>
<a name = "142"><h4>Multiple Notes Per Line</h4></a><a name="index1079"></a>
<p>Notes can be separated by commas<a name="index1080"></a><a name="index1081"></a> or
semicolons<a name="index1082"></a><a name="index1083"></a> as well as by starting a new line.  A comma is
equivalent to typing  <code>N0</code> 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, <i>use commas to separate the notes of a chord.</i></p>

<p>A semicolon is equivalent to starting a new line.  In general, <i>use semicolons to group notes in a melody</i>.  Here is yet another rendition of the Bartok:
</p>
<pre>
*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
</pre>

<p>
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:
</p>
<pre>
*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
</pre>

<p></p>
<a name = "143"><h4>Control Change Commands</h4></a><a name="index1084"></a><a name="index1085"></a>
<p>Any control change can be specified using
the syntax &ldquo;<tt>~<i>n</i>(<i>v</i>)</tt>&rdquo;, where <i>n</i> is the controller number (0 - 127), and 
<i>v</i> 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):

 
<blockquote>
<table>
<tr><td><code>K</code></td><a name="index1086"></a><a name="index1087"></a><td>&nbsp;&nbsp;&nbsp;</td><td>Portamento switch</td></tr>
<tr><td><code>M</code></td><a name="index1088"></a><a name="index1089"></a><td></td><td>Modulation wheel</td></tr>
<tr><td><code>O</code></td><a name="index1090"></a><a name="index1091"></a><td></td><td>Aftertouch</td></tr>
<tr><td><code>X</code></td><a name="index1092"></a><a name="index1093"></a><td></td><td>Volume</td></tr>
<tr><td><code>Y</code></td><a name="index1094"></a><a name="index1095"></a><td></td><td>Pitch bend</td></tr>
<tr><td><code>Z</code></td><a name="index1096"></a><a name="index1097"></a><td></td><td>Program Change</td></tr></table>
</blockquote>

The letter listed beside each control function is the Adagio command
letter.  For example,  <code>M23</code> 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 &ldquo;off&rdquo; 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 <code>K127</code> and off with <code>K0</code>.  Programs are numbered 1 to 128 to correspond to synthesizer displays.</p>
<b><i>About volume:</i></b> 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 <code>L</code> (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.<b><i>About pitch bend:</i></b> 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 <code>Y128</code> translates exactly to 8192. The <i>meaning</i> of pitch bend depends upon your synthesizer and its setting. Most synthesizers let you specify a &ldquo;pitch bend range.&rdquo; A range of one semitone means that <code>Y255</code> will produce a bend of approximately one semitone up, and <code>Y0</code> will bend one semitone down.  If the range is 12 semitones, then the same <code>Y255</code> 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.
<p>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:
</p>
<pre>
*Example 7
C4 LMF M50 Y120 U100 N10
Y110 N10; Y100 N10; Y90 N10; Y80 N10
Y70 N10; Y60 N10; Y50 N10
~5(80)
</pre>

<p></p>

<p>See Section <a href = "#138">Default Attributes</a> on page <a href = "#138">Default Attributes</a> for rules on whether or not a command will play a note.</p>
<a name = "144"><h4>Multiple Tempi</h4></a><a name="index1098"></a><a name="index1099"></a>
<p>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:
</p>
<pre>
*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
</pre>

<p>
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 (<code>N</code>) 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 <code>!TEMPO</code> command cannot have a time (<code>T0</code>) attribute, and a <code>T0</code> by itself would create a note with a duration.  <code>T0 R N0</code> says: &ldquo;go to time 0, do not play a note, and do not advance the time before the next command&rdquo;.
Thus, the time of the <code>!TEMPO 120</code> 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 (<code>C5</code>) of each scale will happen at the same time.
 
<a name = "145"><h4>MIDI Synchronization</h4></a></p>
<a name="index1100"></a><a name="index1101"></a><a name="index1102"></a><a name="index1103"></a>
<p>The Adagio program (but not Nyquist) can synchronize with external devices using MIDI real time messages. Thus, Adagio has a <code>!CLOCK</code> 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). </p>

<p>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
<code>!CLOCK</code> command<a name="index1104"></a> in Adagio turns on a 24 pulse-per-quarter (PPQ) clock at
the current tempo and time:
</p>
<pre>
!TEMPO 100
!CLOCK
</pre>

<p>
A <code>!CLOCK</code> 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.</p>
<small>
Clock commands and thus tempo
changes can take place at arbitrary times.  It is assumed that tempo changes
on an exact 24<sup T>th</sup> of a beat subdivision (for example, exactly on a
beat).  If not, the tempo change will take place on the nearest exact
24<sup T>th</sup> of a beat subdivision.  This may be earlier or later than the
requested time.
</small>
<a name = "146"><h4>System Exclusive Messages</h4></a> 
<p>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 <tt>v</tt> is replaced by 
the channel (voice) and <tt>%1</tt> is replaced by the first parameter.
A macro is invoked by writing &ldquo;~&rdquo; followed by the macro name and a
list of parameters<a name="index1105"></a>:
</p>
<pre>
!DEF LFO F0 43 0v 01 09 %1 F7
Bf5 W ~LFO(25)
</pre>

<p></p>

<p>In general, the <tt>!DEF</tt> command can define any single MIDI message including
a system exclusive
message.  The message must be complete (including the status byte), and each <tt>!DEF</tt> must correspond to just one message.
The symbol following <tt>!DEF</tt> 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:
<dl>
<dt>
<tt>v</tt></dt>
<dd>Insert the 4-bit voice (MIDI channel) number.  If <tt>v</tt> occurs in the
place of a high-order hexadecimal digit, replace <tt>v</tt> with <tt>0v</tt> so that
the channel number is always placed in the low-order 4 bits of a data byte.  In other words, <tt>v</tt> is padded if necessary to fall into the low-order bits.</p>
<dt><tt>%</tt><i>n</i></dt>
<dd>Insert a data byte with the low-order 7 bits of 
parameter number <i>n</i>.  Parameters are numbered 1 through 9.
If the
parameter value is greater than 127, the high-order bits are discarded.<br><br>
<dt><tt>^</tt><i>n</i></dt>
<dd>Insert a data byte with bits 7 through 13 of parameter number
<i>n</i>.  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, <tt>%4^4</tt> will
insert the low-order followed by the high-order parts of parameter 4
into two successive data bytes.
</dd></dl>
<p>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 <a href = "foot.html#foot6">(Footnote 6)</a> . </p>

<p></p>
<pre>
* 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

</pre>

<p></p>
<a name = "147"><h4>Control Ramps</h4></a>
<p>The <tt>!RAMP</tt> command<a name="index1106"></a> 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.
</p>
<pre>
!RAMP X10 X100 Q W2
!RAMP ~23(10) ~23(50) U20 W
!RAMP ~lfo(15) ~lfo(35) U10
</pre>

<p>
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 (<tt>W</tt>).
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 &ldquo;ramped&rdquo;; the others must
remain the same.  For example, the following would ramp the second parameter:
</p>
<pre>
!RAMP ~mysysex(4,23,75) ~mysysex(4,100,75) U10 W
</pre>

<p>
<small></p>

<p>A rather curious and extreme use of macros and ramps is illustrated in the
following example.  The <tt>noteon</tt> macro starts a note, and <tt>noteoff</tt> 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!
</p>
<pre>
!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
</pre>

<p>
</p>
</small>
<a name = "148"><h4>The !End Command</h4></a><a name="index1107"></a><a name="index1108"></a>
<p>The special command  <code>!END</code> marks the end of a score.  Everything beyond that
is ignored, for example:
</p>
<pre>
* this is a score
C; D; E; F; G W
!END
since the score has ended, this text will be ignored
</pre>

<p></p>
<a name = "149"><h4>Calling C Routines</h4></a>
<p>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.</p>

<p>The <code>!CALL</code> command<a name="index1109"></a><a name="index1110"></a> calls a C routine that can in turn invoke a
complex sequence of operations.  Below is a call to a trill<a name="index1111"></a> 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:
</p>
<pre>
!CALL trill(A5,W,2,S,Lmf)  T278 V1
</pre>

<p>
<i>The parameter list should have no spaces</i>, 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.</p>

<p>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. <tt>'a'</tt> is equivalent to <tt>97</tt> because 97 is the decimal
encoding of &ldquo;a&rdquo; in ASCII.</p>

<p>The <code>!CALL</code> may be followed by a limited set of attributes.  These are time (<tt>T</tt>), voice (<tt>V</tt>), and next time (<tt>N</tt>).  The <code>!CALL</code> is made at the current time if no time is specified, and the time of the next adagio command is the time of the  <code>!CALL</code> unless a next time is specified.  In other words, the default is <tt>N0</tt>.</p>
<a name = "150"><h4>Setting C Variables</h4></a>
<p>In addition to calling C routines, there is another way in which scores
can communicate with C.  As with <code>!CALL</code>, specific C code must be linked before these commands can be used, and this is not supported in Nyquist.  
The  <code>!SETI</code> command<a name="index1112"></a><a name="index1113"></a> sets an integer variable
to a value, and the <code>!SETV</code> command<a name="index1114"></a><a name="index1115"></a> sets an element of an integer array.  
For example, the next line sets the variable <tt>delay</tt> to 200 and sets
<tt>transposition[5]</tt> to -4 at time 200:
</p>
<pre>
!SETI delay 200
!SETV transposition 5 -4  T200
</pre>

<p>
As with the <code>!CALL</code> 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.  </p>

<p></p>
<hr>
<a href = "part11.html">Previous Section</a> | <a href = "part13.html">Next Section</a> | <a href = "title.html#toc">Table of Contents</a> | <a href = "indx.html">Index</a> | <a href = "title.html">Title Page</a>
</body></html>