shithub: sox

ref: 88eec9c75d0a23c6c4d5d61af76c6ebd56b82b51
dir: /src/sox.h/

View raw version
/* libSoX Library Public Interface
 *
 * 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.
 * Chris Bagwell And SoX Contributors are not responsible for
 * the consequences of using this software.
 */

#ifndef SOX_H
#define SOX_H

#include <limits.h>
#include <stdarg.h>
#include <stddef.h>

/* Suppress warnings from use of type long long */
#if defined __GNUC__
#pragma GCC system_header
#endif

#if SCHAR_MAX==127 && SCHAR_MIN==(-128)
typedef signed char sox_int8_t;
#elif CHAR_MAX==127 && CHAR_MIN==(-128)
typedef char sox_int8_t;
#else
#error Unable to determine an appropriate definition for sox_int8_t.
#endif

#if UCHAR_MAX==0xff
typedef unsigned char sox_uint8_t;
#elif CHAR_MAX==0xff && CHAR_MIN==0
typedef char sox_uint8_t;
#else
#error Unable to determine an appropriate definition for sox_uint8_t.
#endif

#if SHRT_MAX==32767 && SHRT_MIN==(-32768)
typedef short sox_int16_t;
#elif INT_MAX==32767 && INT_MIN==(-32768)
typedef int sox_int16_t;
#else
#error Unable to determine an appropriate definition for sox_int16_t.
#endif

#if USHRT_MAX==0xffff
typedef unsigned short sox_uint16_t;
#elif UINT_MAX==0xffff
typedef unsigned int sox_uint16_t;
#else
#error Unable to determine an appropriate definition for sox_uint16_t.
#endif

#if INT_MAX==2147483647 && INT_MIN==(-2147483647-1)
typedef int sox_int32_t;
#elif LONG_MAX==2147483647 && LONG_MIN==(-2147483647-1)
typedef long sox_int32_t;
#else
#error Unable to determine an appropriate definition for sox_int32_t.
#endif

#if UINT_MAX==0xffffffff
typedef unsigned int sox_uint32_t;
#elif ULONG_MAX==0xffffffff
typedef unsigned long sox_uint32_t;
#else
#error Unable to determine an appropriate definition for sox_uint32_t.
#endif

#if LONG_MAX==9223372036854775807 && LONG_MIN==(-9223372036854775807-1)
typedef long sox_int64_t;
#elif defined(LLONG_MAX) && defined(LLONG_MIN) && LLONG_MAX==9223372036854775807 && LLONG_MIN==(-9223372036854775807-1)
typedef long long sox_int64_t;
#elif defined(_MSC_VER)
typedef __int64 sox_int64_t;
#else
#error Unable to determine an appropriate definition for sox_int64_t.
#endif

#if ULONG_MAX==0xffffffffffffffff
typedef unsigned long sox_uint64_t;
#elif ULLONG_MAX==0xffffffffffffffff
typedef unsigned long long sox_uint64_t;
#elif defined(_MSC_VER)
typedef unsigned __int64 sox_uint64_t;
#else
#error Unable to determine an appropriate definition for sox_uint64_t.
#endif

typedef sox_int32_t sox_int24_t;   /* sox_int24_t == sox_int32_t (beware of the extra byte) */
typedef sox_uint32_t sox_uint24_t; /* sox_uint24_t == sox_uint32_t (beware of the extra byte) */

