1 /* libSoX Library Public Interface 2 * 3 * Copyright 1999-2012 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 /** @file 12 Contains the interface exposed to clients of the libSoX library. 13 Symbols starting with "sox_" or "SOX_" are part of the public interface for 14 libSoX clients (applications that consume libSoX). Symbols starting with 15 "lsx_" or "LSX_" are internal use by libSoX and plugins. 16 LSX_ and lsx_ symbols should not be used by libSoX-based applications. 17 */ 18 19 #ifndef SOX_H 20 #define SOX_H /**< Client API: This macro is defined if sox.h has been included. */ 21 22 #include <limits.h> 23 #include <stdarg.h> 24 #include <stddef.h> 25 26 #if defined(__cplusplus) 27 extern "C" { 28 #endif 29 30 /* Suppress warnings from use of type long long. */ 31 #if defined __GNUC__ 32 #pragma GCC system_header 33 #endif 34 35 /***************************************************************************** 36 API decoration macros: 37 Mostly for documentation purposes. For some compilers, decorations also affect 38 code generation, influence compiler warnings or activate compiler 39 optimizations. 40 *****************************************************************************/ 41 42 /** 43 Plugins API: 44 Attribute required on all functions exported by libSoX and on all function 45 pointer types used by the libSoX API. 46 */ 47 #ifdef __GNUC__ 48 #define LSX_API __attribute__ ((cdecl)) /* libSoX function */ 49 #elif _MSC_VER 50 #define LSX_API __cdecl /* libSoX function */ 51 #else 52 #define LSX_API /* libSoX function */ 53 #endif 54 55 /** 56 Plugins API: 57 Attribute applied to a parameter or local variable to suppress warnings about 58 the variable being unused (especially in macro-generated code). 59 */ 60 #ifdef __GNUC__ 61 #define LSX_UNUSED __attribute__ ((unused)) /* Parameter or local variable is intentionally unused. */ 62 #else 63 #define LSX_UNUSED /* Parameter or local variable is intentionally unused. */ 64 #endif 65 66 /** 67 Plugins API: 68 LSX_PRINTF12: Attribute applied to a function to indicate that it requires 69 a printf-style format string for arg1 and that printf parameters start at 70 arg2. 71 */ 72 #ifdef __GNUC__ 73 #define LSX_PRINTF12 __attribute__ ((format (printf, 1, 2))) /* Function has printf-style arguments. */ 74 #else 75 #define LSX_PRINTF12 /* Function has printf-style arguments. */ 76 #endif 77 78 /** 79 Plugins API: 80 Attribute applied to a function to indicate that it has no side effects and 81 depends only its input parameters and global memory. If called repeatedly, it 82 returns the same result each time. 83 */ 84 #ifdef __GNUC__ 85 #define LSX_RETURN_PURE __attribute__ ((pure)) /* Function is pure. */ 86 #else 87 #define LSX_RETURN_PURE /* Function is pure. */ 88 #endif 89 90 /** 91 Plugins API: 92 Attribute applied to a function to indicate that the 93 return value is always a pointer to a valid object (never NULL). 94 */ 95 #ifdef _Ret_ 96 #define LSX_RETURN_VALID _Ret_ /* Function always returns a valid object (never NULL). */ 97 #else 98 #define LSX_RETURN_VALID /* Function always returns a valid object (never NULL). */ 99 #endif 100 101 /** 102 Plugins API: 103 Attribute applied to a function to indicate that the return value is always a 104 pointer to a valid array (never NULL). 105 */ 106 #ifdef _Ret_valid_ 107 #define LSX_RETURN_ARRAY _Ret_valid_ /* Function always returns a valid array (never NULL). */ 108 #else 109 #define LSX_RETURN_ARRAY /* Function always returns a valid array (never NULL). */ 110 #endif 111 112 /** 113 Plugins API: 114 Attribute applied to a function to indicate that the return value is always a 115 pointer to a valid 0-terminated array (never NULL). 116 */ 117 #ifdef _Ret_z_ 118 #define LSX_RETURN_VALID_Z _Ret_z_ /* Function always returns a 0-terminated array (never NULL). */ 119 #else 120 #define LSX_RETURN_VALID_Z /* Function always returns a 0-terminated array (never NULL). */ 121 #endif 122 123 /** 124 Plugins API: 125 Attribute applied to a function to indicate that the returned pointer may be 126 null. 127 */ 128 #ifdef _Ret_opt_ 129 #define LSX_RETURN_OPT _Ret_opt_ /* Function may return NULL. */ 130 #else 131 #define LSX_RETURN_OPT /* Function may return NULL. */ 132 #endif 133 134 /** 135 Plugins API: 136 Attribute applied to a parameter to indicate that the parameter is a valid 137 pointer to one const element of the pointed-to type (never NULL). 138 */ 139 #ifdef _In_ 140 #define LSX_PARAM_IN _In_ /* Required const pointer to a valid object (never NULL). */ 141 #else 142 #define LSX_PARAM_IN /* Required const pointer to a valid object (never NULL). */ 143 #endif 144 145 /** 146 Plugins API: 147 Attribute applied to a parameter to indicate that the parameter is a valid 148 pointer to a const 0-terminated string (never NULL). 149 */ 150 #ifdef _In_z_ 151 #define LSX_PARAM_IN_Z _In_z_ /* Required const pointer to 0-terminated string (never NULL). */ 152 #else 153 #define LSX_PARAM_IN_Z /* Required const pointer to 0-terminated string (never NULL). */ 154 #endif 155 156 /** 157 Plugins API: 158 Attribute applied to a parameter to indicate that the parameter is a const 159 pointer to a 0-terminated printf format string. 160 */ 161 #ifdef _Printf_format_string_ 162 #define LSX_PARAM_IN_PRINTF _Printf_format_string_ /* Required const pointer to 0-terminated printf format string (never NULL). */ 163 #else 164 #define LSX_PARAM_IN_PRINTF /* Required const pointer to 0-terminated printf format string (never NULL). */ 165 #endif 166 167 /** 168 Plugins API: 169 Attribute applied to a parameter to indicate that the parameter is a valid 170 pointer to (len) const initialized elements of the pointed-to type, where 171 (len) is the name of another parameter. 172 @param len The parameter that contains the number of elements in the array. 173 */ 174 #ifdef _In_count_ 175 #define LSX_PARAM_IN_COUNT(len) _In_count_(len) /* Required const pointer to (len) valid objects (never NULL). */ 176 #else 177 #define LSX_PARAM_IN_COUNT(len) /* Required const pointer to (len) valid objects (never NULL). */ 178 #endif 179 180 /** 181 Plugins API: 182 Attribute applied to a parameter to indicate that the parameter is a valid 183 pointer to (len) const bytes of initialized data, where (len) is the name of 184 another parameter. 185 @param len The parameter that contains the number of bytes in the array. 186 */ 187 #ifdef _In_bytecount_ 188 #define LSX_PARAM_IN_BYTECOUNT(len) _In_bytecount_(len) /* Required const pointer to (len) bytes of data (never NULL). */ 189 #else 190 #define LSX_PARAM_IN_BYTECOUNT(len) /* Required const pointer to (len) bytes of data (never NULL). */ 191 #endif 192 193 /** 194 Plugins API: 195 Attribute applied to a parameter to indicate that the parameter is either NULL 196 or a valid pointer to one const element of the pointed-to type. 197 */ 198 #ifdef _In_opt_ 199 #define LSX_PARAM_IN_OPT _In_opt_ /* Optional const pointer to a valid object (may be NULL). */ 200 #else 201 #define LSX_PARAM_IN_OPT /* Optional const pointer to a valid object (may be NULL). */ 202 #endif 203 204 /** 205 Plugins API: 206 Attribute applied to a parameter to indicate that the parameter is either NULL 207 or a valid pointer to a const 0-terminated string. 208 */ 209 #ifdef _In_opt_z_ 210 #define LSX_PARAM_IN_OPT_Z _In_opt_z_ /* Optional const pointer to 0-terminated string (may be NULL). */ 211 #else 212 #define LSX_PARAM_IN_OPT_Z /* Optional const pointer to 0-terminated string (may be NULL). */ 213 #endif 214 215 /** 216 Plugins API: 217 Attribute applied to a parameter to indicate that the parameter is a valid 218 pointer to one initialized element of the pointed-to type (never NULL). The 219 function may modify the element. 220 */ 221 #ifdef _Inout_ 222 #define LSX_PARAM_INOUT _Inout_ /* Required pointer to a valid object (never NULL). */ 223 #else 224 #define LSX_PARAM_INOUT /* Required pointer to a valid object (never NULL). */ 225 #endif 226 227 /** 228 Plugins API: 229 Attribute applied to a parameter to indicate that the parameter is a valid 230 pointer to (len) initialized elements of the pointed-to type (never NULL). The 231 function may modify the elements. 232 @param len The parameter that contains the number of elements in the array. 233 */ 234 #ifdef _Inout_count_x_ 235 #define LSX_PARAM_INOUT_COUNT(len) _Inout_count_x_(len) /* Required pointer to (len) valid objects (never NULL). */ 236 #else 237 #define LSX_PARAM_INOUT_COUNT(len) /* Required pointer to (len) valid objects (never NULL). */ 238 #endif 239 240 /** 241 Plugins API: 242 Attribute applied to a parameter to indicate that the parameter is a valid 243 pointer to memory sufficient for one element of the pointed-to type (never 244 NULL). The function will initialize the element. 245 */ 246 #ifdef _Out_ 247 #define LSX_PARAM_OUT _Out_ /* Required pointer to an object to be initialized (never NULL). */ 248 #else 249 #define LSX_PARAM_OUT /* Required pointer to an object to be initialized (never NULL). */ 250 #endif 251 252 /** 253 Plugins API: 254 Attribute applied to a parameter to indicate that the parameter is a valid 255 pointer to memory sufficient for (len) bytes of data (never NULL), where (len) 256 is the name of another parameter. The function may write up to len bytes of 257 data to this memory. 258 @param len The parameter that contains the number of bytes in the array. 259 */ 260 #ifdef _Out_bytecap_ 261 #define LSX_PARAM_OUT_BYTECAP(len) _Out_bytecap_(len) /* Required pointer to writable buffer with room for len bytes. */ 262 #else 263 #define LSX_PARAM_OUT_BYTECAP(len) /* Required pointer to writable buffer with room for len bytes. */ 264 #endif 265 266 /** 267 Plugins API: 268 Attribute applied to a parameter to indicate that the parameter is a valid 269 pointer to memory sufficient for (len) elements of the pointed-to type (never 270 NULL), where (len) is the name of another parameter. On return, (filled) 271 elements will have been initialized, where (filled) is either the dereference 272 of another pointer parameter (for example "*written") or the "return" 273 parameter (indicating that the function returns the number of elements 274 written). 275 @param len The parameter that contains the number of elements in the array. 276 @param filled The dereference of the parameter that receives the number of elements written to the array, or "return" if the value is returned. 277 */ 278 #ifdef _Out_cap_post_count_ 279 #define LSX_PARAM_OUT_CAP_POST_COUNT(len,filled) _Out_cap_post_count_(len,filled) /* Required pointer to buffer for (len) elements (never NULL); on return, (filled) elements will have been initialized. */ 280 #else 281 #define LSX_PARAM_OUT_CAP_POST_COUNT(len,filled) /* Required pointer to buffer for (len) elements (never NULL); on return, (filled) elements will have been initialized. */ 282 #endif 283 284 /** 285 Plugins API: 286 Attribute applied to a parameter to indicate that the parameter is a valid 287 pointer to memory sufficient for (len) elements of the pointed-to type (never 288 NULL), where (len) is the name of another parameter. On return, (filled+1) 289 elements will have been initialized, with the last element having been 290 initialized to 0, where (filled) is either the dereference of another pointer 291 parameter (for example, "*written") or the "return" parameter (indicating that 292 the function returns the number of elements written). 293 @param len The parameter that contains the number of elements in the array. 294 @param filled The dereference of the parameter that receives the number of elements written to the array (not counting the terminating null), or "return" if the value is returned. 295 */ 296 #ifdef _Out_z_cap_post_count_ 297 #define LSX_PARAM_OUT_Z_CAP_POST_COUNT(len,filled) _Out_z_cap_post_count_(len,filled) /* Required pointer to buffer for (len) elements (never NULL); on return, (filled+1) elements will have been initialized, and the array will be 0-terminated. */ 298 #else 299 #define LSX_PARAM_OUT_Z_CAP_POST_COUNT(len,filled) /* Required pointer to buffer for (len) elements (never NULL); on return, (filled+1) elements will have been initialized, and the array will be 0-terminated. */ 300 #endif 301 302 /** 303 Plugins API: 304 Attribute applied to a parameter to indicate that the parameter is either NULL 305 or a valid pointer to memory sufficient for one element of the pointed-to 306 type. The function will initialize the element. 307 */ 308 #ifdef _Out_opt_ 309 #define LSX_PARAM_OUT_OPT _Out_opt_ /* Optional pointer to an object to be initialized (may be NULL). */ 310 #else 311 #define LSX_PARAM_OUT_OPT /* Optional pointer to an object to be initialized (may be NULL). */ 312 #endif 313 314 /** 315 Plugins API: 316 Attribute applied to a parameter to indicate that the parameter is a valid 317 pointer (never NULL) to another pointer which may be NULL when the function is 318 invoked. 319 */ 320 #ifdef _Deref_pre_maybenull_ 321 #define LSX_PARAM_DEREF_PRE_MAYBENULL _Deref_pre_maybenull_ /* Required pointer (never NULL) to another pointer (may be NULL). */ 322 #else 323 #define LSX_PARAM_DEREF_PRE_MAYBENULL /* Required pointer (never NULL) to another pointer (may be NULL). */ 324 #endif 325 326 /** 327 Plugins API: 328 Attribute applied to a parameter to indicate that the parameter is a valid 329 pointer (never NULL) to another pointer which will be NULL when the function 330 returns. 331 */ 332 #ifdef _Deref_post_null_ 333 #define LSX_PARAM_DEREF_POST_NULL _Deref_post_null_ /* Required pointer (never NULL) to another pointer, which will be NULL on exit. */ 334 #else 335 #define LSX_PARAM_DEREF_POST_NULL /* Required pointer (never NULL) to another pointer, which will be NULL on exit. */ 336 #endif 337 338 /** 339 Plugins API: 340 Attribute applied to a parameter to indicate that the parameter is a valid 341 pointer (never NULL) to another pointer which will be non-NULL when the 342 function returns. 343 */ 344 #ifdef _Deref_post_notnull_ 345 #define LSX_PARAM_DEREF_POST_NOTNULL _Deref_post_notnull_ /* Required pointer (never NULL) to another pointer, which will be valid (not NULL) on exit. */ 346 #else 347 #define LSX_PARAM_DEREF_POST_NOTNULL /* Required pointer (never NULL) to another pointer, which will be valid (not NULL) on exit. */ 348 #endif 349 350 /** 351 Plugins API: 352 Expression that "uses" a potentially-unused variable to avoid compiler 353 warnings (especially in macro-generated code). 354 */ 355 #ifdef _PREFAST_ 356 #define LSX_USE_VAR(x) ((void)(x=0)) /* During static analysis, initialize unused variables to 0. */ 357 #else 358 #define LSX_USE_VAR(x) ((void)(x)) /* Parameter or variable is intentionally unused. */ 359 #endif 360 361 /** 362 Plugins API: 363 Compile-time assertion. Causes a compile error if the expression is false. 364 @param e The expression to test. If expression is false, compilation will fail. 365 @param f A unique identifier for the test, for example foo_must_not_be_zero. 366 */ 367 #define lsx_static_assert(e,f) enum {lsx_static_assert_##f = 1/((e) ? 1 : 0)} 368 369 /***************************************************************************** 370 Basic typedefs: 371 *****************************************************************************/ 372 373 /** 374 Client API: 375 Signed twos-complement 8-bit type. Typically defined as signed char. 376 */ 377 #if SCHAR_MAX==127 && SCHAR_MIN==(-128) 378 typedef signed char sox_int8_t; 379 #elif CHAR_MAX==127 && CHAR_MIN==(-128) 380 typedef char sox_int8_t; 381 #else 382 #error Unable to determine an appropriate definition for sox_int8_t. 383 #endif 384 385 /** 386 Client API: 387 Unsigned 8-bit type. Typically defined as unsigned char. 388 */ 389 #if UCHAR_MAX==0xff 390 typedef unsigned char sox_uint8_t; 391 #elif CHAR_MAX==0xff && CHAR_MIN==0 392 typedef char sox_uint8_t; 393 #else 394 #error Unable to determine an appropriate definition for sox_uint8_t. 395 #endif 396 397 /** 398 Client API: 399 Signed twos-complement 16-bit type. Typically defined as short. 400 */ 401 #if SHRT_MAX==32767 && SHRT_MIN==(-32768) 402 typedef short sox_int16_t; 403 #elif INT_MAX==32767 && INT_MIN==(-32768) 404 typedef int sox_int16_t; 405 #else 406 #error Unable to determine an appropriate definition for sox_int16_t. 407 #endif 408 409 /** 410 Client API: 411 Unsigned 16-bit type. Typically defined as unsigned short. 412 */ 413 #if USHRT_MAX==0xffff 414 typedef unsigned short sox_uint16_t; 415 #elif UINT_MAX==0xffff 416 typedef unsigned int sox_uint16_t; 417 #else 418 #error Unable to determine an appropriate definition for sox_uint16_t. 419 #endif 420 421 /** 422 Client API: 423 Signed twos-complement 32-bit type. Typically defined as int. 424 */ 425 #if INT_MAX==2147483647 && INT_MIN==(-2147483647-1) 426 typedef int sox_int32_t; 427 #elif LONG_MAX==2147483647 && LONG_MIN==(-2147483647-1) 428 typedef long sox_int32_t; 429 #else 430 #error Unable to determine an appropriate definition for sox_int32_t. 431 #endif 432 433 /** 434 Client API: 435 Unsigned 32-bit type. Typically defined as unsigned int. 436 */ 437 #if UINT_MAX==0xffffffff 438 typedef unsigned int sox_uint32_t; 439 #elif ULONG_MAX==0xffffffff 440 typedef unsigned long sox_uint32_t; 441 #else 442 #error Unable to determine an appropriate definition for sox_uint32_t. 443 #endif 444 445 /** 446 Client API: 447 Signed twos-complement 64-bit type. Typically defined as long or long long. 448 */ 449 #if LONG_MAX==9223372036854775807 && LONG_MIN==(-9223372036854775807-1) 450 typedef long sox_int64_t; 451 #elif defined(_MSC_VER) 452 typedef __int64 sox_int64_t; 453 #else 454 typedef long long sox_int64_t; 455 #endif 456 457 /** 458 Client API: 459 Unsigned 64-bit type. Typically defined as unsigned long or unsigned long long. 460 */ 461 #if ULONG_MAX==0xffffffffffffffff 462 typedef unsigned long sox_uint64_t; 463 #elif defined(_MSC_VER) 464 typedef unsigned __int64 sox_uint64_t; 465 #else 466 typedef unsigned long long sox_uint64_t; 467 #endif 468 469 #ifndef _DOXYGEN_ 470 lsx_static_assert(sizeof(sox_int8_t)==1, sox_int8_size); 471 lsx_static_assert(sizeof(sox_uint8_t)==1, sox_uint8_size); 472 lsx_static_assert(sizeof(sox_int16_t)==2, sox_int16_size); 473 lsx_static_assert(sizeof(sox_uint16_t)==2, sox_uint16_size); 474 lsx_static_assert(sizeof(sox_int32_t)==4, sox_int32_size); 475 lsx_static_assert(sizeof(sox_uint32_t)==4, sox_uint32_size); 476 lsx_static_assert(sizeof(sox_int64_t)==8, sox_int64_size); 477 lsx_static_assert(sizeof(sox_uint64_t)==8, sox_uint64_size); 478 #endif 479 480 /** 481 Client API: 482 Alias for sox_int32_t (beware of the extra byte). 483 */ 484 typedef sox_int32_t sox_int24_t; 485 486 /** 487 Client API: 488 Alias for sox_uint32_t (beware of the extra byte). 489 */ 490 typedef sox_uint32_t sox_uint24_t; 491 492 /** 493 Client API: 494 Native SoX audio sample type (alias for sox_int32_t). 495 */ 496 typedef sox_int32_t sox_sample_t; 497 498 /** 499 Client API: 500 Samples per second is stored as a double. 501 */ 502 typedef double sox_rate_t; 503 504 /** 505 Client API: 506 File's metadata, access via sox_*_comments functions. 507 */ 508 typedef char * * sox_comments_t; 509 510 /***************************************************************************** 511 Enumerations: 512 *****************************************************************************/ 513 514 /** 515 Client API: 516 Boolean type, assignment (but not necessarily binary) compatible with C++ bool. 517 */ 518 typedef enum sox_bool { 519 sox_bool_dummy = -1, /* Ensure a signed type */ 520 sox_false, /**< False = 0. */ 521 sox_true /**< True = 1. */ 522 } sox_bool; 523 524 /** 525 Client API: 526 no, yes, or default (default usually implies some kind of auto-detect logic). 527 */ 528 typedef enum sox_option_t { 529 sox_option_no, /**< Option specified as no = 0. */ 530 sox_option_yes, /**< Option specified as yes = 1. */ 531 sox_option_default /**< Option unspecified = 2. */ 532 } sox_option_t; 533 534 /** 535 Client API: 536 The libSoX-specific error codes. 537 libSoX functions may return these codes or others that map from errno codes. 538 */ 539 enum sox_error_t { 540 SOX_SUCCESS = 0, /**< Function succeeded = 0 */ 541 SOX_EOF = -1, /**< End Of File or other error = -1 */ 542 SOX_EHDR = 2000, /**< Invalid Audio Header = 2000 */ 543 SOX_EFMT, /**< Unsupported data format = 2001 */ 544 SOX_ENOMEM, /**< Can't alloc memory = 2002 */ 545 SOX_EPERM, /**< Operation not permitted = 2003 */ 546 SOX_ENOTSUP, /**< Operation not supported = 2004 */ 547 SOX_EINVAL /**< Invalid argument = 2005 */ 548 }; 549 550 /** 551 Client API: 552 Flags indicating whether optional features are present in this build of libSoX. 553 */ 554 typedef enum sox_version_flags_t { 555 sox_version_none = 0, /**< No special features = 0. */ 556 sox_version_have_popen = 1, /**< popen = 1. */ 557 sox_version_have_magic = 2, /**< magic = 2. */ 558 sox_version_have_threads = 4, /**< threads = 4. */ 559 sox_version_have_memopen = 8 /**< memopen = 8. */ 560 } sox_version_flags_t; 561 562 /** 563 Client API: 564 Format of sample data. 565 */ 566 typedef enum sox_encoding_t { 567 SOX_ENCODING_UNKNOWN , /**< encoding has not yet been determined */ 568 569 SOX_ENCODING_SIGN2 , /**< signed linear 2's comp: Mac */ 570 SOX_ENCODING_UNSIGNED , /**< unsigned linear: Sound Blaster */ 571 SOX_ENCODING_FLOAT , /**< floating point (binary format) */ 572 SOX_ENCODING_FLOAT_TEXT, /**< floating point (text format) */ 573 SOX_ENCODING_FLAC , /**< FLAC compression */ 574 SOX_ENCODING_HCOM , /**< Mac FSSD files with Huffman compression */ 575 SOX_ENCODING_WAVPACK , /**< WavPack with integer samples */ 576 SOX_ENCODING_WAVPACKF , /**< WavPack with float samples */ 577 SOX_ENCODING_ULAW , /**< u-law signed logs: US telephony, SPARC */ 578 SOX_ENCODING_ALAW , /**< A-law signed logs: non-US telephony, Psion */ 579 SOX_ENCODING_G721 , /**< G.721 4-bit ADPCM */ 580 SOX_ENCODING_G723 , /**< G.723 3 or 5 bit ADPCM */ 581 SOX_ENCODING_CL_ADPCM , /**< Creative Labs 8 --> 2,3,4 bit Compressed PCM */ 582 SOX_ENCODING_CL_ADPCM16, /**< Creative Labs 16 --> 4 bit Compressed PCM */ 583 SOX_ENCODING_MS_ADPCM , /**< Microsoft Compressed PCM */ 584 SOX_ENCODING_IMA_ADPCM , /**< IMA Compressed PCM */ 585 SOX_ENCODING_OKI_ADPCM , /**< Dialogic/OKI Compressed PCM */ 586 SOX_ENCODING_DPCM , /**< Differential PCM: Fasttracker 2 (xi) */ 587 SOX_ENCODING_DWVW , /**< Delta Width Variable Word */ 588 SOX_ENCODING_DWVWN , /**< Delta Width Variable Word N-bit */ 589 SOX_ENCODING_GSM , /**< GSM 6.10 33byte frame lossy compression */ 590 SOX_ENCODING_MP3 , /**< MP3 compression */ 591 SOX_ENCODING_VORBIS , /**< Vorbis compression */ 592 SOX_ENCODING_AMR_WB , /**< AMR-WB compression */ 593 SOX_ENCODING_AMR_NB , /**< AMR-NB compression */ 594 SOX_ENCODING_CVSD , /**< Continuously Variable Slope Delta modulation */ 595 SOX_ENCODING_LPC10 , /**< Linear Predictive Coding */ 596 SOX_ENCODING_OPUS , /**< Opus compression */ 597 598 SOX_ENCODINGS /**< End of list marker */ 599 } sox_encoding_t; 600 601 /** 602 Client API: 603 Flags for sox_encodings_info_t: lossless/lossy1/lossy2. 604 */ 605 typedef enum sox_encodings_flags_t { 606 sox_encodings_none = 0, /**< no flags specified (implies lossless encoding) = 0. */ 607 sox_encodings_lossy1 = 1, /**< encode, decode: lossy once = 1. */ 608 sox_encodings_lossy2 = 2 /**< encode, decode, encode, decode: lossy twice = 2. */ 609 } sox_encodings_flags_t; 610 611 /** 612 Client API: 613 Type of plot. 614 */ 615 typedef enum sox_plot_t { 616 sox_plot_off, /**< No plot = 0. */ 617 sox_plot_octave, /**< Octave plot = 1. */ 618 sox_plot_gnuplot, /**< Gnuplot plot = 2. */ 619 sox_plot_data /**< Plot data = 3. */ 620 } sox_plot_t; 621 622 /** 623 Client API: 624 Loop modes: upper 4 bits mask the loop blass, lower 4 bits describe 625 the loop behaviour, for example single shot, bidirectional etc. 626 */ 627 enum sox_loop_flags_t { 628 sox_loop_none = 0, /**< single-shot = 0 */ 629 sox_loop_forward = 1, /**< forward loop = 1 */ 630 sox_loop_forward_back = 2, /**< forward/back loop = 2 */ 631 sox_loop_8 = 32, /**< 8 loops (??) = 32 */ 632 sox_loop_sustain_decay = 64 /**< AIFF style, one sustain & one decay loop = 64 */ 633 }; 634 635 /** 636 Plugins API: 637 Is file a real file, a pipe, or a url? 638 */ 639 typedef enum lsx_io_type 640 { 641 lsx_io_file, /**< File is a real file = 0. */ 642 lsx_io_pipe, /**< File is a pipe (no seeking) = 1. */ 643 lsx_io_url /**< File is a URL (no seeking) = 2. */ 644 } lsx_io_type; 645 646 /***************************************************************************** 647 Macros: 648 *****************************************************************************/ 649 650 /** 651 Client API: 652 Compute a 32-bit integer API version from three 8-bit parts. 653 @param a Major version. 654 @param b Minor version. 655 @param c Revision or build number. 656 @returns 32-bit integer API version 0x000a0b0c. 657 */ 658 #define SOX_LIB_VERSION(a,b,c) (((a) << 16) + ((b) << 8) + (c)) 659 660 /** 661 Client API: 662 The API version of the sox.h file. It is not meant to follow the version 663 number of SoX but it has historically. Please do not count on 664 SOX_LIB_VERSION_CODE staying in sync with the libSoX version. 665 */ 666 #define SOX_LIB_VERSION_CODE SOX_LIB_VERSION(14, 4, 2) 667 668 /** 669 Client API: 670 Returns the smallest (negative) value storable in a twos-complement signed 671 integer with the specified number of bits, cast to an unsigned integer; 672 for example, SOX_INT_MIN(8) = 0x80, SOX_INT_MIN(16) = 0x8000, etc. 673 @param bits Size of value for which to calculate minimum. 674 @returns the smallest (negative) value storable in a twos-complement signed 675 integer with the specified number of bits, cast to an unsigned integer. 676 */ 677 #define SOX_INT_MIN(bits) (1 <<((bits)-1)) 678 679 /** 680 Client API: 681 Returns the largest (positive) value storable in a twos-complement signed 682 integer with the specified number of bits, cast to an unsigned integer; 683 for example, SOX_INT_MAX(8) = 0x7F, SOX_INT_MAX(16) = 0x7FFF, etc. 684 @param bits Size of value for which to calculate maximum. 685 @returns the largest (positive) value storable in a twos-complement signed 686 integer with the specified number of bits, cast to an unsigned integer. 687 */ 688 #define SOX_INT_MAX(bits) (((unsigned)-1)>>(33-(bits))) 689 690 /** 691 Client API: 692 Returns the largest value storable in an unsigned integer with the specified 693 number of bits; for example, SOX_UINT_MAX(8) = 0xFF, 694 SOX_UINT_MAX(16) = 0xFFFF, etc. 695 @param bits Size of value for which to calculate maximum. 696 @returns the largest value storable in an unsigned integer with the specified 697 number of bits. 698 */ 699 #define SOX_UINT_MAX(bits) (SOX_INT_MIN(bits)|SOX_INT_MAX(bits)) 700 701 /** 702 Client API: 703 Returns 0x7F. 704 */ 705 #define SOX_INT8_MAX SOX_INT_MAX(8) 706 707 /** 708 Client API: 709 Returns 0x7FFF. 710 */ 711 #define SOX_INT16_MAX SOX_INT_MAX(16) 712 713 /** 714 Client API: 715 Returns 0x7FFFFF. 716 */ 717 #define SOX_INT24_MAX SOX_INT_MAX(24) 718 719 /** 720 Client API: 721 Returns 0x7FFFFFFF. 722 */ 723 #define SOX_INT32_MAX SOX_INT_MAX(32) 724 725 /** 726 Client API: 727 Bits in a sox_sample_t = 32. 728 */ 729 #define SOX_SAMPLE_PRECISION 32 730 731 /** 732 Client API: 733 Max value for sox_sample_t = 0x7FFFFFFF. 734 */ 735 #define SOX_SAMPLE_MAX (sox_sample_t)SOX_INT_MAX(32) 736 737 /** 738 Client API: 739 Min value for sox_sample_t = 0x80000000. 740 */ 741 #define SOX_SAMPLE_MIN (sox_sample_t)SOX_INT_MIN(32) 742 743 744 /* Conversions: Linear PCM <--> sox_sample_t 745 * 746 * I/O Input sox_sample_t Clips? Input sox_sample_t Clips? 747 * Format Minimum Minimum I O Maximum Maximum I O 748 * ------ --------- ------------ -- -- -------- ------------ -- -- 749 * Float -inf -1 y n inf 1 - 5e-10 y n 750 * Int8 -128 -128 n n 127 127.9999999 n y 751 * Int16 -32768 -32768 n n 32767 32767.99998 n y 752 * Int24 -8388608 -8388608 n n 8388607 8388607.996 n y 753 * Int32 -2147483648 -2147483648 n n 2147483647 2147483647 n n 754 * 755 * Conversions are as accurate as possible (with rounding). 756 * 757 * Rounding: halves toward +inf, all others to nearest integer. 758 * 759 * Clips? shows whether on not there is the possibility of a conversion 760 * clipping to the minimum or maximum value when inputing from or outputing 761 * to a given type. 762 * 763 * Unsigned integers are converted to and from signed integers by flipping 764 * the upper-most bit then treating them as signed integers. 765 */ 766 767 /** 768 Client API: 769 Declares the temporary local variables that are required when using SOX 770 conversion macros. 771 */ 772 #define SOX_SAMPLE_LOCALS sox_sample_t sox_macro_temp_sample LSX_UNUSED; \ 773 double sox_macro_temp_double LSX_UNUSED 774 775 /** 776 Client API: 777 Sign bit for sox_sample_t = 0x80000000. 778 */ 779 #define SOX_SAMPLE_NEG SOX_INT_MIN(32) 780 781 /** 782 Client API: 783 Converts sox_sample_t to an unsigned integer of width (bits). 784 @param bits Width of resulting sample (1 through 32). 785 @param d Input sample to be converted. 786 @param clips Variable that is incremented if the result is too big. 787 @returns Unsigned integer of width (bits). 788 */ 789 #define SOX_SAMPLE_TO_UNSIGNED(bits,d,clips) \ 790 (sox_uint##bits##_t)(SOX_SAMPLE_TO_SIGNED(bits,d,clips)^SOX_INT_MIN(bits)) 791 792 /** 793 Client API: 794 Converts sox_sample_t to a signed integer of width (bits). 795 @param bits Width of resulting sample (1 through 32). 796 @param d Input sample to be converted. 797 @param clips Variable that is incremented if the result is too big. 798 @returns Signed integer of width (bits). 799 */ 800 #define SOX_SAMPLE_TO_SIGNED(bits,d,clips) \ 801 (sox_int##bits##_t)(LSX_USE_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)) 802 803 /** 804 Client API: 805 Converts signed integer of width (bits) to sox_sample_t. 806 @param bits Width of input sample (1 through 32). 807 @param d Input sample to be converted. 808 @returns SoX native sample value. 809 */ 810 #define SOX_SIGNED_TO_SAMPLE(bits,d)((sox_sample_t)(d)<<(32-bits)) 811 812 /** 813 Client API: 814 Converts unsigned integer of width (bits) to sox_sample_t. 815 @param bits Width of input sample (1 through 32). 816 @param d Input sample to be converted. 817 @returns SoX native sample value. 818 */ 819 #define SOX_UNSIGNED_TO_SAMPLE(bits,d)(SOX_SIGNED_TO_SAMPLE(bits,d)^SOX_SAMPLE_NEG) 820 821 /** 822 Client API: 823 Converts unsigned 8-bit integer to sox_sample_t. 824 @param d Input sample to be converted. 825 @param clips The parameter is not used. 826 @returns SoX native sample value. 827 */ 828 #define SOX_UNSIGNED_8BIT_TO_SAMPLE(d,clips) SOX_UNSIGNED_TO_SAMPLE(8,d) 829 830 /** 831 Client API: 832 Converts signed 8-bit integer to sox_sample_t. 833 @param d Input sample to be converted. 834 @param clips The parameter is not used. 835 @returns SoX native sample value. 836 */ 837 #define SOX_SIGNED_8BIT_TO_SAMPLE(d,clips) SOX_SIGNED_TO_SAMPLE(8,d) 838 839 /** 840 Client API: 841 Converts unsigned 16-bit integer to sox_sample_t. 842 @param d Input sample to be converted. 843 @param clips The parameter is not used. 844 @returns SoX native sample value. 845 */ 846 #define SOX_UNSIGNED_16BIT_TO_SAMPLE(d,clips) SOX_UNSIGNED_TO_SAMPLE(16,d) 847 848 /** 849 Client API: 850 Converts signed 16-bit integer to sox_sample_t. 851 @param d Input sample to be converted. 852 @param clips The parameter is not used. 853 @returns SoX native sample value. 854 */ 855 #define SOX_SIGNED_16BIT_TO_SAMPLE(d,clips) SOX_SIGNED_TO_SAMPLE(16,d) 856 857 /** 858 Client API: 859 Converts unsigned 24-bit integer to sox_sample_t. 860 @param d Input sample to be converted. 861 @param clips The parameter is not used. 862 @returns SoX native sample value. 863 */ 864 #define SOX_UNSIGNED_24BIT_TO_SAMPLE(d,clips) SOX_UNSIGNED_TO_SAMPLE(24,d) 865 866 /** 867 Client API: 868 Converts signed 24-bit integer to sox_sample_t. 869 @param d Input sample to be converted. 870 @param clips The parameter is not used. 871 @returns SoX native sample value. 872 */ 873 #define SOX_SIGNED_24BIT_TO_SAMPLE(d,clips) SOX_SIGNED_TO_SAMPLE(24,d) 874 875 /** 876 Client API: 877 Converts unsigned 32-bit integer to sox_sample_t. 878 @param d Input sample to be converted. 879 @param clips The parameter is not used. 880 @returns SoX native sample value. 881 */ 882 #define SOX_UNSIGNED_32BIT_TO_SAMPLE(d,clips) ((sox_sample_t)(d)^SOX_SAMPLE_NEG) 883 884 /** 885 Client API: 886 Converts signed 32-bit integer to sox_sample_t. 887 @param d Input sample to be converted. 888 @param clips The parameter is not used. 889 @returns SoX native sample value. 890 */ 891 #define SOX_SIGNED_32BIT_TO_SAMPLE(d,clips) (sox_sample_t)(d) 892 893 /** 894 Client API: 895 Converts 32-bit float to sox_sample_t. 896 @param d Input sample to be converted, range [-1, 1). 897 @param clips Variable to increment if the input sample is too large or too small. 898 @returns SoX native sample value. 899 */ 900 #define SOX_FLOAT_32BIT_TO_SAMPLE(d,clips) (sox_sample_t)(LSX_USE_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) 901 902 /** 903 Client API: 904 Converts 64-bit float to sox_sample_t. 905 @param d Input sample to be converted, range [-1, 1). 906 @param clips Variable to increment if the input sample is too large or too small. 907 @returns SoX native sample value. 908 */ 909 #define SOX_FLOAT_64BIT_TO_SAMPLE(d,clips) (sox_sample_t)(LSX_USE_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) 910 911 /** 912 Client API: 913 Converts SoX native sample to an unsigned 8-bit integer. 914 @param d Input sample to be converted. 915 @param clips Variable to increment if input sample is too large. 916 */ 917 #define SOX_SAMPLE_TO_UNSIGNED_8BIT(d,clips) SOX_SAMPLE_TO_UNSIGNED(8,d,clips) 918 919 /** 920 Client API: 921 Converts SoX native sample to an signed 8-bit integer. 922 @param d Input sample to be converted. 923 @param clips Variable to increment if input sample is too large. 924 */ 925 #define SOX_SAMPLE_TO_SIGNED_8BIT(d,clips) SOX_SAMPLE_TO_SIGNED(8,d,clips) 926 927 /** 928 Client API: 929 Converts SoX native sample to an unsigned 16-bit integer. 930 @param d Input sample to be converted. 931 @param clips Variable to increment if input sample is too large. 932 */ 933 #define SOX_SAMPLE_TO_UNSIGNED_16BIT(d,clips) SOX_SAMPLE_TO_UNSIGNED(16,d,clips) 934 935 /** 936 Client API: 937 Converts SoX native sample to a signed 16-bit integer. 938 @param d Input sample to be converted. 939 @param clips Variable to increment if input sample is too large. 940 */ 941 #define SOX_SAMPLE_TO_SIGNED_16BIT(d,clips) SOX_SAMPLE_TO_SIGNED(16,d,clips) 942 943 /** 944 Client API: 945 Converts SoX native sample to an unsigned 24-bit integer. 946 @param d Input sample to be converted. 947 @param clips Variable to increment if input sample is too large. 948 */ 949 #define SOX_SAMPLE_TO_UNSIGNED_24BIT(d,clips) SOX_SAMPLE_TO_UNSIGNED(24,d,clips) 950 951 /** 952 Client API: 953 Converts SoX native sample to a signed 24-bit integer. 954 @param d Input sample to be converted. 955 @param clips Variable to increment if input sample is too large. 956 */ 957 #define SOX_SAMPLE_TO_SIGNED_24BIT(d,clips) SOX_SAMPLE_TO_SIGNED(24,d,clips) 958 959 /** 960 Client API: 961 Converts SoX native sample to an unsigned 32-bit integer. 962 @param d Input sample to be converted. 963 @param clips The parameter is not used. 964 */ 965 #define SOX_SAMPLE_TO_UNSIGNED_32BIT(d,clips) (sox_uint32_t)((d)^SOX_SAMPLE_NEG) 966 967 /** 968 Client API: 969 Converts SoX native sample to a signed 32-bit integer. 970 @param d Input sample to be converted. 971 @param clips The parameter is not used. 972 */ 973 #define SOX_SAMPLE_TO_SIGNED_32BIT(d,clips) (sox_int32_t)(d) 974 975 /** 976 Client API: 977 Converts SoX native sample to a 32-bit float. 978 @param d Input sample to be converted. 979 @param clips Variable to increment if input sample is too large. 980 */ 981 #define SOX_SAMPLE_TO_FLOAT_32BIT(d,clips) (LSX_USE_VAR(sox_macro_temp_double),sox_macro_temp_sample=(d),sox_macro_temp_sample>SOX_SAMPLE_MAX-64?++(clips),1:(((sox_macro_temp_sample+64)&~127)*(1./(SOX_SAMPLE_MAX+1.)))) 982 983 /** 984 Client API: 985 Converts SoX native sample to a 64-bit float. 986 @param d Input sample to be converted. 987 @param clips The parameter is not used. 988 */ 989 #define SOX_SAMPLE_TO_FLOAT_64BIT(d,clips) ((d)*(1./(SOX_SAMPLE_MAX+1.))) 990 991 /** 992 Client API: 993 Clips a value of a type that is larger then sox_sample_t (for example, int64) 994 to sox_sample_t's limits and increment a counter if clipping occurs. 995 @param samp Value (lvalue) to be clipped, updated as necessary. 996 @param clips Value (lvalue) that is incremented if clipping is needed. 997 */ 998 #define SOX_SAMPLE_CLIP_COUNT(samp, clips) \ 999 do { \ 1000 if (samp > SOX_SAMPLE_MAX) \ 1001 { samp = SOX_SAMPLE_MAX; clips++; } \ 1002 else if (samp < SOX_SAMPLE_MIN) \ 1003 { samp = SOX_SAMPLE_MIN; clips++; } \ 1004 } while (0) 1005 1006 /** 1007 Client API: 1008 Clips a value of a type that is larger then sox_sample_t (for example, int64) 1009 to sox_sample_t's limits and increment a counter if clipping occurs. 1010 @param d Value (rvalue) to be clipped. 1011 @param clips Value (lvalue) that is incremented if clipping is needed. 1012 @returns Clipped value. 1013 */ 1014 #define SOX_ROUND_CLIP_COUNT(d, clips) \ 1015 ((d) < 0? (d) <= SOX_SAMPLE_MIN - 0.5? ++(clips), SOX_SAMPLE_MIN: (d) - 0.5 \ 1016 : (d) >= SOX_SAMPLE_MAX + 0.5? ++(clips), SOX_SAMPLE_MAX: (d) + 0.5) 1017 1018 /** 1019 Client API: 1020 Clips a value to the limits of a signed integer of the specified width 1021 and increment a counter if clipping occurs. 1022 @param bits Width (in bits) of target integer type. 1023 @param i Value (rvalue) to be clipped. 1024 @param clips Value (lvalue) that is incremented if clipping is needed. 1025 @returns Clipped value. 1026 */ 1027 #define SOX_INTEGER_CLIP_COUNT(bits,i,clips) ( \ 1028 (i) >(1 << ((bits)-1))- 1? ++(clips),(1 << ((bits)-1))- 1 : \ 1029 (i) <-1 << ((bits)-1) ? ++(clips),-1 << ((bits)-1) : (i)) 1030 1031 /** 1032 Client API: 1033 Clips a value to the limits of a 16-bit signed integer and increment a counter 1034 if clipping occurs. 1035 @param i Value (rvalue) to be clipped. 1036 @param clips Value (lvalue) that is incremented if clipping is needed. 1037 @returns Clipped value. 1038 */ 1039 #define SOX_16BIT_CLIP_COUNT(i,clips) SOX_INTEGER_CLIP_COUNT(16,i,clips) 1040 1041 /** 1042 Client API: 1043 Clips a value to the limits of a 24-bit signed integer and increment a counter 1044 if clipping occurs. 1045 @param i Value (rvalue) to be clipped. 1046 @param clips Value (lvalue) that is incremented if clipping is needed. 1047 @returns Clipped value. 1048 */ 1049 #define SOX_24BIT_CLIP_COUNT(i,clips) SOX_INTEGER_CLIP_COUNT(24,i,clips) 1050 1051 #define SOX_SIZE_MAX ((size_t)(-1)) /**< Client API: Maximum value of size_t. */ 1052 1053 #define SOX_UNSPEC 0 /**< Client API: Members of sox_signalinfo_t are set to SOX_UNSPEC (= 0) if the actual value is not yet known. */ 1054 #define SOX_UNKNOWN_LEN (sox_uint64_t)(-1) /**< Client API: sox_signalinfo_t.length is set to SOX_UNKNOWN_LEN (= -1) within the effects chain if the actual length is not known. Format handlers currently use SOX_UNSPEC instead. */ 1055 #define SOX_IGNORE_LENGTH (sox_uint64_t)(-2) /**< Client API: sox_signalinfo_t.length is set to SOX_IGNORE_LENGTH (= -2) to indicate that a format handler should ignore length information in file headers. */ 1056 1057 #define SOX_DEFAULT_CHANNELS 2 /**< Client API: Default channel count is 2 (stereo). */ 1058 #define SOX_DEFAULT_RATE 48000 /**< Client API: Default rate is 48000Hz. */ 1059 #define SOX_DEFAULT_PRECISION 16 /**< Client API: Default precision is 16 bits per sample. */ 1060 #define SOX_DEFAULT_ENCODING SOX_ENCODING_SIGN2 /**< Client API: Default encoding is SIGN2 (linear 2's complement PCM). */ 1061 1062 #define SOX_LOOP_NONE ((unsigned char)sox_loop_none) /**< Client API: single-shot = 0 */ 1063 #define SOX_LOOP_8 ((unsigned char)sox_loop_8) /**< Client API: 8 loops = 32 */ 1064 #define SOX_LOOP_SUSTAIN_DECAY ((unsigned char)sox_loop_sustain_decay) /**< Client API: AIFF style, one sustain & one decay loop = 64 */ 1065 1066 #define SOX_MAX_NLOOPS 8 /**< Client API: Maximum number of loops supported by sox_oob_t = 8. */ 1067 1068 #define SOX_FILE_NOSTDIO 0x0001 /**< Client API: Does not use stdio routines */ 1069 #define SOX_FILE_DEVICE 0x0002 /**< Client API: File is an audio device */ 1070 #define SOX_FILE_PHONY 0x0004 /**< Client API: Phony file/device (for example /dev/null) */ 1071 #define SOX_FILE_REWIND 0x0008 /**< Client API: File should be rewound to write header */ 1072 #define SOX_FILE_BIT_REV 0x0010 /**< Client API: Is file bit-reversed? */ 1073 #define SOX_FILE_NIB_REV 0x0020 /**< Client API: Is file nibble-reversed? */ 1074 #define SOX_FILE_ENDIAN 0x0040 /**< Client API: Is file format endian? */ 1075 #define SOX_FILE_ENDBIG 0x0080 /**< Client API: For endian file format, is it big endian? */ 1076 #define SOX_FILE_MONO 0x0100 /**< Client API: Do channel restrictions allow mono? */ 1077 #define SOX_FILE_STEREO 0x0200 /**< Client API: Do channel restrictions allow stereo? */ 1078 #define SOX_FILE_QUAD 0x0400 /**< Client API: Do channel restrictions allow quad? */ 1079 1080 #define SOX_FILE_CHANS (SOX_FILE_MONO | SOX_FILE_STEREO | SOX_FILE_QUAD) /**< Client API: No channel restrictions */ 1081 #define SOX_FILE_LIT_END (SOX_FILE_ENDIAN | 0) /**< Client API: File is little-endian */ 1082 #define SOX_FILE_BIG_END (SOX_FILE_ENDIAN | SOX_FILE_ENDBIG) /**< Client API: File is big-endian */ 1083 1084 #define SOX_EFF_CHAN 1 /**< Client API: Effect might alter the number of channels */ 1085 #define SOX_EFF_RATE 2 /**< Client API: Effect might alter sample rate */ 1086 #define SOX_EFF_PREC 4 /**< Client API: Effect does its own calculation of output sample precision (otherwise a default value is taken, depending on the presence of SOX_EFF_MODIFY) */ 1087 #define SOX_EFF_LENGTH 8 /**< Client API: Effect might alter audio length (as measured in time units, not necessarily in samples) */ 1088 #define SOX_EFF_MCHAN 16 /**< Client API: Effect handles multiple channels internally */ 1089 #define SOX_EFF_NULL 32 /**< Client API: Effect does nothing (can be optimized out of chain) */ 1090 #define SOX_EFF_DEPRECATED 64 /**< Client API: Effect will soon be removed from SoX */ 1091 #define SOX_EFF_GAIN 128 /**< Client API: Effect does not support gain -r */ 1092 #define SOX_EFF_MODIFY 256 /**< Client API: Effect does not modify sample values (but might remove or duplicate samples or insert zeros) */ 1093 #define SOX_EFF_ALPHA 512 /**< Client API: Effect is experimental/incomplete */ 1094 #define SOX_EFF_INTERNAL 1024 /**< Client API: Effect present in libSoX but not valid for use by SoX command-line tools */ 1095 1096 /** 1097 Client API: 1098 When used as the "whence" parameter of sox_seek, indicates that the specified 1099 offset is relative to the beginning of the file. 1100 */ 1101 #define SOX_SEEK_SET 0 1102 1103 /***************************************************************************** 1104 Forward declarations: 1105 *****************************************************************************/ 1106 1107 typedef struct sox_format_t sox_format_t; 1108 typedef struct sox_effect_t sox_effect_t; 1109 typedef struct sox_effect_handler_t sox_effect_handler_t; 1110 typedef struct sox_format_handler_t sox_format_handler_t; 1111 1112 /***************************************************************************** 1113 Function pointers: 1114 *****************************************************************************/ 1115 1116 /** 1117 Client API: 1118 Callback to write a message to an output device (console or log file), 1119 used by sox_globals_t.output_message_handler. 1120 */ 1121 typedef void (LSX_API * sox_output_message_handler_t)( 1122 unsigned level, /**< 1 = FAIL, 2 = WARN, 3 = INFO, 4 = DEBUG, 5 = DEBUG_MORE, 6 = DEBUG_MOST. */ 1123 LSX_PARAM_IN_Z char const * filename, /**< Source code __FILENAME__ from which message originates. */ 1124 LSX_PARAM_IN_PRINTF char const * fmt, /**< Message format string. */ 1125 LSX_PARAM_IN va_list ap /**< Message format parameters. */ 1126 ); 1127 1128 /** 1129 Client API: 1130 Callback to retrieve information about a format handler, 1131 used by sox_format_tab_t.fn. 1132 @returns format handler information. 1133 */ 1134 typedef sox_format_handler_t const * (LSX_API * sox_format_fn_t)(void); 1135 1136 /** 1137 Client API: 1138 Callback to get information about an effect handler, 1139 used by the table returned from sox_get_effect_fns(void). 1140 @returns Pointer to information about an effect handler. 1141 */ 1142 typedef sox_effect_handler_t const * (LSX_API *sox_effect_fn_t)(void); 1143 1144 /** 1145 Client API: 1146 Callback to initialize reader (decoder), used by 1147 sox_format_handler.startread. 1148 @returns SOX_SUCCESS if successful. 1149 */ 1150 typedef int (LSX_API * sox_format_handler_startread)( 1151 LSX_PARAM_INOUT sox_format_t * ft /**< Format pointer. */ 1152 ); 1153 1154 /** 1155 Client API: 1156 Callback to read (decode) a block of samples, 1157 used by sox_format_handler.read. 1158 @returns number of samples read, or 0 if unsuccessful. 1159 */ 1160 typedef size_t (LSX_API * sox_format_handler_read)( 1161 LSX_PARAM_INOUT sox_format_t * ft, /**< Format pointer. */ 1162 LSX_PARAM_OUT_CAP_POST_COUNT(len,return) sox_sample_t *buf, /**< Buffer from which to read samples. */ 1163 size_t len /**< Number of samples available in buf. */ 1164 ); 1165 1166 /** 1167 Client API: 1168 Callback to close reader (decoder), 1169 used by sox_format_handler.stopread. 1170 @returns SOX_SUCCESS if successful. 1171 */ 1172 typedef int (LSX_API * sox_format_handler_stopread)( 1173 LSX_PARAM_INOUT sox_format_t * ft /**< Format pointer. */ 1174 ); 1175 1176 /** 1177 Client API: 1178 Callback to initialize writer (encoder), 1179 used by sox_format_handler.startwrite. 1180 @returns SOX_SUCCESS if successful. 1181 */ 1182 typedef int (LSX_API * sox_format_handler_startwrite)( 1183 LSX_PARAM_INOUT sox_format_t * ft /**< Format pointer. */ 1184 ); 1185 1186 /** 1187 Client API: 1188 Callback to write (encode) a block of samples, 1189 used by sox_format_handler.write. 1190 @returns number of samples written, or 0 if unsuccessful. 1191 */ 1192 typedef size_t (LSX_API * sox_format_handler_write)( 1193 LSX_PARAM_INOUT sox_format_t * ft, /**< Format pointer. */ 1194 LSX_PARAM_IN_COUNT(len) sox_sample_t const * buf, /**< Buffer to which samples are written. */ 1195 size_t len /**< Capacity of buf, measured in samples. */ 1196 ); 1197 1198 /** 1199 Client API: 1200 Callback to close writer (decoder), 1201 used by sox_format_handler.stopwrite. 1202 @returns SOX_SUCCESS if successful. 1203 */ 1204 typedef int (LSX_API * sox_format_handler_stopwrite)( 1205 LSX_PARAM_INOUT sox_format_t * ft /**< Format pointer. */ 1206 ); 1207 1208 /** 1209 Client API: 1210 Callback to reposition reader, 1211 used by sox_format_handler.seek. 1212 @returns SOX_SUCCESS if successful. 1213 */ 1214 typedef int (LSX_API * sox_format_handler_seek)( 1215 LSX_PARAM_INOUT sox_format_t * ft, /**< Format pointer. */ 1216 sox_uint64_t offset /**< Sample offset to which reader should be positioned. */ 1217 ); 1218 1219 /** 1220 Client API: 1221 Callback to parse command-line arguments (called once per effect), 1222 used by sox_effect_handler.getopts. 1223 @returns SOX_SUCCESS if successful. 1224 */ 1225 typedef int (LSX_API * sox_effect_handler_getopts)( 1226 LSX_PARAM_INOUT sox_effect_t * effp, /**< Effect pointer. */ 1227 int argc, /**< Number of arguments in argv. */ 1228 LSX_PARAM_IN_COUNT(argc) char *argv[] /**< Array of command-line arguments. */ 1229 ); 1230 1231 /** 1232 Client API: 1233 Callback to initialize effect (called once per flow), 1234 used by sox_effect_handler.start. 1235 @returns SOX_SUCCESS if successful. 1236 */ 1237 typedef int (LSX_API * sox_effect_handler_start)( 1238 LSX_PARAM_INOUT sox_effect_t * effp /**< Effect pointer. */ 1239 ); 1240 1241 /** 1242 Client API: 1243 Callback to process samples, 1244 used by sox_effect_handler.flow. 1245 @returns SOX_SUCCESS if successful. 1246 */ 1247 typedef int (LSX_API * sox_effect_handler_flow)( 1248 LSX_PARAM_INOUT sox_effect_t * effp, /**< Effect pointer. */ 1249 LSX_PARAM_IN_COUNT(*isamp) sox_sample_t const * ibuf, /**< Buffer from which to read samples. */ 1250 LSX_PARAM_OUT_CAP_POST_COUNT(*osamp,*osamp) sox_sample_t * obuf, /**< Buffer to which samples are written. */ 1251 LSX_PARAM_INOUT size_t *isamp, /**< On entry, contains capacity of ibuf; on exit, contains number of samples consumed. */ 1252 LSX_PARAM_INOUT size_t *osamp /**< On entry, contains capacity of obuf; on exit, contains number of samples written. */ 1253 ); 1254 1255 /** 1256 Client API: 1257 Callback to finish getting output after input is complete, 1258 used by sox_effect_handler.drain. 1259 @returns SOX_SUCCESS if successful. 1260 */ 1261 typedef int (LSX_API * sox_effect_handler_drain)( 1262 LSX_PARAM_INOUT sox_effect_t * effp, /**< Effect pointer. */ 1263 LSX_PARAM_OUT_CAP_POST_COUNT(*osamp,*osamp) sox_sample_t *obuf, /**< Buffer to which samples are written. */ 1264 LSX_PARAM_INOUT size_t *osamp /**< On entry, contains capacity of obuf; on exit, contains number of samples written. */ 1265 ); 1266 1267 /** 1268 Client API: 1269 Callback to shut down effect (called once per flow), 1270 used by sox_effect_handler.stop. 1271 @returns SOX_SUCCESS if successful. 1272 */ 1273 typedef int (LSX_API * sox_effect_handler_stop)( 1274 LSX_PARAM_INOUT sox_effect_t * effp /**< Effect pointer. */ 1275 ); 1276 1277 /** 1278 Client API: 1279 Callback to shut down effect (called once per effect), 1280 used by sox_effect_handler.kill. 1281 @returns SOX_SUCCESS if successful. 1282 */ 1283 typedef int (LSX_API * sox_effect_handler_kill)( 1284 LSX_PARAM_INOUT sox_effect_t * effp /**< Effect pointer. */ 1285 ); 1286 1287 /** 1288 Client API: 1289 Callback called while flow is running (called once per buffer), 1290 used by sox_flow_effects.callback. 1291 @returns SOX_SUCCESS to continue, other value to abort flow. 1292 */ 1293 typedef int (LSX_API * sox_flow_effects_callback)( 1294 sox_bool all_done, 1295 void * client_data 1296 ); 1297 1298 /** 1299 Client API: 1300 Callback for enumerating the contents of a playlist, 1301 used by the sox_parse_playlist function. 1302 @returns SOX_SUCCESS if successful, any other value to abort playlist enumeration. 1303 */ 1304 typedef int (LSX_API * sox_playlist_callback_t)( 1305 void * callback_data, 1306 LSX_PARAM_IN_Z char const * filename 1307 ); 1308 1309 /***************************************************************************** 1310 Structures: 1311 *****************************************************************************/ 1312 1313 /** 1314 Client API: 1315 Information about a build of libSoX, returned from the sox_version_info 1316 function. 1317 */ 1318 typedef struct sox_version_info_t { 1319 size_t size; /**< structure size = sizeof(sox_version_info_t) */ 1320 sox_version_flags_t flags; /**< feature flags = popen | magic | threads | memopen */ 1321 sox_uint32_t version_code; /**< version number = 0x140400 */ 1322 char const * version; /**< version string = sox_version(), for example, "14.4.0" */ 1323 char const * version_extra;/**< version extra info or null = "PACKAGE_EXTRA", for example, "beta" */ 1324 char const * time; /**< build time = "__DATE__ __TIME__", for example, "Jan 7 2010 03:31:50" */ 1325 char const * distro; /**< distro or null = "DISTRO", for example, "Debian" */ 1326 char const * compiler; /**< compiler info or null, for example, "msvc 160040219" */ 1327 char const * arch; /**< arch, for example, "1248 48 44 L OMP" */ 1328 /* new info should be added at the end for version backwards-compatibility. */ 1329 } sox_version_info_t; 1330 1331 /** 1332 Client API: 1333 Global parameters (for effects & formats), returned from the sox_get_globals 1334 function. 1335 */ 1336 typedef struct sox_globals_t { 1337 /* public: */ 1338 unsigned verbosity; /**< messages are only written if globals.verbosity >= message.level */ 1339 sox_output_message_handler_t output_message_handler; /**< client-specified message output callback */ 1340 sox_bool repeatable; /**< true to use pre-determined timestamps and PRNG seed */ 1341 1342 /** 1343 Default size (in bytes) used by libSoX for blocks of sample data. 1344 Plugins should use similarly-sized buffers to get best performance. 1345 */ 1346 size_t bufsiz; 1347 1348 /** 1349 Default size (in bytes) used by libSoX for blocks of input sample data. 1350 Plugins should use similarly-sized buffers to get best performance. 1351 */ 1352 size_t input_bufsiz; 1353 1354 sox_int32_t ranqd1; /**< Can be used to re-seed libSoX's PRNG */ 1355 1356 char const * stdin_in_use_by; /**< Private: tracks the name of the handler currently using stdin */ 1357 char const * stdout_in_use_by; /**< Private: tracks the name of the handler currently using stdout */ 1358 char const * subsystem; /**< Private: tracks the name of the handler currently writing an output message */ 1359 char * tmp_path; /**< Private: client-configured path to use for temporary files */ 1360 sox_bool use_magic; /**< Private: true if client has requested use of 'magic' file-type detection */ 1361 sox_bool use_threads; /**< Private: true if client has requested parallel effects processing */ 1362 1363 /** 1364 Log to base 2 of minimum size (in bytes) used by libSoX for DFT (filtering). 1365 Plugins should use similarly-sized DFTs to get best performance. 1366 */ 1367 size_t log2_dft_min_size; 1368 } sox_globals_t; 1369 1370 /** 1371 Client API: 1372 Signal parameters; members should be set to SOX_UNSPEC (= 0) if unknown. 1373 */ 1374 typedef struct sox_signalinfo_t { 1375 sox_rate_t rate; /**< samples per second, 0 if unknown */ 1376 unsigned channels; /**< number of sound channels, 0 if unknown */ 1377 unsigned precision; /**< bits per sample, 0 if unknown */ 1378 sox_uint64_t length; /**< samples * chans in file, 0 if unknown, -1 if unspecified */ 1379 double * mult; /**< Effects headroom multiplier; may be null */ 1380 } sox_signalinfo_t; 1381 1382 /** 1383 Client API: 1384 Basic information about an encoding. 1385 */ 1386 typedef struct sox_encodings_info_t { 1387 sox_encodings_flags_t flags; /**< lossy once (lossy1), lossy twice (lossy2), or lossless (none). */ 1388 char const * name; /**< encoding name. */ 1389 char const * desc; /**< encoding description. */ 1390 } sox_encodings_info_t; 1391 1392 /** 1393 Client API: 1394 Encoding parameters. 1395 */ 1396 typedef struct sox_encodinginfo_t { 1397 sox_encoding_t encoding; /**< format of sample numbers */ 1398 unsigned bits_per_sample;/**< 0 if unknown or variable; uncompressed value if lossless; compressed value if lossy */ 1399 double compression; /**< compression factor (where applicable) */ 1400 1401 /** 1402 Should bytes be reversed? If this is default during sox_open_read or 1403 sox_open_write, libSoX will set them to either no or yes according to the 1404 machine or format default. 1405 */ 1406 sox_option_t reverse_bytes; 1407 1408 /** 1409 Should nibbles be reversed? If this is default during sox_open_read or 1410 sox_open_write, libSoX will set them to either no or yes according to the 1411 machine or format default. 1412 */ 1413 sox_option_t reverse_nibbles; 1414 1415 /** 1416 Should bits be reversed? If this is default during sox_open_read or 1417 sox_open_write, libSoX will set them to either no or yes according to the 1418 machine or format default. 1419 */ 1420 sox_option_t reverse_bits; 1421 1422 /** 1423 If set to true, the format should reverse its default endianness. 1424 */ 1425 sox_bool opposite_endian; 1426 } sox_encodinginfo_t; 1427 1428 /** 1429 Client API: 1430 Looping parameters (out-of-band data). 1431 */ 1432 typedef struct sox_loopinfo_t { 1433 sox_uint64_t start; /**< first sample */ 1434 sox_uint64_t length; /**< length */ 1435 unsigned count; /**< number of repeats, 0=forever */ 1436 unsigned char type; /**< 0=no, 1=forward, 2=forward/back (see sox_loop_* for valid values). */ 1437 } sox_loopinfo_t; 1438 1439 /** 1440 Client API: 1441 Instrument information. 1442 */ 1443 typedef struct sox_instrinfo_t{ 1444 signed char MIDInote; /**< for unity pitch playback */ 1445 signed char MIDIlow; /**< MIDI pitch-bend low range */ 1446 signed char MIDIhi; /**< MIDI pitch-bend high range */ 1447 unsigned char loopmode; /**< 0=no, 1=forward, 2=forward/back (see sox_loop_* values) */ 1448 unsigned nloops; /**< number of active loops (max SOX_MAX_NLOOPS). */ 1449 } sox_instrinfo_t; 1450 1451 /** 1452 Client API: 1453 File buffer info. Holds info so that data can be read in blocks. 1454 */ 1455 typedef struct sox_fileinfo_t { 1456 char *buf; /**< Pointer to data buffer */ 1457 size_t size; /**< Size of buffer in bytes */ 1458 size_t count; /**< Count read into buffer */ 1459 size_t pos; /**< Position in buffer */ 1460 } sox_fileinfo_t; 1461 1462 /** 1463 Client API: 1464 Handler structure defined by each format. 1465 */ 1466 struct sox_format_handler_t { 1467 unsigned sox_lib_version_code; /**< Checked on load; must be 1st in struct*/ 1468 char const * description; /**< short description of format */ 1469 char const * const * names; /**< null-terminated array of filename extensions that are handled by this format */ 1470 unsigned int flags; /**< File flags (SOX_FILE_* values). */ 1471 sox_format_handler_startread startread; /**< called to initialize reader (decoder) */ 1472 sox_format_handler_read read; /**< called to read (decode) a block of samples */ 1473 sox_format_handler_stopread stopread; /**< called to close reader (decoder); may be null if no closing necessary */ 1474 sox_format_handler_startwrite startwrite; /**< called to initialize writer (encoder) */ 1475 sox_format_handler_write write; /**< called to write (encode) a block of samples */ 1476 sox_format_handler_stopwrite stopwrite; /**< called to close writer (decoder); may be null if no closing necessary */ 1477 sox_format_handler_seek seek; /**< called to reposition reader; may be null if not supported */ 1478 1479 /** 1480 Array of values indicating the encodings and precisions supported for 1481 writing (encoding). Precisions specified with default precision first. 1482 Encoding, precision, precision, ..., 0, repeat. End with one more 0. 1483 Example: 1484 unsigned const * formats = { 1485 SOX_ENCODING_SIGN2, 16, 24, 0, // Support SIGN2 at 16 and 24 bits, default to 16 bits. 1486 SOX_ENCODING_UNSIGNED, 8, 0, // Support UNSIGNED at 8 bits, default to 8 bits. 1487 0 // No more supported encodings. 1488 }; 1489 */ 1490 unsigned const * write_formats; 1491 1492 /** 1493 Array of sample rates (samples per second) supported for writing (encoding). 1494 NULL if all (or almost all) rates are supported. End with 0. 1495 */ 1496 sox_rate_t const * write_rates; 1497 1498 /** 1499 SoX will automatically allocate a buffer in which the handler can store data. 1500 Specify the size of the buffer needed here. Usually this will be sizeof(your_struct). 1501 The buffer will be allocated and zeroed before the call to startread/startwrite. 1502 The buffer will be freed after the call to stopread/stopwrite. 1503 The buffer will be provided via format.priv in each call to the handler. 1504 */ 1505 size_t priv_size; 1506 }; 1507 1508 /** 1509 Client API: 1510 Comments, instrument info, loop info (out-of-band data). 1511 */ 1512 typedef struct sox_oob_t{ 1513 /* Decoded: */ 1514 sox_comments_t comments; /**< Comment strings in id=value format. */ 1515 sox_instrinfo_t instr; /**< Instrument specification */ 1516 sox_loopinfo_t loops[SOX_MAX_NLOOPS]; /**< Looping specification */ 1517 1518 /* TBD: Non-decoded chunks, etc: */ 1519 } sox_oob_t; 1520 1521 /** 1522 Client API: 1523 Data passed to/from the format handler 1524 */ 1525 struct sox_format_t { 1526 char * filename; /**< File name */ 1527 1528 /** 1529 Signal specifications for reader (decoder) or writer (encoder): 1530 sample rate, number of channels, precision, length, headroom multiplier. 1531 Any info specified by the user is here on entry to startread or 1532 startwrite. Info will be SOX_UNSPEC if the user provided no info. 1533 At exit from startread, should be completely filled in, using 1534 either data from the file's headers (if available) or whatever 1535 the format is guessing/assuming (if header data is not available). 1536 At exit from startwrite, should be completely filled in, using 1537 either the data that was specified, or values chosen by the format 1538 based on the format's defaults or capabilities. 1539 */ 1540 sox_signalinfo_t signal; 1541 1542 /** 1543 Encoding specifications for reader (decoder) or writer (encoder): 1544 encoding (sample format), bits per sample, compression rate, endianness. 1545 Should be filled in by startread. Values specified should be used 1546 by startwrite when it is configuring the encoding parameters. 1547 */ 1548 sox_encodinginfo_t encoding; 1549 1550 char * filetype; /**< Type of file, as determined by header inspection or libmagic. */ 1551 sox_oob_t oob; /**< comments, instrument info, loop info (out-of-band data) */ 1552 sox_bool seekable; /**< Can seek on this file */ 1553 char mode; /**< Read or write mode ('r' or 'w') */ 1554 sox_uint64_t olength; /**< Samples * chans written to file */ 1555 sox_uint64_t clips; /**< Incremented if clipping occurs */ 1556 int sox_errno; /**< Failure error code */ 1557 char sox_errstr[256]; /**< Failure error text */ 1558 void * fp; /**< File stream pointer */ 1559 lsx_io_type io_type; /**< Stores whether this is a file, pipe or URL */ 1560 sox_uint64_t tell_off; /**< Current offset within file */ 1561 sox_uint64_t data_start; /**< Offset at which headers end and sound data begins (set by lsx_check_read_params) */ 1562 sox_format_handler_t handler; /**< Format handler for this file */ 1563 void * priv; /**< Format handler's private data area */ 1564 }; 1565 1566 /** 1567 Client API: 1568 Information about a loaded format handler, including the format name and a 1569 function pointer that can be invoked to get additional information about the 1570 format. 1571 */ 1572 typedef struct sox_format_tab_t { 1573 char *name; /**< Name of format handler */ 1574 sox_format_fn_t fn; /**< Function to call to get format handler's information */ 1575 } sox_format_tab_t; 1576 1577 /** 1578 Client API: 1579 Global parameters for effects. 1580 */ 1581 typedef struct sox_effects_globals_t { 1582 sox_plot_t plot; /**< To help the user choose effect & options */ 1583 sox_globals_t * global_info; /**< Pointer to associated SoX globals */ 1584 } sox_effects_globals_t; 1585 1586 /** 1587 Client API: 1588 Effect handler information. 1589 */ 1590 struct sox_effect_handler_t { 1591 char const * name; /**< Effect name */ 1592 char const * usage; /**< Short explanation of parameters accepted by effect */ 1593 unsigned int flags; /**< Combination of SOX_EFF_* flags */ 1594 sox_effect_handler_getopts getopts; /**< Called to parse command-line arguments (called once per effect). */ 1595 sox_effect_handler_start start; /**< Called to initialize effect (called once per flow). */ 1596 sox_effect_handler_flow flow; /**< Called to process samples. */ 1597 sox_effect_handler_drain drain; /**< Called to finish getting output after input is complete. */ 1598 sox_effect_handler_stop stop; /**< Called to shut down effect (called once per flow). */ 1599 sox_effect_handler_kill kill; /**< Called to shut down effect (called once per effect). */ 1600 size_t priv_size; /**< Size of private data SoX should pre-allocate for effect */ 1601 }; 1602 1603 /** 1604 Client API: 1605 Effect information. 1606 */ 1607 struct sox_effect_t { 1608 sox_effects_globals_t * global_info; /**< global effect parameters */ 1609 sox_signalinfo_t in_signal; /**< Information about the incoming data stream */ 1610 sox_signalinfo_t out_signal; /**< Information about the outgoing data stream */ 1611 sox_encodinginfo_t const * in_encoding; /**< Information about the incoming data encoding */ 1612 sox_encodinginfo_t const * out_encoding; /**< Information about the outgoing data encoding */ 1613 sox_effect_handler_t handler; /**< The handler for this effect */ 1614 sox_uint64_t clips; /**< increment if clipping occurs */ 1615 size_t flows; /**< 1 if MCHAN, number of chans otherwise */ 1616 size_t flow; /**< flow number */ 1617 void * priv; /**< Effect's private data area (each flow has a separate copy) */ 1618 /* The following items are private to the libSoX effects chain functions. */ 1619 sox_sample_t * obuf; /**< output buffer */ 1620 size_t obeg; /**< output buffer: start of valid data section */ 1621 size_t oend; /**< output buffer: one past valid data section (oend-obeg is length of current content) */ 1622 size_t imin; /**< minimum input buffer content required for calling this effect's flow function; set via lsx_effect_set_imin() */ 1623 }; 1624 1625 /** 1626 Client API: 1627 Chain of effects to be applied to a stream. 1628 */ 1629 typedef struct sox_effects_chain_t { 1630 sox_effect_t **effects; /**< Table of effects to be applied to a stream */ 1631 size_t length; /**< Number of effects to be applied */ 1632 sox_effects_globals_t global_info; /**< Copy of global effects settings */ 1633 sox_encodinginfo_t const * in_enc; /**< Input encoding */ 1634 sox_encodinginfo_t const * out_enc; /**< Output encoding */ 1635 /* The following items are private to the libSoX effects chain functions. */ 1636 size_t table_size; /**< Size of effects table (including unused entries) */ 1637 sox_sample_t *il_buf; /**< Channel interleave buffer */ 1638 } sox_effects_chain_t; 1639 1640 /***************************************************************************** 1641 Functions: 1642 *****************************************************************************/ 1643 1644 /** 1645 Client API: 1646 Returns version number string of libSoX, for example, "14.4.0". 1647 @returns The version number string of libSoX, for example, "14.4.0". 1648 */ 1649 LSX_RETURN_VALID_Z 1650 char const * 1651 LSX_API 1652 sox_version(void); 1653 1654 /** 1655 Client API: 1656 Returns information about this build of libsox. 1657 @returns Pointer to a version information structure. 1658 */ 1659 LSX_RETURN_VALID 1660 sox_version_info_t const * 1661 LSX_API 1662 sox_version_info(void); 1663 1664 /** 1665 Client API: 1666 Returns a pointer to the structure with libSoX's global settings. 1667 @returns a pointer to the structure with libSoX's global settings. 1668 */ 1669 LSX_RETURN_VALID LSX_RETURN_PURE 1670 sox_globals_t * 1671 LSX_API 1672 sox_get_globals(void); 1673 1674 /** 1675 Client API: 1676 Deprecated macro that returns the structure with libSoX's global settings 1677 as an lvalue. 1678 */ 1679 #define sox_globals (*sox_get_globals()) 1680 1681 /** 1682 Client API: 1683 Returns a pointer to the list of available encodings. 1684 End of list indicated by name == NULL. 1685 @returns pointer to the list of available encodings. 1686 */ 1687 LSX_RETURN_ARRAY LSX_RETURN_PURE 1688 sox_encodings_info_t const * 1689 LSX_API 1690 sox_get_encodings_info(void); 1691 1692 /** 1693 Client API: 1694 Deprecated macro that returns the list of available encodings. 1695 End of list indicated by name == NULL. 1696 */ 1697 #define sox_encodings_info (sox_get_encodings_info()) 1698 1699 /** 1700 Client API: 1701 Fills in an encodinginfo with default values. 1702 */ 1703 void 1704 LSX_API 1705 sox_init_encodinginfo( 1706 LSX_PARAM_OUT sox_encodinginfo_t * e /**< Pointer to uninitialized encoding info structure to be initialized. */ 1707 ); 1708 1709 /** 1710 Client API: 1711 Given an encoding (for example, SIGN2) and the encoded bits_per_sample (for 1712 example, 16), returns the number of useful bits per sample in the decoded data 1713 (for example, 16), or returns 0 to indicate that the value returned by the 1714 format handler should be used instead of a pre-determined precision. 1715 @returns the number of useful bits per sample in the decoded data (for example 1716 16), or returns 0 to indicate that the value returned by the format handler 1717 should be used instead of a pre-determined precision. 1718 */ 1719 LSX_RETURN_PURE 1720 unsigned 1721 LSX_API 1722 sox_precision( 1723 sox_encoding_t encoding, /**< Encoding for which to lookup precision information. */ 1724 unsigned bits_per_sample /**< The number of encoded bits per sample. */ 1725 ); 1726 1727 /** 1728 Client API: 1729 Returns the number of items in the metadata block. 1730 @returns the number of items in the metadata block. 1731 */ 1732 size_t 1733 LSX_API 1734 sox_num_comments( 1735 LSX_PARAM_IN_OPT sox_comments_t comments /**< Metadata block. */ 1736 ); 1737 1738 /** 1739 Client API: 1740 Adds an "id=value" item to the metadata block. 1741 */ 1742 void 1743 LSX_API 1744 sox_append_comment( 1745 LSX_PARAM_DEREF_PRE_MAYBENULL LSX_PARAM_DEREF_POST_NOTNULL sox_comments_t * comments, /**< Metadata block. */ 1746 LSX_PARAM_IN_Z char const * item /**< Item to be added in "id=value" format. */ 1747 ); 1748 1749 /** 1750 Client API: 1751 Adds a newline-delimited list of "id=value" items to the metadata block. 1752 */ 1753 void 1754 LSX_API 1755 sox_append_comments( 1756 LSX_PARAM_DEREF_PRE_MAYBENULL LSX_PARAM_DEREF_POST_NOTNULL sox_comments_t * comments, /**< Metadata block. */ 1757 LSX_PARAM_IN_Z char const * items /**< Newline-separated list of items to be added, for example "id1=value1\\nid2=value2". */ 1758 ); 1759 1760 /** 1761 Client API: 1762 Duplicates the metadata block. 1763 @returns the copied metadata block. 1764 */ 1765 LSX_RETURN_OPT 1766 sox_comments_t 1767 LSX_API 1768 sox_copy_comments( 1769 LSX_PARAM_IN_OPT sox_comments_t comments /**< Metadata block to copy. */ 1770 ); 1771 1772 /** 1773 Client API: 1774 Frees the metadata block. 1775 */ 1776 void 1777 LSX_API 1778 sox_delete_comments( 1779 LSX_PARAM_DEREF_PRE_MAYBENULL LSX_PARAM_DEREF_POST_NULL sox_comments_t * comments /**< Metadata block. */ 1780 ); 1781 1782 /** 1783 Client API: 1784 If "id=value" is found, return value, else return null. 1785 @returns value, or null if value not found. 1786 */ 1787 LSX_RETURN_OPT 1788 char const * 1789 LSX_API 1790 sox_find_comment( 1791 LSX_PARAM_IN_OPT sox_comments_t comments, /**< Metadata block in which to search. */ 1792 LSX_PARAM_IN_Z char const * id /**< Id for which to search */ 1793 ); 1794 1795 /** 1796 Client API: 1797 Find and load format handler plugins. 1798 @returns SOX_SUCCESS if successful. 1799 */ 1800 int 1801 LSX_API 1802 sox_format_init(void); 1803 1804 /** 1805 Client API: 1806 Unload format handler plugins. 1807 */ 1808 void 1809 LSX_API 1810 sox_format_quit(void); 1811 1812 /** 1813 Client API: 1814 Initialize effects library. 1815 @returns SOX_SUCCESS if successful. 1816 */ 1817 int 1818 LSX_API 1819 sox_init(void); 1820 1821 /** 1822 Client API: 1823 Close effects library and unload format handler plugins. 1824 @returns SOX_SUCCESS if successful. 1825 */ 1826 int 1827 LSX_API 1828 sox_quit(void); 1829 1830 /** 1831 Client API: 1832 Returns the table of format handler names and functions. 1833 @returns the table of format handler names and functions. 1834 */ 1835 LSX_RETURN_ARRAY LSX_RETURN_PURE 1836 sox_format_tab_t const * 1837 LSX_API 1838 sox_get_format_fns(void); 1839 1840 /** 1841 Client API: 1842 Deprecated macro that returns the table of format handler names and functions. 1843 */ 1844 #define sox_format_fns (sox_get_format_fns()) 1845 1846 /** 1847 Client API: 1848 Opens a decoding session for a file. Returned handle must be closed with sox_close(). 1849 @returns The handle for the new session, or null on failure. 1850 */ 1851 LSX_RETURN_OPT 1852 sox_format_t * 1853 LSX_API 1854 sox_open_read( 1855 LSX_PARAM_IN_Z char const * path, /**< Path to file to be opened (required). */ 1856 LSX_PARAM_IN_OPT sox_signalinfo_t const * signal, /**< Information already known about audio stream, or NULL if none. */ 1857 LSX_PARAM_IN_OPT sox_encodinginfo_t const * encoding, /**< Information already known about sample encoding, or NULL if none. */ 1858 LSX_PARAM_IN_OPT_Z char const * filetype /**< Previously-determined file type, or NULL to auto-detect. */ 1859 ); 1860 1861 /** 1862 Client API: 1863 Opens a decoding session for a memory buffer. Returned handle must be closed with sox_close(). 1864 @returns The handle for the new session, or null on failure. 1865 */ 1866 LSX_RETURN_OPT 1867 sox_format_t * 1868 LSX_API 1869 sox_open_mem_read( 1870 LSX_PARAM_IN_BYTECOUNT(buffer_size) void * buffer, /**< Pointer to audio data buffer (required). */ 1871 size_t buffer_size,/**< Number of bytes to read from audio data buffer. */ 1872 LSX_PARAM_IN_OPT sox_signalinfo_t const * signal, /**< Information already known about audio stream, or NULL if none. */ 1873 LSX_PARAM_IN_OPT sox_encodinginfo_t const * encoding, /**< Information already known about sample encoding, or NULL if none. */ 1874 LSX_PARAM_IN_OPT_Z char const * filetype /**< Previously-determined file type, or NULL to auto-detect. */ 1875 ); 1876 1877 /** 1878 Client API: 1879 Returns true if the format handler for the specified file type supports the specified encoding. 1880 @returns true if the format handler for the specified file type supports the specified encoding. 1881 */ 1882 sox_bool 1883 LSX_API 1884 sox_format_supports_encoding( 1885 LSX_PARAM_IN_OPT_Z char const * path, /**< Path to file to be examined (required if filetype is NULL). */ 1886 LSX_PARAM_IN_OPT_Z char const * filetype, /**< Previously-determined file type, or NULL to use extension from path. */ 1887 LSX_PARAM_IN sox_encodinginfo_t const * encoding /**< Encoding for which format handler should be queried. */ 1888 ); 1889 1890 /** 1891 Client API: 1892 Gets the format handler for a specified file type. 1893 @returns The found format handler, or null if not found. 1894 */ 1895 LSX_RETURN_OPT 1896 sox_format_handler_t const * 1897 LSX_API 1898 sox_write_handler( 1899 LSX_PARAM_IN_OPT_Z char const * path, /**< Path to file (required if filetype is NULL). */ 1900 LSX_PARAM_IN_OPT_Z char const * filetype, /**< Filetype for which handler is needed, or NULL to use extension from path. */ 1901 LSX_PARAM_OUT_OPT char const * * filetype1 /**< Receives the filetype that was detected. Pass NULL if not needed. */ 1902 ); 1903 1904 /** 1905 Client API: 1906 Opens an encoding session for a file. Returned handle must be closed with sox_close(). 1907 @returns The new session handle, or null on failure. 1908 */ 1909 LSX_RETURN_OPT 1910 sox_format_t * 1911 LSX_API 1912 sox_open_write( 1913 LSX_PARAM_IN_Z char const * path, /**< Path to file to be written (required). */ 1914 LSX_PARAM_IN sox_signalinfo_t const * signal, /**< Information about desired audio stream (required). */ 1915 LSX_PARAM_IN_OPT sox_encodinginfo_t const * encoding, /**< Information about desired sample encoding, or NULL to use defaults. */ 1916 LSX_PARAM_IN_OPT_Z char const * filetype, /**< Previously-determined file type, or NULL to auto-detect. */ 1917 LSX_PARAM_IN_OPT sox_oob_t const * oob, /**< Out-of-band data to add to file, or NULL if none. */ 1918 LSX_PARAM_IN_OPT sox_bool (LSX_API * overwrite_permitted)(LSX_PARAM_IN_Z char const * filename) /**< Called if file exists to determine whether overwrite is ok. */ 1919 ); 1920 1921 /** 1922 Client API: 1923 Opens an encoding session for a memory buffer. Returned handle must be closed with sox_close(). 1924 @returns The new session handle, or null on failure. 1925 */ 1926 LSX_RETURN_OPT 1927 sox_format_t * 1928 LSX_API 1929 sox_open_mem_write( 1930 LSX_PARAM_OUT_BYTECAP(buffer_size) void * buffer, /**< Pointer to audio data buffer that receives data (required). */ 1931 LSX_PARAM_IN size_t buffer_size, /**< Maximum number of bytes to write to audio data buffer. */ 1932 LSX_PARAM_IN sox_signalinfo_t const * signal, /**< Information about desired audio stream (required). */ 1933 LSX_PARAM_IN_OPT sox_encodinginfo_t const * encoding, /**< Information about desired sample encoding, or NULL to use defaults. */ 1934 LSX_PARAM_IN_OPT_Z char const * filetype, /**< Previously-determined file type, or NULL to auto-detect. */ 1935 LSX_PARAM_IN_OPT sox_oob_t const * oob /**< Out-of-band data to add to file, or NULL if none. */ 1936 ); 1937 1938 /** 1939 Client API: 1940 Opens an encoding session for a memstream buffer. Returned handle must be closed with sox_close(). 1941 @returns The new session handle, or null on failure. 1942 */ 1943 LSX_RETURN_OPT 1944 sox_format_t * 1945 LSX_API 1946 sox_open_memstream_write( 1947 LSX_PARAM_OUT char * * buffer_ptr, /**< Receives pointer to audio data buffer that receives data (required). */ 1948 LSX_PARAM_OUT size_t * buffer_size_ptr, /**< Receives size of data written to audio data buffer (required). */ 1949 LSX_PARAM_IN sox_signalinfo_t const * signal, /**< Information about desired audio stream (required). */ 1950 LSX_PARAM_IN_OPT sox_encodinginfo_t const * encoding, /**< Information about desired sample encoding, or NULL to use defaults. */ 1951 LSX_PARAM_IN_OPT_Z char const * filetype, /**< Previously-determined file type, or NULL to auto-detect. */ 1952 LSX_PARAM_IN_OPT sox_oob_t const * oob /**< Out-of-band data to add to file, or NULL if none. */ 1953 ); 1954 1955 /** 1956 Client API: 1957 Reads samples from a decoding session into a sample buffer. 1958 @returns Number of samples decoded, or 0 for EOF. 1959 */ 1960 size_t 1961 LSX_API 1962 sox_read( 1963 LSX_PARAM_INOUT sox_format_t * ft, /**< Format pointer. */ 1964 LSX_PARAM_OUT_CAP_POST_COUNT(len,return) sox_sample_t *buf, /**< Buffer from which to read samples. */ 1965 size_t len /**< Number of samples available in buf. */ 1966 ); 1967 1968 /** 1969 Client API: 1970 Writes samples to an encoding session from a sample buffer. 1971 @returns Number of samples encoded. 1972 */ 1973 size_t 1974 LSX_API 1975 sox_write( 1976 LSX_PARAM_INOUT sox_format_t * ft, /**< Format pointer. */ 1977 LSX_PARAM_IN_COUNT(len) sox_sample_t const * buf, /**< Buffer from which to read samples. */ 1978 size_t len /**< Number of samples available in buf. */ 1979 ); 1980 1981 /** 1982 Client API: 1983 Closes an encoding or decoding session. 1984 @returns SOX_SUCCESS if successful. 1985 */ 1986 int 1987 LSX_API 1988 sox_close( 1989 LSX_PARAM_INOUT sox_format_t * ft /**< Format pointer. */ 1990 ); 1991 1992 /** 1993 Client API: 1994 Sets the location at which next samples will be decoded. Returns SOX_SUCCESS if successful. 1995 @returns SOX_SUCCESS if successful. 1996 */ 1997 int 1998 LSX_API 1999 sox_seek( 2000 LSX_PARAM_INOUT sox_format_t * ft, /**< Format pointer. */ 2001 sox_uint64_t offset, /**< Sample offset at which to position reader. */ 2002 int whence /**< Set to SOX_SEEK_SET. */ 2003 ); 2004 2005 /** 2006 Client API: 2007 Finds a format handler by name. 2008 @returns Format handler data, or null if not found. 2009 */ 2010 LSX_RETURN_OPT 2011 sox_format_handler_t const * 2012 LSX_API 2013 sox_find_format( 2014 LSX_PARAM_IN_Z char const * name, /**< Name of format handler to find. */ 2015 sox_bool ignore_devices /**< Set to true to ignore device names. */ 2016 ); 2017 2018 /** 2019 Client API: 2020 Returns global parameters for effects 2021 @returns global parameters for effects. 2022 */ 2023 LSX_RETURN_VALID LSX_RETURN_PURE 2024 sox_effects_globals_t * 2025 LSX_API 2026 sox_get_effects_globals(void); 2027 2028 /** 2029 Client API: 2030 Deprecated macro that returns global parameters for effects. 2031 */ 2032 #define sox_effects_globals (*sox_get_effects_globals()) 2033 2034 /** 2035 Client API: 2036 Finds the effect handler with the given name. 2037 @returns Effect pointer, or null if not found. 2038 */ 2039 LSX_RETURN_OPT LSX_RETURN_PURE 2040 sox_effect_handler_t const * 2041 LSX_API 2042 sox_find_effect( 2043 LSX_PARAM_IN_Z char const * name /**< Name of effect to find. */ 2044 ); 2045 2046 /** 2047 Client API: 2048 Creates an effect using the given handler. 2049 @returns The new effect, or null if not found. 2050 */ 2051 LSX_RETURN_OPT 2052 sox_effect_t * 2053 LSX_API 2054 sox_create_effect( 2055 LSX_PARAM_IN sox_effect_handler_t const * eh /**< Handler to use for effect. */ 2056 ); 2057 2058 /** 2059 Client API: 2060 Applies the command-line options to the effect. 2061 @returns the number of arguments consumed. 2062 */ 2063 int 2064 LSX_API 2065 sox_effect_options( 2066 LSX_PARAM_IN sox_effect_t *effp, /**< Effect pointer on which to set options. */ 2067 int argc, /**< Number of arguments in argv. */ 2068 LSX_PARAM_IN_COUNT(argc) char * const argv[] /**< Array of command-line options. */ 2069 ); 2070 2071 /** 2072 Client API: 2073 Returns an array containing the known effect handlers. 2074 @returns An array containing the known effect handlers. 2075 */ 2076 LSX_RETURN_VALID_Z LSX_RETURN_PURE 2077 sox_effect_fn_t const * 2078 LSX_API 2079 sox_get_effect_fns(void); 2080 2081 /** 2082 Client API: 2083 Deprecated macro that returns an array containing the known effect handlers. 2084 */ 2085 #define sox_effect_fns (sox_get_effect_fns()) 2086 2087 /** 2088 Client API: 2089 Initializes an effects chain. Returned handle must be closed with sox_delete_effects_chain(). 2090 @returns Handle, or null on failure. 2091 */ 2092 LSX_RETURN_OPT 2093 sox_effects_chain_t * 2094 LSX_API 2095 sox_create_effects_chain( 2096 LSX_PARAM_IN sox_encodinginfo_t const * in_enc, /**< Input encoding. */ 2097 LSX_PARAM_IN sox_encodinginfo_t const * out_enc /**< Output encoding. */ 2098 ); 2099 2100 /** 2101 Client API: 2102 Closes an effects chain. 2103 */ 2104 void 2105 LSX_API 2106 sox_delete_effects_chain( 2107 LSX_PARAM_INOUT sox_effects_chain_t *ecp /**< Effects chain pointer. */ 2108 ); 2109 2110 /** 2111 Client API: 2112 Adds an effect to the effects chain, returns SOX_SUCCESS if successful. 2113 @returns SOX_SUCCESS if successful. 2114 */ 2115 int 2116 LSX_API 2117 sox_add_effect( 2118 LSX_PARAM_INOUT sox_effects_chain_t * chain, /**< Effects chain to which effect should be added . */ 2119 LSX_PARAM_INOUT sox_effect_t * effp, /**< Effect to be added. */ 2120 LSX_PARAM_INOUT sox_signalinfo_t * in, /**< Input format. */ 2121 LSX_PARAM_IN sox_signalinfo_t const * out /**< Output format. */ 2122 ); 2123 2124 /** 2125 Client API: 2126 Runs the effects chain, returns SOX_SUCCESS if successful. 2127 @returns SOX_SUCCESS if successful. 2128 */ 2129 int 2130 LSX_API 2131 sox_flow_effects( 2132 LSX_PARAM_INOUT sox_effects_chain_t * chain, /**< Effects chain to run. */ 2133 LSX_PARAM_IN_OPT sox_flow_effects_callback callback, /**< Callback for monitoring flow progress. */ 2134 LSX_PARAM_IN_OPT void * client_data /**< Data to pass into callback. */ 2135 ); 2136 2137 /** 2138 Client API: 2139 Gets the number of clips that occurred while running an effects chain. 2140 @returns the number of clips that occurred while running an effects chain. 2141 */ 2142 sox_uint64_t 2143 LSX_API 2144 sox_effects_clips( 2145 LSX_PARAM_IN sox_effects_chain_t * chain /**< Effects chain from which to read clip information. */ 2146 ); 2147 2148 /** 2149 Client API: 2150 Shuts down an effect (calls stop on each of its flows). 2151 @returns the number of clips from all flows. 2152 */ 2153 sox_uint64_t 2154 LSX_API 2155 sox_stop_effect( 2156 LSX_PARAM_INOUT_COUNT(effp->flows) sox_effect_t * effp /**< Effect to stop. */ 2157 ); 2158 2159 /** 2160 Client API: 2161 Adds an already-initialized effect to the end of the chain. 2162 */ 2163 void 2164 LSX_API 2165 sox_push_effect_last( 2166 LSX_PARAM_INOUT sox_effects_chain_t * chain, /**< Effects chain to which effect should be added. */ 2167 LSX_PARAM_INOUT sox_effect_t * effp /**< Effect to be added. */ 2168 ); 2169 2170 /** 2171 Client API: 2172 Removes and returns an effect from the end of the chain. 2173 @returns the removed effect, or null if no effects. 2174 */ 2175 LSX_RETURN_OPT 2176 sox_effect_t * 2177 LSX_API 2178 sox_pop_effect_last( 2179 LSX_PARAM_INOUT sox_effects_chain_t *chain /**< Effects chain from which to remove an effect. */ 2180 ); 2181 2182 /** 2183 Client API: 2184 Shut down and delete an effect. 2185 */ 2186 void 2187 LSX_API 2188 sox_delete_effect( 2189 LSX_PARAM_INOUT_COUNT(effp->flows) sox_effect_t *effp /**< Effect to be deleted. */ 2190 ); 2191 2192 /** 2193 Client API: 2194 Shut down and delete the last effect in the chain. 2195 */ 2196 void 2197 LSX_API 2198 sox_delete_effect_last( 2199 LSX_PARAM_INOUT sox_effects_chain_t *chain /**< Effects chain from which to remove the last effect. */ 2200 ); 2201 2202 /** 2203 Client API: 2204 Shut down and delete all effects in the chain. 2205 */ 2206 void 2207 LSX_API 2208 sox_delete_effects( 2209 LSX_PARAM_INOUT sox_effects_chain_t *chain /**< Effects chain from which to delete effects. */ 2210 ); 2211 2212 /** 2213 Client API: 2214 Gets the sample offset of the start of the trim, useful for efficiently 2215 skipping the part that will be trimmed anyway (get trim start, seek, then 2216 clear trim start). 2217 @returns the sample offset of the start of the trim. 2218 */ 2219 sox_uint64_t 2220 LSX_API 2221 sox_trim_get_start( 2222 LSX_PARAM_IN sox_effect_t * effp /**< Trim effect. */ 2223 ); 2224 2225 /** 2226 Client API: 2227 Clears the start of the trim to 0. 2228 */ 2229 void 2230 LSX_API 2231 sox_trim_clear_start( 2232 LSX_PARAM_INOUT sox_effect_t * effp /**< Trim effect. */ 2233 ); 2234 2235 /** 2236 Client API: 2237 Returns true if the specified file is a known playlist file type. 2238 @returns true if the specified file is a known playlist file type. 2239 */ 2240 sox_bool 2241 LSX_API 2242 sox_is_playlist( 2243 LSX_PARAM_IN_Z char const * filename /**< Name of file to examine. */ 2244 ); 2245 2246 /** 2247 Client API: 2248 Parses the specified playlist file. 2249 @returns SOX_SUCCESS if successful. 2250 */ 2251 int 2252 LSX_API 2253 sox_parse_playlist( 2254 LSX_PARAM_IN sox_playlist_callback_t callback, /**< Callback to call for each item in the playlist. */ 2255 void * p, /**< Data to pass to callback. */ 2256 LSX_PARAM_IN char const * const listname /**< Filename of playlist file. */ 2257 ); 2258 2259 /** 2260 Client API: 2261 Converts a SoX error code into an error string. 2262 @returns error string corresponding to the specified error code, 2263 or a generic message if the error code is not recognized. 2264 */ 2265 LSX_RETURN_VALID_Z LSX_RETURN_PURE 2266 char const * 2267 LSX_API 2268 sox_strerror( 2269 int sox_errno /**< Error code to look up. */ 2270 ); 2271 2272 /** 2273 Client API: 2274 Gets the basename of the specified file; for example, the basename of 2275 "/a/b/c.d" would be "c". 2276 @returns the number of characters written to base_buffer, excluding the null, 2277 or 0 on failure. 2278 */ 2279 size_t 2280 LSX_API 2281 sox_basename( 2282 LSX_PARAM_OUT_Z_CAP_POST_COUNT(base_buffer_len,return) char * base_buffer, /**< Buffer into which basename should be written. */ 2283 size_t base_buffer_len, /**< Size of base_buffer, in bytes. */ 2284 LSX_PARAM_IN_Z char const * filename /**< Filename from which to extract basename. */ 2285 ); 2286 2287 /***************************************************************************** 2288 Internal API: 2289 WARNING - The items in this section are subject to instability. They only 2290 exist in the public header because sox (the application) currently uses them. 2291 These may be changed or removed in future versions of libSoX. 2292 *****************************************************************************/ 2293 2294 /** 2295 Plugins API: 2296 Print a fatal error in libSoX. 2297 */ 2298 void 2299 LSX_API 2300 lsx_fail_impl( 2301 LSX_PARAM_IN_PRINTF char const * fmt, /**< printf-style format string. */ 2302 ...) 2303 LSX_PRINTF12; 2304 2305 /** 2306 Plugins API: 2307 Print a warning in libSoX. 2308 */ 2309 void 2310 LSX_API 2311 lsx_warn_impl( 2312 LSX_PARAM_IN_PRINTF char const * fmt, /**< printf-style format string. */ 2313 ...) 2314 LSX_PRINTF12; 2315 2316 /** 2317 Plugins API: 2318 Print an informational message in libSoX. 2319 */ 2320 void 2321 LSX_API 2322 lsx_report_impl( 2323 LSX_PARAM_IN_PRINTF char const * fmt, /**< printf-style format string. */ 2324 ...) 2325 LSX_PRINTF12; 2326 2327 /** 2328 Plugins API: 2329 Print a debug message in libSoX. 2330 */ 2331 void 2332 LSX_API 2333 lsx_debug_impl( 2334 LSX_PARAM_IN_PRINTF char const * fmt, /**< printf-style format string. */ 2335 ...) 2336 LSX_PRINTF12; 2337 2338 /** 2339 Plugins API: 2340 Report a fatal error in libSoX; printf-style arguments must follow. 2341 */ 2342 #define lsx_fail sox_get_globals()->subsystem=__FILE__,lsx_fail_impl 2343 2344 /** 2345 Plugins API: 2346 Report a warning in libSoX; printf-style arguments must follow. 2347 */ 2348 #define lsx_warn sox_get_globals()->subsystem=__FILE__,lsx_warn_impl 2349 2350 /** 2351 Plugins API: 2352 Report an informational message in libSoX; printf-style arguments must follow. 2353 */ 2354 #define lsx_report sox_get_globals()->subsystem=__FILE__,lsx_report_impl 2355 2356 /** 2357 Plugins API: 2358 Report a debug message in libSoX; printf-style arguments must follow. 2359 */ 2360 #define lsx_debug sox_get_globals()->subsystem=__FILE__,lsx_debug_impl 2361 2362 /** 2363 Plugins API: 2364 String name and integer values for enumerated types (type metadata), for use 2365 with LSX_ENUM_ITEM, lsx_find_enum_text, and lsx_find_enum_value. 2366 */ 2367 typedef struct lsx_enum_item { 2368 char const *text; /**< String name of enumeration. */ 2369 unsigned value; /**< Integer value of enumeration. */ 2370 } lsx_enum_item; 2371 2372 /** 2373 Plugins API: 2374 Declares a static instance of an lsx_enum_item structure in format 2375 { "item", prefixitem }, for use in declaring lsx_enum_item[] arrays. 2376 @param prefix The prefix to prepend to the item in the enumeration symbolic name. 2377 @param item The user-visible text name of the item (must also be a valid C symbol name). 2378 */ 2379 #define LSX_ENUM_ITEM(prefix, item) {#item, prefix##item}, 2380 2381 /** 2382 Plugins API: 2383 Flags for use with lsx_find_enum_item. 2384 */ 2385 enum 2386 { 2387 lsx_find_enum_item_none = 0, /**< Default parameters (case-insensitive). */ 2388 lsx_find_enum_item_case_sensitive = 1 /**< Enable case-sensitive search. */ 2389 }; 2390 2391 /** 2392 Plugins API: 2393 Looks up an enumeration by name in an array of lsx_enum_items. 2394 @returns the corresponding item, or null if not found. 2395 */ 2396 LSX_RETURN_OPT LSX_RETURN_PURE 2397 lsx_enum_item const * 2398 LSX_API 2399 lsx_find_enum_text( 2400 LSX_PARAM_IN_Z char const * text, /**< Name of enumeration to find. */ 2401 LSX_PARAM_IN lsx_enum_item const * lsx_enum_items, /**< Array of items to search, with text == NULL for last item. */ 2402 int flags /**< Search flags: 0 (case-insensitive) or lsx_find_enum_item_case_sensitive (case-sensitive). */ 2403 ); 2404 2405 /** 2406 Plugins API: 2407 Looks up an enumeration by value in an array of lsx_enum_items. 2408 @returns the corresponding item, or null if not found. 2409 */ 2410 LSX_RETURN_OPT LSX_RETURN_PURE 2411 lsx_enum_item const * 2412 LSX_API 2413 lsx_find_enum_value( 2414 unsigned value, /**< Enumeration value to find. */ 2415 LSX_PARAM_IN lsx_enum_item const * lsx_enum_items /**< Array of items to search, with text == NULL for last item. */ 2416 ); 2417 2418 /** 2419 Plugins API: 2420 Looks up a command-line argument in a set of enumeration names, showing an 2421 error message if the argument is not found in the set of names. 2422 @returns The enumeration value corresponding to the matching enumeration, or 2423 INT_MAX if the argument does not match any enumeration name. 2424 */ 2425 int 2426 LSX_API 2427 lsx_enum_option( 2428 int c, /**< Option character to which arg is associated, for example with -a, c would be 'a'. */ 2429 LSX_PARAM_IN_Z char const * arg, /**< Argument to find in enumeration list. */ 2430 LSX_PARAM_IN lsx_enum_item const * items /**< Array of items to search, with text == NULL for last item. */ 2431 ); 2432 2433 /** 2434 Plugins API: 2435 Determines whether the specified string ends with the specified suffix (case-sensitive). 2436 @returns true if the specified string ends with the specified suffix. 2437 */ 2438 LSX_RETURN_PURE 2439 sox_bool 2440 LSX_API 2441 lsx_strends( 2442 LSX_PARAM_IN_Z char const * str, /**< String to search. */ 2443 LSX_PARAM_IN_Z char const * end /**< Suffix to search for. */ 2444 ); 2445 2446 /** 2447 Plugins API: 2448 Finds the file extension for a filename. 2449 @returns the file extension, not including the '.', or null if filename does 2450 not have an extension. 2451 */ 2452 LSX_RETURN_VALID_Z LSX_RETURN_PURE 2453 char const * 2454 LSX_API 2455 lsx_find_file_extension( 2456 LSX_PARAM_IN_Z char const * pathname /**< Filename to search for extension. */ 2457 ); 2458 2459 /** 2460 Plugins API: 2461 Formats the specified number with up to three significant figures and adds a 2462 metric suffix in place of the exponent, such as 1.23G. 2463 @returns A static buffer with the formatted number, valid until the next time 2464 this function is called (note: not thread safe). 2465 */ 2466 LSX_RETURN_VALID_Z 2467 char const * 2468 LSX_API 2469 lsx_sigfigs3( 2470 double number /**< Number to be formatted. */ 2471 ); 2472 2473 /** 2474 Plugins API: 2475 Formats the specified number as a percentage, showing up to three significant 2476 figures. 2477 @returns A static buffer with the formatted number, valid until the next time 2478 this function is called (note: not thread safe). 2479 */ 2480 LSX_RETURN_VALID_Z 2481 char const * 2482 LSX_API 2483 lsx_sigfigs3p( 2484 double percentage /**< Number to be formatted. */ 2485 ); 2486 2487 /** 2488 Plugins API: 2489 Allocates, deallocates, or resizes; like C's realloc, except that this version 2490 terminates the running application if unable to allocate the requested memory. 2491 @returns New buffer, or null if buffer was freed. 2492 */ 2493 LSX_RETURN_OPT 2494 void * 2495 LSX_API 2496 lsx_realloc( 2497 LSX_PARAM_IN_OPT void *ptr, /**< Pointer to be freed or resized, or null if allocating a new buffer. */ 2498 size_t newsize /**< New size for buffer, or 0 to free the buffer. */ 2499 ); 2500 2501 /** 2502 Plugins API: 2503 Like strcmp, except that the characters are compared without regard to case. 2504 @returns 0 (s1 == s2), negative (s1 < s2), or positive (s1 > s2). 2505 */ 2506 LSX_RETURN_PURE 2507 int 2508 LSX_API 2509 lsx_strcasecmp( 2510 LSX_PARAM_IN_Z char const * s1, /**< First string. */ 2511 LSX_PARAM_IN_Z char const * s2 /**< Second string. */ 2512 ); 2513 2514 2515 /** 2516 Plugins API: 2517 Like strncmp, except that the characters are compared without regard to case. 2518 @returns 0 (s1 == s2), negative (s1 < s2), or positive (s1 > s2). 2519 */ 2520 LSX_RETURN_PURE 2521 int 2522 LSX_API 2523 lsx_strncasecmp( 2524 LSX_PARAM_IN_Z char const * s1, /**< First string. */ 2525 LSX_PARAM_IN_Z char const * s2, /**< Second string. */ 2526 size_t n /**< Maximum number of characters to examine. */ 2527 ); 2528 2529 /** 2530 Plugins API: 2531 Is option argument unsupported, required, or optional. 2532 */ 2533 typedef enum lsx_option_arg_t { 2534 lsx_option_arg_none, /**< Option does not have an argument. */ 2535 lsx_option_arg_required, /**< Option requires an argument. */ 2536 lsx_option_arg_optional /**< Option can optionally be followed by an argument. */ 2537 } lsx_option_arg_t; 2538 2539 /** 2540 Plugins API: 2541 lsx_getopt_init options. 2542 */ 2543 typedef enum lsx_getopt_flags_t { 2544 lsx_getopt_flag_none = 0, /**< no flags (no output, not long-only) */ 2545 lsx_getopt_flag_opterr = 1, /**< if set, invalid options trigger lsx_warn output */ 2546 lsx_getopt_flag_longonly = 2 /**< if set, recognize -option as a long option */ 2547 } lsx_getopt_flags_t; 2548 2549 /** 2550 Plugins API: 2551 lsx_getopt long option descriptor. 2552 */ 2553 typedef struct lsx_option_t { 2554 char const * name; /**< Name of the long option. */ 2555 lsx_option_arg_t has_arg; /**< Whether the long option supports an argument and, if so, whether the argument is required or optional. */ 2556 int * flag; /**< Flag to set if argument is present. */ 2557 int val; /**< Value to put in flag if argument is present. */ 2558 } lsx_option_t; 2559 2560 /** 2561 Plugins API: 2562 lsx_getopt session information (initialization data and state). 2563 */ 2564 typedef struct lsx_getopt_t { 2565 int argc; /**< IN argc: Number of arguments in argv */ 2566 char * const * argv; /**< IN argv: Array of arguments */ 2567 char const * shortopts;/**< IN shortopts: Short option characters */ 2568 lsx_option_t const * longopts; /**< IN longopts: Array of long option descriptors */ 2569 lsx_getopt_flags_t flags; /**< IN flags: Flags for longonly and opterr */ 2570 char const * curpos; /**< INOUT curpos: Maintains state between calls to lsx_getopt */ 2571 int ind; /**< INOUT optind: Maintains the index of next element to be processed */ 2572 int opt; /**< OUT optopt: Receives the option character that caused error */ 2573 char const * arg; /**< OUT optarg: Receives the value of the option's argument */ 2574 int lngind; /**< OUT lngind: Receives the index of the matched long option or -1 if not a long option */ 2575 } lsx_getopt_t; 2576 2577 /** 2578 Plugins API: 2579 Initializes an lsx_getopt_t structure for use with lsx_getopt. 2580 */ 2581 void 2582 LSX_API 2583 lsx_getopt_init( 2584 LSX_PARAM_IN int argc, /**< Number of arguments in argv */ 2585 LSX_PARAM_IN_COUNT(argc) char * const * argv, /**< Array of arguments */ 2586 LSX_PARAM_IN_Z char const * shortopts, /**< Short options, for example ":abc:def::ghi" (+/- not supported) */ 2587 LSX_PARAM_IN_OPT lsx_option_t const * longopts, /**< Array of long option descriptors */ 2588 LSX_PARAM_IN lsx_getopt_flags_t flags, /**< Flags for longonly and opterr */ 2589 LSX_PARAM_IN int first, /**< First argv to check (usually 1) */ 2590 LSX_PARAM_OUT lsx_getopt_t * state /**< State object to be initialized */ 2591 ); 2592 2593 /** 2594 Plugins API: 2595 Gets the next option. Options are parameters that start with "-" or "--". 2596 If no more options, returns -1. If unrecognized short option, returns '?'. 2597 If a recognized short option is missing a required argument, 2598 return (shortopts[0]==':' ? ':' : '?'). If successfully recognized short 2599 option, return the recognized character. If successfully recognized long 2600 option, returns (option.flag ? 0 : option.val). 2601 Note: lsx_getopt does not permute the non-option arguments. 2602 @returns option character (short), val or 0 (long), or -1 (no more). 2603 */ 2604 int 2605 LSX_API 2606 lsx_getopt( 2607 LSX_PARAM_INOUT lsx_getopt_t * state /**< The getopt state pointer. */ 2608 ); 2609 2610 /** 2611 Plugins API: 2612 Gets the file length, or 0 if the file is not seekable/normal. 2613 @returns The file length, or 0 if the file is not seekable/normal. 2614 */ 2615 sox_uint64_t 2616 LSX_API 2617 lsx_filelength( 2618 LSX_PARAM_IN sox_format_t * ft 2619 ); 2620 2621 /* WARNING END */ 2622 2623 #if defined(__cplusplus) 2624 } 2625 #endif 2626 2627 #endif /* SOX_H */ 2628