		~~~~~~~~~~~~~~~~~~
		   GLOCKENCORD
		~~~~~~~~~~~~~~~~~~
	          version 1.1.2
		~~~~~~~~~~~~~~~~~~
		How to create your
		 own  Music Rolls
		   (GCR  files)
		~~~~~~~~~~~~~~~~~~
Please note: versions 1.1.1 and 1.1.2 are functionally identical to version
1.1, and version 1.1 GCR files are still used.

Introduction
------------
In the Automatic mode of Glockencord, a file can be loaded which contains
an encoding of the paper roll used to drive the hammers and play a tune.
The paper roll (or something similar) is a common feature among various
automatic music playing devices from a bygone era, although there are
companies which still produce instruments and rolls, so the industry is
still alive out there in the real world. Music is encoded by punched holes
which (as the paper moves over an actuating mechanism) trigger the playing
of certain parts of the instrument. In the case of the Glockencord, they
are 30 seperate instances of the same instrument, but each tuned to play
a different note in the range which the instrument covers. If you want to
know more about these mechanisms, a good place to start is Wikipedia -
search for "Piano roll". Note that some such mechanisms have the paper
loaded in a zig-zag (like the old continuous feed line printers), and others
have a series of cards joined together which hinge at the joins. I've
chosen a roll of paper for the glockencord, since it lends itself to the
shape of the screen on the DS (and is easier to animate!).

Terminology
-----------
I've done a little research, and there seems to be various names for rolls
of punched paper which encode music: "Piano roll" is a common one as is
"Organ roll". I've settled on a nice generic compromise: "Music roll". The
underlying file which stores the information on the DS will use my own
specially concocted file format: The GCR file ("Glocken-Cord-Roll").

