Comands for VAMP 
    Copyright 2002-2004, Stanley M. Swanson.
       last revised 14 July 2004

    This information is distributed under the terms of the 
    GNU Free Documentation License.  legalities

VAMP was written to generate contra and square dance accompaniment
from traditional melodies (public domain) specified with "abc" notation,
chord sequences (vamping), and a sequence of accents for the notes
in chords which indicate the rhythm (downbeat, etc.) and phrasing of
the music.  These three aspects (melody, chords, rhythm) can be
specified with simple text lines and varied independently.  There are
limitations to this structuring of the musical information, since
it is harder to tweak individual notes than in a GUI type composing
program, but the specifications are more compact and less tedious
to change.  Other aspects of a performance such as tempo, staccato,
and instrument selection can also be specified.  VAMP produces
a MIDI file which is played (or converted to WAV format for a CD)
by a multimedia player (I use Timidity++ on Linux).

abc notation
      keys and modes
volumes and velocities
notes on using TiMidty++
events (variations)
parameters, xtra

Input to the program is command line (text) oriented and can given
in immediate mode or taken from pre-edited files.  An introduction
with examples is in the file  vamp_intro.html.
You will be asked for a log file name at the beginning (useful to
keep track of interactive sessions, or record harmony output).
To exit the program use "quit".

Commands come in two flavors: 
one-liners with a command followed by data 
  ( "quit", "tempo", "instrument", "repeat", "generate", "harmony", 
    "param", "xtra" )
and container type commands where the data appears sandwiched
between a "command" line and its matching terminator "/command".
  ( "melody", "vamp", "chords", "accent", "phrase", 
    "events", "variations", "loops" )
The line oriented format of "abc" notation is retained for
data lines in "melody", and "vamp".

Commands can be abbreviated so long as they remain unambiguous
(presently single letters, except for "vamp", "variations" ).
Commands are case insensitive.  Id's, chord names, and file
names ARE case sensitive.

  The design philosophy with respect to syntax checking has been permissive:
  correct input should give the desired results; incorrect input may be
  detected, but may not be, and useful results are not guaranteed.  Some
  effort has been put into bounds checking for large arrays and protection
  against errors or conditions which will cause program aborts. 

There are several other commands which can be viewed as "one-liners":
the indirect file designator "@path/filename" which switches input 
immediately to the file until an EOF is read.  Indirect files can be 
nested up to 10 deep.  Except for reading parts of an "abc" archive,
an indirect file reference must occur at the top command level,
not within the data lines of container type commands.

