Sound Tools
is a library of sound sample file format readers/writers
and sound effects processors.
Sound Tools includes skeleton C
files to assist you in writing new formats and effects.
The full skeleton driver, skel.c, helps you write drivers
for a new format which has data structures.
The simple skeleton drivers
help you write a new driver for raw (headerless) formats, or
for formats which just have a simple header followed by raw data.
Most sound sample formats are fairly simple: they are just a string
of bytes or words and are presumed to be sampled at a known data rate.
Most of them have a short data structure at the beginning of the file.
INTERNALS
The Sound Tools formats and effects operate on an internal buffer format
of signed 32-bit longs.
The data processing routines are called with buffers of these
samples, and buffer sizes which refer to the number of samples
processed, not the number of bytes.
File readers translate the input samples to signed longs
and return the number of longs read.
For example, data in linear signed byte format is left-shifted 24 bits.
This does cause problems in processing the data.
For example:
*obuf++ = (*ibuf++ + *ibuf++)/2;
would
not
mix down left and right channels into one monophonic channel,
because the resulting samples would overflow 32 bits.
Instead, the ``avg'' effects must use:
*obuf++ = *ibuf++/2 + *ibuf++/2;
Stereo data is stored with the left and right speaker data in
successive samples.
Quadraphonic data is stored in this order:
left front, right front, left rear, right rear.
FORMATS
A
format
is responsible for translating between sound sample files
and an internal buffer. The internal buffer is store in signed longs
with a fixed sampling rate. The
format
operates from two data structures:
a format structure, and a private structure.
The format structure contains a list of control parameters for
the sample: sampling rate, data size (bytes, words, floats, etc.),
encoding (unsigned, signed, logarithmic), number of sound channels.
It also contains other state information: whether the sample file
needs to be byte-swapped, whether fseek() will work, its suffix,
its file stream pointer, its
format
pointer, and the
private
structure for the
format .
The
private
area is just a preallocated data array for the
format
to use however it wishes.
It should have a defined data structure
and cast the array to that structure.
See voc.c for the use of a private data area.
Voc.c has to track the number of samples it
writes and when finishing, seek back to the beginning of the file
and write it out.
The private area is not very large.
The ``echo'' effect has to malloc() a much larger area for its
delay line buffers.
A
format
has 6 routines:
startread
Set up the format parameters, or read in
a data header, or do what needs to be done.
read
Given a buffer and a length:
read up to that many samples,
transform them into signed long integers,
and copy them into the buffer.
Return the number of samples actually read.
stopread
Do what needs to be done.
startwrite
Set up the format parameters, or write out
a data header, or do what needs to be done.
write
Given a buffer and a length:
copy that many samples out of the buffer,
convert them from signed longs to the appropriate
data, and write them to the file.
If it can't write out all the samples,
fail.
stopwrite
Fix up any file header, or do what needs to be done.
EFFECTS
An effects loop has one input and one output stream.
It has 5 routines.
getopts
is called with a character string argument list for the effect.
start
is called with the signal parameters for the input and output
streams.
flow
is called with input and output data buffers,
and (by reference) the input and output data buffer sizes.
It processes the input buffer into the output buffer,
and sets the size variables to the numbers of samples
actually processed.
It is under no obligation to read from the input buffer or
write to the output buffer during the same call. If the
call returns ST_EOF then this should be used as an indication
that this effect will no longer read any data and can be used
to switch to drain mode sooner.
drain
is called after there are no more input data samples.
If the effect wishes to generate more data samples
it copies the generated data into a given buffer
and returns the number of samples generated.
If it fills the buffer, it will be called again, etc.
The echo effect uses this to fade away.
stop
is called when there are no more input samples to process.
stop
may generate output samples on its own.
See echo.c for how to do this,
and see that what it does is absolutely bogus.
COMMENTS
Theoretically, formats can be used to manipulate several files
inside one program. Multi-sample files, for example the download
for a sampling keyboard, can be handled cleanly with this feature.
PORTABILITY PROBLEMS
Many computers don't supply arithmetic shifting, so do multiplies
and divides instead of << and >>. The compiler will do the right
thing if the CPU supplies arithmetic shifting.
Do all arithmetic conversions one stage at a time.
I've had too many problems with "obviously clean" combinations.
In general, don't worry about "efficiency".
The sox.c base translator
is disk-bound on any machine (other than a 8088 PC with an SMD disk
controller).
Just comment your code and make sure it's clean and simple.
You'll find that DSP code is extremely painful to write as it is.
BUGS
The HCOM format is not re-entrant; it can only be used once in a program.
The program/library interface is pretty weak.
There's too much ad-hoc information which a program is supposed to
gather up.
Sound Tools wants to be an object-oriented dataflow architecture.
