PDP-10.its/doc/decus/mblurb.txt

		PDP-10 Music System Introduction
		--------------------------------

	This package of programs and hardware information
makes up the PDP-10 music-compiling and -playing system.

	This system is the result of a long evolution stemming
from a similar system developed on the PDP-1 computer at MIT.
The present system is language-compatible with the PDP-1
system. A (nearly) source-compatible system exists on the 940
computer at B.B.&N., Cambridge, Massachusetts.

	The original specifications, and the implementations
on the PDP-1, and the non-time-sharing PDP-6, are the work of
Peter R. Samson, now at Project MAC, MIT, Cambridge, Mass.

This initial DECUS submission includes: a timesharing version
of the music compiler ("MCOMP"); the PDP6/10 player (which must
run in Executive Mode); documentation for the software and the
hardware; and a small library of music sources transcribed for
the compiler.

	Users are encouraged to add selections to this library,
and DECUS has graciously consented to act as librarian for
such sources.

	More music is available for this system, and will be
added at sporadic intervals.

	I apologize for the delay in submitting this set of
information to DECUS, as I had promised a number of users I
would. We at DEC have had a setback in the Music Project, in
that our HiFi amplifier was stolen some time ago. We will
press on with the music library when possible.

					Robert C. Clements
					PDP-10 Programming

	Music Compiler Specifications

I.A.1.	The first task when preparing a score for the compiler
is to arrange the music in a number of distinct lines
(otherwise called "parts" or "voices"), fitting the
restriction that each part may play only one note at a time.
The compiler will process selections taking from one to eight
parts; the present version of the player will play up to six
parts. The complete specifications for a single part constitute
a "logical tape". The sequence of all parts in a piece make up
the input file for the compiler.

I.A.2.	For each voice, one must supply: (1) a title,
which is all information on the logical tape through the first
slash ("/"); (2) the clef, and the key and time signatures;
(3) a tempo (which needs to occur in only one of the parts);
(4) one or more full measures of music; (5) the command "END"
to terminate the logical tape.



I.B.	Each and every note in a musical score conveys two
pieces of information: (A) Its pitch, indicated by its position
on the staff; (B) Its duration, signified by the form of the
note symbol. Both of these data must be supplied to the
compiler for each note [TFF]. *

-----------------------------

* TFF (too few fields) is an error message produced by the
compiler if this rule is violated. Error messages appear in
square brackets ("[ ]") throughout this specification, and are
summarized in an appendix.

-----------------------------

I.B.1.A.	Pitch
The pitch of a note may be indicated to the compiler by a
number representing the position on the staff which the note
occupies: The correspondence between position and pitch
number is shown in figure 1. The lowest possible pitch number
is 0; the number may be as high as necessary to account for
leger lines above the staff. Notes which appear on
lines are represented by odd numbers; notes appearing in spaces
are represented by even numbers.

I.B.1.B.	Duration
The duration of a note (or rest, section I.B.2) can be specified
by a number, as demonstrated by figure 2. No duration number
may be used except the seven listed in the figure [ERT].

I.B.1.C.	Notes are specified by two numbers: A pitch number
and a duration number conjoined form a note. The two numbers
must be in the order "Pitch--Duration". To distinguish the two
numbers, they must be separated by one or more non-numeric
characters (other than spaces). In the following sections, 
many such characters will be described, with their particular uses.
If no such character is needed for a particular note, the character
"T" is specifically reserved to separate the two numbers. "T" may
be considered an abbreviation for "tone".
Figure 3 shows some notes and their compiler representations
as formed in this manner.

Hereafter, it will be stated that certain characters may be
placed "anywhere" within a note. Actually, of course, they
may not be placed between the digits of a number. They may be
used to separate the two numbers of a note.
I.B.2.	Rests
A rest may be expressed by the letter "R" and a duration number.
The number and the "R" may be put in either order, but practice
has favored putting the duration number after the "R". A pitch
number may not occur in the same note as an "R" [TMF]. A note
should not contain more than one "R" [TMR]. Examples are in
figure 4.

