Tribblix: manual page: libsox

SoX(3) Sound eXchange_ng SoX(3)

NAME

libsox_ng, another audio file-format and effect library

SYNOPSIS

#include <sox_ng.h>

int sox_format_init(void);

void sox_format_quit(void);

sox_format_t *sox_open_read(const char *path, const sox_signalinfo_t *info, sox_encodinginfo_t const *encoding, const char *filetype);

sox_format_t *sox_open_write(char const *filename, sox_signalinfo_t const *info, sox_encodinginfo_t const *encoding, char const *filetype, sox_oob_t const *oob, sox_bool (*overwrite_permitted)(char const *filename));

sox_size_t sox_read(sox_format_t *ft, sox_sample_t *buf, sox_size_t len);

sox_size_t sox_write(sox_format_t *ft, sox_sample_t const *buf, sox_size_t len);

int sox_close(sox_format_t Ift);

int sox_seek(sox_format_t *ft, sox_size_t offset, int whence);

sox_effect_handler_t const *sox_find_effect(char const *name);

sox_effect_t *sox_create_effect(sox_effect_handler_t const *eh);

int sox_effect_options(sox_effect_t *effp, int argc, char * const argv[]);

sox_effects_chain_t *sox_create_effects_chain(sox_encodinginfo_t const *in_enc, sox_encodinginfo_t const *out_enc);

int sox_add_effect(sox_effects_chaint_t *chain, sox_effect_t*effp, sox_signalinfo_t *in, sox_signalinfo_t const *out);

void sox_delete_effects_chain(sox_effects_chain_t *ecp);

cc file.c -o file -lsox_ng

DESCRIPTION

libsox_ng is a library of sound sample file format readers/writers
and sound effects processors. It is mainly developed for use by SoX
but is useful for any sound application.

This is not really a manual for the libsox_ng API; it is a quick
introduction to the basic operations for reading and writing audio
files and to use effect chains, followed by notes on how to write new
format handlers and effects. For an exhaustive description of the
libsox_ng API see http://martinwguy.net/test/soxygen/sox_8h.html

sox_format_init() performs initialization required by all file format
handlers. If compiled with dynamic library support, this will detect
and initialize all external libraries. It should be called before
any file operations are performed.

sox_format_quit() performs some required cleanup related to all file
format handlers.

sox_open_read() opens a file for reading whose name is the string
pointed to by path and associates a sox_format_t with it. A special
name of "-" reads data from stdin. If info is not NULL, it specifies
the data format of the input file and if encoding is not NULL it
gives information already known about the sample encoding. These are
normally only needed for headerless audio files where that
information is not stored in the file. If filetype is non-NULL, it
specifies the file type. If it is NULL, the file type is determined
by looking at the file header and/or the filename extension. Upon
successful completion, sox_open_read() returns a handle to the new
session, which should eventually be closed with sox_close(), or NULL
otherwise.

[3] TODO: Need a way to return reason for failures. Currently, it
relies on sox_warn to print information.

sox_open_write() opens a file for writing whose name is the string
pointed to by path and associates a sox_format_t with it. A special
name of "-" writes data to stdout. info specifies the data format of
the output file. The info structure from an input format handler can
be used to copy data using the same format. If encoding is not NULL,
it specifies the desired sample encoding. Since most file formats
can write data in different data formats, this usually has to be
specified; if NULL, a default is used. If filetype is non-NULL, it
specifies the file type. If it is NULL, SoX derives the file type
from the filename extension. If oob is not NULL, it specifies out-
of-band data to add to the file such as comments, instrument
information and loop points if the file type supports them.
sox_open_write() returns a handle to the new session, which must be
closed with sox_close(), or NULL on failure.

sox_read() reads len samples into buf using the format handler ft.
All data is converted to 32-bit signed samples before being placed in
buf. The value of len is in total samples and if its value is not
divisable by the number of channels, anything might happen. It
returns the number of samples read or zero at the end of the file or
if an error occurred. sox_read's return value does not distiguish
between the end of a file and an error but you can inspect
ft->sox_errno to tell the difference. It should be SOX_SUCCESS or
SOX_EOF unless some other error has occurred previously; you can
clear ft->sox_errno to 0 beforehand to be sure.

sox_read() and sox_write() return the number of samples successfully
read or written. If an error occurs or the end of the file is
reached, the return value is a short item count or SOX_EOF, depending
on the function.

sox_write() writes len samples from buf using the format handler ft.
Data in buf must be 32-bit signed samples which are converted during
the writing process. The value of len is specified in total samples
and must be divisable by the number of channels, otherwise unexpected
things will occur. It returns the actual number of samples encoded,
zero if an error occurred.

sox_close() dissociates a sox_format_t from its underlying file and
set of functions. If the format handler was used for output, any
buffered data is written first. It returns SOX_SUCCESS if everything
went well or the return value from the format's stopread or stopwrite
(probably SOX_EOF) otherwise and the precise reason for failure is
passed to sox_warn() or sox_fail() to print the information. In
either case, no further use should be made to the handle, not even
another call to sox_close().

sox_find_effect() finds the effect called name, returning a pointer
to its sox_effect_handler_t if it exists, NULL otherwise.

sox_create_effect() instantiates an effect into a sox_effect_t given
the address of a sox_effect_handler_t Any missing methods are
automatically set to the appropriate nothing method. It returns a
pointer to the new effect or NULL if it was not found or had problems
starting up.

