PLAY

     By Kelly Roach.  Last revised 5-Feb-84.  Comments & bugs can be
sent to ROACH.PA.
     INTRODUCTION.  The PLAY package, inspired by the Mesa PLAY
package, offers Interlisp-D users a disciplined way to play simple
musical melodies on Xerox 1108 machines.  To use, load
<LISPUSERS>PLAY.DCOM.  Typing (PLAY.DEMO) will demo the PLAY package
to the user.  The main entry points to this package are functions
	(PLAY.NOTES NOTES) and
	(PLAY.MELODY MELODY).
Both these functions take a musical representation, a series of NOTEs
or a MELODY, into a TUNE playable by Interlisp-D's PLAYTUNE function.
To get some feel for this, a sample call to PLAY.NOTES might be
	(PLAY.NOTES '(b b >c >d >d >c b a g g a b b a+ a b b >c >d >d
			>c b a g g a b a g+ g a a b g a B/ >c/ b g a
			B/ >c/ b a g a dx b b >c >d >c b a g g a b a
			g+ g))
and the PLAY package's global DEMO.MELODY is the sort of argument
taken by PLAY.MELODY.  Function
	(PLAY.KEYBOARD)
is a way to catch up on your piano practice.  We now proceed to the
details.  We first discuss the particulars of NOTEs and MELODYs, then
describe the PLAY package functions which can be used with these
objects.


				NOTES.

     A NOTE is a litatom whose pname characters are interpreted as
follows:
	(1) KEY.  "A", "B", "C", "D", "E", "F", "a", "b", "c", "d",
"e", or "f" specifies the note's key.  If the note's key is in upper
case, the note is held for its full duration with no break (a tied or
slurred note).  Most notes are followed by a break and so are in lower
case.  Two additional keys, "R" and "r" play silently and are used as
rests.
	(2) OCTAVE.  Each ">" raises the note an octave.  Each "<"
lowers the note an octave.  Thus, Middle C, High C, and Low C are
represented as C, >C, and <C.  Each octave begins with key C and ends
with key B (those are the rules!).  A schematic of the great staff:
	*---------------- >F
	*                 >E
	*---------------- >D
	*                 >C
	*---------------- B
	*                 A
	*---------------- G
	*                 F
	*---------------- E
	*                 D
	*                 C
	*                 <B
	*---------------- <A
	*                 <G
	*---------------- <F
	*                 <E
	*---------------- <D
	*                 <C
	*---------------- <<B
	*                 <<A
	*---------------- <<G
	(3) ACCIDENTALS.  Each "#" (sharp) raises the note a
semitone.  Each "@" (flat) lowers the note a semitone.  In MELODYs,
"n" (natural) may also be used, (described further below).
Accidentals only affect the note to which they are attached (I.e.,
they do not spread to other notes in a measure etc. as they do in
normal sheet music.  You must explicitly put them where they are
needed.  MELODY KEY's described below can be used to avoid most of the
pain).
	(4) DURATION.  A note starts out as a quarter note.  Each "/"
halves the note's duration.  Each "x" doubles the note's duration.
Thus: "xx" = full, "x" = half, "" = quarter, "/" = eighth, "//" =
sixteenth, etc.
	(5) ARTIFICIAL DIVISION.  Digits "2", "3", "4", "5", "6", "7",
"8", and "9" are used for artificial division: duplets, triplets,
quadruplets, etc.  When digit N occurs, the duration of the note is
multiplied by the factor
	(FQUOTIENT (FDIFFERENCE N 1.0) N)
Thus, the 2nd through 4th notes of the notes (C D3 E3 F3 G) can be
viewed as a triplet.
	(6) DOTS.  One "+" will extend the length of the note by 50%.
Two "+"'s will extend the length of the note by 75%.  And in general,
N "+"'s will extend the length of the note by the factor
	(FQUOTIENT (FTIMES (FPLUS 1.0 (EXPT 2.0 (ADD1 N))))
		   (EXPT 2.0 N))
You probably will never use more than two "+"'s.
	(6) BREAK.  Each "^" causes the duration of the note's break
to double (a staccato note).  Each "_" causes the duration of the
note's break to halve.


				MELODYS

     Knowing the details of NOTEs is enough to allow you to use the
PLAY package's relatively primitive PLAY.NOTES function effectively.
More serious composition, such as playing melodies found in sheet
music, is made facile through the use of MELODYs and function
PLAY.MELODY.
     A melody is an instance of the record type
	(TYPERECORD MELODY (TEMPO KEY METER BEAT PASSAGES))
