User's Guide

Subsumption Strategy Development of a Music Modelling System
Joanna Bryson, MSc project, September 1992


Introduction
------------

This project is primarily an experiment in design and cognition, not a
user-oriented tool.  Consequently, everything that can be done with it
by a user not interesting in experimenting/programming theirself is
explained in the Demonstration Guide.  

The main purpose of this guide is to explain how to create all the
needed in put files, including how to train the weights for the NOTE
module.  At the end there is also an explanation of the command line
flags for all the modules.

I strongly advise reading the Demonstration Guide before reading this.
Other useful references are:
	- the end of the Installation Guide, which contains a list of
	  all the files involved, their uses and locations.
	- the "demo" program itself, which is a shell script.  All the
	  preferred command lines are listed in array initialisations
	  toward the beginning of the file.
	- the dissertation.

I suggest editing your path to include
":/usr/demo/SOUND:[something]/joannabDEMO/PROJECT/bin".

The following sections are organised in the order you will require
files as you progress through the modules.

Capturing the Audio Input
--------- --- ----- -----

This has to be done on a machine with a SUN standard audio input board
and the /usr/demo/SOUND directory installed.  You also need one of the
SUN microphones and adapter cables to plug into the audio port in the
back (by the keyboard jack).  

The easiest way to do this is to use the "soundtool" utility, which
has a nice window interface under sunview.  It is pretty much like a
conventional recording device, see the man page if you have trouble.

Two tips - 
	*** call any files you create [name].au, so that the scripts
below will work and you won't have to do the rest of the conversions
by hand.
	*** edit as much "white noise" at the beginning and end of the
recording out before saving the file.  You do this by selecting the
part of the wave form in the right hand screen that you want by
clicking the left button for the left margin and the right button for
the right.  "Play" and "Save" will then both work only on the marked
region.

Converting the Audio file to FFT
---------- --- ----- ---- -- ---

All you need to do to convert [file].au to [file].fft for the modules
is run "sun2fft [file]".

Creating a Frequency/Weight File
-------- - --------- ------ ----

Requires training the neural net used in NOTE.  Start out by...

Creating a Frequency File
-------- - --------- ----

Do this using the PERL script "note/fw-gen.prl".  Edit this to
determine the range over which you want the file to extend, and the
number of frequencies per octave.  There is a file like this called
"raw.fw" in the "workspace" directory which extends from 220-4000Hz
with 96 input lines per octave.  Fewer input lines results in worse
discrimination, more results in longer computation.

Creating a Key File
-------- - --- ----

In the note subdirectory there is a shell called "key-gen.prl" - if
you edit the number of samples and the length of a sample (in seconds)
it will create the first two columns you need.  You will still have to 
write the pitch classes in by hand (or add another loop if they are
predictable!)  For an example of a training set and its key file, see 
workspace/scale.*

Training
--------

See the demo script for the preferred command line, but I wouldn't
actually run this from a script!  This is a bit hacky right now -
basically you set a flag for a "debugging" file, which writes out
every time there is a report on correctness (see the dissertation).
When you see a good report, copy the debugging file into another name
(or ^C the program).

The name of the program is "train"

recommended flags ---

-f  [file.fw]   the frequency/weight file, may have frequencies only as
		described above.
-i  [file.fft]  the input audio file in FFT format.
-w              tell it to ignore any weights already in the fw file.
                if you omit this, it will _continue_ training from
                whatever weights already exist.
-o  [file.fw]   this isn't actually used, but its required... if the
                program terminated it would save its weights here
-d  [file.fw]   the output you'll really use (see above)
-k  [file.key]  the key file for supervised training.  If you omit
                this flag you get unsupervised training.
-t  [#]		the number of samples exposed before a test && debug
                file write.  You really don't need this very large,
                even 20 is reasonable, but I usually use 40.

other flags ---

-p [.#]		percentage of weights that haven't changed in order
		for the thing to be considered to have "converged".
		(which would make the program terminate...)
-r [.#]		percentage of difference within one weight to its next
		testing to be considered "not to have changed" in the 
		stability test.  These options are replaced by the 
		correctness check in practice.
-T		If this flag is present, instead of _training_ the
		net, you print the output for each randomly generated 
		frame.  Don't really need this now, you can use "note"
		instead, but this program was developed first.


Creating a Chord Template File
-------- - ----- -------- ----

The only other input file needed by the system is a chord template
file.  This file tells the program what pitch classes are in a chord,
and what they are called.  To simplify this process, you only need to
create one instance of the chord type - the instance where the root is
the first pitch class.  An example of this kind of file can be found
in "chord/chords.raw".  Once you have created this file, you can run
the PERL script from the same directory like this, 

"perl scale_chord.pr chords.raw > [filename].ct"  

Notice any comments are preserved, but not in order... they get bunged
to the top of the file.  If you can't find a copy of "chords.raw" to
see what the input should look like, it is printed out in the
dissertation.


The Module Program Command Lines
--- ------ ------- ------- -----

As mentioned above, the preferred command lines for the module
programs all appear in the demo shell script.  The following is a list
of options.  Since each program builds on its predecessors, unless
otherwise noted any command line option applies to any module
following it as well as the one its listed for.


NOTE
----

-f  [file.fw]   the frequency/weight file, contains required
                parameters for the neural net.
-i  [file.fft]  the input audio file in FFT format.
-G              [this module only] print out only the winning pitch
                class and its associated absolute weight.  Without
                this option all twelve pitch classes are printed.

CHORD
-----

-c  [file.ct]   the chord template file
-W              (this module only)  Use a winner-take-all strategy on 
		the NOTE output, rather than maintaining the information
		from all the pitch classes.

THRESH
------

[nb:  doesn't use -c]
-h [.#]		Optional override of default for how much a weight has to 
                change for the note not to be considered stable.


BEAT
----

[nb:  doesn't use -c]


CHANGE
------

-g		use the degradation test rather than the default straight
		rating (I recommend using this flag)

TIMED
-----

(no new flags)


Noise
-----

-M  		output only the melody
-A		output only the accompaniment
		(the default is to output both)
-R		retrofit - that is, take the project out of real time by
		applying what is considered to be the chord at the end of 
		the beat as the chord for the entire beat.