I.B.3.	Comma
A comma may be used alone as a note, meaning to copy the
previous note exactly. The first note in a part may not contain
a comma, as there is then no "previous note" [UNC]. The comma
may also be used with a pitch number or an "R" to form a note;
in this case, the comma means to copy only the duration number
from the previous note. The comma and the pitch number may come
in either order; in practice, the comma generally follows the
pitch number. There should never be more than one comma in
a note [TMC], and there should never be a duration number in
the same note as a comma [TMF]. Figure 5 demonstrates the use
of the comma.

I.B.4.A.	Dotted notes
Often one or more dots occur directly after a note in a score,
indicating that the duration of the note is to be lengthened.
This notation is carried over into the compiler, using
the character "." (period). Each dot adds an amount to the duration:
The first dot in a note adds one-half the duration of the note;
each succeeding dot adds half the duration of the dot before
it. A dot whose duration is less than that of a sixty-fourth
note is ignored [DTU]. It is occasionally convenient to
add a smaller fraction than half the note's duration.
To allow this, the compiler interprets the letter "X" to
mean "halve the value of the dot". Periods and "X"'s may be used
anywhere in a note, and need not be contiguous. Their order
is significant only among themselves. Either character will
suffice to separate the pitch number from the duration number.
The period may not occur in the same note as a comma [TIC].
Figure 6 shows some dotted notes and their translations for
the compiler.


I.B.4.B.	Triplets
Sometimes a group of three notes is to be played in the time
intended for two; musical notation indicates this by the numeral
"3" above the notes, directing that each note be played for
two-thirds its usual duration. This is indicated to the compiler
by including the letter "C" anywhere within each note so
affected. Dots and "X"'s may also be included. It is not
necessary to the compiler that the notes making up a triplet
actually be adjacent notes. A comma in a following note will
copy the "C" only if the note in which the "C" occurs does
not itself contain a comma. (A note with a comma may contain a
"C".) For instances of the use of "C", see figure 7.

I.B.5.A.	Tone relocation
Occasional notes will be found which are either above or below
the staff. The compiler assumes staves to exist above and below
the staff in use, as per figure 8. To refer an individual note
to either adjoining staff, include the letter "A" (above) or
"B" (below) anywhere in the note. These letters may occur
more than once in a note, and their effect is cumulative:
for example, "AA" refers to the second staff above the current
one. The highest pitch available in the compiler is the treble
clef's "A1"; the lowest is the bass clef's "B2" [UAT][AOR][EOR].



I.B.5.B	Accidentals
Accidental signs, and the characters to represent them to
the compiler are shown in figure 9. The appropriate characters
may appear anywhere in the note they affect. An accidental
appearing on a rest is ignored [AIR]. If "=" appears in the
same note with "+" or "-", the "=" takes precedence [NOR].
The character "(" is equivalent to "+", and the character ")"
is equivalent to "="; these exist for historical reasons,
having to do with the FIO-DEC code of the PDP-1.

I.B.6	Articulation
Two notes played in succession are separated and made distinct
to the ear by articulation, which is the effect of a short
duration of silence between them. The duration of the preceding
note is shortened by the period of the silence. The articulation
following a note can be expressed to the compiler by including
an identifying letter anywhere in the note: the five letters
available are explained in the following table.


     LETTER  NAME    DURATION  DURATION     USED FOR
			of	  of
		       NOTE    ARTICULATION

	L    Legato	1	0	Slurs, Legato notes

	E    Eigth	7/8	1/8	Notes not specially marked

	H    Half	1/2	1/2	Staccato for Organ works

	Q    Quarter	3/4	1/4	Alternative to "E"

	S    Staccato	@3/8	@5/8	Alternative to "H"