#if defined(__cplusplus)
extern "C" {
#endif

/* Avoid warnings about unused parameters. */
#ifdef __GNUC__
#define LSX_UNUSED __attribute__ ((unused))
#define LSX_PRINTF __attribute__ ((format (printf, 1, 2)))
#else
#define LSX_UNUSED
#define LSX_PRINTF
#endif
#ifdef _MSC_VER
#define LSX_UNUSED_VAR(x) ((void)(x))
#else
#define LSX_UNUSED_VAR(x) ((void)0)
#endif

/* The following is the API version of libSoX.  It is not meant
 * to follow the version number of SoX but it has historically.
 * Please do not count on these numbers being in sync. */
#define SOX_LIB_VERSION(a,b,c) (((a) << 16) + ((b) << 8) + (c))
#define SOX_LIB_VERSION_CODE   SOX_LIB_VERSION(14, 4, 0)

/* Returns version number */
const char *sox_version(void);

/* Flags indicating whether optional features are present in this build of SoX */
typedef enum sox_version_flags_t {
    sox_version_none = 0,
    sox_version_have_popen = 1,
    sox_version_have_magic = 2,
    sox_version_have_threads = 4,
    sox_version_have_memopen = 8
} sox_version_flags_t;

/* Information about this build of SoX */
typedef struct sox_version_info_t {
    size_t       size;         /* structure size = sizeof(sox_version_info_t) */
    sox_version_flags_t flags; /* feature flags = popen | magic | threads | memopen */
    sox_uint32_t version_code; /* version number = SOX_LIB_VERSION_CODE, i.e. 0x140400 */
    const char * version;      /* version string = sox_version(), i.e. "14.4.0" */
    const char * version_extra;/* version extra info or null = "PACKAGE_EXTRA", i.e. "beta" */
    const char * time;         /* build time = "__DATE__ __TIME__", i.e. "Jan  7 2010 03:31:50" */
    const char * distro;       /* distro or null = "DISTRO", i.e. "Debian" */
    const char * compiler;     /* compiler info or null, i.e. "msvc 160040219" */
    const char * arch;         /* arch, i.e. "1248 48 44 L OMP" */
    /* new info should be added at the end for version backwards-compatibility. */
} sox_version_info_t;

/* gets information about this build of libsox */
sox_version_info_t const * sox_version_info(void);

/* libSoX-specific error codes.  The rest directly map from errno. */
enum sox_error_t {
  SOX_SUCCESS = 0,     /* Function succeeded = 0 */
  SOX_EOF = -1,        /* End Of File or other error = -1 */
  SOX_EHDR = 2000,     /* Invalid Audio Header */
  SOX_EFMT,            /* Unsupported data format */
  SOX_ENOMEM,          /* Can't alloc memory */
  SOX_EPERM,           /* Operation not permitted */
  SOX_ENOTSUP,         /* Operation not supported */
  SOX_EINVAL           /* Invalid argument */
};

/* Boolean type, assignment (but not necessarily binary) compatible with C++ bool */
typedef enum sox_bool {
    sox_false,
    sox_true
} sox_bool;

#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)  /* = 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 */

/* native SoX audio sample type */
typedef sox_int32_t sox_sample_t;

/* Minimum and maximum values a sample can hold. */
#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 */


/*                Conversions: Linear PCM <--> sox_sample_t
 *
 *   I/O      Input    sox_sample_t Clips?   Input    sox_sample_t Clips?
 *  Format   Minimum     Minimum     I O    Maximum     Maximum     I O
 *  ------  ---------  ------------ -- --   --------  ------------ -- --
 *  Float     -inf         -1        y n      inf      1 - 5e-10    y n
 *  Int8      -128        -128       n n      127     127.9999999   n y
 *  Int16    -32768      -32768      n n     32767    32767.99998   n y
 *  Int24   -8388608    -8388608     n n    8388607   8388607.996   n y
 *  Int32  -2147483648 -2147483648   n n   2147483647 2147483647    n n
 *
 * Conversions are as accurate as possible (with rounding).
 *
 * Rounding: halves toward +inf, all others to nearest integer.
 *
 * Clips? shows whether on not there is the possibility of a conversion
 * clipping to the minimum or maximum value when inputing from or outputing
 * to a given type.
 *
 * Unsigned integers are converted to and from signed integers by flipping
 * the upper-most bit then treating them as signed integers.
 */

#define SOX_SAMPLE_LOCALS sox_sample_t sox_macro_temp_sample LSX_UNUSED; \
  double sox_macro_temp_double LSX_UNUSED

#define SOX_SAMPLE_NEG SOX_INT_MIN(32) /* sign bit for sox_sample_t = 0x80000000 */
#define SOX_SAMPLE_TO_UNSIGNED(bits,d,clips) \
  (sox_uint##bits##_t)(SOX_SAMPLE_TO_SIGNED(bits,d,clips)^SOX_INT_MIN(bits))
#define SOX_SAMPLE_TO_SIGNED(bits,d,clips) \
  (sox_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):((sox_uint32_t)(sox_macro_temp_sample+(1<<(31-bits))))>>(32-bits))
#define SOX_SIGNED_TO_SAMPLE(bits,d)((sox_sample_t)(d)<<(32-bits))
#define SOX_UNSIGNED_TO_SAMPLE(bits,d)(SOX_SIGNED_TO_SAMPLE(bits,d)^SOX_SAMPLE_NEG)

#define SOX_UNSIGNED_8BIT_TO_SAMPLE(d,clips) SOX_UNSIGNED_TO_SAMPLE(8,d)
#define SOX_SIGNED_8BIT_TO_SAMPLE(d,clips) SOX_SIGNED_TO_SAMPLE(8,d)
#define SOX_UNSIGNED_16BIT_TO_SAMPLE(d,clips) SOX_UNSIGNED_TO_SAMPLE(16,d)
#define SOX_SIGNED_16BIT_TO_SAMPLE(d,clips) SOX_SIGNED_TO_SAMPLE(16,d)
#define SOX_UNSIGNED_24BIT_TO_SAMPLE(d,clips) SOX_UNSIGNED_TO_SAMPLE(24,d)
#define SOX_SIGNED_24BIT_TO_SAMPLE(d,clips) SOX_SIGNED_TO_SAMPLE(24,d)
#define SOX_UNSIGNED_32BIT_TO_SAMPLE(d,clips) ((sox_sample_t)(d)^SOX_SAMPLE_NEG)
#define SOX_SIGNED_32BIT_TO_SAMPLE(d,clips) (sox_sample_t)(d)
#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)
#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)
#define SOX_SAMPLE_TO_UNSIGNED_8BIT(d,clips) SOX_SAMPLE_TO_UNSIGNED(8,d,clips)
#define SOX_SAMPLE_TO_SIGNED_8BIT(d,clips) SOX_SAMPLE_TO_SIGNED(8,d,clips)
#define SOX_SAMPLE_TO_UNSIGNED_16BIT(d,clips) SOX_SAMPLE_TO_UNSIGNED(16,d,clips)
#define SOX_SAMPLE_TO_SIGNED_16BIT(d,clips) SOX_SAMPLE_TO_SIGNED(16,d,clips)
#define SOX_SAMPLE_TO_UNSIGNED_24BIT(d,clips) SOX_SAMPLE_TO_UNSIGNED(24,d,clips)
#define SOX_SAMPLE_TO_SIGNED_24BIT(d,clips) SOX_SAMPLE_TO_SIGNED(24,d,clips)
#define SOX_SAMPLE_TO_UNSIGNED_32BIT(d,clips) (sox_uint32_t)((d)^SOX_SAMPLE_NEG)
#define SOX_SAMPLE_TO_SIGNED_32BIT(d,clips) (sox_int32_t)(d)
#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.))))
#define SOX_SAMPLE_TO_FLOAT_64BIT(d,clips) ((d)*(1./(SOX_SAMPLE_MAX+1.)))


/* 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.
 */
#define SOX_SAMPLE_CLIP_COUNT(samp, clips) \
  do { \
    if (samp > SOX_SAMPLE_MAX) \
      { samp = SOX_SAMPLE_MAX; clips++; } \
    else if (samp < SOX_SAMPLE_MIN) \
      { samp = SOX_SAMPLE_MIN; clips++; } \
  } while (0)

/* Rvalue MACRO to round and clip a double to a sox_sample_t,
 * and increment a counter if clipping occurs.
 */
#define SOX_ROUND_CLIP_COUNT(d, clips) \
  ((d) < 0? (d) <= SOX_SAMPLE_MIN - 0.5? ++(clips), SOX_SAMPLE_MIN: (d) - 0.5 \
        : (d) >= SOX_SAMPLE_MAX + 0.5? ++(clips), SOX_SAMPLE_MAX: (d) + 0.5)

/* Rvalue MACRO to clip an integer to a given number of bits
 * and increment a counter if clipping occurs.
 */
#define SOX_INTEGER_CLIP_COUNT(bits,i,clips) ( \
  (i) >(1 << ((bits)-1))- 1? ++(clips),(1 << ((bits)-1))- 1 : \
  (i) <-1 << ((bits)-1)    ? ++(clips),-1 << ((bits)-1) : (i))
