ref: 923f690a2f48ca815bce4791f8d02fc8d8322eed
parent: ac589cfe04e965749aef903d16e92c4eda0f0cc5
author: Doug Cook <idigdoug@users.sourceforge.net>
date: Sat Mar 19 19:32:55 EDT 2011
Add a bunch of comments to sox.h. No functional changes.
--- a/src/sox.h
+++ b/src/sox.h
@@ -1,6 +1,6 @@
/* libSoX Library Public Interface
*
- * Copyright 1999-2009 Chris Bagwell and SoX Contributors.
+ * Copyright 1999-2011 Chris Bagwell and SoX Contributors.
*
* This source code is freely redistributable and may be used for
* any purpose. This copyright notice must be maintained.
@@ -45,10 +45,10 @@
const char *sox_version(void); /* Returns version number */
-#define SOX_SUCCESS 0
-#define SOX_EOF (-1) /* End Of File or other error */
+#define SOX_SUCCESS 0 /* Function succeeded (= 0) */
+#define SOX_EOF (-1) /* End Of File or other error (= -1) */
-enum { /* libSoX specific error codes. The rest directly map from errno. */+enum { /* libSoX-specific error codes. The rest directly map from errno. */SOX_EHDR = 2000, /* Invalid Audio Header */
SOX_EFMT, /* Unsupported data format */
SOX_ENOMEM, /* Can't alloc memory */
@@ -61,24 +61,24 @@
* C++ bool */
typedef enum {sox_false, sox_true} sox_bool;-typedef int32_t int24_t; /* But beware of the extra byte. */
-typedef uint32_t uint24_t; /* ditto */
+typedef int32_t int24_t; /* int24_t == int32_t (beware of the extra byte) */
+typedef uint32_t uint24_t; /* uint24_t == uint32_t (beware of the extra byte) */
-#define SOX_INT_MIN(bits) (1 <<((bits)-1))
-#define SOX_INT_MAX(bits) (((unsigned)-1)>>(33-(bits)))
-#define SOX_UINT_MAX(bits) (SOX_INT_MIN(bits)|SOX_INT_MAX(bits))
+#define SOX_INT_MIN(bits) (1 <<((bits)-1)) /* i.e. 0x80, 0x8000, 0x80000000 */
+#define SOX_INT_MAX(bits) (((unsigned)-1)>>(33-(bits))) /* i.e. 0x7F, 0x7FFF, 0x7FFFFFFF */
+#define SOX_UINT_MAX(bits) (SOX_INT_MIN(bits)|SOX_INT_MAX(bits)) /* i.e. 0xFF, 0xFFFF, 0xFFFFFFFF */
-#define SOX_INT8_MAX SOX_INT_MAX(8)
-#define SOX_INT16_MAX SOX_INT_MAX(16)
-#define SOX_INT24_MAX SOX_INT_MAX(24)
-#define SOX_INT32_MAX SOX_INT_MAX(32)
+#define SOX_INT8_MAX SOX_INT_MAX(8) /* = 0x7F */
+#define SOX_INT16_MAX SOX_INT_MAX(16) /* = 0x7FFF */
+#define SOX_INT24_MAX SOX_INT_MAX(24) /* = 0x007FFFFF */
+#define SOX_INT32_MAX SOX_INT_MAX(32) /* = 0x7FFFFFFF */
-typedef int32_t sox_sample_t;
+typedef int32_t sox_sample_t; /* native SoX audio sample type */
/* Minimum and maximum values a sample can hold. */
-#define SOX_SAMPLE_PRECISION 32
-#define SOX_SAMPLE_MAX (sox_sample_t)SOX_INT_MAX(32)
-#define SOX_SAMPLE_MIN (sox_sample_t)SOX_INT_MIN(32)
+#define SOX_SAMPLE_PRECISION 32 /* bits in a sox_sample_t (= 32) */
+#define SOX_SAMPLE_MAX (sox_sample_t)SOX_INT_MAX(32) /* max value for sox_sample_t (= 0x7FFFFFFF) */
+#define SOX_SAMPLE_MIN (sox_sample_t)SOX_INT_MIN(32) /* min value for sox_sample_t (= 0x80000000) */
@@ -108,7 +108,7 @@
#define SOX_SAMPLE_LOCALS sox_sample_t sox_macro_temp_sample UNUSED; \
double sox_macro_temp_double UNUSED
-#define SOX_SAMPLE_NEG SOX_INT_MIN(32)
+#define SOX_SAMPLE_NEG SOX_INT_MIN(32) /* sign bit for sox_sample_t (= 0x80000000) */
#define SOX_SAMPLE_TO_UNSIGNED(bits,d,clips) \
(uint##bits##_t)(SOX_SAMPLE_TO_SIGNED(bits,d,clips)^SOX_INT_MIN(bits))
#define SOX_SAMPLE_TO_SIGNED(bits,d,clips) \
@@ -140,7 +140,7 @@
/* MACRO to clip a data type that is greater then sox_sample_t to
- * sox_sample_t's limits and increment a counter if clipping occurs..
+ * sox_sample_t's limits and increment a counter if clipping occurs.
*/
#define SOX_SAMPLE_CLIP_COUNT(samp, clips) \
do { \@@ -168,45 +168,47 @@
-#define SOX_SIZE_MAX ((size_t)(-1))
+#define SOX_SIZE_MAX ((size_t)(-1)) /* maximum value of size_t */
+/* function-pointer type of globals.output_message_handler */
typedef void (*sox_output_message_handler_t)(unsigned level, const char *filename, const char *fmt, va_list ap);
typedef struct { /* Global parameters (for effects & formats) *//* public: */
- unsigned verbosity;
- sox_output_message_handler_t output_message_handler;
- sox_bool repeatable;
+ unsigned verbosity; /* messages are only written if globals.verbosity >= message.level */
+ sox_output_message_handler_t output_message_handler; /* client-specified message output callback */
+ sox_bool repeatable; /* true to use pre-determined timestamps and PRNG seed */
+
/* The following is used at times in libSoX when alloc()ing buffers
* to perform file I/O. It can be useful to pass in similar sized
- * data to get max performance.
- */
- size_t bufsiz, input_bufsiz;
- int32_t ranqd1; /* Can be used to re-seed libSoX's PRNG */
+ * data to get max performance. */
+ size_t bufsiz; /* default size (in bytes) used for blocks of sample data */
+ size_t input_bufsiz; /* default size (in bytes) used for blocks of input sample data */
+ int32_t ranqd1; /* Can be used to re-seed libSoX's PRNG */
/* private: */
- char const * stdin_in_use_by;
- char const * stdout_in_use_by;
- char const * subsystem;
- char * tmp_path;
- sox_bool use_magic;
+ char const * stdin_in_use_by; /* tracks the name of the handler currently using stdin */
+ char const * stdout_in_use_by; /* tracks the name of the handler currently using stdout */
+ char const * subsystem; /* tracks the name of the handler currently writing an output message */
+ char * tmp_path; /* client-configured path to use for temporary files */
+ sox_bool use_magic; /* true if client has requested use of 'magic' file-type detection */
} sox_globals_t;
-extern sox_globals_t sox_globals;
+extern sox_globals_t sox_globals; /* the SoX global settings */
-typedef double sox_rate_t;
+typedef double sox_rate_t; /* samples per second (= double) */
-#define SOX_UNSPEC 0
-#define SOX_IGNORE_LENGTH (size_t)(-1)
-typedef struct { /* Signal parameters; SOX_UNSPEC if unknown */- sox_rate_t rate; /* sampling rate */
- unsigned channels; /* number of sound channels */
- unsigned precision; /* in bits */
- size_t length; /* samples * chans in file */
+#define SOX_UNSPEC 0 /* unknown value for signal parameter (= 0) */
+#define SOX_IGNORE_LENGTH (size_t)(-1) /* unspecified length for signal.length (= -1) */
+typedef struct { /* Signal parameters; SOX_UNSPEC (= 0) if unknown */+ sox_rate_t rate; /* samples per second, 0 if unknown */
+ unsigned channels; /* number of sound channels, 0 if unknown */
+ unsigned precision; /* bits per sample, 0 if unknown */
+ size_t length; /* samples * chans in file, 0 if unknown */
double * mult; /* Effects headroom multiplier; may be null */
} sox_signalinfo_t;
typedef enum {- SOX_ENCODING_UNKNOWN ,
+ SOX_ENCODING_UNKNOWN , /* encoding has not yet been determined */
SOX_ENCODING_SIGN2 , /* signed linear 2's comp: Mac */
SOX_ENCODING_UNSIGNED , /* unsigned linear: Sound Blaster */
@@ -213,9 +215,9 @@
SOX_ENCODING_FLOAT , /* floating point (binary format) */
SOX_ENCODING_FLOAT_TEXT, /* floating point (text format) */
SOX_ENCODING_FLAC , /* FLAC compression */
- SOX_ENCODING_HCOM , /* */
- SOX_ENCODING_WAVPACK , /* */
- SOX_ENCODING_WAVPACKF , /* */
+ SOX_ENCODING_HCOM , /* Mac FSSD files with Huffman compression */
+ SOX_ENCODING_WAVPACK , /* WavPack with integer samples */
+ SOX_ENCODING_WAVPACKF , /* WavPack with float samples */
SOX_ENCODING_ULAW , /* u-law signed logs: US telephony, SPARC */
SOX_ENCODING_ALAW , /* A-law signed logs: non-US telephony, Psion */
SOX_ENCODING_G721 , /* G.721 4-bit ADPCM */
@@ -225,30 +227,30 @@
SOX_ENCODING_MS_ADPCM , /* Microsoft Compressed PCM */
SOX_ENCODING_IMA_ADPCM , /* IMA Compressed PCM */
SOX_ENCODING_OKI_ADPCM , /* Dialogic/OKI Compressed PCM */
- SOX_ENCODING_DPCM , /* */
- SOX_ENCODING_DWVW , /* */
- SOX_ENCODING_DWVWN , /* */
+ SOX_ENCODING_DPCM , /* Differential PCM: Fasttracker 2 (xi) */
+ SOX_ENCODING_DWVW , /* Delta Width Variable Word */
+ SOX_ENCODING_DWVWN , /* Delta Width Variable Word N-bit */
SOX_ENCODING_GSM , /* GSM 6.10 33byte frame lossy compression */
SOX_ENCODING_MP3 , /* MP3 compression */
SOX_ENCODING_VORBIS , /* Vorbis compression */
SOX_ENCODING_AMR_WB , /* AMR-WB compression */
SOX_ENCODING_AMR_NB , /* AMR-NB compression */
- SOX_ENCODING_CVSD , /* */
- SOX_ENCODING_LPC10 , /* */
+ SOX_ENCODING_CVSD , /* Continuously Variable Slope Delta modulation */
+ SOX_ENCODING_LPC10 , /* Linear Predictive Coding */
SOX_ENCODINGS /* End of list marker */
} sox_encoding_t;
typedef struct {- unsigned flags;
- #define SOX_LOSSY1 1 /* encode, decode, encode, decode: lossy once */
+ unsigned flags; /* lossy once (SOX_LOSSY1), lossy twice (SOX_LOSSY2), or lossless (0) */
+ #define SOX_LOSSY1 1 /* encode, decode: lossy once */
#define SOX_LOSSY2 2 /* encode, decode, encode, decode: lossy twice */
- char const * name;
- char const * desc;
+ char const * name; /* encoding name */
+ char const * desc; /* encoding description */
} sox_encodings_info_t;
-extern sox_encodings_info_t const sox_encodings_info[];
+extern sox_encodings_info_t const sox_encodings_info[]; /* the list of available encodings */
typedef enum {SOX_OPTION_NO, SOX_OPTION_YES, SOX_OPTION_DEFAULT} sox_option_t;@@ -257,7 +259,7 @@
unsigned bits_per_sample; /* 0 if unknown or variable; uncompressed value if lossless; compressed value if lossy */
double compression; /* compression factor (where applicable) */
- /* If these 3 variables are set to DEFAULT, then, during
+ /* If these 3 variables are set to SOX_OPTION_DEFAULT, then, during
* sox_open_read or sox_open_write, libSoX will set them to either
* NO or YES according to the machine or format default. */
sox_option_t reverse_bytes; /* endiannesses... */
@@ -267,9 +269,14 @@
sox_bool opposite_endian;
} sox_encodinginfo_t;
-void sox_init_encodinginfo(sox_encodinginfo_t * e);
-unsigned sox_precision(sox_encoding_t encoding, unsigned pcm_size);
+void sox_init_encodinginfo(sox_encodinginfo_t * e); /* fills in an encodinginfo with default values */
+/* Given an encoding (i.e. SIGN2) and the encoded bits_per_sample (i.e. 16),
+ * returns the number of useful bits per sample in the decoded data (i.e. 16).
+ * Returns 0 to indicate that the value returned by the format handler should
+ * be used instead of a pre-determined precision. */
+unsigned sox_precision(sox_encoding_t encoding, unsigned bits_per_sample);
+
/* Defaults for common hardware */
#define SOX_DEFAULT_CHANNELS 2
#define SOX_DEFAULT_RATE 48000
@@ -278,11 +285,11 @@
/* Loop parameters */
-typedef struct {+typedef struct { /* Looping parameters (out-of-band data) */size_t start; /* first sample */
size_t length; /* length */
- unsigned int count; /* number of repeats, 0=forever */
- unsigned char type; /* 0=no, 1=forward, 2=forward/back */
+ unsigned int count; /* number of repeats, 0=forever */
+ unsigned char type; /* 0=no, 1=forward, 2=forward/back */
} sox_loopinfo_t;
/* Instrument parameters */
@@ -289,7 +296,7 @@
/* vague attempt at generic information for sampler-specific info */
-typedef struct {+typedef struct { /* instrument information */int8_t MIDInote; /* for unity pitch playback */
int8_t MIDIlow, MIDIhi;/* MIDI pitch-bend range */
char loopmode; /* semantics of loop data */
@@ -302,38 +309,50 @@
#define SOX_LOOP_8 32 /* 8 loops: don't know ?? */
#define SOX_LOOP_SUSTAIN_DECAY 64 /* AIFF style: one sustain & one decay loop */
-/*
- * File buffer info. Holds info so that data can be read in blocks.
- */
-
-typedef struct {+typedef struct { /* File buffer info. Holds info so that data can be read in blocks. */char *buf; /* Pointer to data buffer */
- size_t size; /* Size of buffer */
- size_t count; /* Count read in to buffer */
+ size_t size; /* Size of buffer in bytes */
+ size_t count; /* Count read into buffer */
size_t pos; /* Position in buffer */
} sox_fileinfo_t;
-/*
- * Handler structure for each format.
- */
+typedef struct sox_format sox_format_t; /* file format definition */
-typedef struct sox_format sox_format_t;
-
-typedef struct {+typedef struct { /* Handler structure for each format. */unsigned sox_lib_version_code; /* Checked on load; must be 1st in struct*/
- char const * description;
- char const * const * names;
- unsigned int flags;
- int (*startread)(sox_format_t * ft);
- size_t (*read)(sox_format_t * ft, sox_sample_t *buf, size_t len);
- int (*stopread)(sox_format_t * ft);
- int (*startwrite)(sox_format_t * ft);
- size_t (*write)(sox_format_t * ft, const sox_sample_t *buf, size_t len);
- int (*stopwrite)(sox_format_t * ft);
- int (*seek)(sox_format_t * ft, uint64_t offset);
+ char const * description; /* short description of format */
+ char const * const * names; /* null-terminated array of filename extensions that are handled by this format */
+ unsigned int flags; /* File flags (SOX_FILE_...) */
+ int (*startread)(sox_format_t * ft); /* called to initialize reader (decoder) */
+ size_t (*read)(sox_format_t * ft, sox_sample_t *buf, size_t len); /* called to read (decode) a block of samples */
+ int (*stopread)(sox_format_t * ft); /* called to close reader (decoder); may be null if no closing necessary */
+ int (*startwrite)(sox_format_t * ft); /* called to initialize writer (encoder) */
+ size_t (*write)(sox_format_t * ft, const sox_sample_t *buf, size_t len); /* called to write (encode) a block of samples */
+ int (*stopwrite)(sox_format_t * ft); /* called to close writer (decoder); may be null if no closing necessary */
+ int (*seek)(sox_format_t * ft, uint64_t offset); /* called to reposition reader; may be null if not supported */
+
+ /* Array of values indicating the encodings and precisions supported for
+ * writing (encoding). Precisions specified with default precision first.
+ * Encoding, precision, precision, ..., 0, repeat. End with one more 0.
+ * Example:
+ * unsigned const* formats = {+ * SOX_ENCODING_SIGN2, 16, 24, 0, // Support SIGN2 at 16 and 24 bits, default to 16 bits.
+ * SOX_ENCODING_UNSIGNED, 8, 0, // Support UNSIGNED at 8 bits, default to 8 bits.
+ * 0 // No more supported encodings.
+ * };
+ */
unsigned const * write_formats;
+
+ /* Array of sample rates (samples per second) supported for writing (encoding).
+ * NULL if all (or almost all) rates are supported. End with 0. */
sox_rate_t const * write_rates;
+
+ /* SoX will automatically allocate a buffer in which the handler can store data.
+ * Specify the size of the buffer needed here. Usually this will be sizeof(your_struct).
+ * The buffer will be allocated and zeroed before the call to startread/startwrite.
+ * The buffer will be freed after the call to stopread/stopwrite.
+ * The buffer will be provided via format.priv in each call to the handler. */
size_t priv_size;
} sox_format_handler_t;
@@ -341,44 +360,61 @@
* Format information for input and output files.
*/
-typedef char * * sox_comments_t;
+typedef char * * sox_comments_t; /* File's metadata. Access via sox_***_comments functions. */
-size_t sox_num_comments(sox_comments_t comments);
-void sox_append_comment(sox_comments_t * comments, char const * comment);
-void sox_append_comments(sox_comments_t * comments, char const * comment);
-sox_comments_t sox_copy_comments(sox_comments_t comments);
-void sox_delete_comments(sox_comments_t * comments);
-char const * sox_find_comment(sox_comments_t comments, char const * id);
+size_t sox_num_comments(sox_comments_t comments); /* Returns the number of items in the metadata block. */
+void sox_append_comment(sox_comments_t * comments, char const * comment); /* Adds a "id=value" item to the metadata block. */
+void sox_append_comments(sox_comments_t * comments, char const * comment); /* Adds a newline-delimited list of "id=value" items to the metadata block. */
+sox_comments_t sox_copy_comments(sox_comments_t comments); /* Duplicates the metadata block. */
+void sox_delete_comments(sox_comments_t * comments); /* Frees the metadata block. */
+char const * sox_find_comment(sox_comments_t comments, char const * id); /* If "id=value" is found, return value, else return null. */
#define SOX_MAX_NLOOPS 8
-typedef struct {+typedef struct { /* comments, instrument info, loop info (out-of-band data) *//* Decoded: */
- sox_comments_t comments; /* Comment strings */
+ sox_comments_t comments; /* Comment strings in id=value format. */
sox_instrinfo_t instr; /* Instrument specification */
sox_loopinfo_t loops[SOX_MAX_NLOOPS]; /* Looping specification */
/* TBD: Non-decoded chunks, etc: */
-} sox_oob_t; /* Out Of Band data */
+} sox_oob_t;
typedef enum {lsx_io_file, lsx_io_pipe, lsx_io_url} lsx_io_type;-struct sox_format {+struct sox_format { /* Data passed to/from the format handler */char * filename; /* File name */
- sox_signalinfo_t signal; /* Signal specifications */
- sox_encodinginfo_t encoding; /* Encoding specifications */
- char * filetype; /* Type of file */
- sox_oob_t oob; /* Out Of Band data */
+
+ /* Signal specifications for reader (decoder) or writer (encoder):
+ * sample rate, #channels, precision, length, headroom multiplier.
+ * Any info specified by the user is here on entry to startread or
+ * startwrite. Info will be SOX_UNSPEC if the user provided no info.
+ * At exit from startread, 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).
+ * At exit from startwrite, 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. */
+ sox_signalinfo_t signal;
+
+ /* Encoding specifications for reader (decoder) or writer (encoder):
+ * encoding (sample format), bits per sample, compression rate, endianness.
+ * Should be filled in by startread. Values specified should be used
+ * by startwrite when it is configuring the encoding parameters. */
+ sox_encodinginfo_t encoding;
+
+ char * filetype; /* Type of file, as determined by header inspection or libmagic. */
+ sox_oob_t oob; /* comments, instrument info, loop info (out-of-band data) */
sox_bool seekable; /* Can seek on this file */
char mode; /* Read or write mode ('r' or 'w') */- size_t olength; /* Samples * chans written to file */
- size_t clips; /* Incremented if clipping occurs */
+ size_t olength; /* Samples * chans written to file */
+ size_t clips; /* Incremented if clipping occurs */
int sox_errno; /* Failure error code */
char sox_errstr[256]; /* Failure error text */
FILE * fp; /* File stream pointer */
- lsx_io_type io_type;
- long tell_off;
- long data_start;
+ lsx_io_type io_type; /* Stores whether this is a file, pipe or URL */
+ long tell_off; /* Current offset within file */
+ long data_start; /* Offset at which headers end and sound data begins (set by lsx_check_read_params) */
sox_format_handler_t handler; /* Format handler for this file */
void * priv; /* Format handler's private data area */
};
@@ -386,83 +422,106 @@
/* File flags field */
#define SOX_FILE_NOSTDIO 0x0001 /* Does not use stdio routines */
#define SOX_FILE_DEVICE 0x0002 /* File is an audio device */
-#define SOX_FILE_PHONY 0x0004 /* Phony file/device */
+#define SOX_FILE_PHONY 0x0004 /* Phony file/device (i.e. nulfile) */
#define SOX_FILE_REWIND 0x0008 /* File should be rewound to write header */
#define SOX_FILE_BIT_REV 0x0010 /* Is file bit-reversed? */
#define SOX_FILE_NIB_REV 0x0020 /* Is file nibble-reversed? */
#define SOX_FILE_ENDIAN 0x0040 /* Is file format endian? */
-#define SOX_FILE_ENDBIG 0x0080 /* If so, is it big endian? */
+#define SOX_FILE_ENDBIG 0x0080 /* For endian file format, is it big endian? */
#define SOX_FILE_MONO 0x0100 /* Do channel restrictions allow mono? */
#define SOX_FILE_STEREO 0x0200 /* Do channel restrictions allow stereo? */
#define SOX_FILE_QUAD 0x0400 /* Do channel restrictions allow quad? */
-#define SOX_FILE_CHANS (SOX_FILE_MONO | SOX_FILE_STEREO | SOX_FILE_QUAD)
-#define SOX_FILE_LIT_END (SOX_FILE_ENDIAN | 0)
-#define SOX_FILE_BIG_END (SOX_FILE_ENDIAN | SOX_FILE_ENDBIG)
+#define SOX_FILE_CHANS (SOX_FILE_MONO | SOX_FILE_STEREO | SOX_FILE_QUAD) /* No channel restrictions */
+#define SOX_FILE_LIT_END (SOX_FILE_ENDIAN | 0) /* File is little-endian */
+#define SOX_FILE_BIG_END (SOX_FILE_ENDIAN | SOX_FILE_ENDBIG) /* File is big-endian */
-int sox_format_init(void);
-void sox_format_quit(void);
+int sox_format_init(void); /* Find & load format handler plugins. */
+void sox_format_quit(void); /* Unload format handler plugins. */
-int sox_init(void);
-int sox_quit(void);
+int sox_init(void); /* Initialize effects library. */
+int sox_quit(void); /* Close effects library and unload format handler plugins. */
+/* callback to retrieve information about a format handler */
typedef const sox_format_handler_t *(*sox_format_fn_t)(void);
-typedef struct {- char *name;
- sox_format_fn_t fn;
+typedef struct { /* Information about a loaded format handler: name and function pointer */+ char *name; /* Name of format handler */
+ sox_format_fn_t fn; /* Function to call to get format handler's information */
} sox_format_tab_t;
-extern sox_format_tab_t sox_format_fns[];
+extern sox_format_tab_t sox_format_fns[]; /* table of format handler names and functions */
+/* Opens a decoding session for a file. Returned handle must be closed with sox_close(). */
sox_format_t * sox_open_read(
- char const * path,
- sox_signalinfo_t const * signal,
- sox_encodinginfo_t const * encoding,
- char const * filetype);
+ char const * path, /* Path to file to be opened (required). */
+ sox_signalinfo_t const * signal, /* Information already known about audio stream, or NULL if none. */
+ sox_encodinginfo_t const * encoding, /* Information already known about sample encoding, or NULL if none. */
+ char const * filetype); /* Previously-determined file type, or NULL to auto-detect. */
+
+/* Opens a decoding session for a memory buffer. Returned handle must be closed with sox_close(). */
sox_format_t * sox_open_mem_read(
- void * buffer,
- size_t buffer_size,
- sox_signalinfo_t const * signal,
- sox_encodinginfo_t const * encoding,
- char const * filetype);
+ void * buffer, /* Pointer to audio data buffer (required). */
+ size_t buffer_size, /* Number of bytes to read from audio data buffer. */
+ sox_signalinfo_t const * signal, /* Information already known about audio stream, or NULL if none. */
+ sox_encodinginfo_t const * encoding, /* Information already known about sample encoding, or NULL if none. */
+ char const * filetype); /* Previously-determined file type, or NULL to auto-detect. */
+
+/* Returns true if the format handler for the specified file type supports the specified encoding. */
sox_bool sox_format_supports_encoding(
- char const * path,
- char const * filetype,
- sox_encodinginfo_t const * encoding);
+ char const * path, /* Path to file to be examined (required if filetype is NULL). */
+ char const * filetype, /* Previously-determined file type, or NULL to use extension from path. */
+ sox_encodinginfo_t const * encoding); /* Encoding for which format handler should be queried. */
+
+/* Gets the format handler for a specified file type. */
sox_format_handler_t const * sox_write_handler(
- char const * path,
- char const * filetype,
- char const * * filetype1);
+ char const * path, /* Path to file (required if filetype is NULL). */
+ char const * filetype, /* Filetype for which handler is needed, or NULL to use extension from path. */
+ char const * * filetype1); /* Receives the filetype that was detected. Pass NULL if not needed. */
+
+/* Opens an encoding session for a file. Returned handle must be closed with sox_close(). */
sox_format_t * sox_open_write(
- char const * path,
- sox_signalinfo_t const * signal,
- sox_encodinginfo_t const * encoding,
- char const * filetype,
- sox_oob_t const * oob,
- sox_bool (*overwrite_permitted)(const char *filename));
+ char const * path, /* Path to file to be written (required). */
+ sox_signalinfo_t const * signal, /* Information about desired audio stream (required). */
+ sox_encodinginfo_t const * encoding, /* Information about desired sample encoding, or NULL to use defaults. */
+ char const * filetype, /* Previously-determined file type, or NULL to auto-detect. */
+ sox_oob_t const * oob, /* Out-of-band data to add to file, or NULL if none. */
+ sox_bool (*overwrite_permitted)(const char *filename)); /* Called if file exists to determine whether overwrite is ok. */
+
+/* Opens an encoding session for a memory buffer. Returned handle must be closed with sox_close(). */
sox_format_t * sox_open_mem_write(
- void * buffer,
- size_t buffer_size,
- sox_signalinfo_t const * signal,
- sox_encodinginfo_t const * encoding,
- char const * filetype,
- sox_oob_t const * oob);
+ void * buffer, /* Pointer to audio data buffer that will receive data (required). */
+ size_t buffer_size, /* Maximum number of bytes to write to audio data buffer. */
+ sox_signalinfo_t const * signal, /* Information about desired audio stream (required). */
+ sox_encodinginfo_t const * encoding, /* Information about desired sample encoding, or NULL to use defaults. */
+ char const * filetype, /* Previously-determined file type, or NULL to auto-detect. */
+ sox_oob_t const * oob); /* Out-of-band data to add to file, or NULL if none. */
+
+/* Opens an encoding session for a memstream buffer. Returned handle must be closed with sox_close(). */
sox_format_t * sox_open_memstream_write(
- char * * buffer_ptr,
- size_t * buffer_size_ptr,
- sox_signalinfo_t const * signal,
- sox_encodinginfo_t const * encoding,
- char const * filetype,
- sox_oob_t const * oob);
+ char * * buffer_ptr, /* Receives pointer to audio data buffer that receives data (required). */
+ size_t * buffer_size_ptr, /* Receives size of data written to audio data buffer (required). */
+ sox_signalinfo_t const * signal, /* Information about desired audio stream (required). */
+ sox_encodinginfo_t const * encoding, /* Information about desired sample encoding, or NULL to use defaults. */
+ char const * filetype, /* Previously-determined file type, or NULL to auto-detect. */
+ sox_oob_t const * oob); /* Out-of-band data to add to file, or NULL if none. */
+
+/* Reads samples from a decoding session into a sample buffer. Returns # of samples decoded, or 0 for EOF. */
size_t sox_read(sox_format_t * ft, sox_sample_t *buf, size_t len);
+
+/* Writes samples to an encoding session from a sample buffer. Returns # of samples encoded. */
size_t sox_write(sox_format_t * ft, const sox_sample_t *buf, size_t len);
+
+/* Closes an encoding or decoding session. */
int sox_close(sox_format_t * ft);
#define SOX_SEEK_SET 0
+
+/* Sets the location at which next samples will be decoded. Returns SOX_SUCCESS if successful. */
int sox_seek(sox_format_t * ft, uint64_t offset, int whence);
-sox_format_handler_t const * sox_find_format(char const * name, sox_bool no_dev);
+/* Finds a format handler by name. */
+sox_format_handler_t const * sox_find_format(char const * name, sox_bool ignore_devices);
/*
* Structures for effects.
@@ -470,87 +529,119 @@
#define SOX_MAX_EFFECTS 20
-#define SOX_EFF_CHAN 1 /* Can alter # of channels */
-#define SOX_EFF_RATE 2 /* Can alter sample rate */
-#define SOX_EFF_PREC 4 /* Can alter sample precision */
-#define SOX_EFF_LENGTH 8 /* Can alter audio length */
-#define SOX_EFF_MCHAN 16 /* Can handle multi-channel */
-#define SOX_EFF_NULL 32 /* Does nothing */
-#define SOX_EFF_DEPRECATED 64 /* Is living on borrowed time */
-#define SOX_EFF_GAIN 128 /* Does not support gain -r */
-#define SOX_EFF_MODIFY 256 /* Does not modify samples */
-#define SOX_EFF_ALPHA 512 /* Is experimental/incomplete */
-#define SOX_EFF_INTERNAL 1024 /* Is in libSoX but not sox */
+#define SOX_EFF_CHAN 1 /* Effect might alter the number of channels */
+#define SOX_EFF_RATE 2 /* Effect might alter sample rate */
+#define SOX_EFF_PREC 4 /* Effect might alter sample precision */
+#define SOX_EFF_LENGTH 8 /* Effect might alter audio length */
+#define SOX_EFF_MCHAN 16 /* Effect handles multiple channels internally */
+#define SOX_EFF_NULL 32 /* Effect does nothing (can be optimized out of flow) */
+#define SOX_EFF_DEPRECATED 64 /* Effect will soon be removed from SoX */
+#define SOX_EFF_GAIN 128 /* Effect does not support gain -r */
+#define SOX_EFF_MODIFY 256 /* Effect does not modify samples (just watches as data goes through) */
+#define SOX_EFF_ALPHA 512 /* Effect is experimental/incomplete */
+#define SOX_EFF_INTERNAL 1024 /* Effect present libSoX but not valid for use by SoX command-line tools */
typedef enum {sox_plot_off, sox_plot_octave, sox_plot_gnuplot, sox_plot_data} sox_plot_t;typedef struct sox_effect sox_effect_t;
-struct sox_effects_globals { /* Global parameters (for effects) */+struct sox_effects_globals { /* Global parameters for effects */sox_plot_t plot; /* To help the user choose effect & options */
- sox_globals_t * global_info;
+ sox_globals_t * global_info; /* Pointer to associated SoX globals */
};
-typedef struct sox_effects_globals sox_effects_globals_t;
-extern sox_effects_globals_t sox_effects_globals;
+typedef struct sox_effects_globals sox_effects_globals_t; /* Global parameters for effects */
+extern sox_effects_globals_t sox_effects_globals; /* Global parameters for effects */
-typedef struct {- char const * name;
- char const * usage;
- unsigned int flags;
+typedef struct { /* Effect handler information */+ char const * name; /* Effect name */
+ char const * usage; /* Short explanation of parameters accepted by effect */
+ unsigned int flags; /* Combination of SOX_EFF_*** flags */
- int (*getopts)(sox_effect_t * effp, int argc, char *argv[]);
- int (*start)(sox_effect_t * effp);
+ int (*getopts)(sox_effect_t * effp, int argc, char *argv[]); /* Called to parse command-line arguments (called once per effect) */
+ int (*start)(sox_effect_t * effp); /* Called to initialize effect (called once per flow) */
int (*flow)(sox_effect_t * effp, const sox_sample_t *ibuf,
- sox_sample_t *obuf, size_t *isamp, size_t *osamp);
- int (*drain)(sox_effect_t * effp, sox_sample_t *obuf, size_t *osamp);
- int (*stop)(sox_effect_t * effp);
- int (*kill)(sox_effect_t * effp);
- size_t priv_size;
+ sox_sample_t *obuf, size_t *isamp, size_t *osamp); /* Called to process samples */
+ int (*drain)(sox_effect_t * effp, sox_sample_t *obuf, size_t *osamp); /* Called to finish getting output after input is complete */
+ int (*stop)(sox_effect_t * effp); /* Called to shut down effect (called once per flow) */
+ int (*kill)(sox_effect_t * effp); /* Called to shut down effect (called once per effect) */
+ size_t priv_size; /* Size of private data SoX should pre-allocate for effect */
} sox_effect_handler_t;
-struct sox_effect {- sox_effects_globals_t * global_info; /* global parameters */
- sox_signalinfo_t in_signal;
- sox_signalinfo_t out_signal;
- sox_encodinginfo_t const * in_encoding;
- sox_encodinginfo_t const * out_encoding;
- sox_effect_handler_t handler;
- sox_sample_t * obuf; /* output buffer */
- size_t obeg, oend; /* consumed, total length */
+struct sox_effect { /* Effect information */+ sox_effects_globals_t * global_info; /* global effect parameters */
+ sox_signalinfo_t in_signal; /* Information about the incoming data stream */
+ sox_signalinfo_t out_signal; /* Information about the outgoing data stream */
+ sox_encodinginfo_t const * in_encoding; /* Information about the incoming data encoding */
+ sox_encodinginfo_t const * out_encoding; /* Information about the outgoing data encoding */
+ sox_effect_handler_t handler; /* The handler for this effect */
+ sox_sample_t * obuf; /* output buffer */
+ size_t obeg; /* output buffer consumed */
+ size_t oend; /* output buffer total length */
size_t imin; /* minimum input buffer size */
size_t clips; /* increment if clipping occurs */
size_t flows; /* 1 if MCHAN, # chans otherwise */
size_t flow; /* flow # */
- void * priv; /* Effect's private data area */
+ void * priv; /* Effect's private data area */
};
+/* Finds the effect handler with the given name */
sox_effect_handler_t const * sox_find_effect(char const * name);
+
+/* Creates an effect using the given handler */
sox_effect_t * sox_create_effect(sox_effect_handler_t const * eh);
+
+/* Applies the command-line options to the effect. Returns the number of arguments consumed. */
int sox_effect_options(sox_effect_t *effp, int argc, char * const argv[]);
/* Effects chain */
+/* Function that returns information about an effect handler */
typedef const sox_effect_handler_t *(*sox_effect_fn_t)(void);
+
+/* Array of known effect handlers */
extern sox_effect_fn_t sox_effect_fns[];
-struct sox_effects_chain {- sox_effect_t * effects[SOX_MAX_EFFECTS];
- unsigned length;
- sox_sample_t **ibufc, **obufc; /* Channel interleave buffers */
- sox_effects_globals_t global_info;
- sox_encodinginfo_t const * in_enc;
- sox_encodinginfo_t const * out_enc;
+struct sox_effects_chain { /* Chain of effects to be applied to a stream */+ sox_effect_t * effects[SOX_MAX_EFFECTS]; /* Array of effects to be applied to a stream */
+ unsigned length; /* Number of effects to be applied */
+ sox_sample_t **ibufc; /* Channel interleave buffer */
+ sox_sample_t **obufc; /* Channel interleave buffer */
+ sox_effects_globals_t global_info; /* Copy of global effects settings */
+ sox_encodinginfo_t const * in_enc; /* Input encoding */
+ sox_encodinginfo_t const * out_enc; /* Output encoding */
};
typedef struct sox_effects_chain sox_effects_chain_t;
+
+/* Initializes an effects chain. Returned handle must be closed with sox_delete_effects_chain(). */
sox_effects_chain_t * sox_create_effects_chain(
sox_encodinginfo_t const * in_enc, sox_encodinginfo_t const * out_enc);
+
+/* Closes an effects chain. */
void sox_delete_effects_chain(sox_effects_chain_t *ecp);
+
+/* Adds an effect to the effects chain, returns SOX_SUCCESS if successful. */
int sox_add_effect( sox_effects_chain_t * chain, sox_effect_t * effp, sox_signalinfo_t * in, sox_signalinfo_t const * out);
+
+/* Runs the effects chain, returns SOX_SUCCESS if successful. */
int sox_flow_effects(sox_effects_chain_t *, int (* callback)(sox_bool all_done, void * client_data), void * client_data);
+
+/* Gets the number of clips that occurred while running an effects chain */
size_t sox_effects_clips(sox_effects_chain_t *);
+
+/* Shuts down an effect (calls stop on each of its flows) */
size_t sox_stop_effect(sox_effect_t *effp);
+
+/* Adds an already-initialized effect to the end of the chain */
void sox_push_effect_last(sox_effects_chain_t *chain, sox_effect_t *effp);
+
+/* Removes and returns an effect from the end of the chain */
sox_effect_t *sox_pop_effect_last(sox_effects_chain_t *chain);
+
+/* Shut down and delete an effect */
void sox_delete_effect(sox_effect_t *effp);
+
+/* Shut down and delete the last effect in the chain */
void sox_delete_effect_last(sox_effects_chain_t *chain);
+
+/* Shut down and delete all effects in the chain */
void sox_delete_effects(sox_effects_chain_t *chain);
/* The following routines are unique to the trim effect.
@@ -568,10 +659,17 @@
void sox_crop_clear_start(sox_effect_t * effp);
typedef int (* sox_playlist_callback_t)(void *, char *);
+
+/* Returns true if the specified file is a known playlist file type */
sox_bool sox_is_playlist(char const * filename);
+
+/* Parses the specified playlist file */
int sox_parse_playlist(sox_playlist_callback_t callback, void * p, char const * const listname);
+/* Converts a SoX error code into an error string. */
char const * sox_strerror(int sox_errno);
+
+/* Writes an error message regarding the specified filename to the given output file stream */
void sox_output_message(FILE *file, const char *filename, const char *fmt, va_list ap);
/* WARNING BEGIN
@@ -611,4 +709,4 @@
}
#endif
-#endif
+#endif /* SOX_H */