The articulation of notes not containing "E", "H", "S", "L",
or "Q" is explained in section I.D.5. The effect of these
letters in a note is not copied by a comma in a subsequent
note. If more than one of these letters should appear in a
note, the last one will prevail [TMS]. A slur is expressed to
the compiler by making legato all notes in the slur except
the last. A few examples are shown in figure 10.



I.B.7.	Embellishments
Various embellishment signs may appear on a note in a piece
of music, indicating that the note is to be performed more
elaborately than written. In figure 11 are (A) the symbols
appearing in a score (as used by C.P.E.Bach in his "Essay on
the True Art of Playing Keyboard Instruments"); (B) the letter
used to signify that embellishment to the compiler; (C) the
patterns compiled; and (D) the shortest note on which the
compiler will perform that embellishment [EIT].
If more than one embellishment is chosen for one note, the last
one will be taken [TME]. Embellishments may not be called for
on triplet notes [ETR]. Comma does not copy embellishments. An
embellishment will be illegal if any note it generates is out
of range [EOR].

I.B.8.	Grace notes
A grace note (appogiatura) steals its playing time from the
first non-grace note to follow: such a following note must
have sufficient remaining time to sound itself as well [ITG].
A duration may be specified in a grace note, either by a number
or by the comma. If a duration is not specified, a thirty-
second note will be compiled. The letter "G" anywhere in a
note marks it as a grace note. Only one "G" should be used
in a note [TMG].



I.C.	Bars
In a score, the measures are separated by a bar; for the
compiler, the bar is represented by the slash ("/").

I.C.1.	Bar labels
The compiler assigns successive numbers (1,2,3,...) to the
successive measures of the music. If a number appears alone
(i.e., not as a part of the title or a note), it is checked
against the current measure's count [BBL]. It is wise to use
such bar labels frequently; they warn of missing or
duplicated measures, and also serve to identify the measures
in which they appear.

I.C.2	Measure length
When the compiler encounters a slash, it adds up the duration
of all notes since the last slash, and checks the total
duration against the expected length of the measure [MTS][MTL].

I.D.	Commands (pseudo-operations)
Certain instructions must be issued to the compiler on an infrequent
basis. This is accomplished by including in the compiler's 
input certain special words called commands. Some commands
are supplied simply to make the compiler input more compact
or easier to prepare.

I.D.1.	END
The command "END" signifies the end of a voice (or
logical tape) of music. When this command appears, followed by
a space, tab, or carriage return, the compiler completes the
compilation of the current voice, and prepares for the next one.

I.D.2.	UNITS
The total duration of a measure should be stated to the compiler
before any notes or rests occur. To do this, the command "UNITS"
should appear, followed immediately by a number indicating the
number of thirty-second notes which would make a full measure.
This number may be computed by considering the time-signature
as a fraction, and multiplying it by 32. E.g., "waltz-time"
as a fraction is 3/4. 3/4 * 32 = 24. The command "UNITS 24" would
specify this time. The "UNITS" command may occur anywhere
in the text, and takes effect immediately, referring to the
measure where it occurs, and to all following measures until
another "UNITS" command supercedes it.

I.D.3	CLEFS
Prior to the appearance of any notes in the text, the compiler
must be informed of the clef which heads the current staff. There
are four commands, representing the four clefs shown in figure
12. A clef command may occur anywhere in the text, in order
to follow changes of clef in the music, or simply for convenience
where a long run of notes is above or below the current staff.



I.D.4.	Key signature
At the beginning of the music, the key signature should be
stated. In the text, this is done by the use of the command "KEY"
followed by: "=" meaning no sharps or flats; "+" meaning sharps; or
"-" meaning flats. In the case of sharps or flats, the symbol should
immediately be followed by a number, which tells how many sharps
or flats are in the key signature. Samples appear in figure 13.

I.D.5.	Articulation commands
One often encounters a run of several notes which have the same
degree of articulation. To facilitate expressing this to the
compiler, one may use the single articulation letters "S", "L",
"H", "Q", and "E" alone as commands, selecting this degree
of articulation for all succeeding notes which do not themselves
contain any letter "S", "L", "H", "Q", or "E", with the
exception of any note which immediately precedes a rest in the
same measure; such a note is automatically made legato unless
it contains an articulation letter. The articulation commands
may occur anywhere in the text. At the beginning of each part,
the compiler is in "E" articulation. Figure 14 demonstrates
some articulation commands.

I.D.6.	REST
A given voice may be silent for one or more measures. This
may be expressed to the compiler by the command "REST" followed
by the number of inactive measures. (They will all be given
the current measure length.) The rest command may not be used
when notes have already been written in the current measure [ILR].
The rest command should not be followed by a slash. The
"REST" may be thought of as creating measures of rests, complete
with slashes.


I.D.7.	COPY
One or more measures may be identical to measures that have
gone before.It is advised in this case to use the command
"COPY" to duplicate previously written measures. "COPY" must be
followed by two numbers: The number of the first measure to
copy, and the number of the last measure to be copied. The 
first number must be lower than the present measure [BLC], and
the second number must be greater than or equal to the first
[BRC]. The second number may be higher than the current measure;
in this case some measure(s) will be copied more than once.
Like "REST", "COPY" may not be used when some notes are already
written in the current measure [ILC]. "COPY" should not be 
followed by a slash. It may be thought of as copying the measures
complete with the terminating slash. The measures are copied
exactly; they are not modified by a change in the meaning of
the comma, or by a change in the mode of articulation, or
clef or measure length; nor do they change any of these for
non-copied measures to follow. The copied measures will be
performed at the current tempo, however, if that has been changed.

I.D.8.	Transposition
The compiler is able to transpose music, via the commands "UP"
and "DOWN". A number follows the transposition command to specify
the number of semitones that the compiled music will be above
or below the music as written in the text. These commands may
appear anywhere in the text, and they take effect immediately.
To restore the compiler to no transposition, say "UP 0" or
"DOWN 0". The compiler starts each part at zero transposition.

I.D.9.	Tempo
The tempo of a piece may be expressed to the compiler by
the command "TEMPO", followed by a number computed as follows:

	N=1126/(m*f)

where "m" is Maelzel's metronome count for a "f" note. *
I.e., if a quarter note = 60, then "m" =60 and "f"= 1/4.
The number "N" may not be larger than 682 [TS].
The tempo may be changed at any point in the music. It will be
taken to be 170 if no "TEMPO" command is given. A "TEMPO" command
appearing in any one voice will apply to all voices; hence only
one voice need contain the tempo information.

-----------------------------
* This number was computed for the PDP-1 computer. In general,
since various configurations of PDP-6 and PDP-10 run at different
speeds, the "TEMPO" command should be considered as a relative
speed setting, which will need to be adjusted when the music
is played.
-----------------------------
I.E.		Format
The timesharing version of the compiler expects the text
of the music to be compiled as an ASCII file from any of the
usual input devices. Alphabetic characters may appear as
either upper or lower case; lower case is converted to
upper case as the file is read. In general, the text will have
been prepared by an editing program, such as TECO.

I.E.1.
The characters "space", "tab", and "carriage-return/line-
feed" are treated identically by the compiler. Two or more
of these characters are treated the same as just one. These
facts allow great flexibility in the appearance of the printed
text, but it is worthwhile to follow a format which is somewhat
more strict than necessary. One such format, which has proven
satisfactory, is the following:

	A) The title is as long as necessary (using any number
		of lines) and is ended by a slash.

	B) After the title, the CLEF, TIME, KEY and TEMPO
		are specified, in any order.

	C) Each line of the input represents one measure:
		The measure number appears at the left margin,
		and a space is used to separate the notes. The
		line is ended with a slash, ending the measure.

	D) If a measure is too long to fit on one line, it is
		continued on the next line, indented by a tab.
		Only the last line of a measure is ended by the
		slash.

	E) The commands "COPY" and "REST" get a line to
		themselves, with no slash at the end.

	F) "END" is followed by a carriage-return/linefeed.