The "abc" convention of "%" marking the rest of a line as comment 
is generally observed (but there may be contexts where it doesn't work).

The first two comment lines beginning with "#" before a "generate"
command are saved as text in the MIDI file.  If you want to put
copyright information into a MIDI file, either of the following work:

#copyright date Name (other text)
#(c) date Name (etc.)
ABC Parsing Incomplete:

My implementation of "abc" parsing is not complete.  Generally a character
will be correctly interpreted, or rejected (ignored) with a message
"undecodable character ...".

The music itself is given by letters separated by bar lines "|".
An ascending seven note  scale starting with middle C is given with
capital letters: "CDEFGAB"; the octave above that is in lower case:
"cdefgab".  The total range recognized by VAMP is six octaves, specified
by appending commas to lower notes and apostrophes to higher notes:

 C,,, ... B,,,C,, ... B,,C, ... B,C ... Bc ... bc' ... b'c'' ... b'' .

Thus if C4 is middle C, C5 the C above that (lower case c in "abc"-ese),
the range of notes represented is from C1 through B7.

This discussion is not meant to be a tutorial on "abc" notation.
For a complete specification, see the web site of Chris Walshaw, who
originated the notation:

Most of the information lines (except T: L: M: K: X:) are ignored
and treated as comments. (X:n is used for indirect subfile input: see above.)

Trailing dots (dotted notes e.g. "A.B..") are not recognized but one 
can use ">", "<", "/" (for /2), "/m", or "n/m" (for single digits n,m).
Only simple sequences like "a>b", "f<c" are decoded; something
like "g2>f2" is not -- use "g3f" instead.

Repeats and alternate endings are encoded into "abc" internal
information, and are now used for building a complete tune out of fragments.
( It recognizes ":" "[1" "[2" "[3" and the shorthand symbols "|1" "|2" "|3" .) 
I have added an alternate final ending "[3" which substitutes for "[2" on the
last repeat of a tune.

Repeats, etc. are encoded as a sequence of melodic fragments.  An 
initial repeat sign (:) will be supplied if the number of colons is odd.
Only two possible partial sequences are legal:  " |: .... :|"
and "|: ... [1 ... :| [2 ... ".  A final " [2 ... [3..." is treated
as "[2... ||" for the purposes of all repeats except the last, and 
will be played as " [1...:|[3...||" for the last time through.

Guitar chords ("A7", etc.) are ignored (don't generate musical output).
They are stored as strings and are accessed by the harmony analysis code 
(printed for human reference, and compared to assigned chords).

Slurs (notes) and ornaments {notes}, "~", "." for staccato  are 
unimplemented.  Ties given by "-" are parsed and recorded, but 
presently not utilized further.  (Ties may be necessary in harmony
analysis so that a note does not span the half measure boundary.)

Only triples ( e.g. "(3abc" ) are implemented of the possible tuples.

All notes in a chord must have the same length.  Actually the duration is
taken from the first note in the chord and other durations are 
presently ignored.


    Any explicit accidental sign preceding a note
( "^", "_", "=") has effect for that note and for the rest of the measure.
Explicit accidentals are referenced to the piano white notes (K: C), so
most sharps and flats will put you onto the black notes ( however cases like
 ^B or _C are legal ).  Double accidentals ("^^" or "__") are treated
as a single accidental and an undecoded character.


The key line "K: key" determines global accidentals. 
   (e.g. K: G means that F is interpreted as ^F,  
         K:Eb means that E denotes Eb (_E) and B denotes Bb (_B)  )
Modes (ionian, dorian, phrygian, lydian, mixolydian, aeolian, locrian) 
are recognized, as are "major" and "minor". Without further qualification, 
the key is assumed major.  Modes are used to distinguish the tonal center 
from the major key designated by the key signature.  The command
"harmony center" as well as the final note in the tune or phrase may
help in deciding the mode.

This can be of importance in assigning chords. For example, 
K:A would designate A major with 3 sharps and a tonal center of A, 
while K:Dmixolydian designates a tonal center of D but in
a key signature of G (D is a fifth above G).

"melody ... /melody": musical note input in "abc" format:

For insertion of music description in abc format, we retain the 
historical .abc line oriented file format, but bracket
the abc text with a "melody" and a "/melody" line:
melody [m-id]
T: Title
K:A  % key
 |   | ...  % here are the abc notation lines
The optional melody identifier "m-id" is used for keeping 
track of different tunes so that medleys can be generated.
If "m-id" is not present, an identifier of the form "tune##" is
generated, with "##" in the range 01 to 99.

The "abc" data can be in a separate indirect file between brackets,
@indirect_abc_file  [n]
or the indirect file can contain the bracketing lines (and other data). 
The optional number [n] serves to pick out the abc tune designated
by the index X:n in a file containing multiple tunes.
Vamp sequences:

Vamping is a term out of the jazz lexicon which means to produce
a simple, typically improvised,  accompaniment to a melody.  There
is a characteristic "boom chick boom chick" sound for dance
accompaniment which comes from a unison chord on the beat and 
a triad chord on the offbeat.  For contra music, the dancers take 
a step on each "boom".  Peter Barnes has written a comprehensive 
discussion of basic vamping and variations in his book 
"Interview with a Vamper".

Typically the contents of one measure (two beats for reels and jigs, 
three for waltzes, etc.) of vamping accompaniment will be specified in 
slightly specialized abc lines containing a "macro" name followed by 
a measure of abc writing out the notes in the chords.  The macro name
provides a shorthand for designating the accompaniment in the "chords" 
vamp  [v-id] 
intro | [C] [z] [C] [z] | [C] [z] [C] [z] |
 c    | [C,,C,] [CEG] [G,,,G,,] [CEG]   |
 g    | [G,,G,] [GBD] [D,,D,]   [GBD]   |
 cg   | [C,,C,] [CEG] [G,,G,]   [GBD]   |   % c and g vamps combined
Typical vamp measures (cf. Peter Barnes' book, "Interview with a Vamper")
have unison chords in the first and third places and triads in the 
second and fourth.  E.g.
c   | [C,,C,] [CEG] [G,,,G,,] [CEG] |
The sequence "intro" is a mechanism to introduce pre-melody "potatoes"
and any lead-in notes to the melody (before the first "chorded" measure).
To be recognized it must be the first vamp "abc" line to be input.  However,
By using an "events" list, any designated vamp macro may be used as the 

The designator "cg" for the combined C and G chords in one measure is
purely for mnemonic value: it could have been "x" or "whatever".

Although I have typically used a single vamp macro to correspond
to a single melody measure, the substitution is not so limited.
The length can be longer (c.f. "intro" above) or shorter.  The combined
"cg" above could have been coded as
 C   | [C,,C,] [CEG] |   % half measure C vamp
 G   | [G,,G,] [GBD] |   % half measure G vamp
 and entered on a chord line as "C G" rather than "cg".

It is the user's responsibility to include the proper number of 
notes in the right places so that the timing comes out as intended 
and synchronized between "melody" and "chords".  The total number
of measures and ticks is printed out after each generated MIDI
track;  these should be equal for all music tracks in a MIDI file.


Chord sequences will be given in an abbreviated manner, and macro substitution
from the "vamp" information generates a MIDI track for chords.  The chord 
identifier "c-id" is used in an "events" list for medleys or for changing 
accompaniments for different repetitions of the melody.  If "c-id" is not 
present, an identifier of the form "chords##" is generated, with "##" 
in the range 01 to 99. 

No repeat structure is presently implemented for chords, so chords 
for repeat sequences must be explicitly stated.

If only one vamp name is given for each measure of the melody, multiple 
chords in a measure must be manually combined  as "cg" was above.  
Alternatively, shortened chords can be used as discussed above.
In the example below, the second and forth eight beat phrases produce 
identical chords.
chords [c-id]
  c c g c   c c cg g     c c g c    c c C G g  ...
Volume and velocity:

Control of volume (related to MIDI velocity) can be employed
for a number of purposes: to distinguish beats within a phrase
with a hypermeter applied to chords (accent command), to accent
the beats in a melody (phrasing command), to vary the volume level
during repeats of a tune (_volume_ in event command), and to
emphasize particular beats or phrases in synchrony with dance
events (e.g. the balance before a swing by use of a phrase event).  

Mixing (relative loudness of instruments) is perhaps better 
handled by adjusting patch volumes (timidity.cfg) or by using stereo 
channels (pan in param command) and adjusting the balance on the amplifier.

In addition, volume changes on specific voices can be used as a switch
to pick out melody instruments (e.g. to mark alternate phrases by
changing instruments to affect timbre).  Chord rendition can be changed 
from the basic boom-chuck on a piano to a bass strum on the beat by modifying 
the accent to supress the triad on the offbeat.

Since these changes have different scopes (beat, phrase, tune repeat,
entire piece) and conceptually may be applied independently, some easy 
way to combine their effects is needed.  In many MIDI implementations,
velocity is proportional to the logarithm of the volume, which is 
consistent with our perception of volume where constant ratios of 
amplitude or power correspond to similar perceived changes at different 
absolute volume levels (c.f. decibels).  The default scaling in TiMidity 
takes about 21 velocity units to change the waveform amplitude by a 
factor of 2 (which gives a factor of 64, or 36 dB, change from 127 to 0).

Thus to increase the overall volume, all velocities would be incremented by 
the same amount.  Unfortunately, versions of TiMidity before 2.13.0 used a 
linear velocity conversion table; my velocity values were empirically derived, 
but did not work with additive changes.  An accent command which emphasizes
the hypermeter for chords in a phrase based on the linear relationship:

accent volume
 120  60  80  60   90  60  80  60    100  60  80  60   90  60  80  60

is replaced with the following (based on logarithmic velocities):

accent velocity
 136 120 124 120  128 120 124 120    132 120 124 120  128 120 124 120  

in order to get the same final volumes.  Details of the numerical 
signal amplitudes are given in columns 1-3 in this table:

linear      linear      logarithmic   2 note    3 note chords
"velocity"  amplitude   velocity      (+11)       (+17)

120         0.9449        125          136              (effective log vel
100         0.7874        120          131               compensated for 
 90         0.7087        116          127               by chord_delta)
 80         0.6299        113          124
 60         0.4724        104                     121
 40         0.3150         92                     109
There is another complication, in that several independent notes 
sounded in a chord are louder than a single note at a given
volume (or velocity). The effective velocities for two and three note
chords are given in columns 4-5 above. The corrections shown below are 
now subtracted from the input velocity (which indicates the total
volume of the chord) to get velocities for the separate notes.

n    sqrt(n)   delta velocity (cf. def_vol_table[])
1    1.000         0.0
2    1.414        10.6
3    1.732        16.8
4    2.000        21.2
5    2.236        24.6
6    2.449        27.4
7    2.646        29.7

Thus a velocity greater than the MIDI limit of 127 may be input,
assuming that it will be decremented for mulitple notes;  any
velocity > 127 for a single note will be limited to 127 when the
MIDI file is generated.

Thus when playing the basic vamp of a two note unison followed by a
triad chord, we can replace the empirical linear volume accents:

 120  60  80  60   90  60  80  60    100  60  80  60   90  60  80  60

with the logarithmic set:

 136 120 124 120  128 120 124 120    132 120 124 120  128 120 124 120  

and get similar chord volumes with a new version of TiMidity.
The overall velocity of the new set can be reduced from fff (120)
to pp (24) with _volume_ events (an overall velocity decrement) and 
still retain the same volume relationships within the phrase. This 
was not possible when "velocities" had a linear relation to amplitude.

With other MIDI to .wav converters, some experimentation will be
required.  I have modified my TiMidity-2.11.3 to have logarithmic
velocities and expect the 2.13.0 or 2.13.1 distribution will
conform to this scheme by default (after a chorus bug correction).

Note accents (phrasing):

Phrasing will first be approached by specifying the MIDI velocity
(proportional to the logarithm of volume, see above discussion)
for at least the 16 chords in an 8 beat phrase.  Comparison of alternative
phrasing can be tried with information for several 8 beat phrases.
An accent identifer "a-id" is implemented for changes in the rhythmic 
structure in a MIDI file specifed with the "events"/"variations" command.  
If "a-id" is not present, an identifier of the form "accent##" is
generated, with "##" in the range 01 to 99.

An new syntax has been introduced for the "accent" data, supplementing
the older "isvvv" numbers.  Instrument changes are designated by "{i}",
where the number "i" refers to the MIDI instrument given in the i-th
place in the "instrument" command.  Velocity is still given by a number
"vvv", but the staccato is indicated by the number of leading periods
( consistent with the use of leading periods for staccato in "abc").
Thus "{2} 90" translates into "20090" and "..80" represents "2080".

[****************(June 10, 2004)
[ Note that the values given in the following examples are based
[ on velocities proportional to volume, not logarithmically related.
[ The empirical linear volume accents:
[   120  60  80  60   90  60  80  60    100 60  80  60   90  60  80  60
[ are related  (for a basic vamp) to the logarithmic set:
[   136 120 124 120  128 120 124 120   132 120 124 120  128 120 124 120  
[ The velocities associated with fff, ff, ... pp, ppp in the phrase command 
[ were assigned assuming logarthmic velocities.

accent  [a-id]
 100 60 70 60  80 60 70 60    90 60 70 60  80 60 70 60   
This plays the unison chords (onbeat) at varying and higher velocities
(100 70 80 70 90 70 80 70) than the triads (offbeat) at volume 60.
The specified sequence of accents is reused as needed.

The current limitation is 4096 accents. The numbers may have up to 5 decimal 
digits "isvvv".  The rightmost 3 digits (units, tens, hundreds "vvv") are the 
velocity (0-127),  the thousands digit "s" is the staccato multiplier to 
shorten a chord note by a given number of ticks = s*staccato.  Default 
staccato==0, and can be changed with a field in the "param" command.
The left most digit "i" is an index into the instrument list, allowing 
change of the rhythm instrument on demand or whim.

A more complicated example, alternating between piano and guitar
and shortening the triad chords:
instrument 111 1 25   
           % melody: fiddle (111), accompaniment: piano (1) and guitar (25) 
parameter 5 10
accent  [a-id]
 20100 1060 70 1050  80 2060 70 2055   30090 1060 70 1060  80 3060 70 3055   

% new syntax
% {2} 100 .60 70 .50 80 ..60 70 ..55  {3} 90 .60 70 .60 80 ...60 70 ...55

The 20000 in 20100 sets the instrument to piano for 8 chords after which
the 30000 in 30090 switches to guitar.  If the length of a chord note is
60 MIDI ticks (an eighth note), then 1060 plays at volume(velocity) 60
and for 60-1*10 == 50 ticks (followed by a 10 tick "rest"), 2055 plays
for 60-2*10 == 40 ticks at velocity 55, etc.

The default velocity for melody and intro is 104 (==ff: this can be set
with "mix_mel" and "mix_ch" in the "parameter" command).  Staccato shortening 
of a note is limited: at least 1/4 of the nominal duration will remain.


The phrase command specifies the number of beats in a musical phrase and
also longer term volume changes. The simplest data specifies the number
of beats in a phrase, separated by semicolons:

phrase  [phrase-id]
  8; 8; 16; 8; 8; 16;

Contra dance music usually has eight phrases of eight beats each, for a
total of 64 beats (or steps) for each repeat of the melody.  The example above
has all 64 beats, but could have been cut short at " 8; 8; 16; ", with
the pattern being re-used in a loop.
The number of beats in a phrase is used in harmony analysis and in placing
additional accents (down beat, up beat and off beat) on the general dynamic
contour specified by a more complicated phrase statement.

phrase [phrase-id]
 f 8; < 4 > 4; < fff 4 > 12; mf 8; p 8; f 8 ff 8;

The standard symbols "fff  ff  f  mf  mp  p pp ppp" are used to designate MIDI
velocity levels of    120 104 88  72  56 40 24   8   respectively.  For other
values, the symbol "vnnn" can be used. where "nnn" denotes a decimal integer
between 0 and 127.   (NB, the upper limit has been removed to accommodate 
velocity adjustments for chords, but 127 is enforced for individual notes
when MIDI data is generated.)  The bracket symbols "<" and ">" indicate either 
an increment of 16 and and a decrement of 16 in the velocity level (when no other 
velocity symbol is given), or a change from the velocity level given (or implicit) 
before the symbol to that given afterwards.  The beat count specifies the period 
over which the velocity changes linearly.  Beat counts are summed until a ";" 
indicates the end of a phrase.  

In the example above, 8 beats occur at forte, then the level increases to 
ff in 4 beats, decreases back to f in 4 beats (the end of the second phrase.  
In the third (16 beat) phrase, the velocity changes from f to fff in 4 beats, 
then back to ff in 12 beats.  In the second 32 beats, the velocity level  
changes stepwise in 8 beat sections, mf to p to f to fff.

If one wants the ramped change to extend over more than one phrase, a negative
number can be used to adjust the beat count.  E.g. if one had wanted the
"< fff 4 > 12 ;" to span two eight beat phrases, it could have been written
"< fff 4 > 12 - 8; 8;" 

The note durations in melody are not as regular as in the chord accompaniment.
The general dynamic contour is computed on each beat from the information above.
Then the MIDI generation routine tracks the notes in the melody and decides
whether they start on the down beat (beats 1, 3, 5, 7 ... in the phrase), 
the up beat  (beats 2, 4, 6, 8, ...) or in between on the off beat.  
A velocity increment (or decrement) will be combined with the contour level
(defaults +8 for down beat, 0 for up beat, -8 for off beat; which follows
 the general scheme used for chord accents).

The delta values for a down beat, up beat, and off beat may be changed
by entering three values in square brackets on a separate line in a
"phrase" command [default values are 0 0 0]:

phrase [phrase-id]
 [ 4 0 -4 ]
% ... other phrase data ...


Events/variations ...  

The repeat command will be supplemented or replaced by an event list which
can specify when tunes change, chords change, instruments change, etc.
An optional voice specifier may be used for more than two parts.

% events
% time   event-id  [voice]
% time   _special_action_ [data] 
r:m:t   melody-id [ or chord-id or accent-id or phrase-id or vamp_name(for intro)]
r:m:t   _volume_  vel (int)  [to set the relative master velocity(volume)]
r:m:t   _tempo_ bpm (float)  [to change tempo between repeats]
r:m:t   _end_  [defaults to last given r]
The time designator r:m:t specifies which repeat (r == (-1) 0 1 ... n),
which measure (m) in that repeat, and which tick (t) in the measure.
"r" will be mandatory, m and t will default to -1. Note that r,m, and t
are integers and there are no spaces between them and the separating ":".
Initial implementation is granular at the "r" level, ignoring m and t.
[ Synchronization between voices is the responsibity of the user.
[ The program generates the amount of music specified without checking
[ whether melody length matches chord length for each repeat...
[ This freedom allows some special effects, but can be disasterous
[ if mistakes are made.
[ The user should check the number of ticks generated per track.

After a melody-id, chord-id, accent-id, or phrase-id, an optional
voice number may be given (in the range 1 ... 16).  Melodies and phrases
default to 1, chords and accents default to 2. The voice number maps
directly onto the instrument list (and the MIDI channel (+1)).
The special action commands "_volume_", "_tempo_", and "_end_" act 
on every voice.
                       [ examples .... ? ]
Current intent is that full measures in a melody will be 1 ... 32
and measure 0 is for set-up events (e.g. instrument changes)
before the tune starts and for lead-in notes, etc.  The "intro"
sequence will come at r== (-1).

A phrase chunk introduced at r==0 with voice 0 will be used to 
impart overall dynamics (e.g. emphasis of a balance before a swing)
for all voices and all repeats.  It will be referenced to its median
velocity and used as differences.

Event information is sorted as it is input so that a parallel scan
of the events can be made as one loops the repeats, taking all
events with the same 'r' value as initializers for repeat 'r'
( e.g. tempo or accent change, melody or chord change ). 

The syntax and format of an "event" command is somewhat
tedious.  As an example consider 4 repeats of the tune
Lamplighters hornpipe (lamp):
                                      % read definitions of melody, chords, etc.
instruments 111 72 1   % fiddle, clarinet, piano
 -1 potatoes           % conventional intro for dance
  1 lamp      1        % melody on fiddle   [voice 1]
  1 lamp      2        % melody on clarinet [voice 2]
  1 best      3        % chords on piano    [voice 3]
  1 odd       1        % play phrase 1, 3, 5, 7 on fiddle
  1 even      2        % play phrase 2, 4, 6, 8 on clarinet
  1 boomchuck 3        % accent (hypermeter) for piano
  2 half      3        % another set of chords (half measures)
  3 root      3        % chords prefered by harmony 55
  4 last      3        % modify chords for coda at end
A perl script, "dyn" has been written to translate a more compact 
specification into an events list.  This syntax has now been
incorporated directly into VAMP.  

The above "events" list can now be generated by the statements:
-1 potatoes
melody lamp
 fiddle odd
 clarinet even
chords best half root last
 piano boomchuck
Note that lines in the old syntax (line beginning with a numeric time) 
may be intermingled.

In this example, the fiddle and clarinet play alternate 
phrases in the melody; this is coded in the phrasing commands
"odd" and "even".  Four different (but similar) chord sequences
"best", "half", "root", and "last" are used.

The repeat number is deduced from the position in the list.
 (Presently, an explicitly repeated element determines the total
  number of repeats (i.e. "last" above or an "_end_") when "vamp" 
  generates a MIDI file from the events list.)

The voice number is assigned by the order of the appearance of
 of the instrument line ('iname').

The general format of the this condensed input is:

 "topic word"  "list with optional repeat counts [rep]".

dynamics 'velocity1' [rep] 'velocity2' [rep] ...
melody    melody-id [rep] ...
  'iname' phrase-id [rep] ...
chords    chord-id1 [rep] chord-id2 [rep] ...
  'iname' accent-id [rep] ...

The optional repeat count [rep] has a default value of 1.
If more than one repetition of a list item is desired, it may
be followed by a number giving the total number of repeats
(c.f. "dynamics" below).  The last item is implicitly repeated
until the end of the piece (e.g. "melody lamp" and "melody lamp 4"
would be equivalent in this example which has 4 chord sequences).

The topic words "melody", "chords", and "dynamics" serve to introduce
lists of melodies, chords, and volume levels which change at a
time granularity of a tune repeat.

'iname' is an instrument name (piano, fiddle, guitar, bass, sax, clarinet,
           recorder, banjo, dulcimer are recognized) or the phrase
        "instrument n", with n being a MIDI instrument number.

The instruments following a "melody" line play the designated
melodies, with phrasing specified by the list of phrase-id's.

The instruments following a "chords" line play the designated
chord sequences, with accents specified by the list of accent-id's.

Multiple "chords" lines are possible, if the chords vary by instrument.
It is hard to see why one would want multiple melodies (except perhaps
to transpose for a given instrument), but one might want a medley 
(with several melody-id's given in the "melody" line).

The instruments are assigned to voices in the order of their
appearance, and replace the instrument list as if an explicit
"INSTRUMENT" command had been given.

To change the overall volume as the tune is repeated, a
"dynamics" line may be used.

'Volume' levels use the "fff ff ... ppp" symbols, as introduced 
in the "phrase" command.  The general "vnnn" designator is available.
N.B. the repeat count syntax differs slightly from the phrase beat
syntax of the "phrase" command where no implicit beats are assumed.

Adding a line to the above input:
dynamics f 2 mf ff
would intercalate these velocity/volume commands into the events list:
  1 _volume_   88
  3 _volume_   72
  4 _volume_  104

The initial implementation is limited to changes at the repeat boundaries. 

[ (035.17) Translation from r:m:t to ticks from the beginning is
[ problematical since the number of measures in the intro, or in the
[ melody is not fixed.  Moreover if a medley mixes a reel and a jig,
[ changing the tempo and ticks/measure, this info will have to be
[ recorded for each melody and chord sequence...
[ Limitations imposed by note start and stop times  make fine grained 
[ special events imprecise and difficult to properly program. 
[ (043.01) May consider converting r:m:t to r:b specification...
[ with granularity to the nearest beat, using pedometer() to track.

generate n file.out     %  determine output according to "n" 

generate filename       %  use event list to specify output

Generate the designated MIDI file and spawn Timidity to play it unless
"verbose"<0 in the "xtra" command or one is running in Windows. 
The digit n (0,1,2) specifies melody only (0), chords only (1) or both (2).
Presently melody and chords are generated as separate tracks (with option 2).
The file name is arbitrary and does not have to have the extension ".midi" .

If an introductory sequence ("potatoes" lead in notes) is specified as 
a vamp line named "intro" or with the "events/variations" command,
it will be generated before either the melody or chords (i.e. for each voice).

The old-style "gen [012] filename" command operates on the last input
melody, chords, or accent.  The event command is intended to give 
finer and more versatile control of this process by specifying 
melodies, chords and accents with their identifying strings.

[ Synchronization between voices is the responsibity of the user.
[ The program generates the amount of music specified without checking
[ whether melody length matches accompaniment length for each repeat...
[ This freedom allows some special effects, but can be disasterous
[ if mistakes are made (e.g. a chord symbol left undefined).
[ The user should check the number of ticks and measures generated per track.

An as yet incompletely specified set of commands will be used to specify and 
modify repeated instances of the basic 64 beat dance tune.  At minimum, I want
control over instrumentation, tempo, number of repetitions, and output file 
name.  Probably also need comment field specifiers....

instruments  i j k ...   % blank separated list
  Instrument numbers are the correct external MIDI range [1-128]; internally,
one is subtracted to give the byte value for program change.  A command
"instrument 0 " using the number "0" (which is not a valid MIDI instrument) 
suppresses the MIDI "program-change" command for that voice, so that the
timidity option "-I n" can be used to select an instrument when playing.
Present convention is that the first number is the melody instrument,
the second is the default vamp/chord instrument, and the others can be 
designated by the "i" digit in a number in the "accent" command, or used
by additional voices in an "events" command.

Now that voices can be designated in the "event" command, positions in the
instrument list correspond directly to the voice and the MIDI channel
(the first number is the instrument for voice 1 (and channel 0), the 
second for voice 2 (and channel 1), and so on).  Instrument change 
("accent" command) is accomplished by changing the MIDI channel within
a MIDI track.

[ Need to check out percussion ]

tempo bpm(float) [ ticks_per_quarter_note ] 
Gives the tempo in beats per minute (can be decimal fraction such as 124.2),
and MIDI ticks per quarter note.  Ticks_per_quarter_note [default 120] 
should be  given only once per session, before any abc sequences are 
input, since it determines the internal duration of notes in the database.

  N.B. This replaces the "abc" information field "Q:  "  which is ignored.

repeat n
Where n gives the number of times a tune is played.  This affects the
"gen [012]" commands only.  For a "gen" command, the number of repeats
is determined from the "events" list.

parameters  stac_m  stac_c  vel_m  vel_c  pan_m  pan_c
Specifies staccato (note shortening) in ticks for melody (stac_m)
and chords (stac_c).  All melody notes are shortened, only those marked
in the accent list will be shorted for chords (see discussion in
the section on "accent" above). 

Only as many numbers as given will change the variables. A "param" with
no numbers simply prints out the present values.

[  Overall velocity for melody (vel_m), and chords (vel_c) can be given.  
[  An explicit "B chan 7 vel" may override the -A option in timidity,
[  so I will experiment with offsets in the midi generation.
[  vel_m sets the melody velocity in the absence of detailed information
[  from a phrase command.  Normally chord velocities are set with
[  an accent command and vel_c is used for the introductory potatoes.

[  Pan gives a mechanism to locate the voices (melody 0, chords 1,2,..)
[  in either left or right speakers.  Need to experiment with this.
[  035.08  timidity may only allow left, right, center [+mystery???]]

xtra  verbose blur TESTA  TESTB  transpose_m transpose_c
A catchall command for new parameter entry.

  "Verbose" controls the level of debug printout [default 1].
If "verbose" is entered as a negative number, the immediate playing
of the MIDI file by spawning Timidity is supressed.  Debug printout is
now limited to modules by the verbosity class (ten's digit), and the unit's
digit (0, 1, ... 9) controls the amount of printout as before (see source).

  "Blur" gives the number of milliseconds of imprecision for note starts and 
stops relative to the exact metronome [ default 0, usable range up to 20 or so ].
Adding a flag in the hundreds place selects some experimental options:
+000: blur every note, +100: don't blur first note in phrase, +200: positive blur
to melody notes only (leads chords), +300: negative blur (melody lags chords). 

  "TESTA" and "TESTB" are globally defined variables accessible from all 
source modules and used for experimental purposes. 

(046.10: TESTA is used to scale the delta_velocity for chord notes.
          default is 8 which gives 0 -11 -17 ... ; 
          0 results in no decrement (the previous behavior)       )

  "transpose_m" and "transpose_c" specify transposition of melody or chords by 
the given number of half steps [12 is up an octave, -12 is down an octave, 
7 is up a fifth, etc. ]

Harmony analysis, expanded syntax:
harmony [?] [details,nodetails] [log] [interactive] 
        [guitar] [#number#] 
        [restrict] [all,accented,bounding] [measure,half] 
        [center] [phrase,entire] 
guide to keywords
weights and preferences
example(old scheme)

One problem with traditional melodies is that they usually do not have 
any chords specified.  These harmony analysis tools attempt to provide 
some guidance in the assignment of chords (and achieve something like 
70 to 80% agreement with human selections), but the ultimate test is 
musical acceptability.

The key or mode of a piece, along with the actual notes determines which
chords are "best".  The key signature will indicate the major key,
but the tune may be in minor or in one of several modes (Dorian,
Mixolydian).  (This is usually indicated by the relation of the
final tone to the key signature.)  The command "harmony center"
guesses the tonal center by using a consonance/dissonance 
measure of intervals due to Malmberg (1918) [cf. Harry F. Olson,
"Music, Physics and Engineering", Dover, p.260]  Tests of the
"center" command suggest that it is most likely to pick the
dominant (fifth) note of the scale, although sometimes it gets 
the tonic.

As a result of collaboration with Matt Kaufmann, detailed rules
for chord preferences have been implemented. 

Our most successful chord selection heuristics have used both
a weighted sum of the durations of tones in a measure (to pick
the best match between possible chords) and a set of chord
preference scores to break ties.  A bewildering variety of
weighting schemes and preferences can be specifed (see below
for details), but the selections are surprisingly independent
of which particular weights and preferences are used.

The older chord analysis is based on two rules: the fraction of time 
the notes of the measure [or other time interval] spend on the notes 
of the chord, and whether the first and last notes of the "measure" are 
in the chord ("bounding" option,  thanks to Roy Wilhite).
Chords are ranked from best to worst matching.  Other heuristics
may be tried in the future (e.g. accented notes as suggested by
Chris Smith in "Celtic Back-Up for all Instrumentalists", Mel Bay, 1999).

----  KEYWORDS ----------------------------

Harmony keywords (options) may be abbreviated to a non-ambiguous short 
string (one letter for everything but "all" and "accented" or the prefix "no"); 
an ambiguous option (e.g. "a") will be flagged as an error and ignored.

The default settings correspond to:
harmony guitar nodetails nolog 15
Note that the number "15" is the analysis method, specifying the preference
schema (1x) and the tone weighting (5).  See weights and preferences below.

Most keywords set defaults for analysis, which need only be restated if you 
wish to change them. With the defaults as above, only the word "harmony" need 
be given as a command.

"harmony guitar nodetails nolog 15" can be abbreviated to "h g nod nol 15".  

"details" turns on a verbose mode for more output; "d d" will get even 
more details.  "?" prints out a list of the available options.  
"log" records the output to the active log file, if one was specified
when the program was started.

The prefix "no" will turn off an option.  "nodetails" turns off
verbose mode, "nolog" turns off logging, "noguitar" switches
to the older chord heuristics ("restrict, all, noaccented, bounding").

#number# designates an integer.  In "guitar" mode, the integer is
the sum of the chord class and the weight scheme; a negative number
modifies the summary chord printout. In "noguitar" mode, the integer gives
the number of ticks for the analysis (see "measure, half, #number#" below).

"guitar" mode accesses the newer algorithms, utilizing both a
preference heuristic and weight scheme as specified by a number.
    (See weights and preferences below.)
If ABC guitar chords are specfied, their scores are also given.
Both the full and half measures are scored, as seen in the example.  
If you desire to print only the best full measure chords
in the summary printout (e.g. in a waltz), you give the class+weight
method as negative (e.g. -15 instead of 15 above).

"all, accented, bounding" all control an older type of chord 
analysis invoked under the condition "noguitar".
"restrict" considers only 6 possible chords (1 5 4 6m 3m 2m) based
on the major key indicated by the key signature, "norestrict"
widens the scoring to all 24 possible major and minor chords.

"measure, half, #number#"  specify the number of notes used as a
complete measure, half a measure or a number of midi ticks.
The half measure scoring can be confused if a single note bridges
the boundary ( e.g. | AC2E | rather than |AC CE| or | AC-CE| ).

If no number is given, it uses measure delimiters.  Otherwise one specifies
the number of ticks to span (useful for half measures).  Will currently
[032.10] terminate at a bar or a guitar chord. 

"center" guesses at the tonal center, for the "entire" piece and
for the two parts (strains) A and B, assuming a standard AABB structure.
"phrase" is intended to give a shorter span, but is not implemented.

"interactive" allows detailed analysis of specific measures.
(one specifies individual measure numbers, and exits by giving 
a carriage return). 

"statistics" gives counts of the tonic-relative semitones and 
semitone intervals for all the notes in the piece.  It also prints
the weights for a C major chord and the chord preference scores for
the current option number.  For example, "harm stat 15" will give weights 
of type 5 for heuristic class 1x.

-------  WEIGHTS and PREFERENCES  -----------------------

Info on weighting schemes and chord preferences:

All notes are reduced to the 12 semitones of a single octave whose
durations are multiplied by weights which reward notes in a chord
and penalize nearby notes (e.g. those a half tone away).  For notes
in a major triad, the weights for the ten options 0, 1, ... , 9 are:

wtype do      re      mi  fa     sol      la      ti    (diatonic scale)

 2     1   0   0   0   1   0   0   1   0   0   0   0
 3     1  -1   0  -1   1  -1  -1   1  -1   0   0  -1
 4     4  -2   0  -2   2  -2  -2   2  -2   0   0  -1
 5     1  -1   0  -1   1   0  -1   1  -1   0   0   0
 6     1  -1   0  -1   1  -1  -1   1  -1   0   0  -0.5
 7     1  -1   0  -1   1   0  -1   1  -1   0   0   0

Scheme 2 has no penalties and is similar to the older "noguitar norestrict" 
option.  Schemes 3, 5, and 7 penalize tones a half tone away from the notes
in the chord. Scheme 5 does not penalize half tones (fa, ti) in the
scale determined by the key signature; scheme 7 determines the
scale relative to the root of the particular chord being considered. 
Schemes 4 and 6 are attempts to add additional weight to the root note 
of a chord, but are less successful than heuristic 5x below.

Heuristic classes of chord preference scores used to break ties
for equal raw scores from the weight sums (for a major mode):

class   1  5  4  6m  3m  2m  2  3  6  7*   (chord 1==I, 5==V, 6m==vi, etc.)
 0x     0  0  0  0   0   0   0  0  0  0
 1x     6  5  4  3   1   2   2  2  3  1
 2x     6  5  4  3   3   2   0  0  0  1
 3x     9  8  7  5   3   6   5  4  4  1
 4x     9  8  7  5   3   6   5  4  4  1   [see comments below on 4x]   
 5x     9  8  7  5   3   6   5  4  4  1
 6x     9  8  7  5   3   6   5  4  4  1

The scores will be modified for minor mode by switching 1<->6m etc.
(e.g.   1m 5m 4m 6  3    2   2m 3m 6m 7*
 3x     9  8  7  5  3    6   5  4  4  1    )

The x in the units place is to be replaced by the desired weight scheme.

Class 0x relies strictly on the weight sum and characteristically
has several chords (some of which are not key related) with the same
score (use " interactive d d" to see all 24 chord scores).
Class 1x is our first attempt at preferences and was similar to 
the older analysis, but extended beyond the six basic chords in a
key (1 5 4 6m 3m 2m).  Class 2x attempts to do a better job with
various modes (minor, dorian, mixolydian).  Classes 3x through 6x 
include more nonstandard chords with lower scores.  The scores
in 4x are modified by the tonal content of the measure, but
have not proved very useful.  Class 5x looks for the tone of longest 
duration in a measure and considers that for root of the chord to 
select if the chord otherwise has a high weighted duration sum.
Class 6x uses a "jump heuristic" suggested by Lee Couch.  Both 5x 
and 6x are still under evaluation.
* The treatment of seventh chords is incomplete and partly incorrect.

In my experience, options 15, 25, 35, 22 all work reasonably
well, along with 55 for checking root preferences.

----  Example, Guitar chords compared with full and half measure assignments -----

Here is an example with the first 8 measures from Petronella, with full measure
chords found in a previous analyis (harm all bound) supplied as "guitar chords".

Eight bars from the melody in ABC (supplied guitar chords are given within 
double quotes):

    |: "G"B2dB A2dB  | "G"G2G2G2 B,D  | "C"G2CE A2G2  |   "D"FAGE D2gd  |
       "G"B2dB A2dB  | "G"G2G2G2 B,D  | "C"G2Ce A2F2  |[1 "G"G2G2 G2gd :|
Part of the result from "harmony detail detail 15"

 1.    G   186  |  G   126  D    95 ..  + G      186 126
 2.    G   246  |  G   126  G   126 ..    G      246 126
 3.    C   184  |  C   124  G    66 ..  * C      184 124
 4-    G   156  |  D    65  G   126 ..  + D      155  65
 5.    G   186  |  G   126  D    95 ..  + G      186 126
 6.    G   246  |  G   126  G   126 ..    G      246 126
 7-    D   125  |  C   124  D   125 ..  + C      124 124
 8.    G   246  |  G   126  G   126 ..    G      246 126

Format: measure number, flag1, flag2, full measure chord and score "|"
        half measure chords and scores ".." flag3, guitar chords,
        guitar chord scores (full, half_1, half_2)
             ( half_2 appears if two guitar chords are supplied in one measure)

The scores are the sum of the chord weighted duration (ChWtTi) and the key/mode
dependent preferences (Pref) noted above.  Petronella is in the key of G,
and with the default 120 MIDI ticks per quarter note, each 1/16 note
has 30 ticks, for 240 ticks in a measure.  Consider measure 4  ("D"FAGE D2gd ).
The notes are reduced to a standard octave, giving the following durations for 
each semitone:

        fa     sol      la      ti  do      re      mi
         C       D       E      ^F   G       A       B
         0   0  90   0  30   0  30  60   0  30   0   0

The weights (given above in scheme 5 for a C chord) are rotated for different
chord roots. Note that the adjacent half note penalty is 0 for notes in the G 
scale.  The chord preference score for class 1x is given on the right.
  G      0  -1   1  -1   0   0   0   1  -1   0  -1   1         6
  D      0  -1   1  -1   0  -1   1   0  -1   1  -1   0         5
  C      1  -1   0  -1   1  -1   0   1  -1   0   0   0         4

Multiplying the durations by the weights and summing gives these ChWtTi's
for G (150), D(150), and C(90).  It is only the added preference which
distinguishes the scores for G (156) and D (155).  Thus method 15 selects
the tonic chord G over the dominant D for the full measure, whereas 
method 55 would prefer D because the duration of D (90) is greater than
that of G (60). Repeating this analysis for the half measures (FAGE and D2gd)
says that using different chords for each half measure (D G) gives a higher
ChWtTi sum (180) than the ChWtTi for G in the full measure.

    A distinction is made between the printed "score" == ChWtTi + Pref 
    and the ChWtTi which does not depend on the preference.  The ChWtTi is a 
    weighted sum of the durations of the notes which appear in the chord 
    and penalties for notes only a half step away.  The chord preference
    is a tie-breaking increment based on the key so that chords are
    chosen in the order tonic(1), dominant(5), subdominant(4), ...
    if they have the same ChWtTi. 

 flag1:  "."    full or half measure assignments agree with those for supplied chords
              If one guitar chord was supplied:
         "-"    ChWtTi's same for assigned and supplied chords
         ">"   ChWtTi for assigned chord > (at least not == ) that for supplied chord
              If two guitar chords were supplied:
         "~"   ChWtTi same, preference weighting makes choice different
         "#"   more complicated differences
 flag2:  " "   all notes in measure are in designated key
         "@"   one or more notes are accidentals.

Thus the measures with flag1 other than "." are of specific interest.
 flag3:  " "   both half measure assignments identical to full measure assignment
         "u"   half measure assignments not identical, 
                   (sum of half measure ChWtTi <= full measure ChWtTi )
         "+"   sum of half measure ChWtTi > full measure ChWtTi 
                  (indicating that this measure may do better with two chords)
Some summary statistics on how well the assigned chords agree with the supplied chords

28 match,  18 identical,   0 ambiguous,  15 method

For the full 32 measures of Petronella, 28 of them had either the same assigned
chord as the supplied guitar chord, or at least one of the two half measure
"improved" assignments agreed with the guitar chord.  In 18 measures, the
half measure assignments were identical to the full measure. "Ambiguous"
counts the number of instances for which there is another chord with the
same total score as the assigned chord.  This arises most often when
chord preference increment is small or zero, and can be investigated by 
using the interactive option to see all the chord scores for specific measures.
Ambiguous chords will be flagged with an "=" following the chord score
with "detail" or "detail detail" verbosity.

Predicted chords for all measures (GD means G and D played for a half measure each)

  GD    G     C     DG    GD    G     CD    G
  GD    G     C     DG    GD    G     CD    G
  G    AmD    D     G     G    AmD    D     G
  G    AmD    D     G     G    AmD    D     G
A command with option 0 will print the supplied guitar chords;
harmony norestrict guitar 0

Guitar chords
key:  G 7  center  G 7
  G     G     C     D     G     G     C     G
  G     G     C     D     G     G     C     G
  G    Am     D     G     G    Am     D     G
  G    Am     D     G     G    Am     D     G
Note on detail levels:  "nodetail" just gives the
short 4 line 32 chord summaries.  "detail" also prints the
measure lines for which flag1 is not ".". "d d" prints
information for all measures, one line per measure as above.

The half measure scoring can be confused if a single note bridges
the boundary ( e.g. | AC2E | rather than |AC CE| or | AC-CE| ).
This can happen in waltzes (where a half measure analysis probably 
shouldn't be used anyhow) or in the final measure of a phrase
where lead-in notes to the next phrase may diverge from the cadence.

--------Example, original method ----------------
(This is included for historical reference and may require 
 reading the code for full understanding. )

The older [August 2003] default settings correspond to:
harmony all bounding measure restrict noguitar nocenter nodetails nolog
which prints the "best" chord for each measure based on all notes 
(and the first and last notes used as a tie breaker).  Except for the 
"bounding" test, this is roughly equivalent to method 12 above.

Any guitar chords supplied in the ABC will appear at the end of the 
line in brackets. The terse [nodetail] option gives the score for the 
top two chords and the ranking for six chords (i j t u v w,  a single
letter code for the usual notation I II III IV V VI: i u v are
the major tonic, subdominant and dominant chords, while w j t
are the related minor tonic, subdominant and dominant chords).
The detail option gives the total durations of the the relative
semitones [do di re ri mi ... ti] in the analysis interval and a 
second line gives the scores for all six chords along with 
the best chord and any guitar chords in brackets [].

example, key of A major, default note length 1/16 [30 ticks]

 measure 3: |       c2B2B2 cB |
 measure 4: |  "A7" AGAB A2CD |

terse [nodetail] output:

 measure   3 [ 1501  1501]    v j i w t u   E
 measure   4 [ 1503  1502]    u i w j v t   D [A7]

[ 1501, etc. is obscure -- Rosie; 
  SMS: maybe I should junk "iuvwjt" notation and old method, or revise output]

detailed output:

    0   0 150   0  90   0   0   0   0   0   0   0  measure 3 duration 240
 i   90 2, u    0 0, v  150 1, w   90 2, j  150 1, t   90 2, v j i w t u   E
  120   0  30   0  30  30   0   0   0   0   0  30  measure 4 duration 240
 i  150 2, u  150 3, v   60 0, w  150 2, j   60 1, t   60 0, u i w j v t   D [A7]

The sequence "i  150 2" means that for the tonic chord (A), the sum of the
durations is 150 and the bounding score is 2; this is less than the bounding
score of 3 for "u  150 3".  The bounding score is 2 if the first note of the
measure is in the chord, 1 if the last note is included, and 3 if both are.

Loop oriented experiments:
  (A separate command container with options to investigate MIDI behavior.) 
[ ---- this section needs more work ---- ]

The "loops" command is useful for studying the characteristics of the 
MIDI commands and options, such as playing a short tune on all possible 
instruments, or at many different volume (velocity) levels.  

Presently loop options are single letters only.  The basically line oriented 
loop options are bracketed in a container "loops" .... "/loops":
%  a simple loop example to play the tune in r,t,v for instruments i
i ...    % instrument (list or "for-loop")
r ...    % rhythm  (duration of tones in ticks)
t ...    % MIDI numeric tones
v ...    % numeric velocites
g        % generate
%          currently the r and t lines must have the same number of elements

 @loops_file      % given as an indirect file

More details about input options between ("loops ... /loops"):

? help:   print this list
# comment: gives text which goes to output file
% comment: ignore text to end of line (abc convention)
r rhythm (sequence of note lengths in MIDI ticks)
t tone (MIDI note is this value + key base)
v velocity/volume for r/t sequence (add 2000 or 1000 for accent)
  numbers are a space separated list e.g.  12 20 1 3
          or 'for' parameters: '=' start end incr
i instruments (1-128 are general MIDI, 135-181 map to 35-81 in the drum bank)
a accent used if velocity has +2000, +1000
g [file]:  generate MIDI file
p play [current]/n/sequence
k key: base notes [default 0] added to tune values
o order of looping [default: r l a i ]
l loop repetitions [lid] [default: 1]
c (MIDI) code_insert: lid c1 c2 ... cn (unimplemented)
d dump lists (unimplemented)

Numbers for i,r,t,v,a,k,l can be given as a blank separated list
(e.g.  1 3 2 6) , or as a for-loop designator (e.g. = 0 6 2 which
translates to (for j=0; j<6; j += 2)  ). 

Sample "loops" input:
# play C E G  c  on piano, fiddle
# observe that some notes have velocity 0 and do not sound
i 1 111   % piano, fiddle
r 120 120 120 120 120 120 120 120 360
t  60  62  64  65  67  69  71  72  60
v  90   0  90   0  90   0   0  90   0
g  loop.midi
# play C E G on  every fourth instrument
o  r i     % change nesting of loops
i =1 127 4
r 120 120 120 120 120 120 120
t  60  62  64  65  67  69  71
v  90   0  90   0  90   0   0
g  instrum.midi
# play one note on each drum: 35 thru 81
  i =135 181 1
r 120 120
t  60  62
v  90   0
g  drums.midi
quit   %  with esound daemon, all three files play at once


TIPS on using TiMidity++ (tested on versions 2.10, 2.11.3)

    It turns out that the exact choice of velocity levels depends on the
transformation of velocity to volume used by the MIDI player.  Versions of
TiMidity before 13.0 used a linear table (I had supposed it to be logarithmic)
and implicitly a linear table for chorus voices.  As of June 6, 2004,
the chorus routines in playmidi.c were not correct in 2.13.0 either 
(bug report submitted).

I am using a personally corrected version 2.11.3 to produce my second demo CD.

Useful command line options:  (see timidity man page for fuller discussion)

-A volume          percent change of volume level  <=800, >= 0

-T tempo           percent change of tempo  ( <100 slower, >100 faster)

-I n-1             change program to MIDI instrument n 
                   (where instrument 0 was specified in vamp.  
                    format changes in version 2.13.0)

-c file.cfg        additional patch/soundfont configuration information
                   (supercedes contents of /etc/timidity.cfg  or 
                                      /usr/local/share/timidity/timidity.cfg )

-idv,-idvv,-idvvv  debug printout at variable verbosity
-s rate            samples per second (set to 44100 for making CD's)

-Ow -o wav.out     make .wav output file  (default stereo)

-OwM -o file       monophonic output (smaller file, works with play, scope)

-EFchorus=0        turns off chorus effect (makes 2-13.0 logarithmic)

--------------------------------------( cf vamp folder 029.13-4reverse)
Making .wav files with timidity:
timidity -A 200 -s 44100 -Ow -o out.wav in.midi
-A (amplitude 0 - 800 % ) 200 == x2.0
-s 44100   44k1 samples/second 
          (stereo is default, gets CD wav file immediately)
          [order of this option may not be correct]
-Ow  [ make Microsoft RIFF .wav file output ]
-o  out.wav   [specify output file]
- - - - - -
sox in.wav -r 44100 out.wav
convert in.wav to 44100 samples/sec for standard CD tracks.
Recipe to circumvent esound default on havasu (works on sbigraf)

timidity [-A 200] -B 8,12 -Od -s 48000  file.midi
-Od uses /dev/dsp rather than esd.. (see timidity -h, not on man page)
-B 8,12 to forstall crash with float overflow/exception on havasu
-s 48000  default is 32000 which causes warning on havasu
will put this in midivamp for spawn.
consider using ogg-vorbis for compression [ogg123, oggenc] 
since mp3 is proprietary.



I am grateful to a number of musicians who have tolerated "dumb"
questions and educated me while I developed this program.
Among them are Matt Kaufmann, Ann Winget, Lee Couch, Roy Wilhite,
Max Cappleman, Susan Barnes, and Carrie Eskenazi.  I also appreciate
the feedback from people who have listened to various versions of
the tunes generated by the program, especially Rosemarie Swanson.


    Copyright 2002-2004, Stanley M. Swanson.
      12 Sept. 2002; revised 24 Dec. 2002, 10 Feb. 2003, 17 May 2003,
                     31 July 2003, 8 Aug 2003, 1 Mar. 2004, 17 Apr. 2004,
		     10 May 2004, 10 June 2004, 14 July 2004

    This information is distributed under the terms of the 
    GNU Free Documentation License (with no invariant sections and no
    cover requirements).  The accompanying program, VAMP,
    is distributed under the terms of the GNU General Public License,
    version 2 or later (GPL v2).
    NO WARANTEES are made for either the documentation or the software.
    For the full text of the licenses, refer to the Free Software Foundation,
     GNU licenses