Debian Codegraph @

docs/command.md

raw
1 ---
2 layout: page
3 title: libsndfile : the sf_command function.
4 ---
5
6 # sf_command
7
8 ```c
9 int sf_command (SNDFILE *sndfile, int cmd, void *data, int datasize) ;
10 ```
11
12 This function allows the caller to retrieve information from or change aspects
13 of the library behaviour. Examples include retrieving a string containing the
14 library version or changing the scaling applied to floating point sample data
15 during read and write. Most of these operations are performed on a per-file
16 basis.
17
18 The cmd parameter is an integer identifier which is defined in *sndfile.h*. All
19 of the valid command identifiers have names beginning with "SFC_". Data is
20 passed to and returned from the library by use of a void pointer. The library
21 will not read or write more than datasize bytes from the void pointer. For some
22 calls no data is required in which case data should be NULL and datasize may be
23 used for some other purpose.
24
25 The 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
92 Retrieve the version of the library as a string.
93
94 ### Parameters
95
96 sndfile
97 : Not used
98
99 cmd
100 : SFC_GET_LIB_VERSION
101
102 data
103 : A pointer to a char buffer
104
105 datasize
106 : The size of the buffer
107
108 ### Examples
109
110 ```c
111 char buffer [128] ;
112 sf_command (NULL, SFC_GET_LIB_VERSION, buffer, sizeof (buffer)) ;
113 ```
114
115 ### Return value
116
117 This call will return the length of the retrieved version string.
118
119 ### Notes
120
121 The string returned in the buffer passed to this function will not overflow the
122 buffer and will always be null terminated .
123
124 ## SFC_GET_LOG_INFO
125
126 Retrieve the internal per-file operation log.
127
128 This log buffer can often contain a good reason for why libsndfile failed to
129 open a particular file.
130
131 ### Parameters
132
133 sndfile
134 : A valid SNDFILE* pointer
135
136 cmd
137 : SFC_GET_LOG_INFO
138
139 data
140 : A pointer to a char buffer
141
142 datasize
143 : The size of the buffer
144
145 Example:
146
147 ```c
148 char buffer [2048] ;
149 sf_command (sndfile, SFC_GET_LOG_INFO, buffer, sizeof (buffer)) ;
150 ```
151
152 ### Return value
153
154 This call will return the length of the retrieved version string.
155
156 ### Notes
157
158 The string returned in the buffer passed to this function will not overflow the
159 buffer and will always be null terminated.
160
161 ## SFC_GET_CURRENT_SF_INFO
162
163 Retrieve `SF_INFO` struct of opened file.
164
165 `SFC_GET_CURRENT_SF_INFO` command copies `SF_INFO` struct of `sndfile` object to
166 provided buffer.
167
168 ### Parameters
169
170 sndfile
171 : A valid SNDFILE* pointer
172
173 cmd
174 : SFC_GET_CURRENT_SF_INFO
175
176 data
177 : A pointer to a valid SF_INFO* pointer
178
179 datasize
180 : sizeof (SF_INFO)
181
182 ### Examples
183
184 ```c
185 SF_INFO sfinfo ;
186 sf_command (sndfile, SFC_GET_CURRENT_SF_INFO, sfinfo, sizeof (SF_INFO)) ;
187 ```
188
189 ### Return value
190
191 Zero on success, non-zero otherwise.
192
193 ## SFC_CALC_SIGNAL_MAX
194
195 Retrieve the measured maximum signal value. This involves reading through the
196 whole file which can be slow on large files.
197
198 ### Parameters
199
200 sndfile
201 : A valid SNDFILE* pointer
202
203 cmd
204 : SFC_CALC_SIGNAL_MAX
205
206 data
207 : A pointer to a double
208
209 datasize
210 : sizeof (double)
211
212 ### Examples
213
214 ```c
215 double max_val ;
216 sf_command (sndfile, SFC_CALC_SIGNAL_MAX, &max_val, sizeof (max_val)) ;
217 ```
218
219 ### Return value
220
221 Zero on success, non-zero otherwise.
222
223 ## SFC_CALC_NORM_SIGNAL_MAX
224
225 Retrieve the measured normalised maximum signal value. This involves reading
226 through the whole file which can be slow on large files.
227
228 ### Parameters
229
230 sndfile
231 : A valid SNDFILE* pointer
232
233 cmd
234 : SFC_CALC_NORM_SIGNAL_MAX
235
236 data
237 : A pointer to a double
238
239 datasize
240 : sizeof (double)
241
242 ### Examples
243
244 ```c
245 double max_val ;
246 sf_command (sndfile, SFC_CALC_NORM_SIGNAL_MAX, &max_val, sizeof (max_val)) ;
247 ```
248
249 ### Return value
250
251 Zero on success, non-zero otherwise.
252
253 ## SFC_CALC_MAX_ALL_CHANNELS
254
255 Calculate the peak value (ie a single number) for each channel. This involves
256 reading through the whole file which can be slow on large files.
257
258 ### Parameters
259
260 sndfile
261 : A valid SNDFILE* pointer
262
263 cmd
264 : SFC_CALC_MAX_ALL_CHANNELS
265
266 data
267 : A pointer to a double
268
269 datasize
270 : sizeof (double) * number_of_channels
271
272 ### Examples
273
274 ```c
275 double peaks [number_of_channels] ;
276 sf_command (sndfile, SFC_CALC_MAX_ALL_CHANNELS, peaks, sizeof (peaks)) ;
277 ```
278
279 ### Return value
280
281 Zero if peaks have been calculated successfully and non-zero otherwise.
282
283 ## SFC_CALC_NORM_MAX_ALL_CHANNELS
284
285 Calculate the normalised peak for each channel. This involves reading through
286 the whole file which can be slow on large files.
287
288 ### Parameters
289
290 sndfile
291 : A valid SNDFILE* pointer
292
293 cmd
294 : SFC_CALC_NORM_MAX_ALL_CHANNELS
295
296 data
297 : A pointer to a double
298
299 datasize
300 : sizeof (double) * number_of_channels
301
302 ### Examples
303
304 ```c
305 double peaks [number_of_channels] ;
306 sf_command (sndfile, SFC_CALC_NORM_MAX_ALL_CHANNELS, peaks, sizeof (peaks)) ;
307 ```
308
309 ### Return value
310
311 Zero if peaks have been calculated successfully and non-zero otherwise.
312
313 ## SFC_GET_SIGNAL_MAX
314
315 Retrieve the peak value for the file as stored in the file header.
316
317 ### Parameters
318
319 sndfile
320 : A valid SNDFILE* pointer
321
322 cmd
323 : SFC_GET_SIGNAL_MAX
324
325 data
326 : A pointer to a double
327
328 datasize
329 : sizeof (double)
330
331 ### Examples
332
333 ```c
334 double max_peak ;
335 sf_command (sndfile, SFC_GET_SIGNAL_MAX, &max_peak, sizeof (max_peak)) ;
336 ```
337
338 ### Return value
339
340 SF_TRUE if the file header contained the peak value. SF_FALSE
341 otherwise.
342
343 ## SFC_GET_MAX_ALL_CHANNELS
344
345 Retrieve the peak value for the file as stored in the file header.
346
347 ### Parameters
348
349 sndfile
350 : A valid SNDFILE* pointer
351
352 cmd
353 : SFC_GET_SIGNAL_MAX
354
355 data
356 : A pointer to an array of doubles
357
358 datasize
359 : sizeof (double) * number_of_channels
360
361 ### Example
362
363 ```c
364 double peaks [number_of_channels] ;
365 sf_command (sndfile, SFC_GET_MAX_ALL_CHANNELS, peaks, sizeof (peaks)) ;
366 ```
367
368 ### Return value
369
370 SF_TRUE if the file header contains per channel peak values for the file,
371 SF_FALSE otherwise.
372
373 ## SFC_SET_NORM_FLOAT
374
375 This command only affects data read from or written to using the
376 floating point
377 functions:
378
379 ```c
380 size_t sf_read_float (SNDFILE *sndfile, float *ptr, size_t items) ;
381 size_t sf_readf_float (SNDFILE *sndfile, float *ptr, size_t frames) ;
382
383 size_t sf_write_float (SNDFILE *sndfile, float *ptr, size_t items) ;
384 size_t sf_writef_float (SNDFILE *sndfile, float *ptr, size_t frames) ;
385 ```
386
387 ### Parameters
388
389 sndfile
390 : A valid SNDFILE* pointer
391
392 cmd
393 : SFC_SET_NORM_FLOAT
394
395 data
396 : NULL
397
398 datasize
399 : SF_TRUE or SF_FALSE
400
401 For read operations setting normalisation to SF_TRUE means that the data from
402 all subsequent reads will be be normalised to the range [-1.0, 1.0].
403
404 For write operations, setting normalisation to SF_TRUE means than all data
405 supplied to the float write functions should be in the range [-1.0, 1.0] and
406 will be scaled for the file format as necessary.
407
408 For both cases, setting normalisation to SF_FALSE means that no scaling will
409 take place.
410
411 ### Examples
412
413 ```c
414 sf_command (sndfile, SFC_SET_NORM_FLOAT, NULL, SF_TRUE) ;
415
416 sf_command (sndfile, SFC_SET_NORM_FLOAT, NULL, SF_FALSE) ;
417 ```
418
419 ### Return value
420
421 Returns the previous float normalisation mode.
422
423 ## SFC_SET_NORM_DOUBLE
424
425 This command only affects data read from or written to using the double
426 precision floating point
427 functions:
428
429 ```c
430 size_t sf_read_double (SNDFILE *sndfile, double *ptr, size_t items) ;
431 size_t sf_readf_double (SNDFILE *sndfile, double *ptr, size_t frames) ;
432
433 size_t sf_write_double (SNDFILE *sndfile, double *ptr, size_t items) ;
434 size_t sf_writef_double (SNDFILE *sndfile, double *ptr, size_t frames) ;
435 ```
436
437 ### Parameters
438
439 sndfile
440 : A valid SNDFILE* pointer
441
442 cmd
443 : SFC_SET_NORM_DOUBLE
444
445 data
446 : NULL
447
448 datasize
449 : SF_TRUE or SF_FALSE
450
451 For read operations setting normalisation to SF_TRUE means that the data from
452 all subsequent reads will be be normalised to the range [-1.0, 1.0].
453
454 For write operations, setting normalisation to SF_TRUE means than all data
455 supplied to the double write functions should be in the range [-1.0, 1.0] and
456 will be scaled for the file format as necessary.
457
458 For both cases, setting normalisation to SF_FALSE means that no scaling will
459 take place.
460
461 ### Examples
462
463 ```c
464 sf_command (sndfile, SFC_SET_NORM_DOUBLE, NULL, SF_TRUE) ;
465
466 sf_command (sndfile, SFC_SET_NORM_DOUBLE, NULL, SF_FALSE) ;
467 ```
468
469 ### Return value
470
471 Returns the previous double normalisation mode.
472
473 ## SFC_GET_NORM_FLOAT
474
475 Retrieve the current float normalisation mode.
476
477 ### Parameters
478
479 sndfile
480 : A valid SNDFILE* pointer
481
482 cmd
483 : SFC_GET_NORM_FLOAT
484
485 data
486 : NULL
487
488 datasize
489 : anything
490
491 ### Examples
492
493 ```c
494 normalisation = sf_command (sndfile, SFC_GET_NORM_FLOAT, NULL, 0) ;
495 ```
496
497 ### Return value
498
499 Returns TRUE if normalisation is on and FALSE otherwise.
500
501 ## SFC_GET_NORM_DOUBLE
502
503 Retrieve the current float normalisation mode.
504
505 ### Parameters
506
507 sndfile
508 : A valid SNDFILE* pointer
509
510 cmd
511 : SFC_GET_NORM_DOUBLE
512
513 data
514 : NULL
515
516 datasize
517 : anything
518
519 Example:
520
521 ```c
522 normalisation = sf_command (sndfile, SFC_GET_NORM_DOUBLE, NULL, 0) ;
523 ```
524
525 ### Return value
526
527 Returns TRUE if normalisation is on and FALSE otherwise.
528
529 ## SFC_SET_SCALE_FLOAT_INT_READ
530
531 Set/clear the scale factor when integer (short/int) data is read from a file
532 containing floating point data.
533
534 ### Parameters
535
536 sndfile
537 : A valid SNDFILE* pointer
538
539 cmd:
540 SFC_SET_SCALE_FLOAT_INT_READ
541
542 data
543 : NULL
544
545 datasize
546 : TRUE or FALSE
547
548 Example:
549
550 ```c
551 sf_command (sndfile, SFC_SET_SCALE_FLOAT_INT_READ, NULL, SF_TRUE) ;
552 ```
553
554 ### Return value
555
556 Returns the previous `SFC_SET_SCALE_FLOAT_INT_READ` setting for this file.
557
558 ## SFC_SET_SCALE_INT_FLOAT_WRITE
559
560 Set/clear the scale factor when integer (short/int) data is written to a file as
561 floating point data.
562
563 ### Parameters
564
565 sndfile
566 : A valid SNDFILE* pointer
567
568 cmd
569 : SFC_SET_SCALE_INT_FLOAT_WRITE
570
571 data
572 : NULL
573
574 datasize
575 : TRUE or FALSE
576
577 ### Examples
578
579 ```c
580 sf_command (sndfile, SFC_SET_SCALE_INT_FLOAT_WRITE, NULL, SF_TRUE) ;
581 ```
582
583 ### Return value
584
585 Returns the previous `SFC_SET_SCALE_INT_FLOAT_WRITE` setting for this file.
586
587 ## SFC_GET_SIMPLE_FORMAT_COUNT
588
589 Retrieve the number of simple formats supported by libsndfile.
590
591 ### Parameters
592
593 sndfile
594 : Not used.
595
596 cmd
597 : SFC_GET_SIMPLE_FORMAT_COUNT
598
599 data
600 : a pointer to an int
601
602 datasize
603 : sizeof (int)
604
605 ### Examples
606
607 ```c
608 int count ;
609 sf_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
618 Retrieve information about a simple format.
619
620 ### Parameters
621
622 sndfile
623 : Not used.
624
625 cmd
626 : SFC_GET_SIMPLE_FORMAT
627
628 data
629 : a pointer to an SF_FORMAT_INFO struct
630
631 datasize
632 : sizeof (SF_FORMAT_INFO)
633
634 The SF_FORMAT_INFO struct is defined in *sndfile.h* as:
635
636 ```c
637 typedef struct
638 { int format ;
639 const char *name ;
640 const char *extension ;
641 } SF_FORMAT_INFO ;
642 ```
643
644 When `sf_command()` is called with `SF_GET_SIMPLE_FORMAT`, the value of the
645 format field should be the format number (ie 0 \<= format \<= count value
646 obtained using `SF_GET_SIMPLE_FORMAT_COUNT).
647
648 ### Examples
649
650 ```c
651 SF_FORMAT_INFO format_info ;
652 int k, count ;
653
654 sf_command (sndfile, SFC_GET_SIMPLE_FORMAT_COUNT, &count, sizeof (int)) ;
655
656 for (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
665 0 on success and non-zero otherwise.
666
667 The value of the format field of the `SF_FORMAT_INFO` struct will be a value
668 which can be placed in the format field of an `SF_INFO` struct when a file is to
669 be opened for write. The name field will contain a char\* pointer to the name of
670 the string, eg. "WAV (Microsoft 16 bit PCM)". The extension field will contain
671 the most commonly used file extension for that file type.
672
673 ## SFC_GET_FORMAT_INFO
674
675 Retrieve information about a major or subtype format.
676
677 ### Parameters
678
679 sndfile
680 : Not used.
681
682 cmd
683 : SFC_GET_FORMAT_INFO
684
685 data
686 : a pointer to an SF_FORMAT_INFO struct
687
688 datasize
689 : sizeof (SF_FORMAT_INFO)
690
691 The `SF_FORMAT_INFO` struct is defined in \<sndfile.h\> as:
692
693 ```c
694 typedef struct
695 { int format ;
696 const char *name ;
697 const char *extension ;
698 } SF_FORMAT_INFO ;
699 ```
700
701 When `sf_command()` is called with `SF_GET_FORMAT_INFO`, the format field is
702 examined and if (format & `SF_FORMAT_TYPEMASK`) is a valid format then the
703 struct 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
705 subtype format then the struct is filled in with information about the given
706 subtype.
707
708 ### Examples
709
710 ```c
711 SF_FORMAT_INFO format_info ;
712
713 format_info.format = SF_FORMAT_WAV ;
714 sf_command (sndfile, SFC_GET_FORMAT_INFO, &format_info, sizeof (format_info)) ;
715 printf ("%08x %s %s\n", format_info.format, format_info.name, format_info.extension) ;
716
717 format_info.format = SF_FORMAT_ULAW ;
718 sf_command (sndfile, SFC_GET_FORMAT_INFO, &format_info, sizeof (format_info)) ;
719 printf ("%08x %s\n", format_info.format, format_info.name) ;
720 ```
721
722 ### Return value
723
724 0 on success and non-zero otherwise.
725
726 ## SFC_GET_FORMAT_MAJOR_COUNT
727
728 Retrieve the number of major formats.
729
730 ### Parameters
731
732 sndfile
733 : Not used.
734
735 cmd
736 : SFC_GET_FORMAT_MAJOR_COUNT
737
738 data
739 : a pointer to an int
740
741 datasize
742 : sizeof (int)
743
744 ### Examples
745
746 ```c
747 int count ;
748 sf_command (sndfile, SFC_GET_FORMAT_MAJOR_COUNT, &count, sizeof (int)) ;
749 ```
750
751 ### Return value
752
753 0.
754
755 ## SFC_GET_FORMAT_MAJOR
756
757 Retrieve information about a major format type.
758
759 ### Parameters
760
761 sndfile
762 : Not used.
763
764 cmd
765 : SFC_GET_FORMAT_MAJOR
766
767 data
768 : a pointer to an SF_FORMAT_INFO struct
769
770 datasize
771 : sizeof (SF_FORMAT_INFO)
772
773 ### Examples
774
775 ```c
776 SF_FORMAT_INFO format_info ;
777 int k, count ;
778
779 sf_command (sndfile, SFC_GET_FORMAT_MAJOR_COUNT, &count, sizeof (int)) ;
780
781 for (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
788 For 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
793 0 on success and non-zero otherwise.
794
795 The value of the format field will be one of the major format identifiers such
796 as `SF_FORMAT_WAV` or `SF_FORMAT`_AIFF. The name field will contain a char\*
797 pointer to the name of the string, eg. "WAV (Microsoft)". The extension field
798 will contain the most commonly used file extension for that file type.
799
800 ## SFC_GET_FORMAT_SUBTYPE_COUNT
801
802 Retrieve the number of subformats.
803
804 ### Parameters
805
806 sndfile
807 : Not used.
808
809 cmd
810 : SFC_GET_FORMAT_SUBTYPE_COUNT
811
812 data
813 : a pointer to an int
814
815 datasize
816 : sizeof (int)
817
818 ### Examples
819
820 ```c
821 int count ;
822 sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE_COUNT, &count, sizeof (int)) ;
823 ```
824
825 ### Return value
826
827 Returns zero.
828
829 ## SFC_GET_FORMAT_SUBTYPE
830
831 Enumerate the subtypes (this function does not translate a subtype into a string
832 describing that subtype). A typical use case might be retrieving a string
833 description of all subtypes so that a dialog box can be filled in.
834
835 ### Parameters
836
837 sndfile
838 : Not used.
839
840 cmd
841 : SFC_GET_FORMAT_SUBTYPE
842
843 data
844 : a pointer to an SF_FORMAT_INFO struct
845
846 datasize
847 : sizeof (SF_FORMAT_INFO)
848
849 ### Examples
850
851 Example 1: Retrieve all sybtypes supported by the WAV format.
852
853 ```c
854 SF_FORMAT_INFO format_info ;
855 int k, count ;
856
857 sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE_COUNT, &count, sizeof (int)) ;
858
859 for (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
868 Example 2: Print a string describing the `SF_FORMAT_PCM_16` subtype.
869
870 ```c
871 SF_FORMAT_INFO format_info ;
872 int k, count ;
873
874 sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE_COUNT, &count, sizeof (int)) ;
875
876 for (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
886 For 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
891 0 on success and non-zero otherwise.
892
893 The value of the format field will be one of the major format identifiers such
894 as `SF_FORMAT_WAV` or `SF_FORMAT_AIFF`. The name field will contain a char\*
895 pointer 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
900 By 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
902 command, 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
908 sndfile
909 : A valid SNDFILE* pointer
910
911 cmd
912 : SFC_SET_ADD_PEAK_CHUNK
913
914 data
915 : Not used (should be NULL)
916
917 datasize
918 : TRUE or FALSE.
919
920 ### Examples
921
922 ```c
923 /* Turn on the PEAK chunk. */
924 sf_command (sndfile, SFC_SET_ADD_PEAK_CHUNK, NULL, SF_TRUE) ;
925
926 /* Turn off the PEAK chunk. */
927 sf_command (sndfile, SFC_SET_ADD_PEAK_CHUNK, NULL, SF_FALSE) ;
928 ```
929
930 ### Return value
931
932 Returns SF_TRUE if the peak chunk will be written after this call. Returns
933 SF_FALSE if the peak chunk will not be written after this call.
934
935 ## SFC_UPDATE_HEADER_NOW
936
937 The header of an audio file is normally written by libsndfile when the file is
938 closed using [**sf_close()**](api.md#file-close-function).
939
940 There are however situations where large files are being generated and it would
941 be nice to have valid data in the header before the file is complete. Using this
942 command will update the file header to reflect the amount of data written to the
943 file so far. Other programs opening the file for read (before any more data is
944 written) will then read a valid sound file header.
945
946 ### Parameters
947
948 sndfile
949 : A valid SNDFILE* pointer
950
951 cmd
952 : SFC_UPDATE_HEADER_NOW
953
954 data
955 : Not used (should be NULL)
956
957 datasize
958 : Not used.
959
960 ### Examples
961
962 ```c
963 /* Update the header now. */
964 sf_command (sndfile, SFC_UPDATE_HEADER_NOW, NULL, 0) ;
965 ```
966
967 ### Return value
968
969 Returns zero.
970
971 ## SFC_SET_UPDATE_HEADER_AUTO
972
973 Similar to `SFC_UPDATE_HEADER_NOW` but updates the header at the end of every
974 call to the [sf_write\*](api.md#write) functions.
975
976 ### Parameters
977
978 sndfile
979 : A valid SNDFILE* pointer
980
981 cmd
982 : SFC_SET_UPDATE_HEADER_AUTO
983
984 data
985 : Not used (should be NULL)
986
987 datasize
988 : `SF_TRUE` or `SF_FALSE`
989
990 ### Examples
991
992 ```c
993 /* Turn on auto header update. */
994 sf_command (sndfile, SFC_SET_UPDATE_HEADER_AUTO, NULL, SF_TRUE) ;
995
996 /* Turn off auto header update. */
997 sf_command (sndfile, SFC_SET_UPDATE_HEADER_AUTO, NULL, SF_FALSE) ;
998 ```
999
1000 ### Return value
1001
1002 TRUE if auto update header is now on; FALSE otherwise.
1003
1004 ## SFC_FILE_TRUNCATE
1005
1006 Truncate a file that was opened for write or read/write.
1007
1008 ### Parameters
1009
1010 sndfile
1011 : A valid SNDFILE* pointer
1012
1013 cmd
1014 : SFC_FILE_TRUNCATE
1015
1016 data
1017 : A pointer to an sf_count_t.
1018
1019 datasize
1020 : sizeof (sf_count_t)
1021
1022 Truncate the file to the number of frames specified by the sf_count_t pointed to
1023 by data. After this command, both the read and the write pointer will be at the
1024 new end of the file. This command will fail (returning non-zero) if the
1025 requested 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. */
1031 sf_count_t frames = 20 ;
1032 sf_command (sndfile, SFC_FILE_TRUNCATE, &frames, sizeof (frames)) ;
1033 ```
1034
1035 ### Return value
1036
1037 Zero on success, non-zero otherwise.
1038
1039 ## SFC_SET_RAW_START_OFFSET
1040
1041 Change the data start offset for files opened up as `SF_FORMAT_RAW`.
1042
1043 ### Parameters
1044
1045 sndfile
1046 : A valid SNDFILE* pointer
1047
1048 cmd
1049 : SFC_SET_RAW_START_OFFSET
1050
1051 data
1052 : A pointer to an sf_count_t.
1053
1054 datasize
1055 : sizeof (sf_count_t)
1056
1057 For a file opened as format `SF_FORMAT_RAW`, set the data offset to the value
1058 given by `data`.
1059
1060 ### Examples
1061
1062 ```c
1063 /* Reset the data offset to 5 bytes from the start of the file. */
1064 sf_count_t offset = 5 ;
1065 sf_command (sndfile, SFC_SET_RAW_START_OFFSET, &offset, sizeof (offset)) ;
1066 ```
1067
1068 ### Return value
1069
1070 Zero on success, non-zero otherwise.
1071
1072 ## SFC_SET_CLIPPING
1073
1074 Turn on/off automatic clipping when doing floating point to integer conversion.
1075
1076 ### Parameters
1077
1078 sndfile
1079 : A valid SNDFILE* pointer
1080
1081 cmd
1082 : SFC_SET_CLIPPING
1083
1084 data
1085 : NULL
1086
1087 datasize
1088 : SF_TRUE or SF_FALSE.
1089
1090 Turn on (datasize == SF_TRUE) or off (datasize == SF_FALSE) clipping.
1091
1092 ### Examples
1093
1094 ```c
1095 sf_command (sndfile, SFC_SET_CLIPPING, NULL, SF_TRUE) ;
1096 ```
1097
1098 ### Return value
1099
1100 Clipping mode (SF_TRUE or SF_FALSE).
1101
1102 ## SFC_GET_CLIPPING
1103
1104 Turn on/off automatic clipping when doing floating point to integer conversion.
1105
1106 ### Parameters
1107
1108 sndfile
1109 : A valid SNDFILE* pointer
1110
1111 cmd
1112 : SFC_GET_CLIPPING
1113
1114 data
1115 : NULL
1116
1117 datasize
1118 : 0
1119
1120 Retrieve the current cliiping setting.
1121
1122 ### Examples
1123
1124 ```c
1125 sf_command (sndfile, SFC_GET_CLIPPING, NULL, 0) ;
1126 ```
1127
1128 ### Return value
1129
1130 Clipping mode (SF_TRUE or SF_FALSE).
1131
1132 ## SFC_GET_EMBED_FILE_INFO
1133
1134 Get the file offset and file length of a file enbedded within another larger
1135 file.
1136
1137 ### Parameters
1138
1139 sndfile
1140 : A valid SNDFILE* pointer
1141
1142 cmd
1143 : SFC_GET_EMBED_FILE_INFO
1144
1145 data
1146 : a pointer to an SF_EMBED_FILE_INFO struct
1147
1148 datasize
1149 : sizeof (SF_EMBED_FILE_INFO)
1150
1151 The `SF_EMBED_FILE_INFO` struct is defined in *sndfile.h* as:
1152
1153 ```c
1154 typedef struct
1155 { sf_count_t offset ;
1156 sf_count_t length ;
1157 } SF_EMBED_FILE_INFO ;
1158 ```
1159
1160 ### Return value
1161
1162 0 on success and non-zero otherwise.
1163
1164 The value of the offset field of the `SF_EMBED_FILE_INFO` struct will be the
1165 offsets in bytes from the start of the outer file to the start of the audio
1166 file. The value of the offset field of the `SF_EMBED_FILE_INFO` struct will be
1167 the length in bytes of the embedded file.
1168
1169 ## SFC_WAVEX_GET_AMBISONIC
1170
1171 Test if the current file has the GUID of a WAVEX file for any of the Ambisonic
1172 formats.
1173
1174 ### Parameters
1175
1176 sndfile
1177 : A valid SNDFILE* pointer
1178
1179 cmd
1180 : SFC_WAVEX_GET_AMBISONIC
1181
1182 data
1183 : NULL
1184
1185 datasize
1186 : 0
1187
1188 The 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
1194 format does not support ambisonic formats.
1195
1196 ## SFC_WAVEX_SET_AMBISONIC
1197
1198 Set the GUID of a new WAVEX file to indicate an Ambisonics format.
1199
1200 ### Parameters
1201
1202 sndfile
1203 : A valid SNDFILE* pointer
1204
1205 cmd
1206 : SFC_WAVEX_SET_AMBISONIC
1207
1208 data
1209 : NULL
1210
1211 datasize
1212 : SF_AMBISONIC_NONE or SF_AMBISONIC_B_FORMAT
1213
1214 Turn on (`SF_AMBISONIC_B_FORMAT(0x41)`) or off (`SF_AMBISONIC_NONE(0x40)`)
1215 encoding. This command is currently only supported for files with
1216 `SF_FORMAT_WAVEX` format.
1217
1218 The Ambisonic WAVEX formats are defined here:
1219
1220 <http://dream.cs.bath.ac.uk/researchdev/wave-ex/bformat.html>.
1221
1222 ### Return value
1223
1224 Return the ambisonic value that has just been set or zero if the
1225 file format does not support ambisonic encoding.
1226
1227 ## SFC_SET_VBR_ENCODING_QUALITY
1228
1229 Set the Variable Bit Rate encoding quality. The encoding quality value
1230 should be between 0.0 (lowest quality) and 1.0 (highest quality).
1231 Currently this command is only implemented for FLAC and Ogg/Vorbis files.
1232 It has no effect on un-compressed file formats.
1233
1234 ### Parameters
1235
1236 sndfile
1237 : A valid SNDFILE* pointer
1238
1239 cmd
1240 : SFC_SET_VBR_ENCODING_QUALITY
1241
1242 data
1243 : A pointer to a double value
1244
1245 datasize
1246 : sizeof (double)
1247
1248 The command must be sent before any audio data is written to the file.
1249
1250 ### Return value
1251
1252 SF_TRUE if VBR encoding quality was set. SF_FALSE otherwise.
1253
1254 ## SFC_SET_OGG_PAGE_LATENCY_MS
1255
1256 Set page latency for Ogg Opus file in milliseconds. The value should be between
1257 50.0 and 1600.0. This command is only implemented for Ogg Opus files.
1258
1259 ### Parameters
1260
1261 sndfile
1262 : A valid SNDFILE* pointer
1263
1264 cmd
1265 : SFC_SET_OGG_PAGE_LATENCY_MS
1266
1267 data
1268 : A pointer to a double value
1269
1270 datasize
1271 : sizeof (double)
1272
1273 ### Return value
1274
1275 0 on success and non-zero otherwise.
1276
1277 ## SFC_GET_OGG_STREAM_SERIALNO
1278
1279 Get the Ogg stream serial number for files with the Ogg major format. Ogg
1280 stream serail numbers are a randomly chosen 32-bit value, used for
1281 differentiating logical Ogg streams.
1282
1283 ### Parameters
1284
1285 sndfile
1286 : A valid SNDFILE* pointer
1287
1288 cmd
1289 : SFC_SET_OGG_STREAM_SERIALNO
1290
1291 data
1292 : A pointer to a 32-bit int value
1293
1294 datasize
1295 : sizeof (int32_t) = 4
1296
1297 ### Return value
1298
1299 0 on success and non-zero otherwise.
1300
1301 ## SFC_SET_COMPRESSION_LEVEL
1302
1303 Set the compression level. The compression level should be between 0.0 (minimum
1304 compression level) and 1.0 (highest compression level). Currently this command is
1305 only implemented for FLAC and Ogg/Vorbis files. It has no effect on
1306 uncompressed file formats.
1307
1308 ### Parameters
1309
1310 sndfile
1311 : A valid SNDFILE* pointer
1312
1313 cmd
1314 : SFC_SET_COMPRESSION_LEVEL
1315
1316 data
1317 : A pointer to a double value
1318
1319 datasize
1320 : sizeof (double)
1321
1322 The command must be sent before any audio data is written to the file.
1323
1324 ### Return value
1325
1326 SF_TRUE if compression level was set. SF_FALSE otherwise.
1327
1328 ## SFC_RAW_DATA_NEEDS_ENDSWAP
1329
1330 Determine if raw data read using [sf_read_raw()](api.md#raw) needs to be end
1331 swapped on the host CPU.
1332
1333 For 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
1335 little endian machine.
1336
1337 ### Parameters
1338
1339 sndfile
1340 : A valid SNDFILE* pointer
1341
1342 cmd
1343 : SFC_RAW_DATA_NEEDS_ENDSWAP
1344
1345 data
1346 : NULL
1347
1348 datasize
1349 : 0
1350
1351 ### Return value
1352
1353 `SF_TRUE` or `SF_FALSE`.
1354
1355 ## SFC_GET_BROADCAST_INFO
1356
1357 Retrieve the Broadcast Extension Chunk from WAV (and related) files.
1358
1359 ### Parameters
1360
1361 sndfile
1362 : A valid SNDFILE* pointer
1363
1364 cmd
1365 : SFC_GET_BROADCAST_INFO
1366
1367 data
1368 : a pointer to an SF_BROADCAST_INFO struct
1369
1370 datasize
1371 : sizeof (SF_BROADCAST_INFO)
1372
1373 The SF_BROADCAST_INFO struct is defined in *sndfile.h* as:
1374
1375 ```c
1376 typedef 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`
1395 otherwise.
1396
1397 ## SFC_SET_BROADCAST_INFO
1398
1399 Set the Broadcast Extension Chunk for WAV (and related) files.
1400
1401 ### Parameters
1402
1403 sndfile
1404 : A valid SNDFILE* pointer
1405
1406 cmd
1407 : SFC_SET_BROADCAST_INFO
1408
1409 data
1410 : a pointer to an SF_BROADCAST_INFO struct
1411
1412 datasize
1413 : sizeof (SF_BROADCAST_INFO)
1414
1415 ### Return value
1416
1417 `SF_TRUE` if setting the Broadcast Extension chunk was successful and `SF_FALSE`
1418 otherwise.
1419
1420 ## SFC_GET_CHANNEL_MAP_INFO
1421
1422 Retrieve the channel map contained in an AIFF or CAF Channel Layout chunk.
1423
1424 ### Parameters
1425
1426 sndfile
1427 : A valid SNDFILE* pointer
1428
1429 cmd
1430 : SFC_GET_CHANNEL_MAP_INFO
1431
1432 data
1433 : a pointer to an array of int, the same size as the number of channels in the
1434 file
1435
1436 datasize
1437 : number of channels * sizeof (int)
1438
1439 Channel 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
1478 Set the channel map contained in an AIFF or CAF Channel Layout chunk.
1479
1480 ### Parameters
1481
1482 sndfile
1483 : A valid SNDFILE* pointer
1484
1485 cmd
1486 : SFC_SET_CHANNEL_MAP_INFO
1487
1488 data
1489 : a pointer to an array of int, the same size as the number of channels in the
1490 file
1491
1492 datasize
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`
1498 otherwise.
1499
1500 ## SFC_GET_CART_INFO
1501
1502 Retrieve the Cart Chunk from WAV (and related) files. Based on AES46 standard
1503 for CartChunk (see [CartChunk.org](http://www.cartchunk.org/) for more
1504 information.
1505
1506 ### Parameters
1507
1508 sndfile
1509 : A valid SNDFILE* pointer
1510
1511 cmd
1512 : SFC_GET_CART_INFO
1513
1514 data
1515 : a pointer to an SF_CART_INFO struct
1516
1517 datasize
1518 : sizeof (SF_CART_INFO)
1519
1520 The 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
1555 Set the Cart Chunk for WAV (and related) files.
1556
1557 ### Parameters
1558
1559 sndfile
1560 : A valid SNDFILE* pointer
1561
1562 cmd
1563 : SFC_SET_CART_INFO
1564
1565 data
1566 : a pointer to an SF_CART_INFO struct
1567
1568 datasize
1569 : sizeof (SF_CART_INFO)
1570
1571 ### Return value
1572
1573 SF_TRUE if setting the Cart chunk was successful and SF_FALSE otherwise.
1574
1575 ## SFC_GET_LOOP_INFO
1576
1577 Retrieve loop information for file including time signature, length in beats and
1578 original MIDI base note
1579
1580 ### Parameters
1581
1582 sndfile
1583 : A valid SNDFILE* pointer
1584
1585 cmd
1586 : SFC_GET_LOOP_INFO
1587
1588 data
1589 : a pointer to an SF_LOOP_INFO struct
1590
1591 datasize
1592 : sizeof (SF_LOOP_INFO)
1593
1594 The SF_LOOP_INFO struct is defined in *sndfile.h* as:
1595
1596 ```c
1597 typedef 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 length, 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
1618 SF_LOOP_INFO loop;
1619 sf_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`
1625 otherwise.
1626
1627 ## SFC_GET_INSTRUMENT
1628
1629 Retrieve instrument information from file including MIDI base note, keyboard
1630 mapping and looping information (start/stop and mode).
1631
1632 ### Parameters
1633
1634 sndfile
1635 : A valid SNDFILE* pointer
1636
1637 cmd
1638 : SFC_GET_INSTRUMENT
1639
1640 data
1641 : a pointer to an SF_INSTRUMENT struct
1642
1643 datasize
1644 : sizeof (SF_INSTRUMENT)
1645
1646 The `SF_INSTRUMENT` struct is defined in *sndfile.h* as:
1647
1648 ```c
1649 typedef 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
1677 SF_INSTRUMENT inst ;
1678 sf_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
1688 Set the instrument information for the file.
1689
1690 ### Parameters
1691
1692 sndfile
1693 : A valid SNDFILE* pointer
1694
1695 cmd
1696 : SFC_SET_INSTRUMENT
1697
1698 data
1699 : a pointer to an SF_INSTRUMENT struct
1700
1701 datasize
1702 : sizeof (SF_INSTRUMENT)
1703
1704 ### Examples
1705
1706 ```c
1707 SF_INSTRUMENT inst ;
1708 sf_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
1718 Retrieve the number of cue markers available for retrieval using the
1719 [SFC_GET_CUE](#sfc_get_cue) command.
1720
1721 ### Parameters
1722
1723 sndfile
1724 : A valid SNDFILE* pointer
1725
1726 cmd
1727 : SFC_GET_CUE_COUNT
1728
1729 data
1730 : a pointer to a uint32_t
1731
1732 datasize
1733 : sizeof (uint32_t)
1734
1735 ### Examples
1736
1737 ```c
1738 uint32_t cue_count ;
1739 sf_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
1749 Retrieve cue marker information from file.
1750
1751 ### Parameters
1752
1753 sndfile
1754 : A valid SNDFILE* pointer
1755
1756 cmd
1757 : SFC_GET_CUE
1758
1759 data
1760 : a pointer to an SF_CUES struct
1761
1762 datasize
1763 : sizeof (SF_CUES)
1764
1765 The SF_CUES struct is defined in *sndfile.h* as:
1766
1767 ```c
1768 typedef 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
1783 There is also an SF_CUES_VAR \#define that allows reading/writing more than 100
1784 cue markers.
1785
1786 ### Examples
1787
1788 ```c
1789 SF_CUES cues ;
1790 sf_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
1800 Set the cue marker information for the file.
1801
1802 ### Parameters
1803
1804 sndfile
1805 : A valid SNDFILE* pointer
1806
1807 cmd
1808 : SFC_SET_CUE
1809
1810 data
1811 : a pointer to an SF_CUES struct
1812
1813 datasize
1814 : sizeof (SF_CUES)
1815
1816 ### Examples
1817
1818 ```c
1819 SF_CUES cues ;
1820 sf_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
1830 Enable auto downgrade from RF64 to WAV.
1831
1832 The EBU recommendation is that when writing RF64 files and the resulting file is
1833 less than 4Gig in size, it should be downgraded to a WAV file (WAV files have a
1834 maximum size of 4Gig). libsndfile doesn't follow the EBU recommendations
1835 exactly, mainly because the test suite needs to be able test reading/writing
1836 RF64 files without having to generate files larger than 4 gigabytes.
1837
1838 Note: This command should be issued before the first bit of audio data has been
1839 written to the file. Calling this command after audio data has been written will
1840 return the current value of this setting, but will not allow it to be changed.
1841
1842 ### Parameters
1843
1844 sndfile
1845 : A valid SNDFILE* pointer
1846
1847 cmd
1848 : SFC_RF64_AUTO_DOWNGRADE
1849
1850 data
1851 : NULL
1852
1853 datasize
1854 : SF_TRUE or SF_FALSE
1855
1856 ### Examples
1857
1858 ```c
1859 /* Enable auto downgrade on file close. */
1860 sf_command (sndfile, SFC_RF64_AUTO_DOWNGRADE, NULL, SF_TRUE) ;
1861 ```
1862
1863 ### Return value
1864
1865 Returns `SF_TRUE` if `SFC_RF64_AUTO_DOWNGRADE` is set and `SF_FALSE` otherwise.
1866
1867 ## SFC_GET_ORIGINAL_SAMPLERATE
1868
1869 Get original samplerate metadata.
1870
1871 The Opus audio codec stores audio data independent of samplerate, but only
1872 supports encoding or decoding at 8000Hz, 12000Hz, 16000Hz, 24000Hz or 48000Hz.
1873 Opus includes a header field to record the original source input samplerate, and
1874 a samplerate converter may be used if needed.
1875
1876 This 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
1881 sndfile
1882 : A valid SNDFILE* pointer
1883
1884 cmd
1885 : SFC_GET_ORIGINAL_SAMPLERATE
1886
1887 data
1888 : pointer to an integer
1889
1890 datasize
1891 : sizeof (int)
1892
1893 ### Examples
1894
1895 ```c
1896 /* Get the original sample rate */
1897 int original_samplerate ;
1898 sf_command (sndfile, SFC_GET_ORIGINAL_SAMPLERATE, &original_samplerate, sizeof (original_samplerate)) ;
1899 ```
1900
1901 ### Return value
1902
1903 Returns `SF_TRUE` on success, `SF_FALSE` otherwise.
1904
1905 The passed integer is set to the value of the original samplerate.
1906
1907 ## SFC_SET_ORIGINAL_SAMPLERATE
1908
1909 Set original samplerate metadata.
1910
1911 The Opus audio codec stores audio data independent of samplerate, but only
1912 supports encoding or decoding at 8000Hz, 12000Hz, 16000Hz, 24000Hz or 48000Hz.
1913 Opus includes a header field to record the original source input samplerate, and
1914 a samplerate converter may be used if needed.
1915
1916 When writing an Opus file this command sets the original samplerate header field
1917 to the provided value, which is then stored in the file. This has no effect on
1918 the current encoder samplerate.
1919
1920 When reading an Opus file this command overrides the original samplerate value
1921 as read from the file. libsndfile uses this value to choose what samplerate to
1922 decode at, rounding up to the nearest valid Opus samplerate. After a successful
1923 call, the file samplerate and frames count may have changed.
1924
1925 Note: This command should be issued before the first bit of audio data has been
1926 read from or written to the file.
1927
1928 ### Parameters
1929
1930 sndfile
1931 : A valid SNDFILE* pointer
1932
1933 cmd
1934 : SFC_SET_ORIGINAL_SAMPLERATE
1935
1936 data
1937 : pointer to an integer
1938
1939 datasize
1940 : sizeof (int)
1941
1942 ### Examples
1943
1944 ```c
1945 /* Store the original sample rate as 44100 */
1946 int original_samplerate 44100;
1947 sf_command (sndfile, SFC_SET_ORIGINAL_SAMPLERATE, &original_samplerate, sizeof (input_samplerate)) ;
1948 ```
1949
1950 ### Return value
1951
1952 Returns SF_TRUE on success, SF_FALSE otherwise.
1953
1954 On 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
1956 determine the new frames count and samplerate
1957
1958 ## SFC_GET_BITRATE_MODE
1959
1960 Get bitrate mode.
1961
1962 The 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
1972 sndfile
1973 : A valid SNDFILE* pointer
1974
1975 cmd
1976 : SFC_GET_BITRATE_MODE
1977
1978 data
1979 : NULL
1980
1981 datasize
1982 : anything
1983
1984 ### Return value
1985
1986 Returns one of `SF_BITRATE_MODE_XXX` on success, `-1` otherwise.
1987
1988 ## SFC_SET_BITRATE_MODE
1989
1990 Set bitrate mode.
1991
1992 The 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
2002 sndfile
2003 : A valid SNDFILE* pointer
2004
2005 cmd
2006 : SFC_SET_BITRATE_MODE
2007
2008 data
2009 : pointer to an integer
2010
2011 datasize
2012 : sizeof (int)
2013
2014 ### Return value
2015
2016 Returns `SF_TRUE` on success, `SF_FALSE` otherwise.