I.E.2.	Comments
Any material after the title which is typed between square
brackets ("[ ]") is ignored by the compiler. Comments may
thereby be inserted in the text at any point.

I.E.3.	The text for each part appears in sequence in the input
file. Each part must have its own title, "KEY", "UNITS",
clef, and "END".

I.E.4.	Running the compiler.

When the compiler is run, it asks for the input text by
saying "INPUT FILE:". Respond to this with a filename in the
usual format. Next, the compiler asks for the "OUTPUT FILE:".
Again, type a filename. If the output device is the paper tape
punch, a tape is punched in the format read by the music player.
If the output device is a directory device, a copy of the player
is written out, with the music already loaded into it. If the
output is a dectape, this file is ready to load and run via
TENDMP.
The following default file-names, extensions, and devices
are assumed in the commands:
Unless specified, the input device is DSK: .
Unless specified, the input file extension is .MUS .
Unless specified, the output device is PTP: .
Unless specified, the output filename is the same as the
input file-name, or MUSIC if none appeared on input.
Unless specified, the output extension is .SAV if a save-file
is being written, and .MSB otherwise.
	MCOMP Error Messages

AGM	Argument. A command argument is missing or mis-formed.
AIR	Accidental appears in a rest. It is ignored.
AOR	Accidental forced a note out of range. The note is treated
	as a rest.
