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 a integer identifier which is defined in
<sndfile.h
>.
32 All of the valid command identifiers have names begining 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>Retrieve the measured maximum signal value.
</TD>
57 <TD><A HREF=
"#SFC_CALC_NORM_SIGNAL_MAX">SFC_CALC_NORM_SIGNAL_MAX
</A></TD>
58 <TD>Retrieve 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 peaks for all channels.
</TD>
65 <TD><A HREF=
"#SFC_CALC_NORM_MAX_ALL_CHANNELS">SFC_CALC_NORM_MAX_ALL_CHANNELS
</A></TD>
66 <TD>Calculate normalised peaks for all channels.
</TD>
70 <TD><A HREF=
"#SFC_SET_NORM_FLOAT">SFC_SET_NORM_FLOAT
</A></TD>
71 <TD>Modify the normalisation behaviour of the floating point reading and writing functions.
</TD>
74 <TD><A HREF=
"#SFC_SET_NORM_DOUBLE">SFC_SET_NORM_DOUBLE
</A></TD>
75 <TD>Modify the normalisation behaviour of the double precision floating point reading and writing functions.
</TD>
78 <TD><A HREF=
"#SFC_GET_NORM_FLOAT">SFC_GET_NORM_FLOAT
</A></TD>
79 <TD>Retrieve the current normalisation behaviour of the floating point reading and writing functions.
</TD>
82 <TD><A HREF=
"#SFC_GET_NORM_DOUBLE">SFC_GET_NORM_DOUBLE
</A></TD>
83 <TD>Retrieve the current normalisation behaviour of the double precision floating point reading and writing functions.
</TD>
86 <TD><A HREF=
"#SFC_GET_SIMPLE_FORMAT_COUNT">SFC_GET_SIMPLE_FORMAT_COUNT
</A></TD>
87 <TD>Retrieve the number of simple formats supported by libsndfile.
</TD>
90 <TD><A HREF=
"#SFC_GET_SIMPLE_FORMAT">SFC_GET_SIMPLE_FORMAT
</A></TD>
91 <TD>Retrieve information about a simple format.
</TD>
95 <TD><A HREF=
"#SFC_GET_FORMAT_INFO">SFC_GET_FORMAT_INFO
</A></TD>
96 <TD>Retrieve information about a major or subtype format.
</TD>
100 <TD><A HREF=
"#SFC_GET_FORMAT_MAJOR_COUNT">SFC_GET_FORMAT_MAJOR_COUNT
</A></TD>
101 <TD>Retrieve the number of major formats.
</TD>
104 <TD><A HREF=
"#SFC_GET_FORMAT_MAJOR">SFC_GET_FORMAT_MAJOR
</A></TD>
105 <TD>Retrieve information about a major format type.
</TD>
108 <TD><A HREF=
"#SFC_GET_FORMAT_SUBTYPE_COUNT">SFC_GET_FORMAT_SUBTYPE_COUNT
</A></TD>
109 <TD>Retrieve the number of subformats.
</TD>
112 <TD><A HREF=
"#SFC_GET_FORMAT_SUBTYPE">SFC_GET_FORMAT_SUBTYPE
</A></TD>
113 <TD>Retrieve information about a subformat.
</TD>
117 <TD><A HREF=
"#SFC_SET_ADD_PEAK_CHUNK">SFC_SET_ADD_PEAK_CHUNK
</A></TD>
118 <TD>Switch the code for adding the PEAK chunk to WAV and AIFF files on or off.
</TD>
122 <TD><A HREF=
"#SFC_UPDATE_HEADER_NOW">SFC_UPDATE_HEADER_NOW
</A></TD>
123 <TD>Used when a file is open for write, this command will update the file
124 header to reflect the data written so far.
</TD>
127 <TD><A HREF=
"#SFC_SET_UPDATE_HEADER_AUTO">SFC_SET_UPDATE_HEADER_AUTO
</A></TD>
128 <TD>Used when a file is open for write, this command will cause the file header
129 to be updated after each write to the file.
</TD>
133 <TD><A HREF=
"#SFC_FILE_TRUNCATE">SFC_FILE_TRUNCATE
</A></TD>
134 <TD>Truncate a file open for write or for read/write.
</TD>
138 <TD><A HREF=
"#SFC_SET_RAW_START_OFFSET">SFC_SET_RAW_START_OFFSET
</A></TD>
139 <TD>Change the data start offset for files opened up as SF_FORMAT_RAW.
</TD>
146 <TD><A HREF="#add-dither">add dither</A></TD>
147 <TD>Add dither to output on write.</TD>
157 <!-- ========================================================================= -->
158 <A NAME=
"SFC_GET_LIB_VERSION"></A>
159 <H2><BR><B>SFC_GET_LIB_VERSION
</B></H2>
161 Retrieve the version of the library as a string.
167 cmd : SFC_GET_LIB_VERSION
168 data : A pointer to a char buffer
169 datasize : The size of the the buffer
176 sf_command (NULL, SFC_GET_LIB_VERSION, buffer, sizeof (buffer)) ;
180 <DT>Return value:
</DT>
181 <DD><DD>This call will return the length of the retrieved version string.
186 The string returned in the buffer passed to this function will not overflow
187 the buffer and will always be null terminated .
190 <!-- ========================================================================= -->
191 <A NAME=
"SFC_GET_LOG_INFO"></A>
192 <H2><BR><B>SFC_GET_LOG_INFO
</B></H2>
194 Retrieve the log buffer generated when opening a file as a string. This log
195 buffer can often contain a good reason for why libsndfile failed to open a
201 sndfile : A valid SNDFILE* pointer
202 cmd : SFC_GET_LOG_INFO
203 data : A pointer to a char buffer
204 datasize : The size of the the buffer
211 sf_command (sndfile, SFC_GET_LOG_INFO, buffer, sizeof (buffer)) ;
215 <DT>Return value:
</DT>
216 <DD><DD>This call will return the length of the retrieved version string.
221 The string returned in the buffer passed to this function will not overflow
222 the buffer and will always be null terminated .
225 <!-- ========================================================================= -->
226 <A NAME=
"SFC_CALC_SIGNAL_MAX"></A>
227 <H2><BR><B>SFC_CALC_SIGNAL_MAX
</B></H2>
229 Retrieve the measured maximum signal value. This involves reading through
230 the whole file which can be slow on large files.
235 sndfile : A valid SNDFILE* pointer
236 cmd : SFC_CALC_SIGNAL_MAX
237 data : A pointer to a double
238 datasize : sizeof (double)
245 sf_command (sndfile, SFC_CALC_SIGNAL_MAX,
&max_val, sizeof (max_val)) ;
249 <DT>Return value:
</DT>
250 <DD><DD>Zero on success, non-zero otherwise.
253 <!-- ========================================================================= -->
254 <A NAME=
"SFC_CALC_NORM_SIGNAL_MAX"></A>
255 <H2><BR><B>SFC_CALC_NORM_SIGNAL_MAX
</B></H2>
257 Retrieve the measured normailised maximum signal value. This involves reading
258 through the whole file which can be slow on large files.
263 sndfile : A valid SNDFILE* pointer
264 cmd : SFC_CALC_NORM_SIGNAL_MAX
265 data : A pointer to a double
266 datasize : sizeof (double)
273 sf_command (sndfile, SFC_CALC_NORM_SIGNAL_MAX,
&max_val, sizeof (max_val)) ;
277 <DT>Return value:
</DT>
278 <DD><DD>Zero on success, non-zero otherwise.
281 <!-- ========================================================================= -->
282 <A NAME=
"SFC_CALC_MAX_ALL_CHANNELS"></A>
283 <H2><BR><B>SFC_CALC_MAX_ALL_CHANNELS
</B></H2>
285 Calculate peaks for all channels. This involves reading through
286 the whole file which can be slow on large files.
291 sndfile : A valid SNDFILE* pointer
292 cmd : SFC_CALC_MAX_ALL_CHANNELS
293 data : A pointer to a double
294 datasize : sizeof (double) * number_of_channels
300 double peaks [number_of_channels] ;
301 sf_command (sndfile, SFC_CALC_MAX_ALL_CHANNELS, peaks, sizeof (peaks)) ;
304 <DT>Return value:
</DT>
305 <DD>Zero if peaks have been calculated successfully and non-zero otherwise.
309 <!-- ========================================================================= -->
310 <A NAME=
"SFC_CALC_NORM_MAX_ALL_CHANNELS"></A>
311 <H2><BR><B>SFC_CALC_NORM_MAX_ALL_CHANNELS
</B></H2>
313 Calculate normalised peaks for all channels. This involves reading through
314 the whole file which can be slow on large files.
319 sndfile : A valid SNDFILE* pointer
320 cmd : SFC_CALC_NORM_MAX_ALL_CHANNELS
321 data : A pointer to a double
322 datasize : sizeof (double) * number_of_channels
328 double peaks [number_of_channels] ;
329 sf_command (sndfile, SFC_CALC_NORM_MAX_ALL_CHANNELS, peaks, sizeof (peaks)) ;
332 <DT>Return value:
</DT>
333 <DD>Zero if peaks have been calculated successfully and non-zero otherwise.
340 <!-- ========================================================================= -->
342 <A NAME="read-text"></A>
343 <H2><BR><B>Read text</B></H2>
345 Many sound file formats contain allow the inclusion of a text string describing the nature
346 of the file. If a file contains such a string, this functions will return it to the caller.
349 It should be noted that the way the string is added to the file is file format dependant
350 but that any string added with <A HREF="#write-text">write text</A> will be returned by
351 <A HREF="#read-text">read text</A>.
358 sndfile : A valid SNDFILE* pointer
359 cmd : The text string "read text".
360 data : A pointer to a char buffer.
361 datasize : The size of the the buffer.
368 sf_command (sndfile, "read text", buffer, sizeof (buffer)) ;
371 <DT>Return value:</DT>
372 <DD>If a text string is found, this call will return the length of the retrieved text
374 <DD>If no text string is found, zero will be returned and the first element in the
375 buffer will be set to the null character.
377 <DD>The string returned in the buffer passed to this function will not overflow
378 the buffer and will be correctly null terminated .
381 <A NAME="write-text"></A>
382 <H2><BR><B>Write text</B></H2>
384 Add a text string to a file. The text string added can be retrieved when the file is
385 read using <A HREF="#read-text">read text</A>.
391 sndfile : A valid SNDFILE* pointer
392 cmd : The text string "write text".
393 data : A pointer to the string to be added.
400 char text = "The sound of one hand clapping." ;
401 sf_command (sndfile, "write text", text, strlen (text)) ;
404 <DT>Return value: </DT>
405 <DD>If the current file format allows the addition of text strings, the string will
406 be added and the length of the string will be returned.
407 <DD>If the file format does not allow the addition of text strings zero will be returned.
408 <DD>If this function is called after the file is openned but before
413 <!-- ========================================================================= -->
414 <A NAME=
"SFC_SET_NORM_FLOAT"></A>
415 <H2><BR><B>SFC_SET_NORM_FLOAT
</B></H2>
417 This command only affects data read from or written to using the floating point functions:
420 size_t
<A HREF=
"api.html#read">sf_read_float
</A> (SNDFILE *sndfile, float *ptr, size_t items) ;
421 size_t
<A HREF=
"api.html#readf">sf_readf_float
</A> (SNDFILE *sndfile, float *ptr, size_t frames) ;
423 size_t
<A HREF=
"api.html#write">sf_write_float
</A> (SNDFILE *sndfile, float *ptr, size_t items) ;
424 size_t
<A HREF=
"api.html#writef">sf_writef_float
</A> (SNDFILE *sndfile, float *ptr, size_t frames) ;
430 sndfile : A valid SNDFILE* pointer
431 cmd : SFC_SET_NORM_FLOAT
433 datasize : SF_TRUE or SF_FALSE
436 For read operations setting normalisation to SF_TRUE means that the data from all
437 subsequent reads will be be normalised to the range [-
1.0,
1.0].
440 For write operations, setting normalisation to SF_TRUE means than all data supplied
441 to the float write functions should be in the range [-
1.0,
1.0] and will be scaled
442 for the file format as necessary.
445 For both cases, setting normalisation to SF_FALSE means that no scaling will take place.
451 sf_command (sndfile, SFC_SET_NORM_FLOAT, NULL, SF_TRUE) ;
453 sf_command (sndfile, SFC_SET_NORM_FLOAT, NULL, SF_FALSE) ;
456 <DT>Return value:
</DT>
457 <DD>Returns
1 on success or
0 for failure.
460 <!-- ========================================================================= -->
461 <A NAME=
"SFC_SET_NORM_DOUBLE"></A>
462 <H2><BR><B>SFC_SET_NORM_DOUBLE
</B></H2>
464 This command only affects data read from or written to using the double precision
465 floating point functions:
468 size_t
<A HREF=
"api.html#read">sf_read_double
</A> (SNDFILE *sndfile, double *ptr, size_t items) ;
469 size_t
<A HREF=
"api.html#readf">sf_readf_double
</A> (SNDFILE *sndfile, double *ptr, size_t frames) ;
471 size_t
<A HREF=
"api.html#write">sf_write_double
</A> (SNDFILE *sndfile, double *ptr, size_t items) ;
472 size_t
<A HREF=
"api.html#writef">sf_writef_double
</A> (SNDFILE *sndfile, double *ptr, size_t frames) ;
478 sndfile : A valid SNDFILE* pointer
479 cmd : SFC_SET_NORM_DOUBLE
481 datasize : SF_TRUE or SF_FALSE
484 For read operations setting normalisation to SF_TRUE means that the data
485 from all subsequent reads will be be normalised to the range [-
1.0,
1.0].
488 For write operations, setting normalisation to SF_TRUE means than all data supplied
489 to the double write functions should be in the range [-
1.0,
1.0] and will be scaled
490 for the file format as necessary.
493 For both cases, setting normalisation to SF_FALSE means that no scaling will take place.
499 sf_command (sndfile, SFC_SET_NORM_DOUBLE, NULL, SF_TRUE) ;
501 sf_command (sndfile, SFC_SET_NORM_DOUBLE, NULL, SF_FALSE) ;
504 <DT>Return value:
</DT>
505 <DD>Returns
1 on success or
0 for failure.
508 <!-- ========================================================================= -->
509 <A NAME=
"SFC_GET_NORM_FLOAT"></A>
510 <H2><BR><B>SFC_GET_NORM_FLOAT
</B></H2>
512 Retrieve the current float normalisation mode.
518 sndfile : A valid SNDFILE* pointer
519 cmd : SFC_GET_NORM_FLOAT
527 normalisation = sf_command (sndfile, SFC_GET_NORM_FLOAT, NULL,
0) ;
530 <DT>Return value:
</DT>
531 <DD>Returns TRUE if normaisation is on and FALSE otherwise.
534 <!-- ========================================================================= -->
535 <A NAME=
"SFC_GET_NORM_DOUBLE"></A>
536 <H2><BR><B>SFC_GET_NORM_DOUBLE
</B></H2>
538 Retrieve the current float normalisation mode.
544 sndfile : A valid SNDFILE* pointer
545 cmd : SFC_GET_NORM_DOUBLE
553 normalisation = sf_command (sndfile, SFC_GET_NORM_DOUBLE, NULL,
0) ;
556 <DT>Return value:
</DT>
557 <DD>Returns TRUE if normalisation is on and FALSE otherwise.
560 <!-- ========================================================================= -->
561 <A NAME=
"SFC_GET_SIMPLE_FORMAT_COUNT"></A>
562 <H2><BR><B>SFC_GET_SIMPLE_FORMAT_COUNT
</B></H2>
564 Retrieve the number of simple formats supported by libsndfile.
571 cmd : SFC_GET_SIMPLE_FORMAT_COUNT
572 data : a pointer to an int
573 datasize : sizeof (int)
580 sf_command (sndfile, SFC_GET_SIMPLE_FORMAT_COUNT,
&count, sizeof (int)) ;
583 <DT>Return value:
</DT>
587 <!-- ========================================================================= -->
588 <A NAME=
"SFC_GET_SIMPLE_FORMAT"></A>
589 <H2><BR><B>SFC_GET_SIMPLE_FORMAT
</B></H2>
591 Retrieve information about a simple format.
598 cmd : SFC_GET_SIMPLE_FORMAT
599 data : a pointer to an SF_FORMAT_INFO struct
600 datasize : sizeof (SF_FORMAT_INFO)
603 The SF_FORMAT_INFO struct is defined in
<sndfile.h
> as:
609 const char *extension ;
613 When sf_command() is called with SF_GET_SIMPLE_FORMAT, the value of the format
614 field should be the format number (ie
0 <= format <= count value obtained using
615 SF_GET_SIMPLE_FORMAT_COUNT).
621 SF_FORMAT_INFO format_info ;
624 sf_command (sndfile, SFC_GET_SIMPLE_FORMAT_COUNT,
&count, sizeof (int)) ;
626 for (k =
0 ; k < count ; k++)
627 { format_info.format = k ;
628 sf_command (sndfile, SFC_GET_SIMPLE_FORMAT,
&format_info, sizeof (format_info)) ;
629 printf (
"%08x %s %s\n", format_info.format, format_info.name, format_info.extension) ;
633 <DT>Return value:
</DT>
634 <DD>0 on success and non-zero otherwise.
635 <DD>The value of the format field of the SF_FORMAT_INFO struct will be an value which
636 can be placed in the format field of an SF_INFO struct when a file is to be opened
638 <DD>The name field will contain a char* pointer to the name of the string ie
"WAV (Microsoft 16 bit PCM)".
639 <DD>The extention field will contain the most commonly used file extension for that file type.
642 <!-- ========================================================================= -->
643 <A NAME=
"SFC_GET_FORMAT_INFO"></A>
644 <H2><BR><B>SFC_GET_FORMAT_INFO
</B></H2>
646 Retrieve information about a major or subtype format.
653 cmd : SFC_GET_FORMAT_INFO
654 data : a pointer to an SF_FORMAT_INFO struct
655 datasize : sizeof (SF_FORMAT_INFO)
658 The SF_FORMAT_INFO struct is defined in
<sndfile.h
> as:
664 const char *extension ;
668 When sf_command() is called with SF_GET_FORMAT_INFO, the format field is
669 examined and if (format & SF_FORMAT_TYPEMASK) is a valid format then the struct
670 is filled in with information about the given major type.
671 If (format & SF_FORMAT_TYPEMASK) is FALSE and (format & SF_FORMAT_SUBMASK) is a
672 valid subtype format then the struct is filled in with information about the given
679 SF_FORMAT_INFO format_info ;
681 format_info.format = SF_FORMAT_WAV ;
682 sf_command (sndfile, SFC_GET_FORMAT_INFO,
&format_info, sizeof (format_info)) ;
683 printf (
"%08x %s %s\n", format_info.format, format_info.name, format_info.extension) ;
685 format_info.format = SF_FORMAT_ULAW ;
686 sf_command (sndfile, SFC_GET_FORMAT_INFO,
&format_info, sizeof (format_info)) ;
687 printf (
"%08x %s\n", format_info.format, format_info.name) ;
690 <DT>Return value:
</DT>
691 <DD>0 on success and non-zero otherwise.
693 <!-- ========================================================================= -->
694 <A NAME=
"SFC_GET_FORMAT_MAJOR_COUNT"></A>
695 <H2><BR><B>SFC_GET_FORMAT_MAJOR_COUNT
</B></H2>
697 Retrieve the number of major formats.
704 cmd : SFC_GET_FORMAT_MAJOR_COUNT
705 data : a pointer to an int
706 datasize : sizeof (int)
713 sf_command (sndfile, SFC_GET_FORMAT_MAJOR_COUNT,
&count, sizeof (int)) ;
716 <DT>Return value:
</DT>
720 <!-- ========================================================================= -->
721 <A NAME=
"SFC_GET_FORMAT_MAJOR"></A>
722 <H2><BR><B>SFC_GET_FORMAT_MAJOR
</B></H2>
724 Retrieve information about a major format type.
731 cmd : SFC_GET_FORMAT_MAJOR
732 data : a pointer to an SF_FORMAT_INFO struct
733 datasize : sizeof (SF_FORMAT_INFO)
739 SF_FORMAT_INFO format_info ;
742 sf_command (sndfile, SFC_GET_FORMAT_MAJOR_COUNT,
&count, sizeof (int)) ;
744 for (k =
0 ; k < count ; k++)
745 { format_info.format = k ;
746 sf_command (sndfile, SFC_GET_FORMAT_MAJOR,
&format_info, sizeof (format_info)) ;
747 printf (
"%08x %s %s\n", format_info.format, format_info.name, format_info.extension) ;
751 For a more comprehensive example, see the program list_formats.c in the examples/
752 directory of the libsndfile source code distribution.
755 <DT>Return value:
</DT>
756 <DD>0 on success and non-zero otherwise.
757 <DD>The value of the format field will one of the major format identifiers suc as SF_FORMAT_WAV
759 <DD>The name field will contain a char* pointer to the name of the string ie
"WAV (Microsoft)".
760 <DD>The extention field will contain the most commonly used file extension for that file type.
763 <!-- ========================================================================= -->
764 <A NAME=
"SFC_GET_FORMAT_SUBTYPE_COUNT"></A>
765 <H2><BR><B>SFC_GET_FORMAT_SUBTYPE_COUNT
</B></H2>
767 Retrieve the number of subformats.
774 cmd : SFC_GET_FORMAT_SUBTYPE_COUNT
775 data : a pointer to an int
776 datasize : sizeof (int)
783 sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE_COUNT,
&count, sizeof (int)) ;
786 <DT>Return value:
</DT>
790 <!-- ========================================================================= -->
791 <A NAME=
"SFC_GET_FORMAT_SUBTYPE"></A>
792 <H2><BR><B>SFC_GET_FORMAT_SUBTYPE
</B></H2>
794 Retrieve information about a subformat.
801 cmd : SFC_GET_FORMAT_SUBTYPE
802 data : a pointer to an SF_FORMAT_INFO struct
803 datasize : sizeof (SF_FORMAT_INFO)
809 SF_FORMAT_INFO format_info ;
812 sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE_COUNT,
&count, sizeof (int)) ;
814 /* Retrieve all the subtypes supported by the WAV format. */
815 for (k =
0 ; k < count ; k++)
816 { format_info.format = k ;
817 sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE,
&format_info, sizeof (format_info)) ;
818 if (! sf_format_check (format.info | SF_FORMAT_WAV))
820 printf (
"%08x %s\n", format_info.format, format_info.name) ;
824 For a more comprehensive example, see the program list_formats.c in the examples/
825 directory of the libsndfile source code distribution.
828 <DT>Return value:
</DT>
829 <DD>0 on success and non-zero otherwise.
830 <DD>The value of the format field will one of the major format identifiers such as SF_FORMAT_WAV
832 <DD>The name field will contain a char* pointer to the name of the string; for instance
833 "WAV (Microsoft)" or
"AIFF (Apple/SGI)".
834 <DD>The extention field will be a NULL pointer.
837 <!-- ========================================================================= -->
838 <A NAME=
"SFC_SET_ADD_PEAK_CHUNK"></A>
839 <H2><BR><B>SFC_SET_ADD_PEAK_CHUNK
</B></H2>
841 By default, WAV and AIFF files which contain floating point data (subtype SF_FORMAT_FLOAT
842 or SF_FORMAT_DOUBLE) have a PEAK chunk.
843 By using this command, the addition of a PEAK chunk can be turned on or off.
846 Note : This call must be made before any data is written to the file.
851 sndfile : A valid SNDFILE* pointer
852 cmd : SFC_SET_ADD_PEAK_CHUNK
853 data : Not used (should be NULL)
854 datasize : TRUE or FALSE.
860 /* Turn on the PEAK chunk. */
861 sf_command (sndfile, SFC_SET_ADD_PEAK_CHUNK, NULL, SF_TRUE) ;
863 /* Turn off the PEAK chunk. */
864 sf_command (sndfile, SFC_SET_ADD_PEAK_CHUNK, NULL, SF_FALSE) ;
867 <DT>Return value:
</DT>
868 <DD>Returns SF_TRUE if the peak chunk will be written after this call.
869 <DD>Returns SF_FALSE if the peak chunk will not be written after this call.
872 <!-- ========================================================================= -->
873 <A NAME=
"SFC_UPDATE_HEADER_NOW"></A>
874 <H2><BR><B>SFC_UPDATE_HEADER_NOW
</B></H2>
876 The header of an audio file is normally written by libsndfile when the file is
877 closed using
<B>sf_close()
</B>.
880 There are however situations where large files are being generated and it would
881 be nice to have valid data in the header before the file is complete.
882 Using this command will update the file header to reflect the amount of data written
884 Other programs opening the file for read (before any more data is written) will
885 then read a valid sound file header.
890 sndfile : A valid SNDFILE* pointer
891 cmd : SFC_UPDATE_HEADER_NOW
892 data : Not used (should be NULL)
899 /* Update the header now. */
900 sf_command (sndfile, SFC_UPDATE_HEADER_NOW, NULL,
0) ;
903 <DT>Return value:
</DT>
907 <!-- ========================================================================= -->
908 <A NAME=
"SFC_SET_UPDATE_HEADER_AUTO"></A>
909 <H2><BR><B>SFC_SET_UPDATE_HEADER_AUTO
</B></H2>
911 Similar to SFC_UPDATE_HEADER_NOW but updates the header at the end of every call
912 to the
<B>sf_write*
</B> functions.
917 sndfile : A valid SNDFILE* pointer
918 cmd : SFC_UPDATE_HEADER_NOW
919 data : Not used (should be NULL)
920 datasize : SF_TRUE or SF_FALSE
926 /* Turn on auto header update. */
927 sf_command (sndfile, SFC_SET_UPDATE_HEADER_AUTO, NULL, SF_TRUE) ;
929 /* Turn off auto header update. */
930 sf_command (sndfile, SFC_SET_UPDATE_HEADER_AUTO, NULL, SF_FALSE) ;
933 <DT>Return value:
</DT>
934 <DD>TRUE if auto update header is now on; FALSE otherwise.
937 <!-- ========================================================================= -->
938 <A NAME=
"SFC_FILE_TRUNCATE"></A>
939 <H2><BR><B>SFC_FILE_TRUNCATE
</B></H2>
941 Truncate a file open for write or for read/write.
946 sndfile : A valid SNDFILE* pointer
947 cmd : SFC_FILE_TRUNCATE
948 data : A pointer to an sf_count_t.
949 datasize : sizeof (sf_count_t)
953 Truncate the file to the number of frames specified by the sf_count_t pointed
955 After this command, both the read and the write pointer will be
956 at the new end of the file.
957 This command will fail (returning non-zero) if the requested truncate position
958 is beyond the end of the file.
964 /* Truncate the file to a length of
20 frames. */
965 sf_count_t frames =
20 ;
966 sf_command (sndfile, SFC_FILE_TRUNCATE,
&frames, sizeof (frames)) ;
969 <DT>Return value:
</DT>
970 <DD>Zero on sucess, non-zero otherwise.
973 <!-- ========================================================================= -->
974 <A NAME=
"SFC_SET_RAW_START_OFFSET"></A>
975 <H2><BR><B>SFC_SET_RAW_START_OFFSET
</B></H2>
977 Change the data start offset for files opened up as SF_FORMAT_RAW.
982 sndfile : A valid SNDFILE* pointer
983 cmd : SFC_SET_RAW_START_OFFSET
984 data : A pointer to an sf_count_t.
985 datasize : sizeof (sf_count_t)
989 For a file opened as format SF_FORMAT_RAW, set the data offset to the value
996 /* Reset the data offset to
5 bytes from the start of the file. */
997 sf_count_t offset =
5 ;
998 sf_command (sndfile, SFC_SET_RAW_START_OFFSET,
&offset, sizeof (offset)) ;
1001 <DT>Return value:
</DT>
1002 <DD>Zero on sucess, non-zero otherwise.
1005 <!-- ========================================================================= -->
1009 The libsndfile home page is here :
1010 <A HREF=
"http://www.mega-nerd.com/libsndfile/">
1011 http://www.mega-nerd.com/libsndfile/
</A>.