	***********************
	 Simple Multitrack 
	***********************


This set of programs allows the simultaneous recording of an audio track
while listening to a monitor mix of other tracks.  

This software uses the OSS audio drivers found in the Linux kernel or the
CoreAudio API on Mac OS X.  It has been tested on 
	Linux 2.4.20 on a Pentium III 1.4GHz with a SBLive soundcard, and
	Linux 2.4.20 on a Pentium I 120MHz laptop with a Crystal soundcard.
	Mac OS 10.3.3 on a PowerBook G4. 
Both Linux machines are running Slackware, so please tell me about your 
successes or problems on other distros.

Please read the BUGS section of this document.  
If you have bug reports, bug fixes, questions, comments, 
criticism, improvements, or documentation corrections please e-mail me.    

OVERVIEW:
		./build
		cd bin;
		source shellsetup;
	This will compile the programs and put them in your path.
	It will also make your shell prompt shorter, so you have room.
	It will also define a little function that is explained below.

	to record initial track:
		srp < /dev/zero > my_file

	to listen to a track:
		mix 2 1 1 1 my_file | srp > /dev/null

	to listen to one track while recording a new track:
		mix 2 1 1 1 file_1 | srp > file_2

	to listen to two tracks while recording a new track:
		mix 2 1 .5 .5 file_1 .5 .5 file_2 | srp > file_3 


For the curious:
	Simple Multitrack is basically two programs.  They were designed to be 
used together, but they might be useful on their own.  I will describe each 
program separately before discussing them together.

	mix is a command line program.  It mixes one or more monophonic audio 
files into a single output stream.  The output stream can have any number
of channels: mono, stereo, quad, whatever you like.  The output stream is 
written to standard out.  

	The input files are specified as command line arguments, as are the 
gain settings for each input. Invocation goes like this (in stereo mode): 
	mix nocs mgain l_gain_1 r_gain_1 file_1  l_gain_2 r_gain_2 file_2 ...
where nocs is the number of output channels, and mgain is the master gain.

	Command line arguments to mix after the nocs and mgain arguments are 
the channels.  For N output channels, you will have N gain arguments and then
the name of the file.  Therefore, the arguments after nocs and mgain must
appear in (nocs+1)-tuples.

mix will continue to pump out an endless stream of silence 
after the end of the input files is reached.  This behavior is
different from most UNIX command line programs, which exit at the end
of their input data, which closes their stdout.  

	mix can be exited with the keyboard interrupt, ctrl-c.  The input