BBL	Bad Bar Label. Number not the same as current measure number.
BLC	Bad Left Copy. First argument too high, or zero.
BRC	Bad Right Copy. Second argument less than first.
CS	Internal Checksum error. Compiler has blown its mind.
DTU	Dot Time Unavailable. A dot specified too short an interval.
	The dot is ignored.
EIT	Embellishment, insufficient time. The embellishment is
	ignored.
EOR	Embellishment out of range. The embellishment is ignored.
ERT	Erroneous time. Duration number not 1,2,4,...,64.
ETR	Embellishment on triplet. The embellishment is ignored.
ILC	Illegal Copy. Copy command when notes already appear in
	current measure.
ILR	Illegal Rest. Rest command when notes already appear in
	current measure.
ITG	Insufficient time for grace note. The grace note is
	discarded.
# MLD	Measure length differs among the parts, at measure #.
MTL	Measure too long.
MTS	Measure too short.
MYK	Mysterious key. Key command not followed by "+", "-",
	"=", "(", or ")".
NOR	Natural overrides accidental, both appeared in same note.
NPS	Non-existent Pseudo-op (command). An unknown word appeared.
TFF	Too few fields in a note.
TIC	Dot and comma in same note. The dot is ignored.
TME	Too Many Embellishments in one note. The last applies.
TMF	Too Many Fields in a note.
TMS	Too Many articulation (Staccato, etc.) characters in a note.
	The last one applies.
TS	Tempo statement with argument greater than 682.
UAT	Unavailable tone. Tone is outside range of the compiler.
	It is treated as a rest.
UCH	Undefined Character. It is ignored.
UNC	Undefined comma. A comma appeared before a duration
	was specified in a part.

		Music Player Specifications

II.A.1.	The music player is an executive-mode program which
plays the binary output of the music compiler, in real time.
The player plays up to six voices. The six voices are played
in the low-order six bits of accumulator zero,by turning
those bits on and off at an audio rate. These bits reach an
external audio amplifier by means of the MI (memory indicator)
register, when the address switches are set to zero. A tapped
connection is made from the MI's light bulbs, through an "MK10
Music Kludge" to an audio amplifier. ("MK10" is not an official
designation, but it is generally known.)

