ref: 4c6e35d20fcca0017b630bcfaf1df7ffef6df3eb
parent: e2e7cef191606fc6f69a88d8da4e675a3b30c347
author: cbagwell <cbagwell>
date: Mon Sep 26 20:50:49 EDT 2005
doc updates
--- a/Changelog
+++ b/Changelog
@@ -34,8 +34,8 @@
talking to kernel driver. This also means that device names
are now the ALSA logical names instead of /dev type names.
o Added ALSA support to play/rec scripts.
- o Added st_open* and st_close() routines to help simply
- developer interface to libst.
+ o Added st_open*, st_read, st_write, st_seek, st_close routines
+ to help simplify developer interface to libst. See libst.3..
o Force word-alignment on AIFF SSND and APPL chunks on input.
Matthew Hodgson.
--- a/libst.3
+++ b/libst.3
@@ -9,16 +9,36 @@
.if t .sp .5v
.if n .sp
..
-.TH ST 3 "October 15 1996"
+.TH ST 3 "September 26 2005"
.SH NAME
libst \- Sound Tools : sound sample file and effects libraries.
.SH SYNOPSIS
+.B #include <st.h>
+.P
+.B ft_t st_open_input(const char *\fIpath\fB, const st_signalinfo_t *\fIinfo\fB, const char *\fIfiletype\fB, char \fIswap\fB);
+.P
+.B ft_t st_open_output(const char *\fIpath\fB, const st_signalinfo_t *\fIinfo\fB, const st_signalinfo_t *\fIinput_info\fB, const char *\fIcomment\fB, const st_loopinfo_t *\fIloops\fB, const st_instrinfo_t *\fIinstr\fB, const char *\fIfiletype\fB, char \fIswap\fB);
+.P
+.B st_ssize_t st_read(ft_t \fIft\fB, st_sample_t *\fIbuf\fB, st_ssize_t \fIlen\fB);
+.P
+.B st_ssize_t st_write(ft_t \fIft\fB, st_sample_t *\fIbuf\fB, st_ssize_t \fIlen\fB);
+.P
+.B int st_close(ft_t \fIft\fB);
+.P
+.B int st_seek(ft_t \fIft\fB, st_size_t \fIoffset\fB, int \fIwhence\fB);
+.P
.B cc \fIfile.c\fB -o \fIfile \fBlibst.a
.SH DESCRIPTION
.I Sound\ Tools
is a library of sound sample file format readers/writers
-and sound effects processors.
+and sound effects processors. It is mainly developed for use by SoX but is useful for any sound application.
.P
+The function \fBst_read\fR reads \fIlen\fR samples in to \fIbuf\fR using the format handler specified by \fIft\fR. All data read is converted to 32-bit signed samples before being placed in to \fIbuf\fR. The value of \fIlen\fR is specified in total samples. If its value is not evenly divisable by the number of channels, undefined behavior will occur.
+.P
+The function \fBst_write\fR writes \fIlen\fR samples from \fIbuf\fR using the format handler specified by \fIft\fR. Data in \fIbuf\fR must be 32-bit signed samples and will be converted during the write process. The value of \fIlen\fR is specified in total samples. If its value is not evenly divisable by the number of channels, undefined behavior will occur.
+.P
+The \fBst_close\fR function dissociates the named \fIft_t\fR from its underlying file or set of functions. If the format handler was being used for output, any buffered data is written first.
+.P
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
@@ -26,10 +46,16 @@
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.
+.SH RETURN VALUE
+Upon successful completion \fBst_open_input\fR and \fBst_open_output\fR return a ft_t (which is a pointer). Otherwise, NULL is returned. TODO: Need a what to return reason for failures. Currently, relies on st_warn to print information.
.P
-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.
+\fBst_read\fR and \fBst_write\fR return the number of samples successfully read or written. If an error occurs, or the end-of-file is reached, the return value is a short item count or ST_EOF. TODO: \fBst_read\fR does not distiguish between end-of-ifle and error. Need an feof() and ferror() concept to determine which occured.
+.P
+Upon successful completion \fBst_close\fR returns 0. Otherwise, ST_EOF is returned. In either case, any further access (including another call to \fBst_close\fR()) to the handler results in undefined behavior. TODO: Need a way to return reason for failures. Currently, relies on st_warn to print information.
+.P
+Upon successful completion \fBst_seek\fR returns 0. Otherwise, ST_EOF is returned. TODO Need to set a global error and implement st_tell.
+.SH ERRORS
+TODO
.SH INTERNALS
The Sound Tools formats and effects operate on an internal buffer format
of signed 32-bit longs.
@@ -36,8 +62,8 @@
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.
+File readers translate the input samples to signed 32-bit integers
+and return the number of samples read.
For example, data in linear signed byte format is left-shifted 24 bits.
.P
This does cause problems in processing the data.
@@ -69,10 +95,10 @@
a format structure, and a private structure.
.P
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.
+the sample: sampling rate, data size (8, 16, or 32 bits),
+encoding (unsigned, signed, floating point, etc.), 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,
+needs to be byte-swapped, whether st_seek() will work, its suffix,
its file stream pointer, its
.I format
pointer, and the
@@ -164,28 +190,11 @@
may generate output samples on its own.
See echo.c for how to do this,
and see that what it does is absolutely bogus.
-.SH 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.
-.SH 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.
-.P
-Do all arithmetic conversions one stage at a time.
-I've had too many problems with "obviously clean" combinations.
-.P
-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.
.SH BUGS
The HCOM format is not re-entrant; it can only be used once in a program.
.P
+On errors, the effects currently invoke st_fail and rely on that
+calling exit(). They do not currently gracefully fail.
+.P
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.
+