This directory contains the source, executable and DSO library
objects for most of the RTcmix and CMIX instruments (the entries
in ../bin and ../lib are links to this directory).  A listing
and brief description of what's here follows at the end of this
file.  Sample scorefiles and parameters ("p-fields") can
be found in each instrument subdirectory.  All sample scores
have also been linked into the directory "SAMPLE_SCORES".
A fairly comprehensive set of html documents for these
instruments can be found in ../cmix_docs/instruments.html;
or check http://www.music.columbia.edu/cmix for the most
recent updates.

Although each instrument can be compiled as a standalone
instrument, the sample scorefiles make use of the DSO-loading
capability (the load() directive in the scores); thus they
can be run simply by typing:

	CMIX < scorefile

for RTcmix instruments or

	cmix < scorefile

for disk-based (non real-time) CMIX instruments.
RTcmix instruments can also write to aiff disk soundfiles
by putting an 'rtoutput("soundfile.name")' directive in
a scorefile.  The samples written to the soundfile should
be identical to samples realized in real-time.


We tried to make the p-fields for many of these instruments a bit
more consistent, plus nearly all of them now read/write stereo and
mono files (with optional p-fields for stereo placement, input channel
to read).  With only a few exceptions, I've also replaced setline()
with a makegen, figuring that gen 24 does the same thing and it
seems more in line with other aspects of instrument design.
Finally, nearly all of the instruments have an associated
Minc call "reset()" which takes one p-field allowing the user
to specify how many times/sec. to update various envelopes.

NOTE to older cmix users:  one of the biggest changes in terms
of p-field rearrangements is that I have set the first p-field as
the output skip.  This changes the syntax of many of the
cmix sig-processing routines, where the old "insk, outsk, dur"
used to be the thing to do.  Now they are "outsk, insk, dur".
Annoying, eh?


Here's a short note on RT instrument design, adapted from an
older README:


	Each Instrument has two member functions that must be defined
	by the Instrument designer.  A new instrument is intended to
	inherit the basic stuff from the base Instrument class (in
	rtstuff/Instrument.C), but the base class only contains a few
	variables used in setting up the sample loop.  I tried to make
	an Instrument look as much like an existing cmix function
	as possible, mainly to simplify the job of porting stuff
	already done.  The Instrument::init(p, n_args) member function
	does all the setup stuff prior to the sample loop (the code
	should look familiar).  Note that the traditional call to
	"setnote()" is replaced with a calls to "rtsetinput()" or
	"rtsetoutput()" -- these schedule the instrument into the
	appropriate slot(s) on the rtqueue heap.

	The Instrument::run() member function is called
	from the rtqueue heap, and it is expected to deliver
	RTBUFSAMPS worth of samples each time (except when it
	finished by reaching nsamps).  The chunksamps variable
	is calculated by RTcmix to accomplish this and handle
	the correct start and stop amounts (often less than
	one buffer's worth).  The "cursamp" variable is used
	to mark how many samples have actually passed, and
	it holds its value between Instrument::run() calls,
	so it can be used in table() calls, etc.

	So the user-written Instrument sees a call to init() when
	it gets set up on the rtqueue heap, and then it sees a number
	of calls to run() depending on how long the note is.

	Note that variables that are set by the init() member function
	for use by the run() member function are declared in the
	associated .h file for the Instrument.

	Note also the rtprofile() function used to introduce the Instrument
	to the Minc list of RTinstruments.  It is slightly different
	than the equivalent profile() cmix function.  rtprofile()
	has to create a new instance of the user-written Instrument,
	so it has to have an 'auxiliary' function (makeWAVETABLE(), for
	example) to do the job.  RT_INTRO cannot call the constructor
	or the init routine of the user-written Instrument directly.

The directory "TEMPLATE" contains a dummy (non-filled-out) RTcmix
instrument if you want to try coding one up.


The current list of instruments include (CAPITAL letter versions are
the RTcmix instruments):

am,AM:  	amplitude modulate signal processor
aminst,
   AMINST:  	amplitude modulation synthesis instrument
clar,CLAR: 	Perry Cook's "clarinot" physical model
combit,COMBIT:	comb filter signal processor
fminst,FMINST:	frequency modulation instrument
iir,IIR:	infinite impulse response filter
fir,FIR:	finite impulse response filter
metaflute,
  METAFLUTE:	Perry Cook's "Slide Flute", with pitch bend and vibrato
mix,MIX:	soundfile mixing instrument (the "mix" command is in ../cmd)
multicomb,
  MULTICOMB:	4 comb filters simultaneously
sculpt,SCULPT:	resynthesize data from the IRCAM "Audiosculpt" app.
stereo,STEREO:	soundfile mixing instrument
			(the "stereo" cmd is in ../cmd)
strum,STRUM:	Charlie Sullivan's variant of the Karplus-Strong algorithm
wavetable,
  WAVETABLE:	wavetable oscillator instrument
waveshape,
  WAVESHAPE:	waveshaping instrument
del1,DEL1:	single stereo (non-regenerating) delay line instrument
delay,DELAY:	simple regenerating delay line instrument
panecho,
   PANECHO:	stereo regenerating delay line instrument
convolve:	convolution instrument
flange:		stereo flanger
gravy:		pitch and time shifter
lpc:		the original lpc stuff
move:		Doug Scott's room simulation with moving source
mrotate:	time independent dynamically changing pitch-shifter
noise:		noise
place:		Doug Scott's room simulation
pvoc:		phase vocoder (from F. R. Moore)
rotate:		time independent pitch-shifting instrument
sgran:		Mara Helmuth's stochastic granular synthesis instrument
trans:		pitch-shifting instrument, cubic spline interpolation
vwavetable:	wavetable synthesizer w/ vibrato
wah:		moving reson
wahwah:		oscillating reson
wow:		FM modulates an input soundfile
numtest:	writes a single number out repeatedly (for debugging)