#define SOX_16BIT_CLIP_COUNT(i,clips) SOX_INTEGER_CLIP_COUNT(16,i,clips)
#define SOX_24BIT_CLIP_COUNT(i,clips) SOX_INTEGER_CLIP_COUNT(24,i,clips)


#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);

/* Global parameters (for effects & formats) */
typedef struct sox_globals_t {
/* public: */
  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;       /* 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 */

  sox_int32_t  ranqd1;       /* Can be used to re-seed libSoX's PRNG */

/* private: */
  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_bool     use_threads;      /* true if client has requested parallel effects processing */
} sox_globals_t;

/* the SoX global settings */
extern sox_globals_t sox_globals;

/* samples per second = double */
typedef double sox_rate_t;

#define SOX_UNSPEC 0 /* unknown value for signal parameter = 0 */
#define SOX_IGNORE_LENGTH (sox_uint64_t)(-1) /* unspecified length for signal.length = -1 */

/* Signal parameters; SOX_UNSPEC (= 0) if unknown */
typedef struct sox_signalinfo_t {
  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 */
  sox_uint64_t     length;       /* samples * chans in file, 0 if unknown, -1 if unspecified */
  double           * mult;       /* Effects headroom multiplier; may be null */
} sox_signalinfo_t;

/* Format of sample data */
typedef enum sox_encoding_t {
  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 */
  SOX_ENCODING_FLOAT     , /* floating point (binary format) */
  SOX_ENCODING_FLOAT_TEXT, /* floating point (text format) */
  SOX_ENCODING_FLAC      , /* FLAC compression */
  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 */
  SOX_ENCODING_G723      , /* G.723 3 or 5 bit ADPCM */
  SOX_ENCODING_CL_ADPCM  , /* Creative Labs 8 --> 2,3,4 bit Compressed PCM */
  SOX_ENCODING_CL_ADPCM16, /* Creative Labs 16 --> 4 bit Compressed PCM */
  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      , /* 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      , /* Continuously Variable Slope Delta modulation */
  SOX_ENCODING_LPC10     , /* Linear Predictive Coding */

  SOX_ENCODINGS            /* End of list marker */
} sox_encoding_t;