files must be 16-bit 44100 samples/sec monophonic raw signed word files.  
The output stream is in 16-bit 44100 samples/sec stereo raw signed word format.
(Thank God, it's in word format!)  The program sox can be used to convert from 
most audio formats to and from most other audio formats.  

EXAMPLES:
mix 2 1 0 1 my_file 
This pans my_file completely to the right. 

mix 2 1 1 1 my_file 
This centers my_file.

mix 2 .5 1 0 flute 0 1 viola
This puts the flute completely to the left and viola completely to the right.
The master_gain is set to .5 to reduce the overall level of the mix by 3dB.

mix 2 .5 1 .3 flute .2 .9 viola
This is similar but gentler.

mix 2 .5 2 .6 flute .2 .9 viola
This is the same but the flute is louder.	

mix 2 1 2 .6 flute .2 .9 viola .3 .3 violin
The violin is added in the center.

Note: If you get clipping errors when using mix, you can lower the 
mgain factor instead of adjusting all of the individual channel gains,
although that works too.

	srp is a command line program.  It enables simultaneous recording and 
playback of audio using a sound card.  It will only work if your sound card
and its driver support full-duplex operation correctly.  

	srp reads a stream of stereo 16-bit 44100 samples/sec raw signed word 
data on standard in and plays that stream out on the soundcard.  Meanwhile, 
it reads from the left channel of the soundcard and writes a mono 16-bit 44100 
samp/sec stream on standard out.  

EXAMPLES:
srp < my_file > /dev/null
This plays my_file which is stereo. 
Mono files get played at double speed which you probably don't want.

srp < drums > bass
Bass is recorded while listening to a stereo file called drums.

srp < /dev/zero > piano
Record piano while listening to silence.

mix and srp can be used together as a multitrack audio recorder.  The output
format of mix is the same as the input format of srp.  Also, the output format
of srp is the same as the input format of mix.  

EXAMPLES:
mix 2 1 .3 .3 drums .4 .3 bass 1.3 .9 synth | srp > vocal
Vocal track is recorded while listening to mix of drums, bass, and synth.

mix 2 .5 .3 .3 drums .4 .3 bass 1.3 .9 synth 1 1.3 vocal > final_mix;
Drums, bass, synth, and vocal are mixed down to a final stereo mix.
The master_gain of mix is .5 to prevent overload (clipping).

THE STAT HACK:
	mix checks the permissions on the files that it is given as input 
channels.  If a file is not executable, it is read as a regular file 
containing audio data.

If a file is executable, it is executed as a concurrent child process and
the standard output of the child process serves as the data stream for that
input channel.  If a file given to mix is executable, I call it a GENERATOR.
Most likely, generators will be shell scripts.  Generators must produce an 
endless stream of bytes.  By chance, mix has this characteristic.

AN EXAMPLE OF THE STAT HACK:

	mix 2 1 .8 .5 sax 1 1 ./submix | srp > new_track

where submix is an executable file containing

################## begin submix #############
#!/bin/bash

mix 1.5 1 1 k1 1 k2 
################## end submix ###############

In this example, the main mix is invoked in 2-output-channel mode (stereo).
The master gain (mgain) setting is 1.  This means unity gain.
An audio file called sax is used as the first input channel.
The sax's level is 0.8 in the left channel, and 0.5 in the right.
A shell script called submix is used as the second input channel.
The generator script runs and its output appears in the main mix.
Inside the generator script, another instance of mix is running.  
This mix is running with nocs=1, mono output mode.
The mgain setting is 1.5, so output samples are multiplied by 1.5.
The regular file k1 is the first input to this submix, with level 1.
The regular file k2 is the second input to this submix, with level 1.
The main mix is piped to srp so you can hear the mix.
Meanwhile the analog input to the soundcard is recorded to new_track.

You can have any number of inputs, any number of which can be generators.
You can make a tree of mix instances if you like.

SKIP FEATURE:
	To use this feature you need to have sourced the shellsetup script
that is in the bin directory.

If you type
	skip 10
that means that you want the whole simple multitrack command line to skip
10 seconds and then start.  The skip command defines an environment
variable, skipsamps, in your shell which will persist until you change it.

	skip 15.5	
	mix 2 1 2 3 foo 3.2 2.4 goo | srp | skt drums4 | det

In this example, the drummer jumps in at 15.5 seconds to record his
drum track.  This way, he doesn't have to listen to the 15 second 
guitar intro.  15.5 seconds of silence will be prepended to the drums4
file before his take.  This is done in the form of a hole in the file.
Because it is a sparse file, the silence isn't taking up disk space. 
Note: tar can archive sparse files and keep them sparse.  

	If present, the argument to srp is the marker time.  At this
number of seconds into the input, srp will add a beep to the sound that
is played out through the soundcard.  This can be helpful if the file
needs to be edited, cut, spliced, cropped, whatever.

SKT: There is a little program called skt, short for seeking tee.  It
behaves similarly to the Unix tee program, but it seeks forward in the
file.  This is necessary for the skip feature.

DET:	There is also a little program called det, short for detector.  
det reads a 16-bit 44100 sample/sec signed word audio stream from stdin
and writes some useful information on stderr.  It gives you a scrolling
indicator of the maximum absolute value of any sample that was recorded
during the previous 500msec.   

	det also detects and reports input overload.  If det detects samples
that are within one quantization level of the limit, it will print the
word "OVERLOAD" in its output.

	det also detects and reports acoustic markers.  If you have a mic 
plugged into your sound card, you can say "now" into the mic when you hear 
the part of the music that you want to mark.  det will number of seconds
into the input file when you said "now."  This is useful for determining
where you want to cut your file.  det simply looks for a sudden loud sound
as the acoustic marker.  You can also tap the mic or clap your hands or
bang on a drum.  Anything that makes a sudden loud sound should work.  The
detection threshold, DET_THRESHOLD is set in det.h.  

example: (a screenshot!)

# mix 2 1 1 1 track1 .5 .5 track2 | srp | skt track3 | det
**                               |  1714          1.000 sec
*****                            |  4773          1.500 sec
------------------------------------------------------------ marker: 1.505 sec
******                           |  5250          2.000 sec
**                               |  1175          2.500 sec
******                           |  5867          3.000 sec
*********************************| 32767 OVERLOAD 3.500 sec
**                               |  1262          4.000 sec
**                               |  1157          4.500 sec
**                               |  1136          5.000 sec

Here we are listening to a mix of track1 and track2 while recording track3.
tee is being used to send the data to the track3 file for storage and also
send the data to det for analysis.

FILE FORMATS:
Currently the file formats used for audio data are mono signed word raw data
and stereo signed word raw data.  There is nothing special about these file 
formats.  Simple Multitrack could be modified so that it reads other formats
such as the Microsoft .WAV file format.  I am quite happy content to leave
the job of file format conversion to sox.  sox is an extremely flexible full-
featured audio format converter.
http://home.sprynet.com/~cbagwell/sox.html   
sox has a number of useful features.  The man page is very good.

NOTES:
There is a much more powerful command line multitrack program called
ecasound.  

The MP3 encoder, bladeenc will accept the raw data files that 
simple multitrack uses.  There is no need to convert to .WAV format.

TO DO: 
	configure scripts should be used instead of old-fashioned makefiles.

	It is not good to assume that an int is 32 bits nor that a short
	is 16 bits.  

	The command line is starting to become a nightmare.  It is 
	probably time for some reasonable defaults, and optional
	arguments.  In fact, the whole command like processing, 
	including usage checking, is not good.

BUGS:
	The Mac port assumes a lot of stuff that it should be checking.
	For example, the size and number of buffers.   
	
	These programs use native byte order.  Sox can do endian conversion 
	of necessary.

	Many parts of this software are quite hacky.  

	Error handling and reporting can always be better.

	The level indicator in det prints times that are off by a second.	

	Please don't keep quiet if you find a bug.

AUTHOR:

	Kurt Rosenfeld
	My user name is hardware.
	My mail domain is ee.ccny.cuny.edu.
	You can figure out what my email address is.
	
