1 <!DOCTYPE HTML PUBLIC
"-//W3C//DTD HTML 4.0 Transitional//EN">
6 libsndfile : the sf_command function.
8 <META NAME=
"Author" CONTENT=
"Erik de Castro Lopo (erikd AT mega-nerd DOT com)">
9 <!-- Another version at the bottom of the page. -->
10 <META NAME=
"Description" CONTENT=
"The libsndfile API.">
11 <META NAME=
"Keywords" CONTENT=
"WAV AIFF AU libsndfile sound audio dsp Linux">
12 <LINK REL=
"stylesheet" HREF=
"libsndfile.css" TYPE=
"text/css" MEDIA=
"all">
13 <LINK REL=
"stylesheet" HREF=
"print.css" TYPE=
"text/css" MEDIA=
"print">
18 <H1><B>sf_command
</B></H1>
21 int sf_command (SNDFILE *sndfile, int cmd, void *data, int datasize) ;
24 This function allows the caller to retrieve information from or change aspects of the
26 Examples include retrieving a string containing the library version or changing the
27 scaling applied to floating point sample data during read and write.
28 Most of these operations are performed on a per-file basis.
31 The cmd parameter is an integer identifier which is defined in
<sndfile.h
>.
32 All of the valid command identifiers have names beginning with
"SFC_".
33 Data is passed to and returned from the library by use of a void pointer.
34 The library will not read or write more than datasize bytes from the void pointer.
35 For some calls no data is required in which case data should be NULL and datasize
36 may be used for some other purpose.
39 The available commands are as follows:
43 <TABLE BORDER=
"0" WIDTH=
"90%" CELLPADDING=
"4">
45 <TD><A HREF=
"#SFC_GET_LIB_VERSION">SFC_GET_LIB_VERSION
</A></TD>
46 <TD>Retrieve the version of the library.
</TD>
49 <TD><A HREF=
"#SFC_GET_LOG_INFO">SFC_GET_LOG_INFO
</A></TD>
50 <TD>Retrieve the internal per-file operation log.
</TD>
53 <TD><A HREF=
"#SFC_CALC_SIGNAL_MAX">SFC_CALC_SIGNAL_MAX
</A></TD>
54 <TD>Calculate the measured maximum signal value.
</TD>
57 <TD><A HREF=
"#SFC_CALC_NORM_SIGNAL_MAX">SFC_CALC_NORM_SIGNAL_MAX
</A></TD>
58 <TD>Calculate the measured normalised maximum signal value.
</TD>
61 <TD><A HREF=
"#SFC_CALC_MAX_ALL_CHANNELS">SFC_CALC_MAX_ALL_CHANNELS
</A></TD>
62 <TD>Calculate the peak value for each channel.
</TD>
65 <TD><A HREF=
"#SFC_CALC_NORM_MAX_ALL_CHANNELS">SFC_CALC_NORM_MAX_ALL_CHANNELS
</A></TD>
66 <TD>Calculate the normalised peak for each channel.
</TD>
70 <TD><A HREF=
"#SFC_GET_SIGNAL_MAX">SFC_GET_SIGNAL_MAX
</A></TD>
71 <TD>Retrieve the peak value for the file (as stored in the file header).
</TD>
74 <TD><A HREF=
"#SFC_GET_MAX_ALL_CHANNELS">SFC_GET_MAX_ALL_CHANNELS
</A></TD>
75 <TD>Retrieve the peak value for each channel (as stored in the file header).
</TD>
79 <TD><A HREF=
"#SFC_SET_NORM_FLOAT">SFC_SET_NORM_FLOAT
</A></TD>
80 <TD>Modify the normalisation behaviour of the floating point reading and writing functions.
</TD>
83 <TD><A HREF=
"#SFC_SET_NORM_DOUBLE">SFC_SET_NORM_DOUBLE
</A></TD>
84 <TD>Modify the normalisation behaviour of the double precision floating point reading and writing functions.
</TD>
87 <TD><A HREF=
"#SFC_GET_NORM_FLOAT">SFC_GET_NORM_FLOAT
</A></TD>
88 <TD>Retrieve the current normalisation behaviour of the floating point reading and writing functions.
</TD>
91 <TD><A HREF=
"#SFC_GET_NORM_DOUBLE">SFC_GET_NORM_DOUBLE
</A></TD>
92 <TD>Retrieve the current normalisation behaviour of the double precision floating point reading and writing functions.
</TD>
95 <TD><A HREF=
"#SFC_SET_SCALE_FLOAT_INT_READ">SFC_SET_SCALE_FLOAT_INT_READ
</A></TD>
96 <TD>Set/clear the scale factor when integer (short/int) data is read from a file
97 containing floating point data.
</TD>
101 <TD><A HREF=
"#SFC_SET_SCALE_INT_FLOAT_WRITE">SFC_SET_SCALE_INT_FLOAT_WRITE
</A></TD>
102 <TD>Set/clear the scale factor when integer (short/int) data is written to a file
103 as floating point data.
</TD>
107 <TD><A HREF=
"#SFC_GET_SIMPLE_FORMAT_COUNT">SFC_GET_SIMPLE_FORMAT_COUNT
</A></TD>
108 <TD>Retrieve the number of simple formats supported by libsndfile.
</TD>
111 <TD><A HREF=
"#SFC_GET_SIMPLE_FORMAT">SFC_GET_SIMPLE_FORMAT
</A></TD>
112 <TD>Retrieve information about a simple format.
</TD>
116 <TD><A HREF=
"#SFC_GET_FORMAT_INFO">SFC_GET_FORMAT_INFO
</A></TD>
117 <TD>Retrieve information about a major or subtype format.
</TD>
121 <TD><A HREF=
"#SFC_GET_FORMAT_MAJOR_COUNT">SFC_GET_FORMAT_MAJOR_COUNT
</A></TD>
122 <TD>Retrieve the number of major formats.
</TD>
125 <TD><A HREF=
"#SFC_GET_FORMAT_MAJOR">SFC_GET_FORMAT_MAJOR
</A></TD>
126 <TD>Retrieve information about a major format type.
</TD>
129 <TD><A HREF=
"#SFC_GET_FORMAT_SUBTYPE_COUNT">SFC_GET_FORMAT_SUBTYPE_COUNT
</A></TD>
130 <TD>Retrieve the number of subformats.
</TD>
133 <TD><A HREF=
"#SFC_GET_FORMAT_SUBTYPE">SFC_GET_FORMAT_SUBTYPE
</A></TD>
134 <TD>Retrieve information about a subformat.
</TD>
138 <TD><A HREF=
"#SFC_SET_ADD_PEAK_CHUNK">SFC_SET_ADD_PEAK_CHUNK
</A></TD>
139 <TD>Switch the code for adding the PEAK chunk to WAV and AIFF files on or off.
</TD>
143 <TD><A HREF=
"#SFC_UPDATE_HEADER_NOW">SFC_UPDATE_HEADER_NOW
</A></TD>
144 <TD>Used when a file is open for write, this command will update the file
145 header to reflect the data written so far.
</TD>
148 <TD><A HREF=
"#SFC_SET_UPDATE_HEADER_AUTO">SFC_SET_UPDATE_HEADER_AUTO
</A></TD>
149 <TD>Used when a file is open for write, this command will cause the file header
150 to be updated after each write to the file.
</TD>
154 <TD><A HREF=
"#SFC_FILE_TRUNCATE">SFC_FILE_TRUNCATE
</A></TD>
155 <TD>Truncate a file open for write or for read/write.
</TD>
159 <TD><A HREF=
"#SFC_SET_RAW_START_OFFSET">SFC_SET_RAW_START_OFFSET
</A></TD>
160 <TD>Change the data start offset for files opened up as SF_FORMAT_RAW.
</TD>
164 <TD><A HREF=
"#SFC_SET_CLIPPING">SFC_SET_CLIPPING
</A></TD>
165 <TD>Turn on/off automatic clipping when doing floating point to integer
170 <TD><A HREF=
"#SFC_GET_CLIPPING">SFC_GET_CLIPPING
</A></TD>
171 <TD>Retrieve current clipping setting.
</TD>
175 <TD><A HREF=
"#SFC_GET_EMBED_FILE_INFO">SFC_GET_EMBED_FILE_INFO
</A></TD>
176 <TD>Retrieve information about audio files embedded inside other files.
</TD>
180 <TD><A HREF=
"#SFC_WAVEX_GET_AMBISONIC">SFC_GET_AMBISONIC
</A></TD>
181 <TD>Test a WAVEX file for Ambisonic format
</TD>
185 <TD><A HREF=
"#SFC_WAVEX_SET_AMBISONIC">SFC_SET_AMBISONIC
</A></TD>
186 <TD>Modify a WAVEX header for Ambisonic format
</TD>
190 <TD><A HREF=
"#SFC_SET_VBR_ENCODING_QUALITY">SFC_SET_VBR_ENCODING_QUALITY
</A></TD>
191 <TD>Set the the Variable Bit Rate encoding quality
</TD>
195 <TD><A HREF=
"#SFC_RAW_NEEDS_ENDSWAP">SFC_RAW_NEEDS_ENDSWAP
</a></td>
196 <TD>Determine if raw data needs endswapping
</TD>
200 <TD><A HREF=
"#SFC_GET_BROADCAST_INFO">SFC_GET_BROADCAST_INFO
</A></TD>
201 <TD>Retrieve the Broadcast Chunk info
</TD>
205 <TD><A HREF=
"#SFC_SET_BROADCAST_INFO">SFC_SET_BROADCAST_INFO
</A></TD>
206 <TD>Set the Broadcast Chunk info
</TD>
210 <TD><A HREF=
"#SFC_GET_LOOP_INFO">SFC_GET_LOOP_INFO
</A></TD>
211 <TD>Get loop info
</TD>
215 <TD><A HREF=
"#SFC_GET_INSTRUMENT">SFC_GET_INSTRUMENT
</A></TD>
216 <TD>Get instrument info
</TD>
220 <TD><A HREF=
"#SFC_SET_INSTRUMENT">SFC_SET_INSTRUMENT
</A></TD>
221 <TD>Set instrument info
</TD>
225 <TD><A HREF=
"#SFC_SET_VBR_ENCODING_QUALITY">SFC_SET_VBR_ENCODING_QUALITY
</A></TD>
226 <TD>Set variable bit rate encoding quality
</TD>
233 <TD><A HREF="#add-dither">add dither</A></TD>
234 <TD>Add dither to output on write.</TD>
244 <!-- ========================================================================= -->
245 <A NAME=
"SFC_GET_LIB_VERSION"></A>
246 <H2><BR><B>SFC_GET_LIB_VERSION
</B></H2>
248 Retrieve the version of the library as a string.
254 cmd : SFC_GET_LIB_VERSION
255 data : A pointer to a char buffer
256 datasize : The size of the the buffer
263 sf_command (NULL, SFC_GET_LIB_VERSION, buffer, sizeof (buffer)) ;
267 <DT>Return value:
</DT>
268 <DD><DD>This call will return the length of the retrieved version string.
273 The string returned in the buffer passed to this function will not overflow
274 the buffer and will always be null terminated .
277 <!-- ========================================================================= -->
278 <A NAME=
"SFC_GET_LOG_INFO"></A>
279 <H2><BR><B>SFC_GET_LOG_INFO
</B></H2>
281 Retrieve the log buffer generated when opening a file as a string. This log
282 buffer can often contain a good reason for why libsndfile failed to open a
288 sndfile : A valid SNDFILE* pointer
289 cmd : SFC_GET_LOG_INFO
290 data : A pointer to a char buffer
291 datasize : The size of the the buffer
298 sf_command (sndfile, SFC_GET_LOG_INFO, buffer, sizeof (buffer)) ;
302 <DT>Return value:
</DT>
303 <DD><DD>This call will return the length of the retrieved version string.
308 The string returned in the buffer passed to this function will not overflow
309 the buffer and will always be null terminated .
312 <!-- ========================================================================= -->
313 <A NAME=
"SFC_CALC_SIGNAL_MAX"></A>
314 <H2><BR><B>SFC_CALC_SIGNAL_MAX
</B></H2>
316 Retrieve the measured maximum signal value. This involves reading through
317 the whole file which can be slow on large files.
322 sndfile : A valid SNDFILE* pointer
323 cmd : SFC_CALC_SIGNAL_MAX
324 data : A pointer to a double
325 datasize : sizeof (double)
332 sf_command (sndfile, SFC_CALC_SIGNAL_MAX,
&max_val, sizeof (max_val)) ;
336 <DT>Return value:
</DT>
337 <DD><DD>Zero on success, non-zero otherwise.
340 <!-- ========================================================================= -->
341 <A NAME=
"SFC_CALC_NORM_SIGNAL_MAX"></A>
342 <H2><BR><B>SFC_CALC_NORM_SIGNAL_MAX
</B></H2>
344 Retrieve the measured normalised maximum signal value. This involves reading
345 through the whole file which can be slow on large files.
350 sndfile : A valid SNDFILE* pointer
351 cmd : SFC_CALC_NORM_SIGNAL_MAX
352 data : A pointer to a double
353 datasize : sizeof (double)
360 sf_command (sndfile, SFC_CALC_NORM_SIGNAL_MAX,
&max_val, sizeof (max_val)) ;
364 <DT>Return value:
</DT>
365 <DD><DD>Zero on success, non-zero otherwise.
368 <!-- ========================================================================= -->
369 <A NAME=
"SFC_CALC_MAX_ALL_CHANNELS"></A>
370 <H2><BR><B>SFC_CALC_MAX_ALL_CHANNELS
</B></H2>
372 Calculate the peak value (ie a single number) for each channel.
373 This involves reading through the whole file which can be slow on large files.
378 sndfile : A valid SNDFILE* pointer
379 cmd : SFC_CALC_MAX_ALL_CHANNELS
380 data : A pointer to a double
381 datasize : sizeof (double) * number_of_channels
387 double peaks [number_of_channels] ;
388 sf_command (sndfile, SFC_CALC_MAX_ALL_CHANNELS, peaks, sizeof (peaks)) ;
391 <DT>Return value:
</DT>
392 <DD>Zero if peaks have been calculated successfully and non-zero otherwise.
396 <!-- ========================================================================= -->
397 <A NAME=
"SFC_CALC_NORM_MAX_ALL_CHANNELS"></A>
398 <H2><BR><B>SFC_CALC_NORM_MAX_ALL_CHANNELS
</B></H2>
400 Calculate the normalised peak for each channel.
401 This involves reading through the whole file which can be slow on large files.
406 sndfile : A valid SNDFILE* pointer
407 cmd : SFC_CALC_NORM_MAX_ALL_CHANNELS
408 data : A pointer to a double
409 datasize : sizeof (double) * number_of_channels
415 double peaks [number_of_channels] ;
416 sf_command (sndfile, SFC_CALC_NORM_MAX_ALL_CHANNELS, peaks, sizeof (peaks)) ;
419 <DT>Return value:
</DT>
420 <DD>Zero if peaks have been calculated successfully and non-zero otherwise.
426 <!-- ========================================================================= -->
427 <A NAME=
"SFC_GET_SIGNAL_MAX"></A>
428 <H2><BR><B>SFC_GET_SIGNAL_MAX
</B></H2>
430 Retrieve the peak value for the file as stored in the file header.
435 sndfile : A valid SNDFILE* pointer
436 cmd : SFC_GET_SIGNAL_MAX
437 data : A pointer to a double
438 datasize : sizeof (double)
445 sf_command (sndfile, SFC_GET_SIGNAL_MAX,
&max_peak, sizeof (max_peak)) ;
448 <DT>Return value:
</DT>
449 <DD>SF_TRUE if the file header contained the peak value. SF_FALSE otherwise.
452 <!-- ========================================================================= -->
453 <A NAME=
"SFC_GET_MAX_ALL_CHANNELS"></A>
454 <H2><BR><B>SFC_GET_MAX_ALL_CHANNELS
</B></H2>
456 Retrieve the peak value for the file as stored in the file header.
461 sndfile : A valid SNDFILE* pointer
462 cmd : SFC_GET_SIGNAL_MAX
463 data : A pointer to an array of doubles
464 datasize : sizeof (double) * number_of_channels
470 double peaks [number_of_channels] ;
471 sf_command (sndfile, SFC_GET_MAX_ALL_CHANNELS, peaks, sizeof (peaks)) ;
474 <DT>Return value:
</DT>
475 <DD>SF_TRUE if the file header contains per channel peak values for the file.
480 <!-- ========================================================================= -->
481 <A NAME=
"SFC_SET_NORM_FLOAT"></A>
482 <H2><BR><B>SFC_SET_NORM_FLOAT
</B></H2>
484 This command only affects data read from or written to using the floating point functions:
487 size_t
<A HREF=
"api.html#read">sf_read_float
</A> (SNDFILE *sndfile, float *ptr, size_t items) ;
488 size_t
<A HREF=
"api.html#readf">sf_readf_float
</A> (SNDFILE *sndfile, float *ptr, size_t frames) ;
490 size_t
<A HREF=
"api.html#write">sf_write_float
</A> (SNDFILE *sndfile, float *ptr, size_t items) ;
491 size_t
<A HREF=
"api.html#writef">sf_writef_float
</A> (SNDFILE *sndfile, float *ptr, size_t frames) ;
497 sndfile : A valid SNDFILE* pointer
498 cmd : SFC_SET_NORM_FLOAT
500 datasize : SF_TRUE or SF_FALSE
503 For read operations setting normalisation to SF_TRUE means that the data from all
504 subsequent reads will be be normalised to the range [-
1.0,
1.0].
507 For write operations, setting normalisation to SF_TRUE means than all data supplied
508 to the float write functions should be in the range [-
1.0,
1.0] and will be scaled
509 for the file format as necessary.
512 For both cases, setting normalisation to SF_FALSE means that no scaling will take place.
518 sf_command (sndfile, SFC_SET_NORM_FLOAT, NULL, SF_TRUE) ;
520 sf_command (sndfile, SFC_SET_NORM_FLOAT, NULL, SF_FALSE) ;
523 <DT>Return value:
</DT>
524 <DD>Returns the previous float normalisation mode.
527 <!-- ========================================================================= -->
528 <A NAME=
"SFC_SET_NORM_DOUBLE"></A>
529 <H2><BR><B>SFC_SET_NORM_DOUBLE
</B></H2>
531 This command only affects data read from or written to using the double precision
532 floating point functions:
535 size_t
<A HREF=
"api.html#read">sf_read_double
</A> (SNDFILE *sndfile, double *ptr, size_t items) ;
536 size_t
<A HREF=
"api.html#readf">sf_readf_double
</A> (SNDFILE *sndfile, double *ptr, size_t frames) ;
538 size_t
<A HREF=
"api.html#write">sf_write_double
</A> (SNDFILE *sndfile, double *ptr, size_t items) ;
539 size_t
<A HREF=
"api.html#writef">sf_writef_double
</A> (SNDFILE *sndfile, double *ptr, size_t frames) ;
545 sndfile : A valid SNDFILE* pointer
546 cmd : SFC_SET_NORM_DOUBLE
548 datasize : SF_TRUE or SF_FALSE
551 For read operations setting normalisation to SF_TRUE means that the data
552 from all subsequent reads will be be normalised to the range [-
1.0,
1.0].
555 For write operations, setting normalisation to SF_TRUE means than all data supplied
556 to the double write functions should be in the range [-
1.0,
1.0] and will be scaled
557 for the file format as necessary.
560 For both cases, setting normalisation to SF_FALSE means that no scaling will take place.
566 sf_command (sndfile, SFC_SET_NORM_DOUBLE, NULL, SF_TRUE) ;
568 sf_command (sndfile, SFC_SET_NORM_DOUBLE, NULL, SF_FALSE) ;
571 <DT>Return value:
</DT>
572 <DD>Returns the previous double normalisation mode.
575 <!-- ========================================================================= -->
576 <A NAME=
"SFC_GET_NORM_FLOAT"></A>
577 <H2><BR><B>SFC_GET_NORM_FLOAT
</B></H2>
579 Retrieve the current float normalisation mode.
585 sndfile : A valid SNDFILE* pointer
586 cmd : SFC_GET_NORM_FLOAT
594 normalisation = sf_command (sndfile, SFC_GET_NORM_FLOAT, NULL,
0) ;
597 <DT>Return value:
</DT>
598 <DD>Returns TRUE if normalisation is on and FALSE otherwise.
601 <!-- ========================================================================= -->
602 <A NAME=
"SFC_GET_NORM_DOUBLE"></A>
603 <H2><BR><B>SFC_GET_NORM_DOUBLE
</B></H2>
605 Retrieve the current float normalisation mode.
611 sndfile : A valid SNDFILE* pointer
612 cmd : SFC_GET_NORM_DOUBLE
620 normalisation = sf_command (sndfile, SFC_GET_NORM_DOUBLE, NULL,
0) ;
623 <DT>Return value:
</DT>
624 <DD>Returns TRUE if normalisation is on and FALSE otherwise.
628 <!-- ========================================================================= -->
629 <A NAME=
"SFC_SET_SCALE_FLOAT_INT_READ"></A>
630 <H2><BR><B>SFC_SET_SCALE_FLOAT_INT_READ
</B></H2>
632 Set/clear the scale factor when integer (short/int) data is read from a file
633 containing floating point data.
639 sndfile : A valid SNDFILE* pointer
640 cmd : SFC_SET_SCALE_FLOAT_INT_READ
642 datasize : TRUE or FALSE
648 sf_command (sndfile, SFC_SET_SCALE_FLOAT_INT_READ, NULL, SF_TRUE) ;
651 <DT>Return value:
</DT>
652 <DD>Returns the previous SFC_SET_SCALE_FLOAT_INT_READ setting for this file.
656 <!-- ========================================================================= -->
657 <A NAME=
"SFC_SET_SCALE_INT_FLOAT_WRITE"></A>
658 <H2><BR><B>SFC_SET_SCALE_INT_FLOAT_WRITE
</B></H2>
660 Set/clear the scale factor when integer (short/int) data is written to a file
661 as floating point data.
667 sndfile : A valid SNDFILE* pointer
668 cmd : SFC_SET_SCALE_FLOAT_INT_READ
670 datasize : TRUE or FALSE
676 sf_command (sndfile, SFC_SET_SCALE_INT_FLOAT_WRITE, NULL, SF_TRUE) ;
679 <DT>Return value:
</DT>
680 <DD>Returns the previous SFC_SET_SCALE_INT_FLOAT_WRITE setting for this file.
683 <!-- ========================================================================= -->
684 <A NAME=
"SFC_GET_SIMPLE_FORMAT_COUNT"></A>
685 <H2><BR><B>SFC_GET_SIMPLE_FORMAT_COUNT
</B></H2>
687 Retrieve the number of simple formats supported by libsndfile.
694 cmd : SFC_GET_SIMPLE_FORMAT_COUNT
695 data : a pointer to an int
696 datasize : sizeof (int)
703 sf_command (sndfile, SFC_GET_SIMPLE_FORMAT_COUNT,
&count, sizeof (int)) ;
706 <DT>Return value:
</DT>
710 <!-- ========================================================================= -->
711 <A NAME=
"SFC_GET_SIMPLE_FORMAT"></A>
712 <H2><BR><B>SFC_GET_SIMPLE_FORMAT
</B></H2>
714 Retrieve information about a simple format.
721 cmd : SFC_GET_SIMPLE_FORMAT
722 data : a pointer to an SF_FORMAT_INFO struct
723 datasize : sizeof (SF_FORMAT_INFO)
726 The SF_FORMAT_INFO struct is defined in
<sndfile.h
> as:
732 const char *extension ;
736 When sf_command() is called with SF_GET_SIMPLE_FORMAT, the value of the format
737 field should be the format number (ie
0 <= format
<= count value obtained using
738 SF_GET_SIMPLE_FORMAT_COUNT).
744 SF_FORMAT_INFO format_info ;
747 sf_command (sndfile, SFC_GET_SIMPLE_FORMAT_COUNT,
&count, sizeof (int)) ;
749 for (k =
0 ; k
< count ; k++)
750 { format_info.format = k ;
751 sf_command (sndfile, SFC_GET_SIMPLE_FORMAT,
&format_info, sizeof (format_info)) ;
752 printf (
"%08x %s %s\n", format_info.format, format_info.name, format_info.extension) ;
756 <DT>Return value:
</DT>
757 <DD>0 on success and non-zero otherwise.
758 <DD>The value of the format field of the SF_FORMAT_INFO struct will be a value which
759 can be placed in the format field of an SF_INFO struct when a file is to be opened
761 <DD>The name field will contain a char* pointer to the name of the string, eg.
"WAV (Microsoft 16 bit PCM)".
762 <DD>The extension field will contain the most commonly used file extension for that file type.
765 <!-- ========================================================================= -->
766 <A NAME=
"SFC_GET_FORMAT_INFO"></A>
767 <H2><BR><B>SFC_GET_FORMAT_INFO
</B></H2>
769 Retrieve information about a major or subtype format.
776 cmd : SFC_GET_FORMAT_INFO
777 data : a pointer to an SF_FORMAT_INFO struct
778 datasize : sizeof (SF_FORMAT_INFO)
781 The SF_FORMAT_INFO struct is defined in
<sndfile.h
> as:
787 const char *extension ;
791 When sf_command() is called with SF_GET_FORMAT_INFO, the format field is
792 examined and if (format
& SF_FORMAT_TYPEMASK) is a valid format then the struct
793 is filled in with information about the given major type.
794 If (format
& SF_FORMAT_TYPEMASK) is FALSE and (format
& SF_FORMAT_SUBMASK) is a
795 valid subtype format then the struct is filled in with information about the given
802 SF_FORMAT_INFO format_info ;
804 format_info.format = SF_FORMAT_WAV ;
805 sf_command (sndfile, SFC_GET_FORMAT_INFO,
&format_info, sizeof (format_info)) ;
806 printf (
"%08x %s %s\n", format_info.format, format_info.name, format_info.extension) ;
808 format_info.format = SF_FORMAT_ULAW ;
809 sf_command (sndfile, SFC_GET_FORMAT_INFO,
&format_info, sizeof (format_info)) ;
810 printf (
"%08x %s\n", format_info.format, format_info.name) ;
813 <DT>Return value:
</DT>
814 <DD>0 on success and non-zero otherwise.
816 <!-- ========================================================================= -->
817 <A NAME=
"SFC_GET_FORMAT_MAJOR_COUNT"></A>
818 <H2><BR><B>SFC_GET_FORMAT_MAJOR_COUNT
</B></H2>
820 Retrieve the number of major formats.
827 cmd : SFC_GET_FORMAT_MAJOR_COUNT
828 data : a pointer to an int
829 datasize : sizeof (int)
836 sf_command (sndfile, SFC_GET_FORMAT_MAJOR_COUNT,
&count, sizeof (int)) ;
839 <DT>Return value:
</DT>
843 <!-- ========================================================================= -->
844 <A NAME=
"SFC_GET_FORMAT_MAJOR"></A>
845 <H2><BR><B>SFC_GET_FORMAT_MAJOR
</B></H2>
847 Retrieve information about a major format type.
854 cmd : SFC_GET_FORMAT_MAJOR
855 data : a pointer to an SF_FORMAT_INFO struct
856 datasize : sizeof (SF_FORMAT_INFO)
862 SF_FORMAT_INFO format_info ;
865 sf_command (sndfile, SFC_GET_FORMAT_MAJOR_COUNT,
&count, sizeof (int)) ;
867 for (k =
0 ; k
< count ; k++)
868 { format_info.format = k ;
869 sf_command (sndfile, SFC_GET_FORMAT_MAJOR,
&format_info, sizeof (format_info)) ;
870 printf (
"%08x %s %s\n", format_info.format, format_info.name, format_info.extension) ;
874 For a more comprehensive example, see the program list_formats.c in the examples/
875 directory of the libsndfile source code distribution.
878 <DT>Return value:
</DT>
879 <DD>0 on success and non-zero otherwise.
880 <DD>The value of the format field will be one of the major format identifiers such as
881 SF_FORMAT_WAV or SF_FORMAT_AIFF.
882 <DD>The name field will contain a char* pointer to the name of the string, eg.
"WAV (Microsoft)".
883 <DD>The extension field will contain the most commonly used file extension for that file type.
886 <!-- ========================================================================= -->
887 <A NAME=
"SFC_GET_FORMAT_SUBTYPE_COUNT"></A>
888 <H2><BR><B>SFC_GET_FORMAT_SUBTYPE_COUNT
</B></H2>
890 Retrieve the number of subformats.
897 cmd : SFC_GET_FORMAT_SUBTYPE_COUNT
898 data : a pointer to an int
899 datasize : sizeof (int)
906 sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE_COUNT,
&count, sizeof (int)) ;
909 <DT>Return value:
</DT>
913 <!-- ========================================================================= -->
914 <A NAME=
"SFC_GET_FORMAT_SUBTYPE"></A>
915 <H2><BR><B>SFC_GET_FORMAT_SUBTYPE
</B></H2>
917 Enumerate the subtypes (this function does not translate a subtype into
918 a string describing that subtype).
919 A typical use case might be retrieving a string description of all subtypes
920 so that a dialog box can be filled in.
930 cmd : SFC_GET_FORMAT_SUBTYPE
931 data : a pointer to an SF_FORMAT_INFO struct
932 datasize : sizeof (SF_FORMAT_INFO)
935 Example
1: Retrieve all sybtypes supported by the WAV format.
938 SF_FORMAT_INFO format_info ;
941 sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE_COUNT,
&count, sizeof (int)) ;
943 for (k =
0 ; k
< count ; k++)
944 { format_info.format = k ;
945 sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE,
&format_info, sizeof (format_info)) ;
946 if (! sf_format_check (format_info.format | SF_FORMAT_WAV))
948 printf (
"%08x %s\n", format_info.format, format_info.name) ;
952 Example
2: Print a string describing the SF_FORMAT_PCM_16 subtype.
955 SF_FORMAT_INFO format_info ;
958 sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE_COUNT,
&count, sizeof (int)) ;
960 for (k =
0 ; k
< count ; k++)
961 { format_info.format = k ;
962 sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE,
&format_info, sizeof (format_info)) ;
963 if (format_info.format == SF_FORMAT_PCM_16)
964 { printf (
"%08x %s\n", format_info.format, format_info.name) ;
970 For a more comprehensive example, see the program list_formats.c in the examples/
971 directory of the libsndfile source code distribution.
974 <DT>Return value:
</DT>
975 <DD>0 on success and non-zero otherwise.
976 <DD>The value of the format field will be one of the major format identifiers such as
977 SF_FORMAT_WAV or SF_FORMAT_AIFF.
978 <DD>The name field will contain a char* pointer to the name of the string; for instance
979 "WAV (Microsoft)" or
"AIFF (Apple/SGI)".
980 <DD>The extension field will be a NULL pointer.
983 <!-- ========================================================================= -->
984 <A NAME=
"SFC_SET_ADD_PEAK_CHUNK"></A>
985 <H2><BR><B>SFC_SET_ADD_PEAK_CHUNK
</B></H2>
987 By default, WAV and AIFF files which contain floating point data (subtype SF_FORMAT_FLOAT
988 or SF_FORMAT_DOUBLE) have a PEAK chunk.
989 By using this command, the addition of a PEAK chunk can be turned on or off.
992 Note : This call must be made before any data is written to the file.
997 sndfile : A valid SNDFILE* pointer
998 cmd : SFC_SET_ADD_PEAK_CHUNK
999 data : Not used (should be NULL)
1000 datasize : TRUE or FALSE.
1006 /* Turn on the PEAK chunk. */
1007 sf_command (sndfile, SFC_SET_ADD_PEAK_CHUNK, NULL, SF_TRUE) ;
1009 /* Turn off the PEAK chunk. */
1010 sf_command (sndfile, SFC_SET_ADD_PEAK_CHUNK, NULL, SF_FALSE) ;
1013 <DT>Return value:
</DT>
1014 <DD>Returns SF_TRUE if the peak chunk will be written after this call.
1015 <DD>Returns SF_FALSE if the peak chunk will not be written after this call.
1018 <!-- ========================================================================= -->
1019 <A NAME=
"SFC_UPDATE_HEADER_NOW"></A>
1020 <H2><BR><B>SFC_UPDATE_HEADER_NOW
</B></H2>
1022 The header of an audio file is normally written by libsndfile when the file is
1023 closed using
<B>sf_close()
</B>.
1026 There are however situations where large files are being generated and it would
1027 be nice to have valid data in the header before the file is complete.
1028 Using this command will update the file header to reflect the amount of data written
1030 Other programs opening the file for read (before any more data is written) will
1031 then read a valid sound file header.
1036 sndfile : A valid SNDFILE* pointer
1037 cmd : SFC_UPDATE_HEADER_NOW
1038 data : Not used (should be NULL)
1039 datasize : Not used.
1045 /* Update the header now. */
1046 sf_command (sndfile, SFC_UPDATE_HEADER_NOW, NULL,
0) ;
1049 <DT>Return value:
</DT>
1053 <!-- ========================================================================= -->
1054 <A NAME=
"SFC_SET_UPDATE_HEADER_AUTO"></A>
1055 <H2><BR><B>SFC_SET_UPDATE_HEADER_AUTO
</B></H2>
1057 Similar to SFC_UPDATE_HEADER_NOW but updates the header at the end of every call
1058 to the
<B>sf_write*
</B> functions.
1063 sndfile : A valid SNDFILE* pointer
1064 cmd : SFC_UPDATE_HEADER_NOW
1065 data : Not used (should be NULL)
1066 datasize : SF_TRUE or SF_FALSE
1072 /* Turn on auto header update. */
1073 sf_command (sndfile, SFC_SET_UPDATE_HEADER_AUTO, NULL, SF_TRUE) ;
1075 /* Turn off auto header update. */
1076 sf_command (sndfile, SFC_SET_UPDATE_HEADER_AUTO, NULL, SF_FALSE) ;
1079 <DT>Return value:
</DT>
1080 <DD>TRUE if auto update header is now on; FALSE otherwise.
1083 <!-- ========================================================================= -->
1084 <A NAME=
"SFC_FILE_TRUNCATE"></A>
1085 <H2><BR><B>SFC_FILE_TRUNCATE
</B></H2>
1087 Truncate a file that was opened for write or read/write.
1092 sndfile : A valid SNDFILE* pointer
1093 cmd : SFC_FILE_TRUNCATE
1094 data : A pointer to an sf_count_t.
1095 datasize : sizeof (sf_count_t)
1099 Truncate the file to the number of frames specified by the sf_count_t pointed
1101 After this command, both the read and the write pointer will be
1102 at the new end of the file.
1103 This command will fail (returning non-zero) if the requested truncate position
1104 is beyond the end of the file.
1110 /* Truncate the file to a length of
20 frames. */
1111 sf_count_t frames =
20 ;
1112 sf_command (sndfile, SFC_FILE_TRUNCATE,
&frames, sizeof (frames)) ;
1115 <DT>Return value:
</DT>
1116 <DD>Zero on sucess, non-zero otherwise.
1119 <!-- ========================================================================= -->
1120 <A NAME=
"SFC_SET_RAW_START_OFFSET"></A>
1121 <H2><BR><B>SFC_SET_RAW_START_OFFSET
</B></H2>
1123 Change the data start offset for files opened up as SF_FORMAT_RAW.
1128 sndfile : A valid SNDFILE* pointer
1129 cmd : SFC_SET_RAW_START_OFFSET
1130 data : A pointer to an sf_count_t.
1131 datasize : sizeof (sf_count_t)
1135 For a file opened as format SF_FORMAT_RAW, set the data offset to the value
1142 /* Reset the data offset to
5 bytes from the start of the file. */
1143 sf_count_t offset =
5 ;
1144 sf_command (sndfile, SFC_SET_RAW_START_OFFSET,
&offset, sizeof (offset)) ;
1147 <DT>Return value:
</DT>
1148 <DD>Zero on success, non-zero otherwise.
1151 <!-- ========================================================================= -->
1152 <A NAME=
"SFC_SET_CLIPPING"></A>
1153 <H2><BR><B>SFC_SET_CLIPPING
</B></H2>
1155 Turn on/off automatic clipping when doing floating point to integer conversion.
1160 sndfile : A valid SNDFILE* pointer
1161 cmd : SFC_SET_CLIPPING
1163 datasize : SF_TRUE or SF_FALSE.
1167 Turn on (datasize == SF_TRUE) or off (datasize == SF_FALSE) clipping.
1173 sf_command (sndfile, SFC_SET_CLIPPING, NULL, SF_TRUE) ;
1176 <DT>Return value:
</DT>
1177 <DD>Clipping mode (SF_TRUE or SF_FALSE).
1181 <!-- ========================================================================= -->
1182 <A NAME=
"SFC_GET_CLIPPING"></A>
1183 <H2><BR><B>SFC_GET_CLIPPING
</B></H2>
1185 Turn on/off automatic clipping when doing floating point to integer conversion.
1190 sndfile : A valid SNDFILE* pointer
1191 cmd : SFC_GET_CLIPPING
1197 Retrieve the current cliiping setting.
1203 sf_command (sndfile, SFC_GET_CLIPPING, NULL,
0) ;
1206 <DT>Return value:
</DT>
1207 <DD>Clipping mode (SF_TRUE or SF_FALSE).
1210 <!-- ========================================================================= -->
1211 <A NAME=
"SFC_GET_EMBED_FILE_INFO"></A>
1212 <H2><BR><B>SFC_GET_EMBED_FILE_INFO
</B></H2>
1214 Get the file offset and file length of a file enbedded within another
1220 sndfile : A valid SNDFILE* pointer
1221 cmd : SFC_GET_CLIPPING
1222 data : a pointer to an SF_EMBED_FILE_INFO struct
1223 datasize : sizeof (SF_EMBED_FILE_INFO)
1226 The SF_EMBED_FILE_INFO struct is defined in
<sndfile.h
> as:
1230 { sf_count_t offset ;
1232 } SF_EMBED_FILE_INFO ;
1235 <DT>Return value:
</DT>
1236 <DD>0 on success and non-zero otherwise.
1237 <DD>The value of the offset field of the SF_EMBED_FILE_INFO struct will be
1238 the offsets in bytes from the start of the outer file to the start of
1240 <DD>The value of the offset field of the SF_EMBED_FILE_INFO struct will be
1241 the length in bytes of the embedded file.
1246 <!-- ========================================================================= -->
1247 <A NAME=
"SFC_WAVEX_GET_AMBISONIC"></A>
1248 <H2><BR><B>SFC_WAVEX_GET_AMBISONIC
</B></H2>
1250 Test if the current file has the GUID of a WAVEX file for any of the Ambisonic
1256 sndfile : A valid SNDFILE* pointer
1257 cmd : SFC_WAVEX_GET_AMBISONIC
1262 The Ambisonic WAVEX formats are defined here :
1263 <A HREF=
"http://dream.cs.bath.ac.uk/researchdev/wave-ex/bformat.html">
1264 http://dream.cs.bath.ac.uk/researchdev/wave-ex/bformat.html
</A>.
1267 <DT>Return value:
</DT>
1268 <DD>SF_AMBISONIC_NONE or SF_AMBISONIC_B_FORMAT or zero if the file format
1269 does not support ambisonic formats.
1272 <!-- ========================================================================= -->
1273 <A NAME=
"SFC_WAVEX_SET_AMBISONIC"></A>
1274 <H2><BR><B>SFC_WAVEX_SET_AMBISONIC
</B></H2>
1276 Set the GUID of a new WAVEX file to indicate an Ambisonics format.
1281 sndfile : A valid SNDFILE* pointer
1282 cmd : SFC_WAVEX_SET_AMBISONIC
1284 datasize : SF_AMBISONIC_NONE or SF_AMBISONIC_B_FORMAT
1287 Turn on (SF_AMBISONIC_B_FORMAT) or off (SF_AMBISONIC_NONE) encoding.
1288 This command is currently only supported for files with SF_FORMAT_WAVEX format.
1291 The Ambisonic WAVEX formats are defined here :
1292 <A HREF=
"http://dream.cs.bath.ac.uk/researchdev/wave-ex/bformat.html">
1293 http://dream.cs.bath.ac.uk/researchdev/wave-ex/bformat.html
</A>.
1296 <DT>Return value:
</DT>
1297 <DD>Return the ambisonic value that has just been set or zero if the file
1298 format does not support ambisonic encoding.
1301 <!-- ========================================================================= -->
1302 <A NAME=
"SFC_SET_VBR_ENCODING_QUALITY"></A>
1303 <H2><BR><B>SFC_SET_VBR_ENCODING_QUALITY
</B></H2>
1305 Set the the Variable Bit Rate encoding quality.
1306 The encoding quality value should be between
0.0 (lowest quality) and
1.0
1312 sndfile : A valid SNDFILE* pointer
1313 cmd : SFC_SET_VBR_ENCODING_QUALITY
1314 data : A pointer to a double value
1315 datasize : sizeof (double)
1318 The command must be sent before any audio data is written to the file.
1323 <DT>Return value:
</DT>
1324 <DD>Zero on success, non-zero otherwise.
1327 <!-- ========================================================================= -->
1328 <A NAME=
"SFC_RAW_NEEDS_ENDSWAP"></A>
1329 <H2><BR><B>SFC_RAW_NEEDS_ENDSWAP
</B></H2>
1331 Determine if raw data read using
1332 <a href=
"api.html#raw">
1334 needs to be end swapped on the host CPU.
1337 For instance, will return SF_TRUE on when reading WAV containing
1338 SF_FORMAT_PCM_16 data on a big endian machine and SF_FALSE on a little endian
1344 sndfile : A valid SNDFILE* pointer
1345 cmd : SFC_RAW_NEEDS_ENDSWAP
1351 <DT>Return value:
</DT>
1352 <DD>SF_TRUE or SF_FALSE
1356 <!-- ========================================================================= -->
1357 <A NAME=
"SFC_GET_BROADCAST_INFO"></A>
1358 <H2><BR><B>SFC_GET_BROADCAST_INFO
</B></H2>
1360 Retrieve the Broadcast Extension Chunk from WAV (and related) files.
1366 sndfile : A valid SNDFILE* pointer
1367 cmd : SFC_GET_BROADCAST_INFO
1368 data : a pointer to an SF_BROADCAST_INFO struct
1369 datasize : sizeof (SF_BROADCAST_INFO)
1372 The SF_BROADCAST_INFO struct is defined in
<sndfile.h
> as:
1376 { char description [
256] ;
1377 char originator [
32] ;
1378 char originator_reference [
32] ;
1379 char origination_date [
10] ;
1380 char origination_time [
8] ;
1381 unsigned int time_reference_low ;
1382 unsigned int time_reference_high ;
1385 char reserved [
190] ;
1386 unsigned int coding_history_size ;
1387 char coding_history [
256] ;
1388 } SF_BROADCAST_INFO ;
1392 <DT>Return value:
</DT>
1393 <DD>SF_TRUE if the file contained a Broadcast Extension chunk or SF_FALSE
1397 <!-- ========================================================================= -->
1398 <A NAME=
"SFC_SET_BROADCAST_INFO"></A>
1399 <H2><BR><B>SFC_SET_BROADCAST_INFO
</B></H2>
1401 Set the Broadcast Extension Chunk for WAV (and related) files.
1407 sndfile : A valid SNDFILE* pointer
1408 cmd : SFC_SET_BROADCAST_INFO
1409 data : a pointer to an SF_BROADCAST_INFO struct
1410 datasize : sizeof (SF_BROADCAST_INFO)
1414 <DT>Return value:
</DT>
1415 <DD>SF_TRUE if setting the Broadcast Extension chunk was successful and SF_FALSE
1418 <!-- ========================================================================= -->
1420 <A NAME=
"SFC_GET_LOOP_INFO"></A>
1421 <H2><BR><B>SFC_GET_LOOP_INFO
</B></H2>
1423 Retrieve loop information for file including time signature, length in
1424 beats and original MIDI base note
1430 sndfile : A valid SNDFILE* pointer
1431 cmd : SFC_GET_LOOP_INFO
1432 data : a pointer to an SF_LOOP_INFO struct
1433 datasize : sizeof (SF_LOOP_INFO)
1436 The SF_BROADCAST_INFO struct is defined in
<sndfile.h
> as:
1440 { short time_sig_num ; /* any positive integer
> 0 */
1441 short time_sig_den ; /* any positive power of
2 > 0 */
1442 int loop_mode ; /* see SF_LOOP enum */
1444 int num_beats ; /* this is NOT the amount of quarter notes !!!*/
1445 /* a full bar of
4/
4 is
4 beats */
1446 /* a full bar of
7/
8 is
7 beats */
1448 float bpm ; /* suggestion, as it can be calculated using other fields:*/
1449 /* file's lenght, file's sampleRate and our time_sig_den*/
1450 /* -
> bpms are always the amount of _quarter notes_ per minute */
1452 int root_key ; /* MIDI note, or -
1 for None */
1461 sf_command (sndfile, SFC_GET_LOOP_INFO,
&loop, sizeof (loop)) ;
1464 <DT>Return value:
</DT>
1465 <DD>SF_TRUE if the file header contains loop information for the file.
1469 <!-- ========================================================================= -->
1472 <A NAME=
"SFC_GET_INSTRUMENT"></A>
1473 <H2><BR><B>SFC_GET_INSTRUMENT
</B></H2>
1475 Retrieve instrument information from file including MIDI base note,
1476 keyboard mapping and looping informations(start/stop and mode).
1482 sndfile : A valid SNDFILE* pointer
1483 cmd : SFC_GET_INSTRUMENT
1484 data : a pointer to an SF_INSTRUMENT struct
1485 datasize : sizeof (SF_INSTRUMENT)
1489 The SF_INSTRUMENT struct is defined in
<sndfile.h
> as:
1494 ** The loop mode field in SF_INSTRUMENT will be one of the following.
1504 char basenote, detune ;
1505 char velocity_lo, velocity_hi ;
1506 char key_lo, key_hi ;
1511 unsigned int start ;
1513 unsigned int count ;
1514 } loops [
16] ; /* make variable in a sensible way */
1522 SF_INSTRUMENT inst ;
1523 sf_command (sndfile, SFC_GET_INSTRUMENT,
&inst, sizeof (inst)) ;
1526 <DT>Return value:
</DT>
1527 <dd>SF_TRUE if the file header contains instrument information for the
1528 file. SF_FALSE otherwise.
1531 <!-- ========================================================================= -->
1534 <A NAME=
"SFC_SET_INSTRUMENT"></A>
1535 <H2><BR><B>SFC_SET_INSTRUMENT
</B></H2>
1537 Set the instrument information for the file.
1543 sndfile : A valid SNDFILE* pointer
1544 cmd : SFC_GET_INSTRUMENT
1545 data : a pointer to an SF_INSTRUMENT struct
1546 datasize : sizeof (SF_INSTRUMENT)
1552 SF_INSTRUMENT inst ;
1553 sf_command (sndfile, SFC_SET_INSTRUMENT,
&inst, sizeof (inst)) ;
1556 <DT>Return value:
</DT>
1557 <dd>SF_TRUE if the file header contains instrument information for the
1558 file. SF_FALSE otherwise.
1561 <!-- ========================================================================= -->
1564 <A NAME=
"SFC_SET_VBR_ENCODING_QUALITY"></A>
1565 <H2><BR><B>SFC_SET_VBR_ENCODING_QUALITY
</B></H2>
1567 Set the Variable Bite Rate encoding quality.
1568 Currenly only implemented fro Ogg/Vorbis files.
1574 sndfile : A valid SNDFILE* pointer
1575 cmd : SFC_SET_VBR_ENCODING_QUALITY
1576 data : a pointer to double specifing VBR quality
1577 datasize : sizeof (double)
1583 double quality =
0.5 ;
1584 sf_command (sndfile, SFC_SET_VBR_ENCODING_QUALITY,
&quality, sizeof (double)) ;
1587 <DT>Return value:
</DT>
1588 <dd>SF_TRUE if VBR encoding quality was set.
1592 <!-- ========================================================================= -->
1597 The libsndfile home page is here :
1598 <A HREF=
"http://www.mega-nerd.com/libsndfile/">
1599 http://www.mega-nerd.com/libsndfile/
</A>.
projects / Faustine.git / blob