sox_ng/libsoxformat_ng.3

'\" t
'\" The line above instructs most `man' programs to invoke tbl
'\"
'\" Separate paragraphs; not the same as PP which resets indent level.
.de SP
.if t .sp .5
.if n .sp
..
'\"
'\" Replacement em-dash for nroff (default is too short).
.ie n .ds m " -
.el .ds m \(em
'\"
'\" Placeholder macro for if longer nroff arrow is needed.
.ds RA \(->
'\"
'\" Decimal point set slightly raised
.if t .ds d \v'-.15m'.\v'+.15m'
.if n .ds d .
'\"
'\" Enclosure macro for examples
'\" From groff-1.23 CW is undeclared by default but nroff is CW anyway
.if n .ftr CW R
.de XE
.SP
.nf
.ft CW
..
.de XX
.ft R
.SP
.fi
..
.TH LIBSOXFORMAT_NG 3 "January 5, 2026" "SoX" "Sound eXchange_ng"
.SH NAME
libsoxformat_ng \- libsox_ng format handlers' internals
.SH SYNOPSIS
.XE
#include "sox_i.h"

typedef struct {
    ...
} priv_t;

static int startread(sox_format_t *ft);
static size_t read(sox_format_t *ft, sox_sample_t *buf, size_t len);
static int stopread(sox_format_t *ft);
static int startwrite(sox_format_t *ft);
static size_t write(sox_format_t *ft, sox_sample_t *buf, size_t len);
static int stopwrite(sox_format_t *ft);
static int seek(sox_format_t *ft, sox_uint64_t offset);

sox_format_handler_t const *lsx_whatever_format_fn(void)
{
  static char const description[] = "Whatever format";
  static char const * const names = { "wvr", NULL };
  static unsigned const write_encodings[] = {
    SOX_ENCODING_*, \fR{\fP\fIbitwidth\fP,\fR}\fP 0,
    ..., 0,
    0};
  static sox_format_handler_t const handler = { SOX_LIB_VERSION_CODE,
    description, names, \fR{\fPSOX_FILE_* |\fR}\fP 0,
    startread, read, stopread,
    startwrite, write, stopwrite,
    seek, write_encodings,
    sizeof(priv_t)
  };
  return &handler;
}
.XX
.SH DESCRIPTION
How SoX format handlers work and how to write a new one.
.P
SoX's formats and effects operate with an internal sample format of
signed 32-bit integers. 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.
.P
Stereo data is stored with the left and right channels' data
in successive samples and
quadraphonic data is stored left front, right front, left rear, right rear.
.P
A format handler is responsible for translating between sound sample files
and an internal buffer in which sound data is stored as signed 32-bit integers
with a fixed sampling rate.
.XE
.ne 5
struct sox_format_handler {
  unsigned     sox_lib_version_code;        /* Checked on load           */
  char       * description;                 /* Description of the format */
  char     * * names;                       /* Filename extensions       */
  unsigned int flags;                       /* File flags (SOX_FILE_*)   */
  sox_format_handler_startread  startread;  /* Initialize decoder        */
  sox_format_handler_read       read;       /* Decode a block of samples */
  sox_format_handler_stopread   stopread;   /* Close decoder             */
  sox_format_handler_startwrite startwrite; /* Initialize encoder        */
  sox_format_handler_write      write;      /* Encode a block of samples */
  sox_format_handler_stopwrite  stopwrite;  /* Close encoder             */
  sox_format_handler_seek       seek;       /* Reposition reader         */
  unsigned   * write_formats;               /* Encodings and precision   */
  unsigned   * write_rates;                 /* Sample rates              */
  size_t       priv_size;                   /* sizeof(priv_t)            */
};
.XX
.TP
.B sox_uint32_t sox_lib_version_code
Checked when format plugins are loaded to ensure they were compiled
for the same version of libsox that is calling them.
.TP
.B char *description
A short description of the format, printed by \fBsox_ng\ --help-format\fR.
.TP
.B char **names
A null-terminated array of filename extensions (without the dot) that
are handled by this format.
.TP
.B unsigned int flags
The logical OR of:
.sp .5
.RS
.TS
lB l.
SOX_FILE_NOSTDIO	The handler does not use stdio routines
SOX_FILE_DEVICE	The file is an audio device
SOX_FILE_PHONY	Phony file/device (for example /dev/null)
SOX_FILE_REWIND	File should be rewound to write header
SOX_FILE_BIT_REV	Is the file bit-reversed?
SOX_FILE_NIB_REV	Is the file nibble-reversed?
SOX_FILE_ENDIAN	Is the file format endian?
SOX_FILE_ENDBIG	For an endian file format, is it big endian?
SOX_FILE_MONO	Do channel restrictions allow mono?
SOX_FILE_STEREO	Do channel restrictions allow stereo?
SOX_FILE_QUAD	Do channel restrictions allow quad?
SOX_FILE_LIT_END	A mask to OR in if the file is little-endian
SOX_FILE_BIG_END	A mask to OR in if the file is big-endian
SOX_FILE_CHANS	T{
A mask to interrogate channels restrictions.
If \fBflags\ &\ SOX_FILE_CHANS\fR is 0, there are no restrictions
T}
.TE
.RE
.TP
.B int (*startread)(sox_format_t *\fIfp\fP)
A function to set up the format parameters, read in a data header and
do anything else that needs to be done before decoding data.
It returns \fBSOX_SUCCESS\fR if all went well,
or a non-zero value if there was some problem with the file,
in which case \fBread\fR and \fBstopread\fR will not be called.
.SP
At exit from \fBstartread\fP, \fBsox_format_t.signal\fP should be
completely filled in, using either data from the file's headers (if available)
or whatever the format is guessing/assuming if header data is not available.
.TP
.B size_t (*read)(sox_format_t *\fIft\fP, sox_sample_t *\fIbuf\fP, size_t \fIlen\fP)
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.
.TP
.B int (*stopread)(sox_format_t *\fIft\fP)
Does what needs to be done when it has finished reading.
.TP
.B int (*startwrite)(sox_format_t *\fIft\fP)
Set up the format parameters, maybe write out a data header,
and any other preliminaries for encoding the format.
It returns \fBSOX_SUCCESS\fR if all went well,
or a non-zero value if there was some problem,
in which case \fBwrite\fR and \fBstopwrite\fR will not be called.
.SP
At exit from \fBstartwrite\fP, \fBsox_format_t.signal\fP should be
completely filled in, using either the data that was specified, or
values chosen by the format based on the format's defaults or capabilities.
.TP
.B size_t (*write)(sox_format_t *\fIft\fP, sox_sample_t *\fIbuf\fP, size_t \fIlen\fP)
Given a buffer and a length, copy that many samples out of the buffer,
convert them from signed longs to the appropriate data types
and write them to the file.
If it can't write all the samples out, it returns a lesser number of samples.
.TP
.B int (*stopwrite)(sox_format_t *\fIft\fP)
Fix up the file header or whatever else needs to be done
before closing the file.
.TP
.B unsigned *write_formats
An array of values indicating the encodings and precisions supported for
writing (encoding). Precisions are specified with default precision first,
and with 0 and repeat, and list ends with with one more 0.
.SP
An example for a format that supports signed integers at depths of 16 and 24 bits
with a default of 16, and 8-bit unsigned:
.XE
.ne 4
   unsigned const * formats = {
     SOX_ENCODING_SIGN2, 16, 24, 0,
     SOX_ENCODING_UNSIGNED, 8, 0,
     0 };
.XX
.TP
.B sox_rate_t *write_rates
An zero-terminated array of sample rates that are supported for writing,
NULL if all rates are supported.
.TP
.B size_t priv_size
The size of the format's \fBpriv_t\fR.
SoX automatically allocates a buffer in which the handler can store
its private data, of which the size is specified here.
Usually this will be \fBsizeof(priv_t)\fR.
The buffer is allocated and zeroed before the call to
\fBstartread\fR/\fBstartwrite\fR,
is freed after the call to \fBstopread\fR/\fBstopwrite\fR
and is provided via \fBft->priv\fR in each call to the handler's functions.
.SH EXAMPLES
The SoX source code includes a skeleton C file to assist you in writing new
formats (\fBsrc/skelform.c\fR).
New formats can often just deal with the header and then use
\fBraw.c\fR's routines for reading and writing.
.SH SEE ALSO
.BR sox_ng (1),
.BR libsox_ng (3),
.BR soxformat_ng (7) and
\f(CWsrc/skelform.c\fR in the SoX source code.