/* Flags for sox_encodings_info_t: lossless/lossy1/lossy2 */
typedef enum sox_encodings_flags_t {
  sox_encodings_none   = 0, /* no flags specified (implies lossless encoding) */
  sox_encodings_lossy1 = 1, /* encode, decode: lossy once */
  sox_encodings_lossy2 = 2  /* encode, decode, encode, decode: lossy twice */
} sox_encodings_flags_t;

#define SOX_LOSSY1 sox_encodings_lossy1 /* encode, decode: lossy once */
#define SOX_LOSSY2 sox_encodings_lossy2 /* encode, decode, encode, decode: lossy twice */

typedef struct sox_encodings_info_t {
  sox_encodings_flags_t flags; /* lossy once (lossy1), lossy twice (lossy2), or lossless (0) */
  char const * name;           /* encoding name */
  char const * desc;           /* encoding description */
} sox_encodings_info_t;

/* the list of available encodings */
extern sox_encodings_info_t const sox_encodings_info[];

/* yes, no, or default (auto-detect) */
typedef enum sox_option_t {
    SOX_OPTION_NO,
    SOX_OPTION_YES,
    SOX_OPTION_DEFAULT
} sox_option_t;

/* Encoding parameters */
typedef struct sox_encodinginfo_t {
  sox_encoding_t encoding; /* format of sample numbers */
  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 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... */
  sox_option_t reverse_nibbles;
  sox_option_t reverse_bits;

  sox_bool opposite_endian;
} sox_encodinginfo_t;