sox_effect_options() passes options into an effect to control its
behavior. If it succeeds, effp->in_signal may[1] contain the rate
and channel count at which it requires input data and
effp->out_signal may contain the rate and channel count it outputs.
When it is present, this information is used[2] to ensure that
appropriate effects are placed in the effects chain to handle any
needed conversions. It returns the number of arguments consumed or
SOX_EOF if any invalid options were passed.

[1] Does the effect have the option of setting these or can you
optionally set them?

[2] Does it do this automatically or do you have to add the right
effects?

Setting options is only supported before the effect is started. The
behavior is undefined if its called when the effect has already
started.

sox_create_effects_chain() creates an effects chain to which effects
can be added. in_enc and out_enc are the signal encoding of the
chain's input and output. The pointers to in_enc and out_enc are
stored internally, so their memory should not be freed until the
effect chain has been deleted. Their values may change to reflect
new input or output encodings when effects start up or are restarted.
It returns a pointer to the new chain or NULL if something went
wrong.

sox_add_effect adds an effect to a chain. in specifies the input
signal info for the effect, out is a suggestion as to what the output
signal should be but, depending on the effect options given and on
in, the effect can choose to do differently. Whatever output rate
and channels the effect produces are written back to in. in should
be stored and passed to each call to sox_add_effect so that changes
propagate to each new effect. It returns SOX_SUCCESS if it was
successful.

sox_delete_effects_chain() closes an effects chain and releases any
resources reserved during the creation of the chain. It calls
sox_delete_effects() if any effects are still in the chain.

SoX includes skeleton C files to assist you in writing new formats
(skelform.c) and effects (skeleff.c). New formats can often just
deal with the header and then use raw.c's routines for reading and
writing.

example0.c and example1.c are a good starting point to see how to
write applications using libsox_ng and sox_ng.c itself is also a good
reference.

RETURN VALUE

sox_seek returns 0 if it succeeds, SOX_EOF otherwise

[6] TODO Need to set a global error and implement sox_tell.

ERRORS

[7] TODO

INTERNALS

SoX's formats and effects operate with an internal sample format of
signed 32-bit integer. 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 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.

Representing samples as integers can cause problems when processing
audio. For example, if an effect to mix down left and right channels
into one monophonic channel were to use the line
*obuf++ = (*ibuf++ + *ibuf++)/2;
distortion may occur since the intermediate addition can overflow 32
bits.
*obuf++ = *ibuf++/2 + *ibuf++/2;
would get round the overflow but at the expense of the least
significant bit.

Stereo data is stored with the left and right speaker data in
successive samples and quadraphonic data is stored 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 stored 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
audio: sampling rate, data size (8, 16 or 32 bits), encoding
(unsigned, signed, floating point etc.), and the number of sound
channels. It also contains other state information: whether the
sample file needs to be byte-swapped, whether sox_seek() will work,
its suffix, its file stream pointer, its format pointer and the
format's private structure.

The private area is 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 an example of 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 nto the header. The private area is usually not very
large and some effects, such as echo, lsx_malloc() larger areas for
delay lines and such.

A format has 6 routines:

startread Set up the format parameters, read in a data
header or do anything else that 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. it
returns the number of samples actually read.

stopread Do what needs to be done when it has finished
reading.

startwrite Set up the format parameters, maybe write out a
data header and any any other preliminaries for
writing the format.

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, it will return [7].

[7] What? SOX_EOF or a short-or-0 number of samples?

stopwrite Typically, fix up the file header or whatever
else needs to be done.

EFFECTS

Each effect runs with one input and one output stream. An effect's
implementation comprises six functions that may be called according
to the following flow diagram:
LOOP (invocations with different parameters)
getopts
LOOP (invocations with the same parameters)
LOOP (channels)
start
LOOP (while there is input audio to process)
LOOP (channels)
flow
LOOP (while there is output audio to generate)
LOOP (channels)
drain
LOOP (channels)
stop
kill
Functions that an effect does not need can be NULL. An effect that
is marked `MCHAN' does not use the LOOP (channels) lines and must
perform multiple channel processing inside the affected functions.
Multiple effect instances may be processed in parallel.

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 SOX_EOF, this means
that the effect will not read any more data and
can be used to switch to drain mode sooner.

drain is called when there are no more input data
samples. If the effect wishes to generate more
data samples, it copies the generated data into
the given buffer and returns the number of
samples generated. If it fills the buffer, it
will be called again; The echo effect uses this
to fade away.

stop is called when there are no more input samples
and no more output samples to process. It is
typically used to close or free resources such as
memory and temporary files that were allocated
during start. See echo.c for an example.

kill is called to allow resources allocated by getopts
to be released. See pad.c for an example.

LINKING

How you link against libsox_ng depends on how SoX was built on your
system. For a static build, just link against the library. For a
dynamic build, use libtool to link with the correct linker flags. See
the libtool manual for details; basically, you use it like this:
libtool --mode=link gcc -o prog /path/to/libsox_ng.la

LICENSE

Copyright 1991-2015 Lance Norskog, Chris Bagwell and sundry
contributors.

This library is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License version 2.1 as
published by the Free Software Foundation.

This library is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.

AUTHORS

The many authors and contributors are listed in the README file that
is distributed with the source code.