Installation Guide

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

Environment Requirements
----------- ------------

This program must be run on a machine with a standard SUN sound board,
which currently means either a SPARCstation SLC or an ELC.

It is assumed that the "csound" package is available and in the users
path (currently in /local/bin on the animals).  It is also assumed that
the directory /usr/demo/SOUND is installed.

The main programs all produce ascii output, and require no special
windowing.  The demo program can run in either X or sunview.  Note:
the SUN "soundtool" utility used for recording input files and adjusting
the volume and output (jack or speaker) is much better in its sunview
version, so I recommend that system.

Environment Setups
---------- ------

Nothing is required except knowing the correct paths.  This is done 
for you by the "demo" program.

Making the Executables
------ --- -----------

Many of the small utilities are perl scripts and some need to be run
as "perl [file].prl [arguments]".  The bulk of the program is in C++.
To make all of the executables, type "make" in the main demo
directory.

Warning:  One set of dependencies I was too lazy to get correct...
If you edit a header file, you should remove the object files from any
"higher level" modules.  If in doubt, just type in the main directory
"rm */*.o" before typing "make".  The order of the modules, from low
to high, is:  note, chord, thresh, beat, change, timed, (noise).

Summary of Files
------- -- -----

Due to the large number of files involved in this project, the top
level directory consists mostly of subdirectories.  I have listed
everything in "ls -F" format, so filenames followed by a / are a
directory, by a * are executable, by an @ are symbolic links (to 
other files in this directory system!)

Makefile	makes the programs (actually calls the makes in each 
		subdirectory)
beat/	     	the files associated with the BEAT and THRESH modules
bin/         	a single directory to add to the path, contains
             	executables or links to executables.
change/		the files associated with CHANGE
chord/		files associated with the THRESH module
demo*           demand executable PERL script for running the full system
input/		files for manipulating the audio input files
lib/		library routines for the modules
noise/		files for the NOISE robot (creates score files for "csound")
note/		files associated with the NOTE module
timed/		files associated with the TIMED module
workspace/	where you execute the programs... input and output files.


The following is a listing of the contents of the subdirectories.
Notice that for the modules, the executables actually live in the
directories with their source code, and are only linked to the bin/
directory.  I will not explain module source files or Makefile here,
only the exceptional files or programs.  For more information on the
module programs, see the dissertation ;-)


beat:
Makefile
beat*
beat.cc
beat.h
beat_b.cc
thresh*
thresh.cc
thresh.h

bin:
beat@
change@
chord@
fft-look@   	see the "input" subdirectory
noise@
noise2sun*      shell script to convert the output of "noise" into a sun
		audio file, suitable for running with the "play" or 
		"soundtool" utilities.
note@
showin@		see the "note" subdirectory
sun2fft*	a shell script to convert the output of the "record"
		"soundtool" utilities into fft files (fast fourier
		transformation) suitable for input to the module programs.
sun2ircam@	see the "input" subdirectory
thresh@
timed@
train@		see the "noise" subdirectory

change:
Makefile
change*
change.cc
change.h
change_o.cc

chord:
Makefile
README		explains the making of the "chords.ct" file required
		by "chord" and higher modules.
cfiles.cc
chord*
chord.cc
chord_net.cc
chord_net.h
chord_util.cc
chord_util.h
chords.raw	contains the templates for different chord types for
		the "A" pitch class (must be edited by hand)
scale_chord.pr  PERL script that permutes chords.raw for the other 11 
		pitch classes

input:
Makefile
fft-look*	program to change an fft file into ascii
fft-look.c
freq-dom.prl    perl program to see which are the main frequencies
		per fourier frame
max-freq.prl    perl program to determine the highest frequency in a
                file produced by fft-look
maxes           output of max-freq.prl for a file made by "pvanal" (csound)
sfheaders.c
sfutil.c
sun2ircam*     	program for converting sun audio files to IRCAM format
		(required by "pvanal" (csound))
sun2ircam.c
sunsun.c

lib:
libmuslib.a	the library of the module's object code (used by
		higher modules)

noise:
Makefile
noise*
noise.cc

note:
Makefile
freq_ins.cc
fw-gen.prl 	PERL shell for generating a frequency/weight file with
		only the frequencies, used for training.
infft.cc
infft.h
intrain.cc
intrain.h
key-gen.prl	PERL shell that facilitates the creation of a key file
		for a training file - a lot still has to be done by hand!
nfiles.cc
note*		the actual module for this directory
note.cc
note_net.cc
note_net.h
note_util.cc
note_util.h
range.cc
ranger.cc	a main() for testing the Range class operators
showin.cc	a main() for printing the input to the program as it
		looks before being input into the net (used for input
		to "matlab" to diagram a frequency chart)
train*		program for training / generating the weights for 
		the neural network used by NOTE
train.cc
train_nn.cc
train_nn.h

timed:
Makefile
beat_pred.cc
timed*
timed.cc
timed.h


In the "workspace" directory:
	*.au is the raw audio inputs as created by
	     "record"/"soundtool"
	*.fft is the file created by "pvanal" that is used as input
	     by all the module programs.
	*.sco is the created by "noise" as input into "csound"
	*.cs is the audio output file created by "csound" which can
	     be played by "play"/"soundtool"

Most of these tags are my own convention, and can be altered on the
command line.  But if you don't use the same ones as me, you can't use
my nice shell utilities!

workspace:
chords.ct	file of chord templates required by programs using the
		CHORD module
dogsong.au
dogsong.cs
dogsong.fft
dogsong.sco
fastpw2.au
fastpw2.cs
fastpw2.fft
fastpw2.sco
flute.orc	the "orchestra" file used by csound to determine how
		the score files will sound.  You can use another one
		if you want, it's an optional second argument to 
		"noise2sun".
malt.au
malt.cs
malt.fft
malt.sco
malt_nod.au
malt_nod.cs
malt_nod.fft
malt_nod.sco
note.fw		my personal favorite set of weights, used by the NOTE module
scale.au        scale is not a song, it's the training file!
scale.fft
scale.key       the key to scale, required in order to do supervised training.
slowpw.au
slowpw.cs
slowpw.fft
slowpw.sco
wedith.au
wedith.cs
wedith.fft
wedith.sco



---------------  End of install_guide  (last updated Sept 24, 1992)