II.A.2.	The music compiler's output may be a paper tape, to be
read by the music player, or it may be a .SAV copy of the player
with the music already loaded into it. In the case of paper tape,
the tape format is the same as that of the PDP-1 version of the
music compiler and player, for compatibility.

II.A.3	The music player is controlled by the data switches.
The switches control both the reading of paper tape, and the
playing of music.

II.B.	Loading the player:
The player and a piece of music may be loaded together by TENDMP,
or separately from paper tapes. This more primitive technique
works as follows:

	1) Using the Read-In switch, load the RIM10B paper
tape of the PLAYER. (This tape may be created by
assembling PLAYER.MAC .) The starting address of PLAYER is 140.

	2) Put the binary paper tape, output by the compiler,
in the reader.

	3)Turn on, then off, either switch 3 or 4: switch 3 if
the music is from 1 to 3 parts, switch 4 if the music is from
4 to 6 parts.

	4) the player will now read the tape. (A checksum
failure causes a halt.) When the tape is read in, the music
is ready to play.

At this point, you are in the same state as if you had compiled
the music directly to DECtape and then loaded it with TENDMP.
II.C.	The music PLAYER uses the data switches as follows:

Switch 0 - Stop playing (or reading) music. Wait for further
		switch commands.
Switch 1 - Start playing the music from the beginning.
Switch 2 - Detune the six voices, as follows: (Detuning the
		voices slightly prevents cancellation due to
		exact unison (or octave) notes.)
	Read switches 18-35, considering them as six groups
		of three bits. Voice 1 (MI 30) is associated
		with switches 18-20; Voice 2 (MI 31) with 21-23;
		... Voice 6 (MI35) with 33-35. Each switch group
		contains a number from 0 to 7. A 7 tunes "A" to
		exactly 440 Hz. 6 through 0 progressively flatten
		the voice.
Switch 3 - Load a binary paper tape of from 1 to 3 voices.
Switch 4 - Load a binary paper tape of from 4 to 6 voices.
Switch 5 - Tune up the computer. The player adjusts to
		the speed of the machine. This adjusts the
		tuning only, not the tempo.
	(NOTE: If you don't have 60 Hz power, reassemble with
		JIFSEC modified.)
Switch 7 - Go to location 37400 (16 K TENDMP) at end of music.
Switch 13 - Append a binary paper tape of from 1 to 3 voices.
Switch 14 - Append a binary paper tape of from 4 to 6 voices.
Switch 17 - Tempo control: Use switches 18-35 as a scale
		factor, modifying the original tempo of the
		music.

		Music Kludge Hardware ("MK10")

	As described in the PLAYER specifications, the music
is played by turning the six low-order bits of the MI on and
off at an audio rate. This information must be tapped off and
fed to an audio amplifier, in order to be heard.

	The attached diagram shows a simple scheme for doing
this, which involves only plugging a module extender in
series with the lamp-driver card behind the PDP-10 console.

(NOTE: For simple, quick-and dirty listening, placing a
transistor radio near the MI, or near Bay 2 of the KA10
will produce the music, but hardly in Hi Fi.)

	Using the MK10, each of the six lamp drivers now
feeds two volume controls in addition to the lamps. This load
is easily within the ratings of the lamp drivers. The volume
controls adjust how much signal from each lamp is sent to each
of two stereo output connectors. The signals are filtered
slightly by capacitors to dull the raspy quality of the square
waves produced by the lamp drivers.

	By cutting the circuit in half, a simpler, monophonic
MK10 could be built. By adding switched capacitors, or R-L-C
networks, more variety in the sound of the voices can be
obtained.

	The output of the MK10 shown is suitable for the
"TUNER" or "TAPE AMP" inputs of the usual HI-FI amplifiers.

	It is advisable to warn your field-service engineer,
or enlist his aid, before installing your MK10. The MK10 is
not a DEC-supplied option for the PDP-10.