The GCR format
--------------
There are a few lines in a GCR file which are there to determine general
things about the music roll, but the bulk of the file defines where the
holes you see on the roll are punched. I will explain this briefly here,
but I have supplied a compiler that will generate the GCR file for you
from a text file containing a simpler notation, and will discuss the format
of that text file properly in the next section. This overview of the GCR
format is given here for completeness.

	Line	Field	Meaning
	-----------------------
	  1	  1	Literally set to "GCR", to avoid confusion with
			other file formats which share the same extension.
	  1	  2	The version or variant number. For Glockencord
			version 1.1 this must be set to "1.1".
	  2	  1	The number of voices (or instruments) encoded
			in the file. For Glockencord 1.1 this should be
			set to 30. Any additional voices will be ignored.
	  2	  2	Tempo of the piece in beats per second, for
			example: 7 denotes that 7 rows of punched holes
			pass over the actuating mechanism every second.
	  3	  1	Percussion vs. Non-percussion instrument flags.
			This has been provided to allow me to expand the
			GCR format for later projects. For glockencord
			version 1.1 this line must be set to five '@'
			symbols (denotes all voices are percussive).
	4 to (n-1)	Each line specifies the holes to be punched in
			one row of the music roll encoded into five bytes
			as follows:

			+--------+--------+--------+--------+--------+
			|01xxxxxx|01xxxxxx|01xxxxxx|01xxxxxx|01xxxxxx|
			+--------+--------+--------+--------+--------+
			Each 'x' denotes one voice. The first is "G" in
			the lowest octave. The last is "C" in the top
			octave. If set to 1, a hole is "punched" in that
			position (otherwise it's set to 0). The "01" at
			the start of each byte allows the file to be
			viewed/printed (avoiding non-printable characters).
	  line n	The last line of the file must be set to the
			letters E,N and D.

Using the Compiler
------------------
This simplifies things somewhat (for a start, you don't have to think in
binary). The compiler itself is called "GCR compiler.exe", and runs on
Miscrosoft Windows. Create a text file using your preferred text editor
(such as notepad or vim, for example) and then drag-and-drop the text file
to GCR compiler: The GCR file will be created in the same folder as the
text file. You might be able to create the text file in a word processor
(such as Lotus Word Pro), but you must be able to write it as a plain
text file: I haven't tried this myself, but it may well work. Create the
text file using the following format:

	Line	Format			Meaning
	----	------			-------
	  1	30,nn (or 30,n.n)	"30" is literal.
					"nn" or "n.n" is a number (which
					may include a decimal point).
					It specifies the tempo in beats per
					second.

	  2	TRANSPOSE,nn		Tells the compiler to transpose
					the piece by the number of semitones
					indicated by nn (a whole number).
					If nn is positve, the piece is
					transposed up. If negative, it's
					transposed down.
					THIS LINE IS OPTIONAL. If omitted,
					leave the line out entirely (line 3
					in this format will be line 2 and so
					on...)

	3 to (n-1)	Note list	See below.

	  n	END			The last line must be set to END.

For every line of the text file (except the last), anything after a TAB
character is ignored, and can be used to put in comments (such as the title
of the piece).
	  
Note list
---------
Each line containing a note list relates to one row of the final Music
roll in the order included in the text file. Each note is specified as
three characters: The basic note (ie: C, D, E, F, G, A or B); a Sharp/flat
indicator which is set to # to sharpen the note, b (lowercase B) to
flatten it, or - (minus-sign) to leave the note as a natural; and a single
digit to denote the octave, where '1' is the lowest octave and '4' is the
highest. The octave is taken as moving up on the note of C, hence C-2 is one
semitone above B-1.

Glockencord version 1.1 can handle notes in the range "G-1" to "C-4". I
usually find that (for most purposes) having "C-2" relating to middle-C
works quite well, but this is not mandatory: You could have "C-3" relating
to middle-C, which would allow you to encode the C below Middle-C (although
higher notes would then be a problem). See notes below on Transposing for
a discussion of getting the music to fit the range of the Glockencord.

If you want notes to be played one after the other, place them on seperate
lines. To play them at the same time, place them next to eachother on the
same line (no spaces).

The text between the lines below show how you would encode the scale of G,
playing each note one at a time:

		------------
		G-2
		A-2
		B-2
		C-3
		D-3
		E-3
		F#3
		G-3
		------------

The text between the lines below show how you would play the chord C-E-F-C
with the notes sounding at the same time:

		------------
		C-2E-2F-2C-3
		------------

If you want NOTHING to play for a beat, specify a rest. This is done using
three lower-case 'x's for the line instead of specifying any note.

Making the timing fit
---------------------
Each line is one "beat", or row of holes punched on the paper roll. The
tempo (beats per second) it defined in the first line of the text file.
Generally, the approach which seems to work best is to search through the
score you're transcribing for the shortest duration of note (eg: semi-quaver)
and then using this length of note as your "beat". If, for example,
the tempo of the piece is 120 crotchets per minute, and you're working
with a semi-quaver beat, set the tempo on the first line to 8.

If a note in the music is longer than the beat you're using for the Music
Roll, treat it as a short note followed by the appropriate number of rests.
For example, suppose you are working with each beat being a quaver, and
you have a piece which is crotchet, quaver, quaver, crotchet (all middle-C),
you would encode as follows:

	------------
	C-2
	xxx
	C-2
	C-2
	C-2
	xxx
	------------

Lets suppose now that the first crotchet was accompanied by a minim (D#) and
the last crotchet by two quavers:

	------------
	C-2D#2
	xxx
	C-2
	C-2
	C-2D#2
	D#2
	------------

Since Glockencord is a percussion-based instrument, note duration has no
real effect on the sound: Only the timing counts. Hence pieces that rely on
long sustained notes (such as church organ pieces) may not sound too great.

Note that the Americans refer to minims as half-notes, crotchets as quarter-
notes, quavers as eighth-notes and semi-quavers as sixteenth-notes.
Personally, I find that hemi-demi-semi-quaver sounds more romantic than
one-sixty-fourth-note.

Transposing
-----------
The glockencord has a range of 30 semi-tones (G1 to C4). Any piece of
music which requires a range outside this is clearly going to be problematic.
While there is nothing that can be done to resolve this when a piece
requires a range of more than 30 semitones, we can move all the notes up
or down (transposing) to move the range covered by the music to match the
range of the glockencord. If all notes in the music lie within the range
of the instrument, we don't need to do anything.

Search through the score you're transposing, and look for the lowest note
and highest note. Work out how many semitones you'd need to raise or lower
the piece by to make it "fit", and add a second line to the text file that
starts "TRANSPOSE" (no quotes) followed by a comma, and is followed by the
number of semitones required (with a minus sign if you need to transpose
down).

Sometimes a score has more than one part (eg: a bass line on the lower
stave). If this is the case, you might get extra flexibility by
raising or lowering one of the parts by a whole octave: just simply enter
the transposed notes in this instance with a different octave number.

The musicrolls.ini file
-----------------------
If you create a new music roll, you need to add its details to the
musicrolls.ini file. Add a new line to the file containing the name of
the GCR file (without the .gcr extension) followed by a comma and then by
the title of the piece. Increase the number on the first line to match the
number of Music rolls specified.

Copying to the DS
-----------------
Copy the modified musicrolls.ini file and the new GCR file to the folder
/DATA/glockencord on the SD card used by the DS. On switching to Automatic
mode in Glockencord version 1.1, the new tune should appear in the list.
Load it, and it should play.

Examples
--------
I have included a folder in the Zip file called "examples". This contains
the text sourcecode for the supplied music rolls so you can see how they
were coded.
