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