THE CMU MIDI TOOLKIT ``Charles Ives'''' Edition

The MIDI version of Adagio currentlyuses the timbre attribute to select a MIDI ``program'' synthesizer preset.Adagio has been extended to allow MIDI controller data such as modulation wh

THE CMU MIDI TOOLKIT ``Charles Ives'' Edition

Carnegie-Mellon University does not warrant, guarantee or make any

representation regarding your requirements or that CMT is free of errors

Neither Carnegie-Mellon University nor anyone else who has been involved inthe creation, production, or delivery of CMT program shall be liable for anydirect, indirect, consequential or incidental damages arising out of use orinability to use CMT

Preface This manual is a guide for users of the Carnegie Mellon University MIDI

Toolkit, also known as CMT, a collection of software for experimental computermusic using standard Musical Instrument Digital Interface (MIDI) equipment.This manual corresponds to CMT Version 2.00

This is the Charles Ives edition, the first CMT manual This manual is

updated periodically as new programs are contributed to CMT and as bugs arediscovered and fixed I solicit your help in making this manual more accurateand complete PLEASE help us by noting any errors, omissions, or suggestionsyou may have You can send your suggestions to Dannenberg@A.CS.CMU.EDU

(ARPAnet) via computer mail, or by campus mail to Roger B Dannenberg, Centerfor Art and Technology, CFA, or by ordinary mail to Roger B Dannenberg, Centerfor Art and Technology, Carnegie Mellon University, Pittsburgh, PA 15213-3890,USA A bug report form can be found at the end of this manual

Many people have contributed to CMT which grew out of earlier computer musicsystems used in the CMU Computer and Electronic Music Studio Dean Rubinewrote the first MPU-401 interface routines with help from Dale Amon Joe

Newcomer ported this first version to his IBM-AT and helped clear up many ofour interrupt problems Aaron Wohl wrote routines to use the PC timer and mademany good suggestions for improvements The Tuning program and the initialtuning software were written by Michael Cressman Most of the development workwas done on the IBM-XT in the CMU Computer and Electronic Music Studio Thismachine was part of a grant from IBM

I also wish to acknowledge support from CMU through the Music Department, theComputer Science Department, the Center for the Design of Educational

Computing, and especially the Center for Art and Technology

1 Introduction and Overview

The CMU MIDI Toolkit (CMT) is a software package designed for experimentalcomputer music education, composition, performance, and research CMT includes

a compiler for a simple, text-based music language, and software for recording,playing, and computing MIDI data in real time CMT has three major

attractions: the flexibility of an open-ended design, the availability ofsource code, and low system cost

What does CMT do? The major components and their functions are:

- Adagio is a language and an associated compiler In Adagio, a note

is represented by a line of text that specifies attributes such as

pitch, duration, and loudness Adagio is quite flexible and is

compatible with several different ways of thinking about scores For example, ``Q'' stands for a quarter note, but duration can also be

indicated by ``U87'', which means 0.87 seconds Adagio also supports arbitrary tuning systems

- Transcribe reads input from a MIDI keyboard or other MIDI controller

and produces an Adagio score The score can be played back using

Adagio, or it can be edited with a text editor to make alterations

Since Transcribe output is at least somewhat readable by people, it

can also be used for performance analysis

- Record is a combination of Adagio and Transcribe It plays an

existing Adagio score while transcribing a performance Thus,

complex compositions can be created one part at a time as if using a

multi-track tape recorder

- DXGet and DXPut are programs for recording and replaying MIDI system

exclusive messages These programs are typically used to save and

restore synthesis parameters for a digital synthesizer

- Moxc is a real-time programming environment that is ideal for writing interactive music programs Moxc is an extension of the C

programming language and is based on Douglas Collinge's Moxie

language

- Also provided are routines (in C) that allow direct production of

MIDI output Other routines are available to read MIDI data from a

circular input buffer and to get the current time with 0.01 second

resolution

Required hardware and software CMT runs on an IBM-XT or IBM-AT with a

Roland MPU-401 MIDI interface and IBM-PC interface adapter You should alsohave a screen-based text editor To use Moxc, you will need a Lattice C

compiler

Other details CMT is distributed by the CMU Center for Art and Technology,Carnegie-Mellon University, Pittsburgh, PA, 15213 We hope that users willcontribute new software to the system and enhance the existing software invarious ways We will encourage this by helping to integrate and document newsoftware and by distributing software updates to CMT users

1.1 Installing CMT

CMT comes on a set of two floppy disks Disk #1 contains executable programsand some example files Disk #2 contains source code and files you need inorder to recompile CMT programs If you have a hard disk, you should copy thecontents of the floppy disks that come with CMT onto the hard disk Put Disk

#1 in the floppy disk drive and type:

Some useful non-music programs are included with CMT They are make, grep, and

ls To install these programs, type:

cd \bin

copy a:\bin\*.*

If you want to use CMT to write programs, you should copy the contents of Disk

#2 into your cmt directory Put Disk #2 into the floppy disk drive and type:

If you want to use the same synthesizer for both input and output, a slightlydifferent approach is necessary Here, you should go ahead and connect bothMPU-401 IN and OUT to your synthesizer OUT and IN, respectively To avoid theproblem of having outputs returned as inputs, you should use the ``-block''option on all CMT software When the software is not running, it may be

necessary to disconnect either of the two MIDI cables because the MPU-401

default is to resend all inputs as outputs In some cases, the DX7 cannot

handle having its output data returned to its input.

2 DOS Utilities

Before describing music software that comes with the CMU MIDI Toolkit, someDOS commands and utility programs are described Three programs are providedwith CMT to help make your life easier These are make, ls, and grep A

section on backing up files, intended for novice users, is also included inthis chapter

2.1 make

The make program is based on the Unix (Unix is a trademark of A.T.& T BellLaboratories) program of the same name, and is documented in the file make.man.The purpose of make is to figure out what has to be recompiled when you edit afile A file called makefile contains a list of file dependencies and a

command that specifies how to recompile a dependent file The make programfigures out what files have changed by examining their ``last modified'' timesand dates Therefore, if you use make, you must always tell DOS the time anddate when you turn on your machine An example of an entry in makefile

describing a dependency is

ADOBJ = adagio.obj phase1.obj phase2.obj adaspace.obj noteoff.obj

MUSICLIB = cmt.lib

adagio.exe : #(ADOBJ) #(MUSICLIB)

link #(COBJ) #(ADOBJ),adagio,,#(LIBS)

In this example, ADOBJ is a symbol that is defined in the first line to be alist of files The line with the colon (:) says that adagio.exe depends uponeverything on the right of the colon, that is, all of the object files

represented by ADOBJ and also the file cmt.lib, represented by MUSICLIB Ifadagio.exe does not exist or is older than one of the files it depends upon, itshould be remade by executing the lines after the line stating the dependency

In this case, there is only one command (starting with the word link) needed The file makefile, from which this example was taken, is provided with CMTand contains a complete list of CMT file dependencies It is a good reference

if you have questions about how to write a makefile

To use make, simply give it the file you want to make up-to-date For

This will not remove OBJ files You can get rid of unneeded OBJ files bytyping:

make cleanobjs

2.2 ls

The ls program is like the DOS dir command, except it lists file names only(no size and date information), and the names are formatted into columns inalphabetical order The current version of ls does not work with large

directories, although this may be fixed by the time you read this.

2.3 grep

The grep program searches one or more files for a text string If the string

is found, the line containing the string is printed grep is indispensable forreading someone else's code For example, to find out where fileopen is

declared (as well as where it is used), type

grep fileopen *.c

in the CMT source code directory

2.4 Backing up files

Note: This section is intended for new users of the CMU Computer Music

Studio, but it is worth reading if you are inexperienced with personal

computers

The IBM XT system has a built-in disk that can store about 10 million

characters of information Unfortunately, that may not be enough to meet thedemands of all of the studio users Fortunately, there is an alternative way

to store information called the floppy disk Floppy disks are also a good way

to make copies of your work for safe keeping There is always a small chancethat all of your data will be lost from the Studio computer To protect

yourself, you should keep a backup copy of any critical files on a floppy disk.Floppy disks are thin magnetic disks that come in a protective sleeve and

insert into the slot in front of the IBM XT

To make a backup copy of your directory,

1 put a floppy disk into the disk drive slot and push down the door

2 if you have not used the disk before, type

up you directory, then you will lose last week's version of tune.gio from yourfloppy disk It will be replaced by the current version

To copy individual files, type

copy filename a:

where filename is the file you want to save on floppy To recover an

individual file from floppy disk to your directory, type

copy a:filename

3 The Adagio 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 maywant to glance at the examples in Section 3.3 starting on page 5 before reading

any further.

A note is described in Adagio by a set of attributes, and any attribute notspecified is ``inherited'' from the previous line Attributes may appear inany order and must be separated by one or more blanks An attribute may notcontain any blanks The attributes are: time, pitch, loudness, voice number,duration, and timbre

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 quitewell as a representation for MIDI scores The MIDI version of Adagio currentlyuses the timbre attribute to select a MIDI ``program'' (synthesizer preset).Adagio has been extended to allow MIDI controller data such as modulation

wheels, pitch bend, and volume

A note command in Adagio must be separated from other notes Usually, notesare distinguished by writing each one on a separate line Notes can also beseparated 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 or

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

2 An empty command (a blank line, for example) is ignored as if it

were a comment (To be consistent, a blank line ought to generate a

note that inherits all of its attributes from the previous one

Adagio is intentionally inconsistent in this respect.)

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, and currently, the only special commands are

the Rate and Tempo commands, described below Special commands

extend to the end of the line

4 Control change commands are used to control parameters like pitch

bend that can change as a note is playing Control change commands

can be specified along with notes or by themselves A command that

specifies only control changes will not produce a note

Adagio is insensitive to case, thus ``A'' is equivalent to ``a'', and you canmix upper and lower case letters freely

TQ3 3 quarter note's duration

If no time is specified, the default time is the sum of the time and durationattributes of the previous note (But see Section 3.1.4.) Time is measuredrelative to the time of the most recent Tempo or Rate command (See the

examples in Section 3.3 for some clarification of this point.)

3.1.2 Pitch

The pitch attribute specifies what frequency to produce Standard scalepitches 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)

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 Accidentals can go before or afterthe octave number, so FS3 and F3S have the same meaning An alternate notationfor pitch is Pn, where n is an integer representing the pitch Middle C (C4)

is equivalent to P48, CS4 is P49, etc [If you know MIDI codes, you will

notice that P48 in Adagio results in a MIDI pitch code of 60 The ``middle C =48'' convention was borrowed from Gary Nelson's MPL and it is consistent withMUSIC V, cmusic, and many other computer music languages I decided to stickwith the convention on the assumption that if you know enough about MIDI toknow that middle C is 60, then you know enough not to be confused by Adagio andother CMT software.] If you do not specify an octave, Adagio will choose onefor 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 thelower octave

3.1.3 Duration

Duration is specified by a letter indicating a number of beats, followed byone 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), and S (sixteenth,1/4 beat) The default tempo is 100 beats per minute (see Section 3.1.9).These codes may be followed by a "T" (triplet), indicting a duration of 2/3 thenormal A dot (".") after a duration code extends it by half to 3/2 the

normal Finally, an integer after a note multiplies its duration by the

indicated value (the result is still just one note) 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)

Finally, a duration may be noted by Un, where n is an integer indicating

followed by a number indicating hundredths of seconds, or followed by a

duration as described above The next note will then start at the time of thecurrent note plus the duration specified after ``N'' If the next note has anexplicit time attribute (``T''), then the specified time will override the onebased on the previous note Examples:

N0 start the next note at the same time as the current one

N50 start the next note 0.5 seconds after the current one

NQT start the next note 2/3 beat after the current one

3.1.5 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 theresult of the current note command In all other respects, the command isprocessed just like any other line This means that attributes such as

duration, loudness, and pitch can be specified, and anything specified will beinherited 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 notinherited For example:

R H a half (two beat) rest

RH illegal, R must be separated from other fields by space(s)

Because some synthesizers (e.g a DX7) cannot change programs (presets)

rapidly, it may be desirable to change programs at the beginning of a rest sothat the synthesizer will be ready to play by the end of the rest See Section3.1.8 for an example

3.1.6 Loudness

Loudness is indicated by an ``L'' followed by a dynamic marking from thefollowing: PPP, PP, P, MP, MF, F, FF, FFF Alternatively, a number from 0 to

127 may be used The loudness attribute is the MIDI note velocity The

dynamic markings are translated into numbers as follows:

synthesizer, Adagio cannot tell you when you exceed the limit Similarly,Adagio cannot tell whether your synthesizer is set up to respond to a givenchannel, so there is no guarantee that what you write will actually be heard

3.1.8 Timbre (MIDI program)

A MIDI program (synthesizer preset) can be selected using the attribute

``Zn'', where n is the program number Notice that in MIDI, changing the

program on a given channel will effect all notes on that channel Also, formany synthesizers, you will not be able to change programs at the start of anote 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

The cartridge programs on a DX7 can be accessed by adding 32 to the cartridgeprogram number For example, cartridge program number 10 is specified by Z42

3.1.9 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 thatthis is a special command line rather than a note definition A special

command takes the place of a note specification No other attributes should bewritten on a line with a special command The new tempo affects all succeedingnotes The time attribute of all succeeding notes is now measured relative tothe time of the Tempo command Durations specified in hundredths of seconds(for example U58, N15, or T821) are not affected by the Tempo command

The Tempo command is fairly clever about default durations If the lastduration 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

durations specified in hundredths of seconds

3.1.10 Rate

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

*Example 1 Happy Birthday tune (C major)

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'sMikrokosmos (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 Theright hand part is played on voice (MIDI channel) 1 and the left hand part onvoice 2 Notice the specification of the time attribute to indicate that voice

2 starts at time 0 Also, I have taken advantage of default octaves to reducetyping

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 lastTempo command:

*Example 3 4 measures in 2 sections

Notice that the piece is written in 4 sections The first plays a rest

followed by two measures, starting at time 0 The next section changes thetime back to zero and plays two measures of the left hand part (voice 2) Thenext command (!TEMPO 100) sets the tempo to 100 (it already is) and sets thereference 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 T0attribute, so it will also start at measure 3 Notice how the !TEMPO commandcan serve to divide a piece into sections

The last example will show yet another way to express the same piece of musicusing the ``Next'' attribute Only the first bar of music is given

*Example 4 use of the Next attribute

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 ofeach pair

3.4 Advanced features

Adagio allows you to write multiple commands on one line and to program MIDIcontrol functions It is also possible to write music with multiple tempi

3.4.1 Multiple notes per line

Notes can be separated by commas or semicolons as well as by starting a newline A comma is equivalent to typing N0 and starting a new line A semicolon

is equivalent to starting a new line Here is yet another rendition of theBartok:

*Example 5 use of semicolons

3.4.2 Control change commands

The current version of Adagio can control the following functions:

Pitch bend (Y)

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 Exceptfor pitch bend and the portamento switch, all values range from 0 to 127

Pitch bend is ``off'' or centered at 128, and has a range from 0 to 255 Turn

on portamento with K127 and off with K0

There is no convenient way to get smoothly varying functions You can eithertype in many control changes to achieve the effect you want or generate a filewith the transcribe program containing the data you want

Control changes can be part of a note specification or independent In thefollowing example, a middle C is played with a modulation wheel setting of 50and a pitch bend of 120 Then, at 0.1 second intervals, the pitch bend isdecreased by 10:

*Example 7

C4 LMF M50 Y120 U100 N10

Y110 N10; Y100 N10; Y90 N10; Y80 N10; Y70 N10; Y60 N10; Y50 N10

3.4.3 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

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 arest, and a next (N) attribute is used to specify that the next default timewill be at the same time as the current one Thus, the time of the !TEMPO 120command is zero After the 12 note scale, the tempo is changed to 100 and afinal 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

3.5 Running Adagio

To use Adagio, create an Adagio score using a text editor By convention,Adagio scores are named something.gio, where something is any name you like,and ``.gio'' is a hint that this is an Adagio score

To listen to the score, type

adagio something

Notice that typing the ``.gio'' is optional with Adagio (but you must type thefull file name when you use the editor) If all goes well, you will get thefollowing prompt:

Type <RETURN> to play notes, q<RETURN> to quit, ?<RETURN> for help:

If you type ``?RETURN'', you get a complete list of commands:

<return> Play music

q<return> Quit Adagio (Exit)

r<return> Read tuning file

m<return> Turn on MIDI byte trace

-m<return> Turn off MIDI byte trace

s<return> Report state

t<return> Turn on music operation trace

-t<return> Turn off music operation trace

?<return> This message

If you type RETURN to start your piece, Adagio first sends a MIDI programchange to program 1 on each of the 16 MIDI channels Exactly 1 second aftertyping RETURN, Adagio starts playing your score

If you type ``qRETURN'', Adagio will exit

If you type ``rRETURN'', you will get a prompt for a tuning file (see Chapter4) This command is useful for playing a single score with different tuningswithout exiting Adagio

The ``m'' command causes Adagio to print a trace of all MIDI data This isnot useful for anything other than debugging changes to Adagio The ``-m''command turns tracing off

The ``s'' command reports what data will be traced

The ``t'' command causes Adagio to print a trace of all music operations.The information printed in a fairly readable form as opposed to the numbersprinted using the ``m'' switch The ``-t'' switch turns off the music

operation trace

3.5.1 Debugging Adagio Scores

While the score is playing, you can type the space bar to stop the

performance The computer screen will then tell you where it was at the momentyou hit the space bar This is very handy for finding the source of bad notes.For example, if you hear a bad note, play the score again and type a space whenyou hear the mistake Suppose the screen says that you were playing a notefrom line 123 and another from line 259 Remember these numbers, quit Adagio(type ``Q''), and type

3.5.2 Command Line Options

The following options can be specified in the command line:

- -debug (or -d): turn on debugging code

- -help: print a list of command line options

- -miditrace (or -m): turn on MIDI byte trace

- -trace (or -t): turn on music operation trace

- -at: tell Adagio that you are running on an AT (This option is

redundant information for debugging There is no advantage to using

it because Adagio and other CMT software can determine the machine

type automatically.)

- -metronome (or -met): turn on the MPU-401 metronome This is only

useful for debugging because there is no way to set the metronome

speed

- -simulated (or -s): simulate the MPU-401 but do not use it This is

only useful for debugging and may not be implemented

- -xt: tell Adagio that you are running on an XT (This option is for

debugging _ see -at.)

- -print: tells Adagio to print details of each note on the console

- -block: turns off the MPU-401 MIDI THRU function so that the input is not passed to the output

- -tune filename: tells Adagio to use filename to specify tuning

adagio score -tune meantone

4 Defining Nonstandard Tunings

Tuning in MIDI is normally twelve-tone equal temperment MIDI has no

provisions to change this except by using the pitch bend control In general,

a different setting of pitch bend is needed for each pitch in a scale

Needless to say, this can be very tedious to program explicitly; however CMThas a way to automate the use of pitch bend to obtain the desired scale

Notice that pitch bend affects every note on a given channel; therefore, it isgenerally not possible to play several notes on one channel whenever alternatetunings are desired (Ignoring this limitation can lead to some very

interesting effects, however.)

The tuning mechanism in CMT is quite simple: whenever a program (Adagio,Record, Transcribe, Moxc, etc.) goes to play a note, the note's pitch is used

as an index into a table of (pitch, pitch bend) pairs The pitch bend is sent,followed immediately by the pitch from the table Using the table, it is

possible to translate every specified pitch into an arbitrary pitch and pitchbend

Important: CMT assumes that you have set up your synthesizer so that thepitch bend range is one semitone (100 cents) and that the synthesizer changesfrequency exponentially with respect to the pitch bend value If your

synthesizer is different, it will be necessary to modify CMT to make its tuningmechanism more general The current system seems to work fine with a DX7 Theformula used to calculate the MIDI pitch bend data is

PitchBend = (8192 * c) + 8192,where c is the pitch bend in cents (not the velocity of light)

A scale is defined by a ``tuning'' file (``.tun'' is the default suffix),which can be created with the help of a program called tuning, described below.The format of the file is simple Each line of text in the file consists ofthree numbers The first is a note number (48 is middle C) between -12 and

115 The second is a pitch, also between -12 and 115, and the third is thepitch bend, between -100, and 100 Any pitches that are not mentioned in thefile are given their normal equal-temperment interpretation.

To use a tuning file, say meantone.tun, you type the following option

anywhere in the command line:

-tune meantone

If no tuning is specified, then notes are not translated and no pitch bendcommands are sent

4.1 The Tuning Program

The tuning program lets you define scales in terms of ratios or cents

You run Tuning by typing

tuning myscale

where myscale.tun is the name of the tuning file you want to create (Anextension of ``.tun'' will automatically be appended.) The program then

prints:

You will now create a pitch file

r - enter a range of values

o - enter one octave (that will be generalized)

p - enter one pitch (you choose)

q - quit

Command >>

To which you should respond with one of r, o, p, or q The actions associatedwith each command are described below:

4.1.1 Entering a range of pitches

The r command prompts you for a range of pitches and then prompts you for apitch and pitch bend for each pitch in the range For example, The following

is a transcript of what you would do to make C4 through D4 sound 1 step and 10cents (110 cents) higher (user typein is in italics):

Command >>r

Adagio note range is -12 115

What range of notes would you like to enter ?

From >> 48

To >> 50

For the given Adagio note number, enter the desired pitch

and the amount of pitchbend in cents

Bend range = -100 100, '0' for no pitch bend

4.1.2 Entering an octave

The o command lets you enter information for one octave and then

automatically transpose that information (by octaves) to provide informationfor all possible pitches Here is an abbreviated sample transcript for a

tuning in which every other note is 50 cents sharp:

Command >>o

You will input the information for one octave and that

will be generalized for all octaves

Would you like to enter the information as

(1) frequency ratios of notes to a tonic

or (2) semitones (integer) + pitchbend (in cents)

>>2

For the given note number, enter the desired pitch

and the amount of pitchbend in cents based on given tonic

1 unit of pitch = 1 semitone the tonic (note 0) has pitch 0 and

4.1.3 Entering one pitch

You can use the p command to modify just one pitch This is useful to goback and change information you have entered with the r or o commands Here is

an example that makes A4 (pitch number 57) play an octave higher:

Command >>p

Adagio note range is -12 115 Which note would you like to enter ?

(type return to quit)

Note >>57

For the given pitch number, enter pitch parameters

Bend range = -100 100 cents, 0 for no pitch bend

Adagio note range is -12 115 Which note would you like to enter ?

(type return to quit)

Note >>

4.1.4 Saving a tuning file

When you are done, use the q command to save the tuning file:

Command >>q

As discussed above, you can use the resulting file with Adagio, Record, andMoxc to control tuning

4.2 The Retune Program

A simple demonstration program is included with CMT to allow you to

``retune'' a MIDI controller To use it, you should connect a MIDI controller(e.g a DX7) to MIDI IN or your computer interface, and connect MIDI OUT of theinterface to a synthesizer (e.g a TX816) Run Retune by typing:

retune -tune myscale

where myscale.tun is a tuning file previously created Now, as you play on thecontroller, the Retune program will use pitch bend in real time to adjust thepitch of each note

Note: The Retune program is \test\retune.exe on CMT DISK 1 You may have tocopy it to your \cmt directory to use it from another directory Also noticethat since pitch bends apply to the whole keyboard, polyphonic notes interferewith one another

5 The Transcribe Program

5.1 Overview

The Transcribe program is used to record performances via MIDI and to

translate them into Adagio Rather than attempt to guess musical durations(like a dotted-quarter), Transcribe records all times and durations in

hundredths of seconds This program, together with Record makes it fairlysimple to build up complex Adagio scores one part at a time Transcribed musiccan be copied, edited, or repeated using an ordinary text editor The outputfrom Transcribe might also be useful in the study or evaluation of

extension of ``.gio'' will be assumed Transcribe will then ask you if youwant to record control information:

Pitch bend, etc on? [n]

Type ``y'', ``n'', or just RETURN for the default (n) Generally, you shouldtype RETURN At present, recording control information tends to use up theavailable recording memory very quickly, so it is of limited use When youhave finished what you want to play, type the space bar on the IBM This

signals the program to stop and write out the notes This file can now beplayed by Adagio and what comes out will be very similar to what you just heardyourself play

5.3 Timbre

When you start Transcribe, it sends MIDI program change commands to program 1

on all MIDI channels When you make a program change on the synthesizer,

Transcribe records the change and translates it into an Adagio Z attribute.This corresponds to the default Z1 attribute in Adagio and to the fact thatAdagio also initializes all MIDI channels to program 1

Note: Transcribe (and Record) record Z attributes whenever they receive aMIDI Program Change command Synthesizers normally send this when you change apreset sound using the controls on the synthesizer One noteable exception isthat if a Yamaha synthesizer is in the ``Sys Info Avail'' mode, then pressing

a button to change the program causes the synthesizer to dump all of the

internal data comprising the program No MIDI Program Change command is sent,

so Transcribe records nothing You can find out what is happening by runningthe MM (Midi Monitor) program and pushing a program change button on your

synthesizer For Yamaha synthesizers, the mode should be ``Sys Info Unavail'',which is a fairly cryptic way to say ``send program numbers instead of programdata''

5.4 Command Line Options

The following options can be specified in the command line:

- -debug (or -d): turn on debugging code

- -help: print a list of command line options

- -miditrace (or -m): turn on MIDI byte trace

- -trace (or -t): turn on music operation trace

- -block: turns off the MPU-401 MIDI THRU function so that the input is not passed to the output

- -control (or -c) on: record control information, do not present the

``Pitch bend, etc on?'' query

- -control (or -c) off: do not record control information, do not

present the ``Pitch bend, etc on?'' query

6 The Record Program

Record uses the Adagio compiler to get old.gio ready to play It then promptsyou with:

Type <RETURN> to record, q<RETURN> to quit, ?<RETURN> for help:

The possible responses are described in detail in Section 3.5 Normally, youshould just type RETURN to start playing and recording Next, you will get aprompt for the file you want to create:

Name of output file:

Type new The extension gio will be added automatically if you do not provideany extension

After a delay of one second, Record begins to play the score in old Thedelay is not precise, so you would normally put something into old to ``countoff'' the start of the piece Record also records anything you play

Recording does not stop until you type the space bar, even if old finishesplaying

After you type the space bar, you will again get the prompt:

Type <RETURN> to record, q<RETURN> to quit, ?<RETURN> for help:

You can erase and re-record new by repeating the instructions given above.(This time, you will have to confirm that you want to erase new.gio.)

Otherwise, just type q to quit

You now have two files, old.gio and new.gio The next section describes how

to merge files to create a single file for Adagio

6.3 Merging Adagio Scores

A few tricks are helpful in merging two scores into one In this section, Iwill describe the basics of making two scores play at the same time as well asgetting two scores to play in sequence It should be remembered that the goal

is simply to create an Adagio score If you try something that does not work,you should be able to look at your scores and figure out where the problem is

6.3.1 Playing two scores in sequence

To play two scores in sequence, you should edit the first score file so thatthe last line contains the last event of that score Since Adagio scores arenot necessarily written in time order, this may or may not be the case

Transcribe and Record always write scores in the order of note start times

The last note will specify a next (N) attribute that corresponds to the timeyou typed the space bar.

Once you get the timing of the last note right, it should be apparent that ifyou insert some notes at the end of the score, they will be played after thescore (unless they specify a time (T) attribute) You might want to conduct anexperiment to find out where your score ends If you insert the line

C6 LFFF U20

at the end of your file, you should here a distinctively loud and high note atthe end of your score If the ``end'' comes too early or too late, you shouldedit your file accordingly

You can insert an entire file at the end of another file using the DOS copycommand:

copy score1.gio+score2.gio

DOS knows nothing about Adagio, so the gio extensions must be specified Thiscommand will modify score1.gio by appending the contents of score2.gio, which

is not modified An alternative form is

copy score1.gio+score2.gio score3.gio

which puts the result into score3.gio, leaving score1.gio and score2.gio

intact

If score2.gio does not specify (T) attributes, then appending the scoresshould be adequate On the other hand, if score2.gio specifies times relative

to the beginning of the score, you can insert a !TEMPO command at the

beginning Then, when score2.gio is appended to score1.gio, the !TEMPO commandwill occur at the end of score1.gio, and everything in score2.gio will be

measured relative to the !TEMPO command

6.3.2 Playing two scores at the same time

To get two scores to play at the same time, you should make sure that thesecond score includes a time (T) attribute on or before its first note

Otherwise, the second score will be played after the first one (Record

automatically inserts a time attribute on the first note of each file it

creates The time is the correct one assuming you want to merge the recordedfile (e.g new.gio with the played file (e.g old.gio) The DOS copy command

is used to merge the two files as described above

A typical problem is trying to play two scores on the same voice (MIDI

channel) This is only a problem if both scores try to play the same note atthe same time MIDI assumes that notes are turned on by pressing keys, and it

is impossible to press the same key twice without first releasing it Thisproblem usually manifests itself as notes that get cut off early If you aretrying to merge two files with the same voice, you might want to change thevoice specified for the second file to make sure the two scores do not

interfere (This of course assumes you have several synthesizers so that youcan play several channels at once.)

6.4 Command Line Options

The following options can be specified in the command line:

- -debug (or -d): turn on debugging code

- -help: print a list of command line options

- -miditrace (or -m): turn on MIDI byte trace

- -trace (or -t): turn on music operation trace.

- -at: tell Record that you are running on an AT (This option is

redundant information for debugging There is no advantage to using

it because Record and other CMT software can determine the machine

type automatically.)

- -metronome (or -met): turn on the MPU-401 metronome This is only

useful for debugging because there is no way to set the metronome

- -control (or -c) off: do not record control information, do not

present the ``Pitch bend, etc on?'' query

record foo -c off -block

7 DXGet and DXPut

DXGet and DXPut are used to store and recall programs for synthesizers.These are generally voice programs, but in general they can be any sequence ofMIDI system exclusive messages

Do you want instructions? [y]

to which you can respond with "y," "n," or just RETURN to indicate yes If

your response is yes, the following instructions are printed:

This program will let you save DX7 and TX816 voice programs To save DX7 programs, you must connect DX7 MIDI OUT to MPU 401 MIDI IN For

TX816 programs, connect TX816 MIDI OUT to MPU 401 MIDI IN, and set the OUT SLOT (leftmost display) to the module from which you want data

For DX7: push the orange FUNCTION key, then the green 8 Push 8

repeatedly until the display says SYS INFO AVAIL or SYS INFO UNAVAIL

If the display says SYS INFO UNAVAIL, push YES to change the display to SYS INFO AVAIL Now, select a voice with the INTERNAL or CARTRIDGE

button followed by a (green) number For ALL DX7 voices: after getting the SYS INFO AVAIL display, push 8 again to get MIDI TRANSMIT ? Push YES For TX816: Hold down SELECT until you see UT in the display Let

up on SELECT and then push it once more to get the flashing dU Push

YES to dump all data from this module Hold down SELECT until you see digits in the display After data is dumped, dxget will tell you what

it got and write data to a file Use dxput to copy a file to a dx

module

Next, you are prompted as follows:

Ready for your data Type space when you are done

and you should cause your synthesizer to send whatever system exclusive

messages you want to save One or more messages can be saved Notice thatDXGet will not request information automatically This would require DXGet toknow about types of synthesizers To be more general, DXGet is very simple.Consequently, you must manually cause your synthesizer to send the desiredinformation to DXGet

After one or more messages have been sent, type the space bar and the

messages will be saved in the file you specified The file format is simplybytes in hexadecimal separated by spaces As the data is output, DXGet willcheck to make sure the data has not been garbled A warning will be printed ifany errors are detected DXGet will also try to print a description of theexclusive messages it received You can send the data back to your synthesizerusing the DXPut program described below

NOTE: If you find that you are sending two messages instead of one when youuse DXGet, here is what is probably happening: When you push the ``yes''

button to send data, the DX7 sends a MIDI message that means ``push the `yes'button'', analogous to sending a MIDI note-on message whey you press a key.Next, the DX7 sends voice data as requested Meanwhile, the first MIDI messagehas gone into the MPU-401 MIDI IN port and has been forwarded to the MIDI OUTport If the MPU-401 MIDI OUT is connected to the DX7 MIDI IN, then the DX7gets a second request (via MIDI) to send data! You can avoid this by

disconnecting the DX7 MIDI IN cable or by using the ``-block'' switch when yourun DXGet

7.2 DXPut

The DXPut program takes files created by DXGet and sends them as MIDI output

To run DXPut, type

dxput filename

where filename is the file created by DXGet A default extension of ``dx7'' isassumed if you do not specify one After starting, DXPut will ask:

Do you want instructions? [y]

The instructions are as follows:

This program will let you send voice programs to a DX7 or TX816 You must send a file previously created by the dxget program To send DX7

programs, you must connect MPU 401 MIDI OUT to DX7 MIDI IN For TX816 programs, connect MPU 401 MIDI OUT to TX816 MIDI IN For a DX7 voice: push the orange FUNCTION key, then the green 8 Push 8 repeatedly

until the display says SYS INFO AVAIL or SYS INFO UNAVAIL If the

display says SYS INFO UNAVAIL, push YES to change to SYS INFO AVAIL

Next, push MEMORY PROTECT/INTERNAL, then NO, and then then MEMORY

SELECT/INTERNAL Now, type the name of a file created by dxget and then the space bar to send data To store the voice program on the DX7,

hold down STORE while you push a (green) number The current voice at this number will be erased and replaced by the new voice For ALL DX7 voices: Same as for a single DX7 voice, but all 32 voice programs on

the DX7 will be replaced when you type Y in response to `Are you sure?'

on the computer For all TX816 voices: To store into one module, push

NO until the MEMORY PROTECT light goes out Make sure other MEMORY

PROTECT lights are ON Type Y in response to 'Are you sure?' on the

computer

Assuming the file you specified contains valid data, you will next see theprompt:

Ready with your data Type space when you are ready

Type space to send the data If a message is one which DXPut knows will cause

a major change, you will be asked for confirmation before the data is sent Atpresent DXPut only asks you to confirm Yamaha 32 voice and 64 performance datamessages

After the data in the file is sent, you are prompted by:

Type Q to quit, RETURN to send another file:

As the computer says, you can quit or continue to send more data Typing afile name gets you back to the prompt: ``Do you want instructions? [y]'', whicheven if you asked for them earlier have by now have scrolled off the screen

This program will play 4 notes in sequence by ``calling'' note 4 times Youindicate what kind of note you want by giving two parameters in parenthesesafter the word ``note'' The parameters for note specify pitch and duration.The pitch parameter is 48 for middle C (C4), and goes up by one for each

semitone Thus, the pitches in this program are C4, D4, E4, and F4 The

second parameter is the duration parameter, expressed in hundredths of a

second Thus, the first note will be 1 second long, the next two will be 0.5seconds, and the last will be 1 second

A few more observations: notice that the ``score'' consists of calls to notepreceded by a name, ``mainscore()'', and is bracketed by the words ``begin''and ``end'' Also notice that calls to note are separated by semicolons (;).All of these details are essential, and C is not very forgiving of even trivialmistakes The first line of the program is called a comment Any text between/* and */ is ignored by C You will find it useful to use comments to remindyourself what your program does, when it was written, and so on The nextline, beginning with ``#include'' tells the C compiler to read the file

``musiprog.h'' from the system library This file contains important

definitions for music, so every program you write should contain this line Unlike Adagio, C is a case sensitive language This means that mainscore,MainScore, MAINSCORE, and MaInScOrE are all distinct identifiers Because ofthis, I suggest that you never use upper case letters in C programs, except instrings and comments

To hear the results of this program, you have to compile your program, thenlink it, and then execute it The Lattice C compiler (invoked by the commandcmtc) translates your program into a machine language form which is stored in afile This file is then linked, or combined with other programs to produce anexecutable program file This file can then be executed, meaning that themachine instructions in the file are loaded into working memory, and the

computer then carries them out To compile your program (called foo.c), typethe following:

cmtc foo.c

If your program has errors, the line number where the error was discovered will

be printed along with a brief description of the error You must fix theseerrors by editing your program and then compiling again When the compilephase and then the link phase completes without errors, you can link your

program by typing:

cmtl foo

The command cmtl is short for cmt link Be sure the last character is theletter l, not the numeral 1 If no errors are reported by the linker, yourprogram is ready to run Otherwise, you will have to fix your program with theeditor, recompile, and relink To run your program, type

foo

To run your program again, you need not recompile unless you change your

program with the editor

the flag and carefully exits your program if the flag is set Since gettime iscalled by almost every procedure that takes any significant time to execute(e.g note, rest, and rest until), it is a pretty safe bet that typing CTRL-Cwill terminate any program.]

8.4 Writing a Procedure

Procedures allow you to give a name to a musical phrase The phrase can then

be called from several places This saves your having to retype all of thecalls to note every time you want to hear the phrase In the following

example, there are two phrases, or procedures, up and down, which are calledfrom mainscore:

When this program is run, the computer will do what mainscore says to do.The first call is to up, so the computer finds the definition of up and doeswhat up says to do In this case, up plays four notes (C, D, E, F) Now that

up is finished, mainscore continues by calling down, which in turn plays (G, F,

E, D) When down returns, mainscore continues with another call to up, andagain up will play C, D, E, F Finally, up returns and mainscore plays a C

At this point the mainscore program is finished

8.5 Repeats

Repetition is important in both programming and music To repeat a phrase, aspecial ``repeat'' construct is provided Consider the following example: #include "cmtprog.h"

mainscore()

begin

repeat(i, 5)

note(48, 30);

note(60, 30) endrep

end

Look at the two calls to note above By themselves, these calls would play thephrase C4 C5 The repeat construct consists of the form

repeat(counter, howmany) phrase endrep

where counter is just the name you want the computer to give to a variablenumber that keeps track of which repeat is being played (more about this

later), howmany is the number of repeats to take, and phrase is a sequence ofcalls to note or any other procedure The example above will play the phraseC4 C5 C4 C5 C4 C5 C4 C5 C4 C5 because we wrote 5 for the number of repeats Ifyou like, you can repeat up to about 30,000 times

The phrase could just as well have been calls to other procedures The nextexample uses repeat to play C4 D4 E4 F4 three times, using the up procedureused earlier

construct) that makes this programming task easy:

note(55, 120)otherwise

note(50, 15);