/* fills in an encodinginfo with default values */
void sox_init_encodinginfo(sox_encodinginfo_t * e);

/* 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     /* = 2 (stereo) */
#define SOX_DEFAULT_RATE      48000 /* = 48000Hz */
#define SOX_DEFAULT_PRECISION 16    /* = 16 bits per sample */
#define SOX_DEFAULT_ENCODING  SOX_ENCODING_SIGN2 /* = SIGN2 (linear 2's complement PCM) */

/* Loop parameters */

/* Loop modes, upper 4 bits mask the loop blass, lower 4 bits describe */
/* the loop behaviour, ie. single shot, bidirectional etc. */
enum sox_loop_flags_t {
  sox_loop_none = 0,          /* single-shot = 0 */
  sox_loop_forward = 1,       /* forward loop = 1 */
  sox_loop_forward_back = 2,  /* forward/back loop = 2 */
  sox_loop_8 = 32,            /* 8 loops (??) = 32 */
  sox_loop_sustain_decay = 64 /* AIFF style, one sustain & one decay loop = 64 */
};
#define SOX_LOOP_NONE          ((unsigned char)sox_loop_none)          /* single-shot = 0 */
#define SOX_LOOP_8             ((unsigned char)sox_loop_8)             /* 8 loops (??) = 32 */
#define SOX_LOOP_SUSTAIN_DECAY ((unsigned char)sox_loop_sustain_decay) /* AIFF style, one sustain & one decay loop = 64 */

/* Looping parameters (out-of-band data) */
typedef struct sox_loopinfo_t {
  sox_uint64_t  start;  /* first sample */
  sox_uint64_t  length; /* length */
  unsigned      count;  /* number of repeats, 0=forever */
  unsigned char type;   /* 0=no, 1=forward, 2=forward/back (see sox_loop_... for valid values) */
} sox_loopinfo_t;

/* Instrument parameters */

/* vague attempt at generic information for sampler-specific info */

/* instrument information */
typedef struct sox_instrinfo_t{
  signed char MIDInote;   /* for unity pitch playback */
  signed char MIDIlow;    /* MIDI pitch-bend low range */
  signed char MIDIhi;     /* MIDI pitch-bend high range */
  unsigned char loopmode; /* 0=no, 1=forward, 2=forward/back (see sox_loop_... values) */
  unsigned nloops;  /* number of active loops (max SOX_MAX_NLOOPS) */
} sox_instrinfo_t;

