src/sox.h

   1 /* libSoX Library Public Interface
   2  *
   3  * Copyright 1999-2009 Chris Bagwell and SoX Contributors.
   4  *
   5  * This source code is freely redistributable and may be used for
   6  * any purpose.  This copyright notice must be maintained.
   7  * Chris Bagwell And SoX Contributors are not responsible for
   8  * the consequences of using this software.
   9  */
  10
  11 #ifndef SOX_H
  12 #define SOX_H
  13
  14 #include <limits.h>
  15 #include <stdarg.h>
  16 #include <stddef.h> /* Ensure NULL etc. are available throughout SoX */
  17 #include <stdio.h>
  18 #include <stdlib.h>
  19 #include "soxstdint.h"
  20
  21 #if defined(__cplusplus)
  22 extern "C" {
  23 #endif
  24
  25 /* Avoid warnings about unused parameters. */
  26 #ifdef __GNUC__
  27 #define UNUSED __attribute__ ((unused))
  28 #define PRINTF __attribute__ ((format (printf, 1, 2)))
  29 #else
  30 #define UNUSED
  31 #define PRINTF
  32 #endif
  33 #ifdef _MSC_VER
  34 #define LSX_UNUSED_VAR(x) ((void)(x))
  35 #else
  36 #define LSX_UNUSED_VAR(x) ((void)0)
  37 #endif
  38
  39 /* The following is the API version of libSoX.  It is not meant
  40  * to follow the version number of SoX but it has historically.
  41  * Please do not count on these numbers being in sync.
  42  */
  43 #define SOX_LIB_VERSION(a,b,c) (((a) << 16) + ((b) << 8) + (c))
  44 #define SOX_LIB_VERSION_CODE SOX_LIB_VERSION(14, 3, 2)
  45
  46 const char *sox_version(void);   /* Returns version number */
  47
  48 #define SOX_SUCCESS 0
  49 #define SOX_EOF (-1)             /* End Of File or other error */
  50
  51 enum { /* libSoX specific error codes.  The rest directly map from errno. */
  52   SOX_EHDR = 2000,     /* Invalid Audio Header */
  53   SOX_EFMT,            /* Unsupported data format */
  54   SOX_ENOMEM,          /* Can't alloc memory */
  55   SOX_EPERM,           /* Operation not permitted */
  56   SOX_ENOTSUP,         /* Operation not supported */
  57   SOX_EINVAL           /* Invalid argument */
  58 };
  59
  60 /* Boolean type, assignment (but not necessarily binary) compatible with
  61  * C++ bool */
  62 typedef enum {sox_false, sox_true} sox_bool;
  63
  64 typedef int32_t int24_t;     /* But beware of the extra byte. */
  65 typedef uint32_t uint24_t;   /* ditto */
  66
  67 #define SOX_INT_MIN(bits) (1 <<((bits)-1))
  68 #define SOX_INT_MAX(bits) (((unsigned)-1)>>(33-(bits)))
  69 #define SOX_UINT_MAX(bits) (SOX_INT_MIN(bits)|SOX_INT_MAX(bits))
  70
  71 #define SOX_INT8_MAX  SOX_INT_MAX(8)
  72 #define SOX_INT16_MAX SOX_INT_MAX(16)
  73 #define SOX_INT24_MAX SOX_INT_MAX(24)
  74 #define SOX_INT32_MAX SOX_INT_MAX(32)
  75
  76 typedef int32_t sox_sample_t;
  77
  78 /* Minimum and maximum values a sample can hold. */
  79 #define SOX_SAMPLE_PRECISION 32
  80 #define SOX_SAMPLE_MAX (sox_sample_t)SOX_INT_MAX(32)
  81 #define SOX_SAMPLE_MIN (sox_sample_t)SOX_INT_MIN(32)
  82
  83
  84
  85 /*                Conversions: Linear PCM <--> sox_sample_t
  86  *
  87  *   I/O      Input    sox_sample_t Clips?   Input    sox_sample_t Clips?
  88  *  Format   Minimum     Minimum     I O    Maximum     Maximum     I O
  89  *  ------  ---------  ------------ -- --   --------  ------------ -- --
  90  *  Float     -inf         -1        y n      inf      1 - 5e-10    y n
  91  *  Int8      -128        -128       n n      127     127.9999999   n y
  92  *  Int16    -32768      -32768      n n     32767    32767.99998   n y
  93  *  Int24   -8388608    -8388608     n n    8388607   8388607.996   n y
  94  *  Int32  -2147483648 -2147483648   n n   2147483647 2147483647    n n
  95  *
  96  * Conversions are as accurate as possible (with rounding).
  97  *
  98  * Rounding: halves toward +inf, all others to nearest integer.
  99  *
 100  * Clips? shows whether on not there is the possibility of a conversion
 101  * clipping to the minimum or maximum value when inputing from or outputing
 102  * to a given type.
 103  *
 104  * Unsigned integers are converted to and from signed integers by flipping
 105  * the upper-most bit then treating them as signed integers.
 106  */
 107
 108 #define SOX_SAMPLE_LOCALS sox_sample_t sox_macro_temp_sample UNUSED; \
 109   double sox_macro_temp_double UNUSED
 110
 111 #define SOX_SAMPLE_NEG SOX_INT_MIN(32)
 112 #define SOX_SAMPLE_TO_UNSIGNED(bits,d,clips) \
 113   (uint##bits##_t)(SOX_SAMPLE_TO_SIGNED(bits,d,clips)^SOX_INT_MIN(bits))
 114 #define SOX_SAMPLE_TO_SIGNED(bits,d,clips) \
 115   (int##bits##_t)(LSX_UNUSED_VAR(sox_macro_temp_double),sox_macro_temp_sample=(d),sox_macro_temp_sample>SOX_SAMPLE_MAX-(1<<(31-bits))?++(clips),SOX_INT_MAX(bits):((uint32_t)(sox_macro_temp_sample+(1<<(31-bits))))>>(32-bits))
 116 #define SOX_SIGNED_TO_SAMPLE(bits,d)((sox_sample_t)(d)<<(32-bits))
 117 #define SOX_UNSIGNED_TO_SAMPLE(bits,d)(SOX_SIGNED_TO_SAMPLE(bits,d)^SOX_SAMPLE_NEG)
 118
 119 #define SOX_UNSIGNED_8BIT_TO_SAMPLE(d,clips) SOX_UNSIGNED_TO_SAMPLE(8,d)
 120 #define SOX_SIGNED_8BIT_TO_SAMPLE(d,clips) SOX_SIGNED_TO_SAMPLE(8,d)
 121 #define SOX_UNSIGNED_16BIT_TO_SAMPLE(d,clips) SOX_UNSIGNED_TO_SAMPLE(16,d)
 122 #define SOX_SIGNED_16BIT_TO_SAMPLE(d,clips) SOX_SIGNED_TO_SAMPLE(16,d)
 123 #define SOX_UNSIGNED_24BIT_TO_SAMPLE(d,clips) SOX_UNSIGNED_TO_SAMPLE(24,d)
 124 #define SOX_SIGNED_24BIT_TO_SAMPLE(d,clips) SOX_SIGNED_TO_SAMPLE(24,d)
 125 #define SOX_UNSIGNED_32BIT_TO_SAMPLE(d,clips) ((sox_sample_t)(d)^SOX_SAMPLE_NEG)
 126 #define SOX_SIGNED_32BIT_TO_SAMPLE(d,clips) (sox_sample_t)(d)
 127 #define SOX_FLOAT_32BIT_TO_SAMPLE(d,clips) (sox_sample_t)(LSX_UNUSED_VAR(sox_macro_temp_sample),sox_macro_temp_double=(d)*(SOX_SAMPLE_MAX+1.),sox_macro_temp_double<SOX_SAMPLE_MIN?++(clips),SOX_SAMPLE_MIN:sox_macro_temp_double>=SOX_SAMPLE_MAX+1.?sox_macro_temp_double>SOX_SAMPLE_MAX+1.?++(clips),SOX_SAMPLE_MAX:SOX_SAMPLE_MAX:sox_macro_temp_double)
 128 #define SOX_FLOAT_64BIT_TO_SAMPLE(d,clips) (sox_sample_t)(LSX_UNUSED_VAR(sox_macro_temp_sample),sox_macro_temp_double=(d)*(SOX_SAMPLE_MAX+1.),sox_macro_temp_double<0?sox_macro_temp_double<=SOX_SAMPLE_MIN-.5?++(clips),SOX_SAMPLE_MIN:sox_macro_temp_double-.5:sox_macro_temp_double>=SOX_SAMPLE_MAX+.5?sox_macro_temp_double>SOX_SAMPLE_MAX+1.?++(clips),SOX_SAMPLE_MAX:SOX_SAMPLE_MAX:sox_macro_temp_double+.5)
 129 #define SOX_SAMPLE_TO_UNSIGNED_8BIT(d,clips) SOX_SAMPLE_TO_UNSIGNED(8,d,clips)
 130 #define SOX_SAMPLE_TO_SIGNED_8BIT(d,clips) SOX_SAMPLE_TO_SIGNED(8,d,clips)
 131 #define SOX_SAMPLE_TO_UNSIGNED_16BIT(d,clips) SOX_SAMPLE_TO_UNSIGNED(16,d,clips)
 132 #define SOX_SAMPLE_TO_SIGNED_16BIT(d,clips) SOX_SAMPLE_TO_SIGNED(16,d,clips)
 133 #define SOX_SAMPLE_TO_UNSIGNED_24BIT(d,clips) SOX_SAMPLE_TO_UNSIGNED(24,d,clips)
 134 #define SOX_SAMPLE_TO_SIGNED_24BIT(d,clips) SOX_SAMPLE_TO_SIGNED(24,d,clips)
 135 #define SOX_SAMPLE_TO_UNSIGNED_32BIT(d,clips) (uint32_t)((d)^SOX_SAMPLE_NEG)
 136 #define SOX_SAMPLE_TO_SIGNED_32BIT(d,clips) (int32_t)(d)
 137 #define SOX_SAMPLE_TO_FLOAT_32BIT(d,clips) (LSX_UNUSED_VAR(sox_macro_temp_double),sox_macro_temp_sample=(d),sox_macro_temp_sample>SOX_SAMPLE_MAX-128?++(clips),1:(((sox_macro_temp_sample+128)&~255)*(1./(SOX_SAMPLE_MAX+1.))))
 138 #define SOX_SAMPLE_TO_FLOAT_64BIT(d,clips) ((d)*(1./(SOX_SAMPLE_MAX+1.)))
 139
 140
 141
 142 /* MACRO to clip a data type that is greater then sox_sample_t to
 143  * sox_sample_t's limits and increment a counter if clipping occurs..
 144  */
 145 #define SOX_SAMPLE_CLIP_COUNT(samp, clips) \
 146   do { \
 147     if (samp > SOX_SAMPLE_MAX) \
 148       { samp = SOX_SAMPLE_MAX; clips++; } \
 149     else if (samp < SOX_SAMPLE_MIN) \
 150       { samp = SOX_SAMPLE_MIN; clips++; } \
 151   } while (0)
 152
 153 /* Rvalue MACRO to round and clip a double to a sox_sample_t,
 154  * and increment a counter if clipping occurs.
 155  */
 156 #define SOX_ROUND_CLIP_COUNT(d, clips) \
 157   ((d) < 0? (d) <= SOX_SAMPLE_MIN - 0.5? ++(clips), SOX_SAMPLE_MIN: (d) - 0.5 \
 158         : (d) >= SOX_SAMPLE_MAX + 0.5? ++(clips), SOX_SAMPLE_MAX: (d) + 0.5)
 159
 160 /* Rvalue MACRO to clip an integer to a given number of bits
 161  * and increment a counter if clipping occurs.
 162  */
 163 #define SOX_INTEGER_CLIP_COUNT(bits,i,clips) ( \
 164   (i) >(1 << ((bits)-1))- 1? ++(clips),(1 << ((bits)-1))- 1 : \
 165   (i) <-1 << ((bits)-1)    ? ++(clips),-1 << ((bits)-1) : (i))
 166 #define SOX_16BIT_CLIP_COUNT(i,clips) SOX_INTEGER_CLIP_COUNT(16,i,clips)
 167 #define SOX_24BIT_CLIP_COUNT(i,clips) SOX_INTEGER_CLIP_COUNT(24,i,clips)
 168
 169
 170
 171 #define SOX_SIZE_MAX ((size_t)(-1))
 172
 173 typedef void (*sox_output_message_handler_t)(unsigned level, const char *filename, const char *fmt, va_list ap);
 174
 175 typedef struct { /* Global parameters (for effects & formats) */
 176 /* public: */
 177   unsigned     verbosity;
 178   sox_output_message_handler_t output_message_handler;
 179   sox_bool     repeatable;
 180 /* The following is used at times in libSoX when alloc()ing buffers
 181  * to perform file I/O.  It can be useful to pass in similar sized
 182  * data to get max performance.
 183  */
 184   size_t       bufsiz, input_bufsiz;
 185   int32_t      ranqd1; /* Can be used to re-seed libSoX's PRNG */
 186
 187 /* private: */
 188   char const * stdin_in_use_by;
 189   char const * stdout_in_use_by;
 190   char const * subsystem;
 191   char       * tmp_path;
 192   sox_bool     use_magic;
 193 } sox_globals_t;
 194 extern sox_globals_t sox_globals;
 195
 196 typedef double sox_rate_t;
 197
 198 #define SOX_UNSPEC 0
 199 #define SOX_IGNORE_LENGTH (size_t)(-1)
 200 typedef struct { /* Signal parameters; SOX_UNSPEC if unknown */
 201   sox_rate_t       rate;         /* sampling rate */
 202   unsigned         channels;     /* number of sound channels */
 203   unsigned         precision;    /* in bits */
 204   size_t           length;       /* samples * chans in file */
 205   double           * mult;       /* Effects headroom multiplier; may be null */
 206 } sox_signalinfo_t;
 207
 208 typedef enum {
 209   SOX_ENCODING_UNKNOWN   ,
 210
 211   SOX_ENCODING_SIGN2     , /* signed linear 2's comp: Mac */
 212   SOX_ENCODING_UNSIGNED  , /* unsigned linear: Sound Blaster */
 213   SOX_ENCODING_FLOAT     , /* floating point (binary format) */
 214   SOX_ENCODING_FLOAT_TEXT, /* floating point (text format) */
 215   SOX_ENCODING_FLAC      , /* FLAC compression */
 216   SOX_ENCODING_HCOM      , /*  */
 217   SOX_ENCODING_WAVPACK   , /*  */
 218   SOX_ENCODING_WAVPACKF  , /*  */
 219   SOX_ENCODING_ULAW      , /* u-law signed logs: US telephony, SPARC */
 220   SOX_ENCODING_ALAW      , /* A-law signed logs: non-US telephony, Psion */
 221   SOX_ENCODING_G721      , /* G.721 4-bit ADPCM */
 222   SOX_ENCODING_G723      , /* G.723 3 or 5 bit ADPCM */
 223   SOX_ENCODING_CL_ADPCM  , /* Creative Labs 8 --> 2,3,4 bit Compressed PCM */
 224   SOX_ENCODING_CL_ADPCM16, /* Creative Labs 16 --> 4 bit Compressed PCM */
 225   SOX_ENCODING_MS_ADPCM  , /* Microsoft Compressed PCM */
 226   SOX_ENCODING_IMA_ADPCM , /* IMA Compressed PCM */
 227   SOX_ENCODING_OKI_ADPCM , /* Dialogic/OKI Compressed PCM */
 228   SOX_ENCODING_DPCM      , /*  */
 229   SOX_ENCODING_DWVW      , /*  */
 230   SOX_ENCODING_DWVWN     , /*  */
 231   SOX_ENCODING_GSM       , /* GSM 6.10 33byte frame lossy compression */
 232   SOX_ENCODING_MP3       , /* MP3 compression */
 233   SOX_ENCODING_VORBIS    , /* Vorbis compression */
 234   SOX_ENCODING_AMR_WB    , /* AMR-WB compression */
 235   SOX_ENCODING_AMR_NB    , /* AMR-NB compression */
 236   SOX_ENCODING_CVSD      , /*  */
 237   SOX_ENCODING_LPC10     , /*  */
 238
 239   SOX_ENCODINGS            /* End of list marker */
 240 } sox_encoding_t;
 241
 242 typedef struct {
 243   unsigned flags;
 244   #define SOX_LOSSY1 1     /* encode, decode, encode, decode: lossy once */
 245   #define SOX_LOSSY2 2     /* encode, decode, encode, decode: lossy twice */
 246
 247   char const * name;
 248   char const * desc;
 249 } sox_encodings_info_t;
 250
 251 extern sox_encodings_info_t const sox_encodings_info[];
 252
 253 typedef enum {SOX_OPTION_NO, SOX_OPTION_YES, SOX_OPTION_DEFAULT} sox_option_t;
 254
 255 typedef struct { /* Encoding parameters */
 256   sox_encoding_t encoding; /* format of sample numbers */
 257   unsigned bits_per_sample;  /* 0 if unknown or variable; uncompressed value if lossless; compressed value if lossy */
 258   double compression;      /* compression factor (where applicable) */
 259
 260   /* If these 3 variables are set to DEFAULT, then, during
 261    * sox_open_read or sox_open_write, libSoX will set them to either
 262    * NO or YES according to the machine or format default. */
 263   sox_option_t reverse_bytes;    /* endiannesses... */
 264   sox_option_t reverse_nibbles;
 265   sox_option_t reverse_bits;
 266
 267   sox_bool opposite_endian;
 268 } sox_encodinginfo_t;
 269
 270 void sox_init_encodinginfo(sox_encodinginfo_t * e);
 271 unsigned sox_precision(sox_encoding_t encoding, unsigned pcm_size);
 272
 273 /* Defaults for common hardware */
 274 #define SOX_DEFAULT_CHANNELS  2
 275 #define SOX_DEFAULT_RATE      48000
 276 #define SOX_DEFAULT_PRECISION 16
 277 #define SOX_DEFAULT_ENCODING  SOX_ENCODING_SIGN2
 278
 279 /* Loop parameters */
 280
 281 typedef struct {
 282   size_t    start;          /* first sample */
 283   size_t    length;         /* length */
 284   unsigned int  count;          /* number of repeats, 0=forever */
 285   unsigned char type;           /* 0=no, 1=forward, 2=forward/back */
 286 } sox_loopinfo_t;
 287
 288 /* Instrument parameters */
 289
 290 /* vague attempt at generic information for sampler-specific info */
 291
 292 typedef struct {
 293   int8_t MIDInote;       /* for unity pitch playback */
 294   int8_t MIDIlow, MIDIhi;/* MIDI pitch-bend range */
 295   char loopmode;       /* semantics of loop data */
 296   unsigned nloops;     /* number of active loops (max SOX_MAX_NLOOPS) */
 297 } sox_instrinfo_t;
 298
 299 /* Loop modes, upper 4 bits mask the loop blass, lower 4 bits describe */
 300 /* the loop behaviour, ie. single shot, bidirectional etc. */
 301 #define SOX_LOOP_NONE          0
 302 #define SOX_LOOP_8             32 /* 8 loops: don't know ?? */
 303 #define SOX_LOOP_SUSTAIN_DECAY 64 /* AIFF style: one sustain & one decay loop */
 304
 305 /*
 306  * File buffer info.  Holds info so that data can be read in blocks.
 307  */
 308
 309 typedef struct {
 310   char          *buf;                 /* Pointer to data buffer */
 311   size_t        size;                 /* Size of buffer */
 312   size_t        count;                /* Count read in to buffer */
 313   size_t        pos;                  /* Position in buffer */
 314 } sox_fileinfo_t;
 315
 316
 317 /*
 318  * Handler structure for each format.
 319  */
 320
 321 typedef struct sox_format sox_format_t;
 322
 323 typedef struct {
 324   unsigned     sox_lib_version_code; /* Checked on load; must be 1st in struct*/
 325   char         const * description;
 326   char         const * const * names;
 327   unsigned int flags;
 328   int          (*startread)(sox_format_t * ft);
 329   size_t   (*read)(sox_format_t * ft, sox_sample_t *buf, size_t len);
 330   int          (*stopread)(sox_format_t * ft);
 331   int          (*startwrite)(sox_format_t * ft);
 332   size_t   (*write)(sox_format_t * ft, const sox_sample_t *buf, size_t len);
 333   int          (*stopwrite)(sox_format_t * ft);
 334   int          (*seek)(sox_format_t * ft, uint64_t offset);
 335   unsigned     const * write_formats;
 336   sox_rate_t   const * write_rates;
 337   size_t       priv_size;
 338 } sox_format_handler_t;
 339
 340 /*
 341  *  Format information for input and output files.
 342  */
 343
 344 typedef char * * sox_comments_t;
 345
 346 size_t sox_num_comments(sox_comments_t comments);
 347 void sox_append_comment(sox_comments_t * comments, char const * comment);
 348 void sox_append_comments(sox_comments_t * comments, char const * comment);
 349 sox_comments_t sox_copy_comments(sox_comments_t comments);
 350 void sox_delete_comments(sox_comments_t * comments);
 351 char const * sox_find_comment(sox_comments_t comments, char const * id);
 352
 353 #define SOX_MAX_NLOOPS           8
 354
 355 typedef struct {
 356   /* Decoded: */
 357   sox_comments_t   comments;              /* Comment strings */
 358   sox_instrinfo_t  instr;                 /* Instrument specification */
 359   sox_loopinfo_t   loops[SOX_MAX_NLOOPS]; /* Looping specification */
 360
 361   /* TBD: Non-decoded chunks, etc: */
 362 } sox_oob_t;                              /* Out Of Band data */
 363
 364 typedef enum {lsx_io_file, lsx_io_pipe, lsx_io_url} lsx_io_type;
 365
 366 struct sox_format {
 367   char             * filename;      /* File name */
 368   sox_signalinfo_t signal;          /* Signal specifications */
 369   sox_encodinginfo_t encoding;      /* Encoding specifications */
 370   char             * filetype;      /* Type of file */
 371   sox_oob_t        oob;             /* Out Of Band data */
 372   sox_bool         seekable;        /* Can seek on this file */
 373   char             mode;            /* Read or write mode ('r' or 'w') */
 374   size_t       olength;         /* Samples * chans written to file */
 375   size_t       clips;           /* Incremented if clipping occurs */
 376   int              sox_errno;       /* Failure error code */
 377   char             sox_errstr[256]; /* Failure error text */
 378   FILE             * fp;            /* File stream pointer */
 379   lsx_io_type      io_type;
 380   long             tell_off;
 381   long             data_start;
 382   sox_format_handler_t handler;     /* Format handler for this file */
 383   void             * priv;          /* Format handler's private data area */
 384 };
 385
 386 /* File flags field */
 387 #define SOX_FILE_NOSTDIO 0x0001 /* Does not use stdio routines */
 388 #define SOX_FILE_DEVICE  0x0002 /* File is an audio device */
 389 #define SOX_FILE_PHONY   0x0004 /* Phony file/device */
 390 #define SOX_FILE_REWIND  0x0008 /* File should be rewound to write header */
 391 #define SOX_FILE_BIT_REV 0x0010 /* Is file bit-reversed? */
 392 #define SOX_FILE_NIB_REV 0x0020 /* Is file nibble-reversed? */
 393 #define SOX_FILE_ENDIAN  0x0040 /* Is file format endian? */
 394 #define SOX_FILE_ENDBIG  0x0080 /* If so, is it big endian? */
 395 #define SOX_FILE_MONO    0x0100 /* Do channel restrictions allow mono? */
 396 #define SOX_FILE_STEREO  0x0200 /* Do channel restrictions allow stereo? */
 397 #define SOX_FILE_QUAD    0x0400 /* Do channel restrictions allow quad? */
 398
 399 #define SOX_FILE_CHANS   (SOX_FILE_MONO | SOX_FILE_STEREO | SOX_FILE_QUAD)
 400 #define SOX_FILE_LIT_END (SOX_FILE_ENDIAN | 0)
 401 #define SOX_FILE_BIG_END (SOX_FILE_ENDIAN | SOX_FILE_ENDBIG)
 402
 403 int sox_format_init(void);
 404 void sox_format_quit(void);
 405
 406 int sox_init(void);
 407 int sox_quit(void);
 408
 409 typedef const sox_format_handler_t *(*sox_format_fn_t)(void);
 410
 411 typedef struct {
 412   char *name;
 413   sox_format_fn_t fn;
 414 } sox_format_tab_t;
 415
 416 extern sox_format_tab_t sox_format_fns[];
 417
 418 sox_format_t * sox_open_read(
 419     char               const * path,
 420     sox_signalinfo_t   const * signal,
 421     sox_encodinginfo_t const * encoding,
 422     char               const * filetype);
 423 sox_format_t * sox_open_mem_read(
 424     void                     * buffer,
 425     size_t                     buffer_size,
 426     sox_signalinfo_t   const * signal,
 427     sox_encodinginfo_t const * encoding,
 428     char               const * filetype);
 429 sox_bool sox_format_supports_encoding(
 430     char               const * path,
 431     char               const * filetype,
 432     sox_encodinginfo_t const * encoding);
 433 sox_format_handler_t const * sox_write_handler(
 434     char               const * path,
 435     char               const * filetype,
 436     char               const * * filetype1);
 437 sox_format_t * sox_open_write(
 438     char               const * path,
 439     sox_signalinfo_t   const * signal,
 440     sox_encodinginfo_t const * encoding,
 441     char               const * filetype,
 442     sox_oob_t          const * oob,
 443     sox_bool           (*overwrite_permitted)(const char *filename));
 444 sox_format_t * sox_open_mem_write(
 445     void                     * buffer,
 446     size_t                     buffer_size,
 447     sox_signalinfo_t   const * signal,
 448     sox_encodinginfo_t const * encoding,
 449     char               const * filetype,
 450     sox_oob_t          const * oob);
 451 sox_format_t * sox_open_memstream_write(
 452     char                     * * buffer_ptr,
 453     size_t                   * buffer_size_ptr,
 454     sox_signalinfo_t   const * signal,
 455     sox_encodinginfo_t const * encoding,
 456     char               const * filetype,
 457     sox_oob_t          const * oob);
 458 size_t sox_read(sox_format_t * ft, sox_sample_t *buf, size_t len);
 459 size_t sox_write(sox_format_t * ft, const sox_sample_t *buf, size_t len);
 460 int sox_close(sox_format_t * ft);
 461
 462 #define SOX_SEEK_SET 0
 463 int sox_seek(sox_format_t * ft, uint64_t offset, int whence);
 464
 465 sox_format_handler_t const * sox_find_format(char const * name, sox_bool no_dev);
 466
 467 /*
 468  * Structures for effects.
 469  */
 470
 471 #define SOX_MAX_EFFECTS 20
 472
 473 #define SOX_EFF_CHAN     1           /* Can alter # of channels */
 474 #define SOX_EFF_RATE     2           /* Can alter sample rate */
 475 #define SOX_EFF_PREC     4           /* Can alter sample precision */
 476 #define SOX_EFF_LENGTH   8           /* Can alter audio length */
 477 #define SOX_EFF_MCHAN    16          /* Can handle multi-channel */
 478 #define SOX_EFF_NULL     32          /* Does nothing */
 479 #define SOX_EFF_DEPRECATED 64        /* Is living on borrowed time */
 480 #define SOX_EFF_GAIN     128         /* Does not support gain -r */
 481 #define SOX_EFF_MODIFY   256         /* Does not modify samples */
 482 #define SOX_EFF_ALPHA    512         /* Is experimental/incomplete */
 483 #define SOX_EFF_INTERNAL 1024        /* Is in libSoX but not sox */
 484
 485 typedef enum {sox_plot_off, sox_plot_octave, sox_plot_gnuplot, sox_plot_data} sox_plot_t;
 486 typedef struct sox_effect sox_effect_t;
 487 struct sox_effects_globals { /* Global parameters (for effects) */
 488   sox_plot_t plot;         /* To help the user choose effect & options */
 489   sox_globals_t * global_info;
 490 };
 491 typedef struct sox_effects_globals sox_effects_globals_t;
 492 extern sox_effects_globals_t sox_effects_globals;
 493
 494 typedef struct {
 495   char const * name;
 496   char const * usage;
 497   unsigned int flags;
 498
 499   int (*getopts)(sox_effect_t * effp, int argc, char *argv[]);
 500   int (*start)(sox_effect_t * effp);
 501   int (*flow)(sox_effect_t * effp, const sox_sample_t *ibuf,
 502       sox_sample_t *obuf, size_t *isamp, size_t *osamp);
 503   int (*drain)(sox_effect_t * effp, sox_sample_t *obuf, size_t *osamp);
 504   int (*stop)(sox_effect_t * effp);
 505   int (*kill)(sox_effect_t * effp);
 506   size_t       priv_size;
 507 } sox_effect_handler_t;
 508
 509 struct sox_effect {
 510   sox_effects_globals_t    * global_info; /* global parameters */
 511   sox_signalinfo_t         in_signal;
 512   sox_signalinfo_t         out_signal;
 513   sox_encodinginfo_t       const * in_encoding;
 514   sox_encodinginfo_t       const * out_encoding;
 515   sox_effect_handler_t     handler;
 516   sox_sample_t             * obuf;        /* output buffer */
 517   size_t               obeg, oend;    /* consumed, total length */
 518   size_t               imin;          /* minimum input buffer size */
 519   size_t               clips;         /* increment if clipping occurs */
 520   size_t               flows;         /* 1 if MCHAN, # chans otherwise */
 521   size_t               flow;          /* flow # */
 522   void                     * priv;        /* Effect's private data area */
 523 };
 524
 525 sox_effect_handler_t const * sox_find_effect(char const * name);
 526 sox_effect_t * sox_create_effect(sox_effect_handler_t const * eh);
 527 int sox_effect_options(sox_effect_t *effp, int argc, char * const argv[]);
 528
 529 /* Effects chain */
 530
 531 typedef const sox_effect_handler_t *(*sox_effect_fn_t)(void);
 532 extern sox_effect_fn_t sox_effect_fns[];
 533
 534 struct sox_effects_chain {
 535   sox_effect_t * effects[SOX_MAX_EFFECTS];
 536   unsigned length;
 537   sox_sample_t **ibufc, **obufc; /* Channel interleave buffers */
 538   sox_effects_globals_t global_info;
 539   sox_encodinginfo_t const * in_enc;
 540   sox_encodinginfo_t const * out_enc;
 541 };
 542 typedef struct sox_effects_chain sox_effects_chain_t;
 543 sox_effects_chain_t * sox_create_effects_chain(
 544     sox_encodinginfo_t const * in_enc, sox_encodinginfo_t const * out_enc);
 545 void sox_delete_effects_chain(sox_effects_chain_t *ecp);
 546 int sox_add_effect( sox_effects_chain_t * chain, sox_effect_t * effp, sox_signalinfo_t * in, sox_signalinfo_t const * out);
 547 int sox_flow_effects(sox_effects_chain_t *, int (* callback)(sox_bool all_done, void * client_data), void * client_data);
 548 size_t sox_effects_clips(sox_effects_chain_t *);
 549 size_t sox_stop_effect(sox_effect_t *effp);
 550 void sox_push_effect_last(sox_effects_chain_t *chain, sox_effect_t *effp);
 551 sox_effect_t *sox_pop_effect_last(sox_effects_chain_t *chain);
 552 void sox_delete_effect(sox_effect_t *effp);
 553 void sox_delete_effect_last(sox_effects_chain_t *chain);
 554 void sox_delete_effects(sox_effects_chain_t *chain);
 555
 556 /* The following routines are unique to the trim effect.
 557  * sox_trim_get_start can be used to find what is the start
 558  * of the trim operation as specified by the user.
 559  * sox_trim_clear_start will reset what ever the user specified
 560  * back to 0.
 561  * These two can be used together to find out what the user
 562  * wants to trim and use a sox_seek() operation instead.  After
 563  * sox_seek()'ing, you should set the trim option to 0.
 564  */
 565 size_t sox_trim_get_start(sox_effect_t * effp);
 566 void sox_trim_clear_start(sox_effect_t * effp);
 567 size_t sox_crop_get_start(sox_effect_t * effp);
 568 void sox_crop_clear_start(sox_effect_t * effp);
 569
 570 typedef int (* sox_playlist_callback_t)(void *, char *);
 571 sox_bool sox_is_playlist(char const * filename);
 572 int sox_parse_playlist(sox_playlist_callback_t callback, void * p, char const * const listname);
 573
 574 char const * sox_strerror(int sox_errno);
 575 void sox_output_message(FILE *file, const char *filename, const char *fmt, va_list ap);
 576
 577 /* WARNING BEGIN
 578  *
 579  * The items in this section are subject to instability.  They only exist
 580  * in public API because sox (the application) make use of them but
 581  * may not be supported and may change rapidly.
 582  */
 583 void lsx_fail(const char *, ...) PRINTF;
 584 void lsx_warn(const char *, ...) PRINTF;
 585 void lsx_report(const char *, ...) PRINTF;
 586 void lsx_debug(const char *, ...) PRINTF;
 587
 588 #define lsx_fail       sox_globals.subsystem=__FILE__,lsx_fail
 589 #define lsx_warn       sox_globals.subsystem=__FILE__,lsx_warn
 590 #define lsx_report     sox_globals.subsystem=__FILE__,lsx_report
 591 #define lsx_debug      sox_globals.subsystem=__FILE__,lsx_debug
 592
 593 typedef struct {char const *text; unsigned value;} lsx_enum_item;
 594 #define LSX_ENUM_ITEM(prefix, item) {#item, prefix##item},
 595
 596 lsx_enum_item const * lsx_find_enum_text(char const * text, lsx_enum_item const * lsx_enum_items, unsigned flags);
 597 #define LSX_FET_CASE 1
 598 lsx_enum_item const * lsx_find_enum_value(unsigned value, lsx_enum_item const * lsx_enum_items);
 599 int lsx_enum_option(int c, lsx_enum_item const * items);
 600 sox_bool lsx_strends(char const * str, char const * end);
 601 char const * lsx_find_file_extension(char const * pathname);
 602 char const * lsx_sigfigs3(double number);
 603 char const * lsx_sigfigs3p(double percentage);
 604 void *lsx_realloc(void *ptr, size_t newsize);
 605 int lsx_strcasecmp(const char * s1, const char * s2);
 606 int lsx_strncasecmp(char const * s1, char const * s2, size_t n);
 607
 608 /* WARNING END */
 609
 610 #if defined(__cplusplus)
 611 }
 612 #endif
 613
 614 #endif