1--- 2layout: page 3title: libsndfile : the sf_command function. 4--- 5 6# sf_command 7 8```c 9int sf_command (SNDFILE *sndfile, int cmd, void *data, int datasize) ; 10``` 11 12This function allows the caller to retrieve information from or change aspects 13of the library behaviour. Examples include retrieving a string containing the 14library version or changing the scaling applied to floating point sample data 15during read and write. Most of these operations are performed on a per-file 16basis. 17 18The cmd parameter is an integer identifier which is defined in *sndfile.h*. All 19of the valid command identifiers have names beginning with "SFC_". Data is 20passed to and returned from the library by use of a void pointer. The library 21will not read or write more than datasize bytes from the void pointer. For some 22calls no data is required in which case data should be NULL and datasize may be 23used for some other purpose. 24 25The available commands are as follows: 26 27| Name | Description | 28|:------------------------------------------------------------------|:--------------------------------------------------------| 29| [SFC_GET_LIB_VERSION](#sfc_get_lib_version) | Retrieve the version of the library as a string. | 30| [SFC_GET_LOG_INFO](#sfc_get_log_info) | Retrieve the internal per-file operation log. | 31| [SFC_GET_CURRENT_SF_INFO](#sfc_get_current_sf_info) | Retrieve `SF_INFO` struct of opened file. | 32| [SFC_CALC_SIGNAL_MAX](#sfc_calc_signal_max) | Calculate the measured maximum signal value. | 33| [SFC_CALC_NORM_SIGNAL_MAX](#sfc_calc_norm_signal_max) | Calculate the measured normalised maximum signal value. | 34| [SFC_CALC_MAX_ALL_CHANNELS](#sfc_calc_max_all_channels) | Calculate the peak value for each channel. | 35| [SFC_CALC_NORM_MAX_ALL_CHANNELS](#sfc_calc_norm_max_all_channels) | Calculate the normalised peak for each channel. | 36| [SFC_GET_SIGNAL_MAX](#sfc_get_signal_max) | Retrieve the peak value for the file. | 37| [SFC_GET_MAX_ALL_CHANNELS](#sfc_get_max_all_channels) | Retrieve the peak value for each channel. | 38| [SFC_SET_NORM_FLOAT](#sfc_set_norm_float) | Set float normalisation behaviour. | 39| [SFC_SET_NORM_DOUBLE](#sfc_set_norm_double) | Set double normalisation behaviour. | 40| [SFC_GET_NORM_FLOAT](#sfc_get_norm_float) | Get float normalisation behaviour. | 41| [SFC_GET_NORM_DOUBLE](#sfc_get_norm_double) | Get double normalisation behaviour. | 42| [SFC_SET_SCALE_FLOAT_INT_READ](#sfc_set_scale_float_int_read) | Control scale factor on read. | 43| [SFC_SET_SCALE_INT_FLOAT_WRITE](#sfc_set_scale_int_float_write) | Control scale factor on write. | 44| [SFC_GET_SIMPLE_FORMAT_COUNT](#sfc_get_simple_format_count) | Get simple formats count. | 45| [SFC_GET_SIMPLE_FORMAT](#sfc_get_simple_format) | Get information about a simple format. | 46| [SFC_GET_FORMAT_INFO](#sfc_get_format_info) | Get information about a major or subtype format. | 47| [SFC_GET_FORMAT_MAJOR_COUNT](#sfc_get_format_major_count) | Get the number of major formats. | 48| [SFC_GET_FORMAT_MAJOR](#sfc_get_format_major) | Get information about a major format type. | 49| [SFC_GET_FORMAT_SUBTYPE_COUNT](#sfc_get_format_subtype_count) | Get the number of subformats. | 50| [SFC_GET_FORMAT_SUBTYPE](#sfc_get_format_subtype) | Get information about a subformat. | 51| [SFC_SET_ADD_PEAK_CHUNK](#sfc_set_add_peak_chunk) | Control PEAK chunk write to WAV and AIFF. | 52| [SFC_UPDATE_HEADER_NOW](#sfc_update_header_now) | Update the file header in write mode on demand. | 53| [SFC_SET_UPDATE_HEADER_AUTO](#sfc_set_update_header_auto) | Update the file header on each write. | 54| [SFC_FILE_TRUNCATE](#sfc_file_truncate) | Truncate a file open for write or for read/write. | 55| [SFC_SET_RAW_START_OFFSET](#sfc_set_raw_start_offset) | Change the data start offset for raw files. | 56| SFC_SET_DITHER_ON_WRITE | Not implemented. | 57| SFC_SET_DITHER_ON_READ | Not implemented. | 58| SFC_GET_DITHER_INFO_COUNT | Not implemented. | 59| SFC_GET_DITHER_INFO | Not implemented. | 60| [SFC_SET_CLIPPING](#sfc_set_clipping) | Control automatic clipping behaviour. | 61| [SFC_GET_CLIPPING](#sfc_get_clipping) | Get current clipping setting. | 62| [SFC_GET_EMBED_FILE_INFO](#sfc_get_embed_file_info) | Get information about embedded audio files. | 63| [SFC_WAVEX_GET_AMBISONIC](#sfc_wavex_get_ambisonic) | Test a WAVEX file for Ambisonic format. | 64| [SFC_WAVEX_SET_AMBISONIC](#sfc_wavex_set_ambisonic) | Modify a WAVEX header for Ambisonic format. | 65| [SFC_SET_VBR_ENCODING_QUALITY](#sfc_set_vbr_encoding_quality) | Set the Variable Bit Rate encoding quality. | 66| [SFC_SET_OGG_PAGE_LATENCY_MS](#sfc_set_ogg_page_latency_ms) | Set Ogg page latency for Opus file. | 67| [SFC_GET_OGG_STREAM_SERIALNO](#sfc_get_ogg_stream_serialno) | Get Ogg stream serial number. | 68| [SFC_SET_COMPRESSION_LEVEL](#sfc_set_compression_level) | Set the compression level. | 69| [SFC_RAW_DATA_NEEDS_ENDSWAP](#sfc_raw_data_needs_endswap) | Determine if raw data needs endswapping. | 70| [SFC_GET_BROADCAST_INFO](#sfc_get_broadcast_info) | Get the Broadcast Chunk info. | 71| [SFC_SET_BROADCAST_INFO](#sfc_set_broadcast_info) | Set the Broadcast Chunk info. | 72| [SFC_GET_CHANNEL_MAP_INFO](#sfc_get_channel_map_info) | Get the channel map info. | 73| [SFC_SET_CHANNEL_MAP_INFO](#sfc_set_channel_map_info) | Set the channel map info. | 74| [SFC_SET_CART_INFO](#sfc_set_cart_info) | Set the Cart Chunk info. | 75| [SFC_GET_CART_INFO](#sfc_get_cart_info) | Get the Cart Chunk info. | 76| [SFC_GET_LOOP_INFO](#sfc_get_loop_info) | Get loop info. | 77| [SFC_GET_INSTRUMENT](#sfc_get_instrument) | Get instrument info. | 78| [SFC_SET_INSTRUMENT](#sfc_set_instrument) | Set instrument info. | 79| [SFC_GET_CUE_COUNT](#sfc_get_cue_count) | Get the cue marker count. | 80| [SFC_GET_CUE](#sfc_get_cue) | Get cue marker info. | 81| [SFC_SET_CUE](#sfc_set_cue) | Set cue marker info. | 82| [SFC_RF64_AUTO_DOWNGRADE](#sfc_rf64_auto_downgrade) | Set auto downgrade from RF64 to WAV. | 83| [SFC_GET_ORIGINAL_SAMPLERATE](#sfc_get_original_samplerate) | Get original samplerate metadata. | 84| [SFC_SET_ORIGINAL_SAMPLERATE](#sfc_set_original_samplerate) | Set original samplerate metadata. | 85| [SFC_GET_BITRATE_MODE](#sfc_get_bitrate_mode) | Get bitrate mode. | 86| [SFC_SET_BITRATE_MODE](#sfc_set_bitrate_mode) | Set bitrate mode. | 87 88--- 89 90## SFC_GET_LIB_VERSION 91 92Retrieve the version of the library as a string. 93 94### Parameters 95 96sndfile 97: Not used 98 99cmd 100: SFC_GET_LIB_VERSION 101 102data 103: A pointer to a char buffer 104 105datasize 106: The size of the buffer 107 108### Examples 109 110```c 111char buffer [128] ; 112sf_command (NULL, SFC_GET_LIB_VERSION, buffer, sizeof (buffer)) ; 113``` 114 115### Return value 116 117This call will return the length of the retrieved version string. 118 119### Notes 120 121The string returned in the buffer passed to this function will not overflow the 122buffer and will always be null terminated . 123 124## SFC_GET_LOG_INFO 125 126Retrieve the internal per-file operation log. 127 128This log buffer can often contain a good reason for why libsndfile failed to 129open a particular file. 130 131### Parameters 132 133sndfile 134: A valid SNDFILE* pointer 135 136cmd 137: SFC_GET_LOG_INFO 138 139data 140: A pointer to a char buffer 141 142datasize 143: The size of the buffer 144 145Example: 146 147```c 148char buffer [2048] ; 149sf_command (sndfile, SFC_GET_LOG_INFO, buffer, sizeof (buffer)) ; 150``` 151 152### Return value 153 154This call will return the length of the retrieved version string. 155 156### Notes 157 158The string returned in the buffer passed to this function will not overflow the 159buffer and will always be null terminated. 160 161## SFC_GET_CURRENT_SF_INFO 162 163Retrieve `SF_INFO` struct of opened file. 164 165`SFC_GET_CURRENT_SF_INFO` command copies `SF_INFO` struct of `sndfile` object to 166provided buffer. 167 168### Parameters 169 170sndfile 171: A valid SNDFILE* pointer 172 173cmd 174: SFC_GET_CURRENT_SF_INFO 175 176data 177: A pointer to a valid SF_INFO* pointer 178 179datasize 180: sizeof (SF_INFO) 181 182### Examples 183 184```c 185SF_INFO sfinfo ; 186sf_command (sndfile, SFC_GET_CURRENT_SF_INFO, sfinfo, sizeof (SF_INFO)) ; 187``` 188 189### Return value 190 191Zero on success, non-zero otherwise. 192 193## SFC_CALC_SIGNAL_MAX 194 195Retrieve the measured maximum signal value. This involves reading through the 196whole file which can be slow on large files. 197 198### Parameters 199 200sndfile 201: A valid SNDFILE* pointer 202 203cmd 204: SFC_CALC_SIGNAL_MAX 205 206data 207: A pointer to a double 208 209datasize 210: sizeof (double) 211 212### Examples 213 214```c 215double max_val ; 216sf_command (sndfile, SFC_CALC_SIGNAL_MAX, &max_val, sizeof (max_val)) ; 217``` 218 219### Return value 220 221Zero on success, non-zero otherwise. 222 223## SFC_CALC_NORM_SIGNAL_MAX 224 225Retrieve the measured normalised maximum signal value. This involves reading 226through the whole file which can be slow on large files. 227 228### Parameters 229 230sndfile 231: A valid SNDFILE* pointer 232 233cmd 234: SFC_CALC_NORM_SIGNAL_MAX 235 236data 237: A pointer to a double 238 239datasize 240: sizeof (double) 241 242### Examples 243 244```c 245double max_val ; 246sf_command (sndfile, SFC_CALC_NORM_SIGNAL_MAX, &max_val, sizeof (max_val)) ; 247``` 248 249### Return value 250 251Zero on success, non-zero otherwise. 252 253## SFC_CALC_MAX_ALL_CHANNELS 254 255Calculate the peak value (ie a single number) for each channel. This involves 256reading through the whole file which can be slow on large files. 257 258### Parameters 259 260sndfile 261: A valid SNDFILE* pointer 262 263cmd 264: SFC_CALC_MAX_ALL_CHANNELS 265 266data 267: A pointer to a double 268 269datasize 270: sizeof (double) * number_of_channels 271 272### Examples 273 274```c 275double peaks [number_of_channels] ; 276sf_command (sndfile, SFC_CALC_MAX_ALL_CHANNELS, peaks, sizeof (peaks)) ; 277``` 278 279### Return value 280 281Zero if peaks have been calculated successfully and non-zero otherwise. 282 283## SFC_CALC_NORM_MAX_ALL_CHANNELS 284 285Calculate the normalised peak for each channel. This involves reading through 286the whole file which can be slow on large files. 287 288### Parameters 289 290sndfile 291: A valid SNDFILE* pointer 292 293cmd 294: SFC_CALC_NORM_MAX_ALL_CHANNELS 295 296data 297: A pointer to a double 298 299datasize 300: sizeof (double) * number_of_channels 301 302### Examples 303 304```c 305double peaks [number_of_channels] ; 306sf_command (sndfile, SFC_CALC_NORM_MAX_ALL_CHANNELS, peaks, sizeof (peaks)) ; 307``` 308 309### Return value 310 311Zero if peaks have been calculated successfully and non-zero otherwise. 312 313## SFC_GET_SIGNAL_MAX 314 315Retrieve the peak value for the file as stored in the file header. 316 317### Parameters 318 319sndfile 320: A valid SNDFILE* pointer 321 322cmd 323: SFC_GET_SIGNAL_MAX 324 325data 326: A pointer to a double 327 328datasize 329: sizeof (double) 330 331### Examples 332 333```c 334double max_peak ; 335sf_command (sndfile, SFC_GET_SIGNAL_MAX, &max_peak, sizeof (max_peak)) ; 336``` 337 338### Return value 339 340SF_TRUE if the file header contained the peak value. SF_FALSE 341otherwise. 342 343## SFC_GET_MAX_ALL_CHANNELS 344 345Retrieve the peak value for the file as stored in the file header. 346 347### Parameters 348 349sndfile 350: A valid SNDFILE* pointer 351 352cmd 353: SFC_GET_SIGNAL_MAX 354 355data 356: A pointer to an array of doubles 357 358datasize 359: sizeof (double) * number_of_channels 360 361### Example 362 363```c 364double peaks [number_of_channels] ; 365sf_command (sndfile, SFC_GET_MAX_ALL_CHANNELS, peaks, sizeof (peaks)) ; 366``` 367 368### Return value 369 370SF_TRUE if the file header contains per channel peak values for the file, 371SF_FALSE otherwise. 372 373## SFC_SET_NORM_FLOAT 374 375This command only affects data read from or written to using the 376floating point 377functions: 378 379```c 380size_t sf_read_float (SNDFILE *sndfile, float *ptr, size_t items) ; 381size_t sf_readf_float (SNDFILE *sndfile, float *ptr, size_t frames) ; 382 383size_t sf_write_float (SNDFILE *sndfile, float *ptr, size_t items) ; 384size_t sf_writef_float (SNDFILE *sndfile, float *ptr, size_t frames) ; 385``` 386 387### Parameters 388 389sndfile 390: A valid SNDFILE* pointer 391 392cmd 393: SFC_SET_NORM_FLOAT 394 395data 396: NULL 397 398datasize 399: SF_TRUE or SF_FALSE 400 401For read operations setting normalisation to SF_TRUE means that the data from 402all subsequent reads will be be normalised to the range [-1.0, 1.0]. 403 404For write operations, setting normalisation to SF_TRUE means than all data 405supplied to the float write functions should be in the range [-1.0, 1.0] and 406will be scaled for the file format as necessary. 407 408For both cases, setting normalisation to SF_FALSE means that no scaling will 409take place. 410 411### Examples 412 413```c 414sf_command (sndfile, SFC_SET_NORM_FLOAT, NULL, SF_TRUE) ; 415 416sf_command (sndfile, SFC_SET_NORM_FLOAT, NULL, SF_FALSE) ; 417``` 418 419### Return value 420 421Returns the previous float normalisation mode. 422 423## SFC_SET_NORM_DOUBLE 424 425This command only affects data read from or written to using the double 426precision floating point 427functions: 428 429```c 430size_t sf_read_double (SNDFILE *sndfile, double *ptr, size_t items) ; 431size_t sf_readf_double (SNDFILE *sndfile, double *ptr, size_t frames) ; 432 433size_t sf_write_double (SNDFILE *sndfile, double *ptr, size_t items) ; 434size_t sf_writef_double (SNDFILE *sndfile, double *ptr, size_t frames) ; 435``` 436 437### Parameters 438 439sndfile 440: A valid SNDFILE* pointer 441 442cmd 443: SFC_SET_NORM_DOUBLE 444 445data 446: NULL 447 448datasize 449: SF_TRUE or SF_FALSE 450 451For read operations setting normalisation to SF_TRUE means that the data from 452all subsequent reads will be be normalised to the range [-1.0, 1.0]. 453 454For write operations, setting normalisation to SF_TRUE means than all data 455supplied to the double write functions should be in the range [-1.0, 1.0] and 456will be scaled for the file format as necessary. 457 458For both cases, setting normalisation to SF_FALSE means that no scaling will 459take place. 460 461### Examples 462 463```c 464sf_command (sndfile, SFC_SET_NORM_DOUBLE, NULL, SF_TRUE) ; 465 466sf_command (sndfile, SFC_SET_NORM_DOUBLE, NULL, SF_FALSE) ; 467``` 468 469### Return value 470 471Returns the previous double normalisation mode. 472 473## SFC_GET_NORM_FLOAT 474 475Retrieve the current float normalisation mode. 476 477### Parameters 478 479sndfile 480: A valid SNDFILE* pointer 481 482cmd 483: SFC_GET_NORM_FLOAT 484 485data 486: NULL 487 488datasize 489: anything 490 491### Examples 492 493```c 494normalisation = sf_command (sndfile, SFC_GET_NORM_FLOAT, NULL, 0) ; 495``` 496 497### Return value 498 499Returns TRUE if normalisation is on and FALSE otherwise. 500 501## SFC_GET_NORM_DOUBLE 502 503Retrieve the current float normalisation mode. 504 505### Parameters 506 507sndfile 508: A valid SNDFILE* pointer 509 510cmd 511: SFC_GET_NORM_DOUBLE 512 513data 514: NULL 515 516datasize 517: anything 518 519Example: 520 521```c 522normalisation = sf_command (sndfile, SFC_GET_NORM_DOUBLE, NULL, 0) ; 523``` 524 525### Return value 526 527Returns TRUE if normalisation is on and FALSE otherwise. 528 529## SFC_SET_SCALE_FLOAT_INT_READ 530 531Set/clear the scale factor when integer (short/int) data is read from a file 532containing floating point data. 533 534### Parameters 535 536sndfile 537: A valid SNDFILE* pointer 538 539cmd: 540SFC_SET_SCALE_FLOAT_INT_READ 541 542data 543: NULL 544 545datasize 546: TRUE or FALSE 547 548Example: 549 550```c 551sf_command (sndfile, SFC_SET_SCALE_FLOAT_INT_READ, NULL, SF_TRUE) ; 552``` 553 554### Return value 555 556Returns the previous `SFC_SET_SCALE_FLOAT_INT_READ` setting for this file. 557 558## SFC_SET_SCALE_INT_FLOAT_WRITE 559 560Set/clear the scale factor when integer (short/int) data is written to a file as 561floating point data. 562 563### Parameters 564 565sndfile 566: A valid SNDFILE* pointer 567 568cmd 569: SFC_SET_SCALE_INT_FLOAT_WRITE 570 571data 572: NULL 573 574datasize 575: TRUE or FALSE 576 577### Examples 578 579```c 580sf_command (sndfile, SFC_SET_SCALE_INT_FLOAT_WRITE, NULL, SF_TRUE) ; 581``` 582 583### Return value 584 585Returns the previous `SFC_SET_SCALE_INT_FLOAT_WRITE` setting for this file. 586 587## SFC_GET_SIMPLE_FORMAT_COUNT 588 589Retrieve the number of simple formats supported by libsndfile. 590 591### Parameters 592 593sndfile 594: Not used. 595 596cmd 597: SFC_GET_SIMPLE_FORMAT_COUNT 598 599data 600: a pointer to an int 601 602datasize 603: sizeof (int) 604 605### Examples 606 607```c 608int count ; 609sf_command (sndfile, SFC_GET_SIMPLE_FORMAT_COUNT, &count, sizeof (int)) ; 610``` 611 612### Return value 613 614`0`. 615 616## SFC_GET_SIMPLE_FORMAT 617 618Retrieve information about a simple format. 619 620### Parameters 621 622sndfile 623: Not used. 624 625cmd 626: SFC_GET_SIMPLE_FORMAT 627 628data 629: a pointer to an SF_FORMAT_INFO struct 630 631datasize 632: sizeof (SF_FORMAT_INFO) 633 634The SF_FORMAT_INFO struct is defined in *sndfile.h* as: 635 636```c 637typedef struct 638{ int format ; 639 const char *name ; 640 const char *extension ; 641} SF_FORMAT_INFO ; 642``` 643 644When `sf_command()` is called with `SF_GET_SIMPLE_FORMAT`, the value of the 645format field should be the format number (ie 0 \<= format \<= count value 646obtained using `SF_GET_SIMPLE_FORMAT_COUNT). 647 648### Examples 649 650```c 651SF_FORMAT_INFO format_info ; 652int k, count ; 653 654sf_command (sndfile, SFC_GET_SIMPLE_FORMAT_COUNT, &count, sizeof (int)) ; 655 656for (k = 0 ; k < count ; k++) 657{ format_info.format = k ; 658 sf_command (sndfile, SFC_GET_SIMPLE_FORMAT, &format_info, sizeof (format_info)) ; 659 printf ("%08x %s %s\n", format_info.format, format_info.name, format_info.extension) ; 660 } ; 661``` 662 663### Return value 664 6650 on success and non-zero otherwise. 666 667The value of the format field of the `SF_FORMAT_INFO` struct will be a value 668which can be placed in the format field of an `SF_INFO` struct when a file is to 669be opened for write. The name field will contain a char\* pointer to the name of 670the string, eg. "WAV (Microsoft 16 bit PCM)". The extension field will contain 671the most commonly used file extension for that file type. 672 673## SFC_GET_FORMAT_INFO 674 675Retrieve information about a major or subtype format. 676 677### Parameters 678 679sndfile 680: Not used. 681 682cmd 683: SFC_GET_FORMAT_INFO 684 685data 686: a pointer to an SF_FORMAT_INFO struct 687 688datasize 689: sizeof (SF_FORMAT_INFO) 690 691The `SF_FORMAT_INFO` struct is defined in \<sndfile.h\> as: 692 693```c 694typedef struct 695{ int format ; 696 const char *name ; 697 const char *extension ; 698} SF_FORMAT_INFO ; 699``` 700 701When `sf_command()` is called with `SF_GET_FORMAT_INFO`, the format field is 702examined and if (format & `SF_FORMAT_TYPEMASK`) is a valid format then the 703struct is filled in with information about the given major type. If (format & 704`SF_FORMAT_TYPEMASK`) is FALSE and (format & `SF_FORMAT_SUBMASK`) is a valid 705subtype format then the struct is filled in with information about the given 706subtype. 707 708### Examples 709 710```c 711SF_FORMAT_INFO format_info ; 712 713format_info.format = SF_FORMAT_WAV ; 714sf_command (sndfile, SFC_GET_FORMAT_INFO, &format_info, sizeof (format_info)) ; 715printf ("%08x %s %s\n", format_info.format, format_info.name, format_info.extension) ; 716 717format_info.format = SF_FORMAT_ULAW ; 718sf_command (sndfile, SFC_GET_FORMAT_INFO, &format_info, sizeof (format_info)) ; 719printf ("%08x %s\n", format_info.format, format_info.name) ; 720``` 721 722### Return value 723 7240 on success and non-zero otherwise. 725 726## SFC_GET_FORMAT_MAJOR_COUNT 727 728Retrieve the number of major formats. 729 730### Parameters 731 732sndfile 733: Not used. 734 735cmd 736: SFC_GET_FORMAT_MAJOR_COUNT 737 738data 739: a pointer to an int 740 741datasize 742: sizeof (int) 743 744### Examples 745 746```c 747int count ; 748sf_command (sndfile, SFC_GET_FORMAT_MAJOR_COUNT, &count, sizeof (int)) ; 749``` 750 751### Return value 752 7530. 754 755## SFC_GET_FORMAT_MAJOR 756 757Retrieve information about a major format type. 758 759### Parameters 760 761sndfile 762: Not used. 763 764cmd 765: SFC_GET_FORMAT_MAJOR 766 767data 768: a pointer to an SF_FORMAT_INFO struct 769 770datasize 771: sizeof (SF_FORMAT_INFO) 772 773### Examples 774 775```c 776SF_FORMAT_INFO format_info ; 777int k, count ; 778 779sf_command (sndfile, SFC_GET_FORMAT_MAJOR_COUNT, &count, sizeof (int)) ; 780 781for (k = 0 ; k < count ; k++) 782{ format_info.format = k ; 783 sf_command (sndfile, SFC_GET_FORMAT_MAJOR, &format_info, sizeof (format_info)) ; 784 printf ("%08x %s %s\n", format_info.format, format_info.name, format_info.extension) ; 785 } ; 786``` 787 788For a more comprehensive example, see the program `list_formats.c` in the 789`examples/` directory of the libsndfile source code distribution. 790 791### Return value 792 7930 on success and non-zero otherwise. 794 795The value of the format field will be one of the major format identifiers such 796as `SF_FORMAT_WAV` or `SF_FORMAT`_AIFF. The name field will contain a char\* 797pointer to the name of the string, eg. "WAV (Microsoft)". The extension field 798will contain the most commonly used file extension for that file type. 799 800## SFC_GET_FORMAT_SUBTYPE_COUNT 801 802Retrieve the number of subformats. 803 804### Parameters 805 806sndfile 807: Not used. 808 809cmd 810: SFC_GET_FORMAT_SUBTYPE_COUNT 811 812data 813: a pointer to an int 814 815datasize 816: sizeof (int) 817 818### Examples 819 820```c 821int count ; 822sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE_COUNT, &count, sizeof (int)) ; 823``` 824 825### Return value 826 827Returns zero. 828 829## SFC_GET_FORMAT_SUBTYPE 830 831Enumerate the subtypes (this function does not translate a subtype into a string 832describing that subtype). A typical use case might be retrieving a string 833description of all subtypes so that a dialog box can be filled in. 834 835### Parameters 836 837sndfile 838: Not used. 839 840cmd 841: SFC_GET_FORMAT_SUBTYPE 842 843data 844: a pointer to an SF_FORMAT_INFO struct 845 846datasize 847: sizeof (SF_FORMAT_INFO) 848 849### Examples 850 851Example 1: Retrieve all sybtypes supported by the WAV format. 852 853```c 854SF_FORMAT_INFO format_info ; 855int k, count ; 856 857sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE_COUNT, &count, sizeof (int)) ; 858 859for (k = 0 ; k < count ; k++) 860{ format_info.format = k ; 861 sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE, &format_info, sizeof (format_info)) ; 862 if (! sf_format_check (format_info.format | SF_FORMAT_WAV)) 863 continue ; 864 printf ("%08x %s\n", format_info.format, format_info.name) ; 865 } ; 866``` 867 868Example 2: Print a string describing the `SF_FORMAT_PCM_16` subtype. 869 870```c 871SF_FORMAT_INFO format_info ; 872int k, count ; 873 874sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE_COUNT, &count, sizeof (int)) ; 875 876for (k = 0 ; k < count ; k++) 877{ format_info.format = k ; 878 sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE, &format_info, sizeof (format_info)) ; 879 if (format_info.format == SF_FORMAT_PCM_16) 880 { printf ("%08x %s\n", format_info.format, format_info.name) ; 881 break ; 882 } ; 883 } ; 884``` 885 886For a more comprehensive example, see the program `list_formats.c` in the 887`examples/` directory of the libsndfile source code distribution. 888 889### Return value 890 8910 on success and non-zero otherwise. 892 893The value of the format field will be one of the major format identifiers such 894as `SF_FORMAT_WAV` or `SF_FORMAT_AIFF`. The name field will contain a char\* 895pointer to the name of the string; for instance "WAV (Microsoft)" or "AIFF 896(Apple/SGI)". The extension field will be a NULL pointer. 897 898## SFC_SET_ADD_PEAK_CHUNK 899 900By default, WAV and AIFF files which contain floating point data (subtype 901`SF_FORMAT_FLOAT` or `SF_FORMAT_DOUBLE`) have a PEAK chunk. By using this 902command, the addition of a PEAK chunk can be turned on or off. 903 904**Note**: This call must be made before any data is written to the file. 905 906### Parameters 907 908sndfile 909: A valid SNDFILE* pointer 910 911cmd 912: SFC_SET_ADD_PEAK_CHUNK 913 914data 915: Not used (should be NULL) 916 917datasize 918: TRUE or FALSE. 919 920### Examples 921 922```c 923/* Turn on the PEAK chunk. */ 924sf_command (sndfile, SFC_SET_ADD_PEAK_CHUNK, NULL, SF_TRUE) ; 925 926/* Turn off the PEAK chunk. */ 927sf_command (sndfile, SFC_SET_ADD_PEAK_CHUNK, NULL, SF_FALSE) ; 928``` 929 930### Return value 931 932Returns SF_TRUE if the peak chunk will be written after this call. Returns 933SF_FALSE if the peak chunk will not be written after this call. 934 935## SFC_UPDATE_HEADER_NOW 936 937The header of an audio file is normally written by libsndfile when the file is 938closed using [**sf_close()**](api.md#file-close-function). 939 940There are however situations where large files are being generated and it would 941be nice to have valid data in the header before the file is complete. Using this 942command will update the file header to reflect the amount of data written to the 943file so far. Other programs opening the file for read (before any more data is 944written) will then read a valid sound file header. 945 946### Parameters 947 948sndfile 949: A valid SNDFILE* pointer 950 951cmd 952: SFC_UPDATE_HEADER_NOW 953 954data 955: Not used (should be NULL) 956 957datasize 958: Not used. 959 960### Examples 961 962```c 963/* Update the header now. */ 964sf_command (sndfile, SFC_UPDATE_HEADER_NOW, NULL, 0) ; 965``` 966 967### Return value 968 969Returns zero. 970 971## SFC_SET_UPDATE_HEADER_AUTO 972 973Similar to `SFC_UPDATE_HEADER_NOW` but updates the header at the end of every 974call to the [sf_write\*](api.md#write) functions. 975 976### Parameters 977 978sndfile 979: A valid SNDFILE* pointer 980 981cmd 982: SFC_SET_UPDATE_HEADER_AUTO 983 984data 985: Not used (should be NULL) 986 987datasize 988: `SF_TRUE` or `SF_FALSE` 989 990### Examples 991 992```c 993/* Turn on auto header update. */ 994sf_command (sndfile, SFC_SET_UPDATE_HEADER_AUTO, NULL, SF_TRUE) ; 995 996/* Turn off auto header update. */ 997sf_command (sndfile, SFC_SET_UPDATE_HEADER_AUTO, NULL, SF_FALSE) ; 998``` 999 1000### Return value 1001 1002TRUE if auto update header is now on; FALSE otherwise. 1003 1004## SFC_FILE_TRUNCATE 1005 1006Truncate a file that was opened for write or read/write. 1007 1008### Parameters 1009 1010sndfile 1011: A valid SNDFILE* pointer 1012 1013cmd 1014: SFC_FILE_TRUNCATE 1015 1016data 1017: A pointer to an sf_count_t. 1018 1019datasize 1020: sizeof (sf_count_t) 1021 1022Truncate the file to the number of frames specified by the sf_count_t pointed to 1023by data. After this command, both the read and the write pointer will be at the 1024new end of the file. This command will fail (returning non-zero) if the 1025requested truncate position is beyond the end of the file. 1026 1027### Examples 1028 1029```c 1030/* Truncate the file to a length of 20 frames. */ 1031sf_count_t frames = 20 ; 1032sf_command (sndfile, SFC_FILE_TRUNCATE, &frames, sizeof (frames)) ; 1033``` 1034 1035### Return value 1036 1037Zero on sucess, non-zero otherwise. 1038 1039## SFC_SET_RAW_START_OFFSET 1040 1041Change the data start offset for files opened up as `SF_FORMAT_RAW`. 1042 1043### Parameters 1044 1045sndfile 1046: A valid SNDFILE* pointer 1047 1048cmd 1049: SFC_SET_RAW_START_OFFSET 1050 1051data 1052: A pointer to an sf_count_t. 1053 1054datasize 1055: sizeof (sf_count_t) 1056 1057For a file opened as format `SF_FORMAT_RAW`, set the data offset to the value 1058given by `data`. 1059 1060### Examples 1061 1062```c 1063/* Reset the data offset to 5 bytes from the start of the file. */ 1064sf_count_t offset = 5 ; 1065sf_command (sndfile, SFC_SET_RAW_START_OFFSET, &offset, sizeof (offset)) ; 1066``` 1067 1068### Return value 1069 1070Zero on success, non-zero otherwise. 1071 1072## SFC_SET_CLIPPING 1073 1074Turn on/off automatic clipping when doing floating point to integer conversion. 1075 1076### Parameters 1077 1078sndfile 1079: A valid SNDFILE* pointer 1080 1081cmd 1082: SFC_SET_CLIPPING 1083 1084data 1085: NULL 1086 1087datasize 1088: SF_TRUE or SF_FALSE. 1089 1090Turn on (datasize == SF_TRUE) or off (datasize == SF_FALSE) clipping. 1091 1092### Examples 1093 1094```c 1095sf_command (sndfile, SFC_SET_CLIPPING, NULL, SF_TRUE) ; 1096``` 1097 1098### Return value 1099 1100Clipping mode (SF_TRUE or SF_FALSE). 1101 1102## SFC_GET_CLIPPING 1103 1104Turn on/off automatic clipping when doing floating point to integer conversion. 1105 1106### Parameters 1107 1108sndfile 1109: A valid SNDFILE* pointer 1110 1111cmd 1112: SFC_GET_CLIPPING 1113 1114data 1115: NULL 1116 1117datasize 1118: 0 1119 1120Retrieve the current cliiping setting. 1121 1122### Examples 1123 1124```c 1125sf_command (sndfile, SFC_GET_CLIPPING, NULL, 0) ; 1126``` 1127 1128### Return value 1129 1130Clipping mode (SF_TRUE or SF_FALSE). 1131 1132## SFC_GET_EMBED_FILE_INFO 1133 1134Get the file offset and file length of a file enbedded within another larger 1135file. 1136 1137### Parameters 1138 1139sndfile 1140: A valid SNDFILE* pointer 1141 1142cmd 1143: SFC_GET_EMBED_FILE_INFO 1144 1145data 1146: a pointer to an SF_EMBED_FILE_INFO struct 1147 1148datasize 1149: sizeof (SF_EMBED_FILE_INFO) 1150 1151The `SF_EMBED_FILE_INFO` struct is defined in *sndfile.h* as: 1152 1153```c 1154typedef struct 1155{ sf_count_t offset ; 1156 sf_count_t length ; 1157} SF_EMBED_FILE_INFO ; 1158``` 1159 1160### Return value 1161 11620 on success and non-zero otherwise. 1163 1164The value of the offset field of the `SF_EMBED_FILE_INFO` struct will be the 1165offsets in bytes from the start of the outer file to the start of the audio 1166file. The value of the offset field of the `SF_EMBED_FILE_INFO` struct will be 1167the length in bytes of the embedded file. 1168 1169## SFC_WAVEX_GET_AMBISONIC 1170 1171Test if the current file has the GUID of a WAVEX file for any of the Ambisonic 1172formats. 1173 1174### Parameters 1175 1176sndfile 1177: A valid SNDFILE* pointer 1178 1179cmd 1180: SFC_WAVEX_GET_AMBISONIC 1181 1182data 1183: NULL 1184 1185datasize 1186: 0 1187 1188The Ambisonic WAVEX formats are defined here: 1189<http://dream.cs.bath.ac.uk/researchdev/wave-ex/bformat.html>. 1190 1191### Return value 1192 1193`SF_AMBISONIC_NONE(0x40)` or `SF_AMBISONIC_B_FORMAT(0x41)` or zero if the file 1194format does not support ambisonic formats. 1195 1196## SFC_WAVEX_SET_AMBISONIC 1197 1198Set the GUID of a new WAVEX file to indicate an Ambisonics format. 1199 1200### Parameters 1201 1202sndfile 1203: A valid SNDFILE* pointer 1204 1205cmd 1206: SFC_WAVEX_SET_AMBISONIC 1207 1208data 1209: NULL 1210 1211datasize 1212: SF_AMBISONIC_NONE or SF_AMBISONIC_B_FORMAT 1213 1214Turn on (`SF_AMBISONIC_B_FORMAT(0x41)`) or off (`SF_AMBISONIC_NONE(0x40)`) 1215encoding. This command is currently only supported for files with 1216`SF_FORMAT_WAVEX` format. 1217 1218The Ambisonic WAVEX formats are defined here: 1219 1220<http://dream.cs.bath.ac.uk/researchdev/wave-ex/bformat.html>. 1221 1222### Return value 1223 1224Return the ambisonic value that has just been set or zero if the 1225file format does not support ambisonic encoding. 1226 1227## SFC_SET_VBR_ENCODING_QUALITY 1228 1229Set the Variable Bit Rate encoding quality. The encoding quality value 1230should be between 0.0 (lowest quality) and 1.0 (highest quality). 1231Currenly this command is only implemented for FLAC and Ogg/Vorbis files. 1232It has no effect on un-compressed file formats. 1233 1234### Parameters 1235 1236sndfile 1237: A valid SNDFILE* pointer 1238 1239cmd 1240: SFC_SET_VBR_ENCODING_QUALITY 1241 1242data 1243: A pointer to a double value 1244 1245datasize 1246: sizeof (double) 1247 1248The command must be sent before any audio data is written to the file. 1249 1250### Return value 1251 1252SF_TRUE if VBR encoding quality was set. SF_FALSE otherwise. 1253 1254## SFC_SET_OGG_PAGE_LATENCY_MS 1255 1256Set page latency for Ogg Opus file in milliseconds. The value should be between 125750.0 and 1600.0. This command is only implemented for Ogg Opus files. 1258 1259### Parameters 1260 1261sndfile 1262: A valid SNDFILE* pointer 1263 1264cmd 1265: SFC_SET_OGG_PAGE_LATENCY_MS 1266 1267data 1268: A pointer to a double value 1269 1270datasize 1271: sizeof (double) 1272 1273### Return value 1274 12750 on success and non-zero otherwise. 1276 1277## SFC_GET_OGG_STREAM_SERIALNO 1278 1279Get the Ogg stream serial number for files with the Ogg major format. Ogg 1280stream serail numbers are a randomly chosen 32-bit value, used for 1281differentiating logical Ogg streams. 1282 1283### Parameters 1284 1285sndfile 1286: A valid SNDFILE* pointer 1287 1288cmd 1289: SFC_SET_OGG_STREAM_SERIALNO 1290 1291data 1292: A pointer to a 32-bit int value 1293 1294datasize 1295: sizeof (int32_t) = 4 1296 1297### Return value 1298 12990 on success and non-zero otherwise. 1300 1301## SFC_SET_COMPRESSION_LEVEL 1302 1303Set the compression level. The compression level should be between 0.0 (minimum 1304compression level) and 1.0 (highest compression level). Currenly this command is 1305only implemented for FLAC and Ogg/Vorbis files. It has no effect on 1306uncompressed file formats. 1307 1308### Parameters 1309 1310sndfile 1311: A valid SNDFILE* pointer 1312 1313cmd 1314: SFC_SET_COMPRESSION_LEVEL 1315 1316data 1317: A pointer to a double value 1318 1319datasize 1320: sizeof (double) 1321 1322The command must be sent before any audio data is written to the file. 1323 1324### Return value 1325 1326SF_TRUE if compression level was set. SF_FALSE otherwise. 1327 1328## SFC_RAW_DATA_NEEDS_ENDSWAP 1329 1330Determine if raw data read using [sf_read_raw()](api.md#raw) needs to be end 1331swapped on the host CPU. 1332 1333For instance, will return SF_TRUE on when reading WAV containing 1334`SF_FORMAT_PCM_16` data on a big endian machine and `SF_FALSE` on a 1335little endian machine. 1336 1337### Parameters 1338 1339sndfile 1340: A valid SNDFILE* pointer 1341 1342cmd 1343: SFC_RAW_DATA_NEEDS_ENDSWAP 1344 1345data 1346: NULL 1347 1348datasize 1349: 0 1350 1351### Return value 1352 1353`SF_TRUE` or `SF_FALSE`. 1354 1355## SFC_GET_BROADCAST_INFO 1356 1357Retrieve the Broadcast Extension Chunk from WAV (and related) files. 1358 1359### Parameters 1360 1361sndfile 1362: A valid SNDFILE* pointer 1363 1364cmd 1365: SFC_GET_BROADCAST_INFO 1366 1367data 1368: a pointer to an SF_BROADCAST_INFO struct 1369 1370datasize 1371: sizeof (SF_BROADCAST_INFO) 1372 1373The SF_BROADCAST_INFO struct is defined in *sndfile.h* as: 1374 1375```c 1376typedef struct 1377{ char description [256] ; 1378 char originator [32] ; 1379 char originator_reference [32] ; 1380 char origination_date [10] ; 1381 char origination_time [8] ; 1382 unsigned int time_reference_low ; 1383 unsigned int time_reference_high ; 1384 short version ; 1385 char umid [64] ; 1386 char reserved [190] ; 1387 unsigned int coding_history_size ; 1388 char coding_history [256] ; 1389} SF_BROADCAST_INFO ; 1390``` 1391 1392### Return value 1393 1394`SF_TRUE` if the file contained a Broadcast Extension chunk or `SF_FALSE` 1395otherwise. 1396 1397## SFC_SET_BROADCAST_INFO 1398 1399Set the Broadcast Extension Chunk for WAV (and related) files. 1400 1401### Parameters 1402 1403sndfile 1404: A valid SNDFILE* pointer 1405 1406cmd 1407: SFC_SET_BROADCAST_INFO 1408 1409data 1410: a pointer to an SF_BROADCAST_INFO struct 1411 1412datasize 1413: sizeof (SF_BROADCAST_INFO) 1414 1415### Return value 1416 1417`SF_TRUE` if setting the Broadcast Extension chunk was successful and `SF_FALSE` 1418otherwise. 1419 1420## SFC_GET_CHANNEL_MAP_INFO 1421 1422Retrieve the channel map contained in an AIFF or CAF Channel Layout chunk. 1423 1424### Parameters 1425 1426sndfile 1427: A valid SNDFILE* pointer 1428 1429cmd 1430: SFC_GET_CHANNEL_MAP_INFO 1431 1432data 1433: a pointer to an array of int, the same size as the number of channels in the 1434file 1435 1436datasize 1437: number of channels * sizeof (int) 1438 1439Channel map positions are defined in an enum in *sndfile.h*: 1440 1441| Name | Value | Description | 1442|:-------------------------------------|:------|:------------------------------------------------------------------| 1443| SF_CHANNEL_MAP_INVALID | 0 | | 1444| SF_CHANNEL_MAP_MONO | 1 | | 1445| SF_CHANNEL_MAP_LEFT | 2 | Apple calls this 'Left' | 1446| SF_CHANNEL_MAP_RIGHT | 3 | Apple calls this 'Right' | 1447| SF_CHANNEL_MAP_CENTER | 4 | Apple calls this 'Center' | 1448| SF_CHANNEL_MAP_FRONT_LEFT | 5 | | 1449| SF_CHANNEL_MAP_FRONT_RIGHT | 6 | | 1450| SF_CHANNEL_MAP_FRONT_CENTER | 7 | | 1451| SF_CHANNEL_MAP_REAR_CENTER | 8 | Apple calls this 'Center Surround', Msft calls this 'Back Center' | 1452| SF_CHANNEL_MAP_REAR_LEFT | 9 | Apple calls this 'Left Surround', Msft calls this 'Back Left' | 1453| SF_CHANNEL_MAP_REAR_RIGHT | 10 | Apple calls this 'Right Surround', Msft calls this 'Back Right' | 1454| SF_CHANNEL_MAP_LFE | 11 | Apple calls this 'LFEScreen', Msft calls this 'Low Frequency' | 1455| SF_CHANNEL_MAP_FRONT_LEFT_OF_CENTER | 12 | Apple calls this 'Left Center' | 1456| SF_CHANNEL_MAP_FRONT_RIGHT_OF_CENTER | 13 | Apple calls this 'Right Center' | 1457| SF_CHANNEL_MAP_SIDE_LEFT | 14 | Apple calls this 'Left Surround Direct' | 1458| SF_CHANNEL_MAP_SIDE_RIGHT | 15 | Apple calls this 'Right Surround Direct' | 1459| SF_CHANNEL_MAP_TOP_CENTER | 16 | Apple calls this 'Top Center Surround' | 1460| SF_CHANNEL_MAP_TOP_FRONT_LEFT | 17 | Apple calls this 'Vertical Height Left' | 1461| SF_CHANNEL_MAP_TOP_FRONT_RIGHT | 18 | Apple calls this 'Vertical Height Right' | 1462| SF_CHANNEL_MAP_TOP_FRONT_CENTER | 19 | Apple calls this 'Vertical Height Center' | 1463| SF_CHANNEL_MAP_TOP_REAR_LEFT | 20 | Apple and MS call this 'Top Back Left' | 1464| SF_CHANNEL_MAP_TOP_REAR_RIGHT | 21 | Apple and MS call this 'Top Back Right' | 1465| SF_CHANNEL_MAP_TOP_REAR_CENTER | 22 | Apple and MS call this 'Top Back Center' | 1466| SF_CHANNEL_MAP_AMBISONIC_B_W | 23 | | 1467| SF_CHANNEL_MAP_AMBISONIC_B_X | 24 | | 1468| SF_CHANNEL_MAP_AMBISONIC_B_Y | 25 | | 1469| SF_CHANNEL_MAP_AMBISONIC_B_Z | 26 | | 1470| SF_CHANNEL_MAP_MAX | 27 | | 1471 1472### Return value 1473 1474`SF_TRUE` if the file contained a Channel Layout chunk or `SF_FALSE` otherwise. 1475 1476## SFC_SET_CHANNEL_MAP_INFO 1477 1478Set the channel map contained in an AIFF or CAF Channel Layout chunk. 1479 1480### Parameters 1481 1482sndfile 1483: A valid SNDFILE* pointer 1484 1485cmd 1486: SFC_SET_CHANNEL_MAP_INFO 1487 1488data 1489: a pointer to an array of int, the same size as the number of channels in the 1490file 1491 1492datasize 1493: number of channels * sizeof (int) 1494 1495### Return value 1496 1497`SF_TRUE` if setting the Channel Layout chunk was successful and `SF_FALSE` 1498otherwise. 1499 1500## SFC_GET_CART_INFO 1501 1502Retrieve the Cart Chunk from WAV (and related) files. Based on AES46 standard 1503for CartChunk (see [CartChunk.org](http://www.cartchunk.org/) for more 1504information. 1505 1506### Parameters 1507 1508sndfile 1509: A valid SNDFILE* pointer 1510 1511cmd 1512: SFC_GET_CART_INFO 1513 1514data 1515: a pointer to an SF_CART_INFO struct 1516 1517datasize 1518: sizeof (SF_CART_INFO) 1519 1520The SF_CART_INFO struct is defined in *sndfile.h* as: 1521 1522```c 1523#define SF_CART_INFO_VAR(p_tag_text_size) \ 1524 struct 1525 { char version [4] ; 1526 char title [64] ; 1527 char artist [64] ; 1528 char cut_id [64] ; 1529 char client_id [64] ; 1530 char category [64] ; 1531 char classification [64] ; 1532 char out_cue [64] ; 1533 char start_date [10] ; 1534 char start_time [8] ; 1535 char end_date [10] ; 1536 char end_time [8] ; 1537 char producer_app_id [64] ; 1538 char producer_app_version [64] ; 1539 char user_def [64] ; 1540 long level_reference ; 1541 SF_CART_TIMER post_timers [8] ; 1542 char reserved [276] ; 1543 char url [1024] ; 1544 unsigned int tag_text_size ; 1545 char tag_text[p_tag_text_size] ; 1546 } 1547``` 1548 1549### Return value 1550 1551`SF_TRUE` if the file contained a Cart chunk or `SF_FALSE` otherwise. 1552 1553## SFC_SET_CART_INFO 1554 1555Set the Cart Chunk for WAV (and related) files. 1556 1557### Parameters 1558 1559sndfile 1560: A valid SNDFILE* pointer 1561 1562cmd 1563: SFC_SET_CART_INFO 1564 1565data 1566: a pointer to an SF_CART_INFO struct 1567 1568datasize 1569: sizeof (SF_CART_INFO) 1570 1571### Return value 1572 1573SF_TRUE if setting the Cart chunk was successful and SF_FALSE otherwise. 1574 1575## SFC_GET_LOOP_INFO 1576 1577Retrieve loop information for file including time signature, length in beats and 1578original MIDI base note 1579 1580### Parameters 1581 1582sndfile 1583: A valid SNDFILE* pointer 1584 1585cmd 1586: SFC_GET_LOOP_INFO 1587 1588data 1589: a pointer to an SF_LOOP_INFO struct 1590 1591datasize 1592: sizeof (SF_LOOP_INFO) 1593 1594The SF_LOOP_INFO struct is defined in *sndfile.h* as: 1595 1596```c 1597typedef struct 1598{ short time_sig_num ; /* any positive integer > 0 */ 1599 short time_sig_den ; /* any positive power of 2 > 0 */ 1600 int loop_mode ; /* see SF_LOOP enum */ 1601 1602 int num_beats ; /* this is NOT the amount of quarter notes !!!*/ 1603 /* a full bar of 4/4 is 4 beats */ 1604 /* a full bar of 7/8 is 7 beats */ 1605 1606 float bpm ; /* suggestion, as it can be calculated using other fields:*/ 1607 /* file's lenght, file's sampleRate and our time_sig_den*/ 1608 /* -> bpms are always the amount of _quarter notes_ per minute */ 1609 1610 int root_key ; /* MIDI note, or -1 for None */ 1611 int future [6] ; 1612} SF_LOOP_INFO ; 1613``` 1614 1615### Examples 1616 1617```c 1618SF_LOOP_INFO loop; 1619sf_command (sndfile, SFC_GET_LOOP_INFO, &loop, sizeof (loop)) ; 1620``` 1621 1622### Return value 1623 1624`SF_TRUE` if the file header contains loop information for the file, `SF_FALSE` 1625otherwise. 1626 1627## SFC_GET_INSTRUMENT 1628 1629Retrieve instrument information from file including MIDI base note, keyboard 1630mapping and looping informations(start/stop and mode). 1631 1632### Parameters 1633 1634sndfile 1635: A valid SNDFILE* pointer 1636 1637cmd 1638: SFC_GET_INSTRUMENT 1639 1640data 1641: a pointer to an SF_INSTRUMENT struct 1642 1643datasize 1644: sizeof (SF_INSTRUMENT) 1645 1646The `SF_INSTRUMENT` struct is defined in *sndfile.h* as: 1647 1648```c 1649typedef struct 1650{ int gain ; 1651 char basenote, detune ; 1652 char velocity_lo, velocity_hi ; 1653 char key_lo, key_hi ; 1654 int loop_count ; 1655 1656 struct 1657 { int mode ; 1658 unsigned int start ; 1659 unsigned int end ; 1660 unsigned int count ; 1661 } loops [16] ; /* make variable in a sensible way */ 1662} SF_INSTRUMENT ; 1663``` 1664 1665`mode` values are defined as: 1666 1667| Name | Value | Description | 1668|:--------------------|:------|:------------| 1669| SF_LOOP_NONE | 800 | | 1670| SF_LOOP_FORWARD | 801 | | 1671| SF_LOOP_BACKWARD | 802 | | 1672| SF_LOOP_ALTERNATING | 803 | | 1673 1674### Examples 1675 1676```c 1677SF_INSTRUMENT inst ; 1678sf_command (sndfile, SFC_GET_INSTRUMENT, &inst, sizeof (inst)) ; 1679``` 1680 1681### Return value 1682 1683`SF_TRUE` if the file header contains instrument information for the file, 1684`SF_FALSE` otherwise. 1685 1686## SFC_SET_INSTRUMENT 1687 1688Set the instrument information for the file. 1689 1690### Parameters 1691 1692sndfile 1693: A valid SNDFILE* pointer 1694 1695cmd 1696: SFC_SET_INSTRUMENT 1697 1698data 1699: a pointer to an SF_INSTRUMENT struct 1700 1701datasize 1702: sizeof (SF_INSTRUMENT) 1703 1704### Examples 1705 1706```c 1707SF_INSTRUMENT inst ; 1708sf_command (sndfile, SFC_SET_INSTRUMENT, &inst, sizeof (inst)) ; 1709``` 1710 1711### Return value 1712 1713`SF_TRUE` if the file header contains instrument information for the file, 1714`SF_FALSE` otherwise. 1715 1716## SFC_GET_CUE_COUNT 1717 1718Retrieve the number of cue markers available for retrieval using the 1719[SFC_GET_CUE](#sfc_get_cue) command. 1720 1721### Parameters 1722 1723sndfile 1724: A valid SNDFILE* pointer 1725 1726cmd 1727: SFC_GET_CUE_COUNT 1728 1729data 1730: a pointer to a uint32_t 1731 1732datasize 1733: sizeof (uint32_t) 1734 1735### Examples 1736 1737```c 1738uint32_t cue_count ; 1739sf_command (sndfile, SFC_GET_CUE_COUNT, &cue_count, sizeof (cue_count)) ; 1740``` 1741 1742### Return value 1743 1744`SF_TRUE` if the file header contains cue marker information for the file, 1745`SF_FALSE` otherwise. 1746 1747## SFC_GET_CUE 1748 1749Retrieve cue marker information from file. 1750 1751### Parameters 1752 1753sndfile 1754: A valid SNDFILE* pointer 1755 1756cmd 1757: SFC_GET_CUE 1758 1759data 1760: a pointer to an SF_CUES struct 1761 1762datasize 1763: sizeof (SF_CUES) 1764 1765The SF_CUES struct is defined in *sndfile.h* as: 1766 1767```c 1768typedef struct 1769{ int cue_count ; 1770 1771 struct 1772 { int32_t indx ; 1773 uint32_t position ; 1774 int32_t fcc_chunk ; 1775 int32_t chunk_start ; 1776 int32_t block_start ; 1777 uint32_t sample_offset ; 1778 char name [256] ; 1779 } cue_points [100] ; 1780} SF_CUES ; 1781``` 1782 1783There is also an SF_CUES_VAR \#define that allows reading/writing more than 100 1784cue markers. 1785 1786### Examples 1787 1788```c 1789SF_CUES cues ; 1790sf_command (sndfile, SFC_GET_CUE, &cues, sizeof (cues)) ; 1791``` 1792 1793### Return value 1794 1795`SF_TRUE` if the file header contains cue marker information for the file, 1796`SF_FALSE` otherwise. 1797 1798## SFC_SET_CUE 1799 1800Set the cue marker information for the file. 1801 1802### Parameters 1803 1804sndfile 1805: A valid SNDFILE* pointer 1806 1807cmd 1808: SFC_SET_CUE 1809 1810data 1811: a pointer to an SF_CUES struct 1812 1813datasize 1814: sizeof (SF_CUES) 1815 1816### Examples 1817 1818```c 1819SF_CUES cues ; 1820sf_command (sndfile, SFC_SET_CUE, &cues, sizeof (cues)) ; 1821``` 1822 1823### Return value 1824 1825`SF_TRUE` if the file header contains cue marker information for the file, 1826`SF_FALSE` otherwise. 1827 1828## SFC_RF64_AUTO_DOWNGRADE 1829 1830Enable auto downgrade from RF64 to WAV. 1831 1832The EBU recomendation is that when writing RF64 files and the resulting file is 1833less than 4Gig in size, it should be downgraded to a WAV file (WAV files have a 1834maximum size of 4Gig). libsndfile doesn't follow the EBU recommendations 1835exactly, mainly because the test suite needs to be able test reading/writing 1836RF64 files without having to generate files larger than 4 gigabytes. 1837 1838Note: This command should be issued before the first bit of audio data has been 1839written to the file. Calling this command after audio data has been written will 1840return the current value of this setting, but will not allow it to be changed. 1841 1842### Parameters 1843 1844sndfile 1845: A valid SNDFILE* pointer 1846 1847cmd 1848: SFC_RF64_AUTO_DOWNGRADE 1849 1850data 1851: NULL 1852 1853datasize 1854: SF_TRUE or SF_FALSE 1855 1856### Examples 1857 1858```c 1859/* Enable auto downgrade on file close. */ 1860sf_command (sndfile, SFC_RF64_AUTO_DOWNGRADE, NULL, SF_TRUE) ; 1861``` 1862 1863### Return value 1864 1865Returns `SF_TRUE` if `SFC_RF64_AUTO_DOWNGRADE` is set and `SF_FALSE` otherwise. 1866 1867## SFC_GET_ORIGINAL_SAMPLERATE 1868 1869Get original samplerate metadata. 1870 1871The Opus audio codec stores audio data independent of samplerate, but only 1872supports encoding or decoding at 8000Hz, 12000Hz, 16000Hz, 24000Hz or 48000Hz. 1873Opus includes a header field to record the original source input samplerate, and 1874a samplerate converter may be used if needed. 1875 1876This command gets the original samplerate header field. It does not enable any 1877(non-existent) samplerate conversion, nor change the current decoder samplerate. 1878 1879### Parameters 1880 1881sndfile 1882: A valid SNDFILE* pointer 1883 1884cmd 1885: SFC_GET_ORIGINAL_SAMPLERATE 1886 1887data 1888: pointer to an integer 1889 1890datasize 1891: sizeof (int) 1892 1893### Examples 1894 1895```c 1896/* Get the original sample rate */ 1897int original_samplerate ; 1898sf_command (sndfile, SFC_GET_ORIGINAL_SAMPLERATE, &original_samplerate, sizeof (original_samplerate)) ; 1899``` 1900 1901### Return value 1902 1903Returns `SF_TRUE` on success, `SF_FALSE` otherwise. 1904 1905The passed integer is set to the value of the original samplerate. 1906 1907## SFC_SET_ORIGINAL_SAMPLERATE 1908 1909Set original samplerate metadata. 1910 1911The Opus audio codec stores audio data independent of samplerate, but only 1912supports encoding or decoding at 8000Hz, 12000Hz, 16000Hz, 24000Hz or 48000Hz. 1913Opus includes a header field to record the original source input samplerate, and 1914a samplerate converter may be used if needed. 1915 1916When writing an Opus file this command sets the original samplerate header field 1917to the provided value, which is then stored in the file. This has no effect on 1918the current encoder samplerate. 1919 1920When reading an Opus file this command overrides the original samplerate value 1921as read from the file. libsndfile uses this value to choose what samplerate to 1922decode at, rounding up to the nearest valid Opus samplerate. After a successful 1923call, the file samplerate and frames count may have changed. 1924 1925Note: This command should be issued before the first bit of audio data has been 1926read from or written to the file. 1927 1928### Parameters 1929 1930sndfile 1931: A valid SNDFILE* pointer 1932 1933cmd 1934: SFC_SET_ORIGINAL_SAMPLERATE 1935 1936data 1937: pointer to an integer 1938 1939datasize 1940: sizeof (int) 1941 1942### Examples 1943 1944```c 1945/* Store the original sample rate as 44100 */ 1946int original_samplerate 44100; 1947sf_command (sndfile, SFC_SET_ORIGINAL_SAMPLERATE, &original_samplerate, sizeof (input_samplerate)) ; 1948``` 1949 1950### Return value 1951 1952Returns SF_TRUE on success, SF_FALSE otherwise. 1953 1954On write, can only succeed if no data has been written. On read, if successful, 1955[SFC_GET_CURRENT_SF_INFO](#sfc_get_current_sf_info) should be called to 1956determine the new frames count and samplerate 1957 1958## SFC_GET_BITRATE_MODE 1959 1960Get bitrate mode. 1961 1962The bitrate mode is one of: 1963 1964| Name | Value | Description | 1965|:-------------------------|:------|:------------------| 1966| SF_BITRATE_MODE_CONSTANT | 800 | Constant bitrate. | 1967| SF_BITRATE_MODE_AVERAGE | 801 | Average bitrate. | 1968| SF_BITRATE_MODE_VARIABLE | 802 | Variable bitrate. | 1969 1970### Parameters 1971 1972sndfile 1973: A valid SNDFILE* pointer 1974 1975cmd 1976: SFC_GET_BITRATE_MODE 1977 1978data 1979: NULL 1980 1981datasize 1982: anything 1983 1984### Return value 1985 1986Returns one of `SF_BITRATE_MODE_XXX` on success, `-1` otherwise. 1987 1988## SFC_SET_BITRATE_MODE 1989 1990Set bitrate mode. 1991 1992The bitrate mode is one of: 1993 1994| Name | Value | Description | 1995|:-------------------------|:------|:------------------| 1996| SF_BITRATE_MODE_CONSTANT | 800 | Constant bitrate. | 1997| SF_BITRATE_MODE_AVERAGE | 801 | Average bitrate. | 1998| SF_BITRATE_MODE_VARIABLE | 802 | Variable bitrate. | 1999 2000### Parameters 2001 2002sndfile 2003: A valid SNDFILE* pointer 2004 2005cmd 2006: SFC_SET_BITRATE_MODE 2007 2008data 2009: pointer to an integer 2010 2011datasize 2012: sizeof (int) 2013 2014### Return value 2015 2016Returns `SF_TRUE` on success, `SF_FALSE` otherwise. 2017