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