Copyright (C) 2000-2012 |
Manpages STSection: C Library Functions (3)Updated: October 15 1996 Index Return to Main Contents NAMElibst - Sound Tools : sound sample file and effects libraries.SYNOPSIScc file.c -o file libst.aDESCRIPTIONSound 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.INTERNALSThe 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. FORMATSA 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:
EFFECTSAn effects loop has one input and one output stream. It has 5 routines.
COMMENTSTheoretically, 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 PROBLEMSMany 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.BUGSThe 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.
IndexThis document was created by man2html, using the manual pages. Time: 11:32:09 GMT, April 19, 2024 |