Category : C Source Code
Archive   : SOX.ZIP
Filename : ST.DOC

 
Output of file : ST.DOC contained in archive : SOX.ZIP



ST(1) USER COMMANDS ST(1)



NAME
st - Sound Tools - sound sample file and effects libraries.

SYNOPSIS
cc file.c -o file libst.a

DESCRIPTION
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 for-
mats and effects. The full skeleton driver, skel.c, helps
you write drivers for a new format which has data struc-
tures. 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 mono-
phonic 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.), style (unsigned, signed, loga-
rithmic), 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



Sun Release 4.1 Last change: 1






ST(1) USER COMMANDS ST(1)



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 sam-
ples 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 appropri-
ate 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 argu-
ment 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 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 fill the output



Sun Release 4.1 Last change: 2






ST(1) USER COMMANDS ST(1)



buffer.

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 mul-
tiplies 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 sup-
posed to gather up. Sound Tools wants to be an object-
oriented dataflow architecture. The human ear can't really
hear better than 20 bits. With an internal format of 16
bits, we will eventually destroy information when used to
mix CD's. The internal format should be 24-bit signed data.
But, with 24 bits you still have to be careful multiplying.
Check the ``vibro'' effect for how it handles this problem.









Sun Release 4.1 Last change: 3





  3 Responses to “Category : C Source Code
Archive   : SOX.ZIP
Filename : ST.DOC

  1. Very nice! Thank you for this wonderful archive. I wonder why I found it only now. Long live the BBS file archives!

  2. This is so awesome! 😀 I’d be cool if you could download an entire archive of this at once, though.

  3. But one thing that puzzles me is the “mtswslnkmcjklsdlsbdmMICROSOFT” string. There is an article about it here. It is definitely worth a read: http://www.os2museum.com/wp/mtswslnk/