Field PASSAGES of a MELODY is a list of PASSAGEs which are instances
of the record type
	(RECORD PASSAGE (REPEATS MEASURES))
The fields of these two record declarations are explained as follows:
	(1) TEMPO of a MELODY is the speed with which the melody is
played.  TEMPO can be any of the litatoms ALLEGRO, FAST, MODERATO,
MODERATE, ADAGIO, or SLOW, or can be a positive integer specifying the
number of beats per minute for the melody.  (ALLEGRO=FAST=120,
MODERATO=MODERATE=90, and ADAFIO=SLOW=60 beats per minute).  The TEMPO
for most melodies is MODERATE.
	(2) KEY of a MELODY is the melody's key signature. KEY can be
any of the litatoms CMAJOR, GMAJOR, DMAJOR, AMAJOR, EMAJOR, BMAJOR,
F#MAJOR, C#MAJOR, FMAJOR, B@MAJOR, E@MAJOR, A@MAJOR, D@MAJOR, G@MAJOR,
or C@MAJOR.  Or KEY can be a list whose CAR is either of # or @ and
whose CDR's elements are drawn from the list (C D E F G A B).  The KEY
of a MELODY determines which notes in the melody are automatically
played sharp or flat.  Accidentals occuring on a note cancel any
effect KEY would have had on that note.  Accidental "n" (natural) is
used to just cancel the KEY's effect.
	(3) METER of a MELODY is the number of beats per measure for
the melody, the numerator of the time signature you will find in sheet
music (e.g. 3 in 3/4 time).  METER isn't used much for anything right
now by the PLAY package, but could be used later on as a check that
the duration for each of your measures is correct.  Usually METER is
4.
	(4) BEAT of a MELODY is the kind of note being used as the
beat for the melody, the denominator of a time signature.  A BEAT = 4,
8, or 16 corresponds to quarter, eighth, or sixteenth notes.  Usually
BEAT is 4.
	(5) PASSAGES of a MELODY is a list of PASSAGEs.  Each passage
in a melody contains fiedls REPEATS and MEASURES.  If MAXREPEAT is the
maximum repeat number occurring in the REPEATS fields of a melody's
passages, then MAXREPEAT passes will be made over the melody.
	(6) REPEATS of a PASSAGE is a list of positive integers
indicating on which passes through the melody this passage will be
played.  If positive integer I occurs in REPEATS, then the passage
will be played on pass I.
	(7) MEASURES of a PASSAGE is a list of measures.  Each measure
is a list of notes.  In sheet music, measures are delimited be
vertical lines.  If you organize your notes into the same measures you
find in your sheet music, you'll probably have an easier time at
trying to edit your melody later on when you need to compare the
melody against the sheet music.



			PLAY FUNCTIONS

     The patient reader is now in a position to use the functions the
PLAY package has to offer.  The following functions are made available
to the user:
	(1) (PLAY.NOTES NOTES) converts a list of NOTEs into a TUNE
which can be played by PLAYTUNE.
	(2) (PLAY.MELODY MELODY) converts a MELODY into a TUNE which
can be played by PLAYTUNE.
	(3) (PLAY.KEYBOARD) converts the user's keyboard into a
primitive piano.  The row of keys "ASDFGHJKL;'_" are played as
<A, <B, C, D, E, F, G, A, B, >C, >D, and >E.  Sharp keys can be found
on the row above.  Hitting the space bar causes PLAY.KEYBOARD to
return the TUNE you played, which can be played by PLAYTUNE.
	(4) (PLAY.TRANSCRIBE TUNE) can transcribe a TUNE produced by
PLAY.KEYBOARD.  (Duration information is just thrown away since there
does not seem to be a satisfactory way of getting it right).
	(5) (PLAY.ADJUST.TEMPO TUNE FACTOR) can be used to adjust the
speed of a TUNE.  TUNE's speed will be uniformly increased by FACTOR.
	(6) (PLAY.ADJUST.PITCH TUNE SEMITONES) can be used to adjust
the pitch of a TUNE.  TUNE's pitch will be uniformly increased
SEMITONES semitones.
	(7) (PLAY.MESA STRING) converts a Mesa PLAY package string
into a list of NOTEs that can be played by PLAY.NOTES.
	(8) (PLAY.DEMO) demos the PLAY package.