/* File buffer info.  Holds info so that data can be read in blocks. */
typedef struct sox_fileinfo_t {
  char          *buf;                 /* Pointer to data 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;


typedef struct sox_format_t sox_format_t; /* file format definition */

/* Handler structure defined by each format. */
typedef struct sox_format_handler_t {
  unsigned     sox_lib_version_code; /* Checked on load; must be 1st in struct*/
  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, sox_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;

/*
 *  Format information for input and output files.
 */

/* File's metadata. Access via sox_..._comments functions. */
typedef char * * sox_comments_t;

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

/* comments, instrument info, loop info (out-of-band data) */
typedef struct sox_oob_t{
  /* Decoded: */
  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;

/* Is file a real file, a pipe, or a url? */
typedef enum lsx_io_type
{
    lsx_io_file,
    lsx_io_pipe,
    lsx_io_url
} lsx_io_type;

struct sox_format_t { /* Data passed to/from the format handler */
  char             * filename;      /* File name */
  
  /* 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') */
  sox_uint64_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 */
  void             * fp;            /* File stream pointer */
  lsx_io_type      io_type;         /* Stores whether this is a file, pipe or URL */
  sox_uint64_t     tell_off;        /* Current offset within file */
  sox_uint64_t     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 */
};

/* 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 (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 /* 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) /* 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);  /* Find & load format handler plugins. */
void sox_format_quit(void); /* Unload format handler plugins. */

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);

/* Information about a loaded format handler: name and function pointer */
typedef struct sox_format_tab_t {
  char *name;         /* Name of format handler */
  sox_format_fn_t fn; /* Function to call to get format handler's information */
} sox_format_tab_t;

/* the table of format handler names and functions */
extern sox_format_tab_t sox_format_fns[];

/* Opens a decoding session for a file. Returned handle must be closed with sox_close(). */
sox_format_t * sox_open_read(
    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,      /* 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,       /* 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,         /* 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,     /* 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,      /* 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,    /* 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, sox_uint64_t offset, int whence);

/* Finds a format handler by name. */
sox_format_handler_t const * sox_find_format(char const * name, sox_bool ignore_devices);

/*
 * Structures for effects.
 */

#define SOX_MAX_EFFECTS 20

#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_t {
    sox_plot_off,
    sox_plot_octave,
    sox_plot_gnuplot,
    sox_plot_data
} sox_plot_t;

typedef struct sox_effect_t sox_effect_t;

/* Global parameters for effects */
typedef struct sox_effects_globals_t {
  sox_plot_t plot;         /* To help the user choose effect & options */
  sox_globals_t * global_info; /* Pointer to associated SoX globals */
} sox_effects_globals_t;

/* Global parameters for effects */
extern sox_effects_globals_t sox_effects_globals;

/* Effect handler information */
typedef struct sox_effect_handler_t {
  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[]); /* 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);       /* 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;

/* Effect information */
struct sox_effect_t {
  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 */
};

/* 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[];

/* Chain of effects to be applied to a stream */
typedef struct sox_effects_chain_t {
  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 */
} 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.
 * sox_trim_get_start can be used to find what is the start
 * of the trim operation as specified by the user.
 * sox_trim_clear_start will reset what ever the user specified
 * back to 0.
 * These two can be used together to find out what the user
 * wants to trim and use a sox_seek() operation instead.  After
 * sox_seek()'ing, you should set the trim option to 0.
 */
sox_uint64_t sox_trim_get_start(sox_effect_t * effp);
void sox_trim_clear_start(sox_effect_t * effp);
sox_uint64_t sox_crop_get_start(sox_effect_t * effp);
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);

/* Gets the basename of the specified file, i.e. for "/a/b/c.d", gets "c".
 * Returns the number of characters written to base_buffer, excluding the null. */
int sox_basename(char * base_buffer, size_t base_buffer_len, const char * filename);

/* WARNING BEGIN
 *
 * The items in this section are subject to instability.  They only exist
 * in public API because sox (the application) make use of them but
 * may not be supported and may change rapidly.
 */
void lsx_fail(const char *, ...) LSX_PRINTF;
void lsx_warn(const char *, ...) LSX_PRINTF;
void lsx_report(const char *, ...) LSX_PRINTF;
void lsx_debug(const char *, ...) LSX_PRINTF;

#define lsx_fail       sox_globals.subsystem=__FILE__,lsx_fail
#define lsx_warn       sox_globals.subsystem=__FILE__,lsx_warn
#define lsx_report     sox_globals.subsystem=__FILE__,lsx_report
#define lsx_debug      sox_globals.subsystem=__FILE__,lsx_debug

typedef struct lsx_enum_item {
    char const *text;
    unsigned value;
} lsx_enum_item;
#define LSX_ENUM_ITEM(prefix, item) {#item, prefix##item},

lsx_enum_item const * lsx_find_enum_text(char const * text, lsx_enum_item const * lsx_enum_items, unsigned flags);
#define LSX_FET_CASE 1
lsx_enum_item const * lsx_find_enum_value(unsigned value, lsx_enum_item const * lsx_enum_items);
int lsx_enum_option(int c, lsx_enum_item const * items);
sox_bool lsx_strends(char const * str, char const * end);
char const * lsx_find_file_extension(char const * pathname);
char const * lsx_sigfigs3(double number);
char const * lsx_sigfigs3p(double percentage);
void *lsx_realloc(void *ptr, size_t newsize);
int lsx_strcasecmp(const char * s1, const char * s2);
int lsx_strncasecmp(char const * s1, char const * s2, size_t n);

/* WARNING END */

#if defined(__cplusplus)
}
#endif

#endif /* SOX_H */