Gitiles
Code Review Sign In
review.jami.net / jami-client-android / 3874e557ab7b54f78566363f6deeb3d08933f5dd / . / jni / libsndfile / doc / command.html
blob: 3af84c83c0a84699c58b4b242950e15defe5becc [file] [log] [blame]
Alexandre Lision7c6f4a62013-09-05 13:27:01 -0400[diff] [blame]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<HTML>
3
4<HEAD>
5 <TITLE>
6 libsndfile : the sf_command function.
7 </TITLE>
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">
14</HEAD>
15
16<BODY>
17
18<H1><B>sf_command</B></H1>
19<PRE>
20
21 int sf_command (SNDFILE *sndfile, int cmd, void *data, int datasize) ;
22</PRE>
23<P>
24 This function allows the caller to retrieve information from or change aspects of the
25 library behaviour.
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.
29</P>
30<P>
31 The cmd parameter is an integer identifier which is defined in &lt;sndfile.h&gt;.
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.
37</P>
38<P>
39 The available commands are as follows:
40</P>
41
42<CENTER>
43<TABLE BORDER="0" WIDTH="90%" CELLPADDING="4">
44<TR>
45 <TD><A HREF="#SFC_GET_LIB_VERSION">SFC_GET_LIB_VERSION</A></TD>
46 <TD>Retrieve the version of the library.</TD>
47</TR>
48<TR>
49 <TD><A HREF="#SFC_GET_LOG_INFO">SFC_GET_LOG_INFO</A></TD>
50 <TD>Retrieve the internal per-file operation log.</TD>
51</TR>
52<TR>
53 <TD><A HREF="#SFC_CALC_SIGNAL_MAX">SFC_CALC_SIGNAL_MAX</A></TD>
54 <TD>Calculate the measured maximum signal value.</TD>
55</TR>
56<TR>
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>
59</TR>
60<TR>
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>
63</TR>
64<TR>
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>
67</TR>
68
69<TR>
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>
72</TR>
73<TR>
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>
76</TR>
77
78<TR>
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>
81</TR>
82<TR>
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>
85</TR>
86<TR>
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>
89</TR>
90<TR>
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>
93</TR>
94<TR>
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>
98</TR>
99
100<TR>
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>
104</TR>
105
106<TR>
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>
109</TR>
110<TR>
111 <TD><A HREF="#SFC_GET_SIMPLE_FORMAT">SFC_GET_SIMPLE_FORMAT</A></TD>
112 <TD>Retrieve information about a simple format.</TD>
113</TR>
114
115<TR>
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>
118</TR>
119
120<TR>
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>
123</TR>
124<TR>
125 <TD><A HREF="#SFC_GET_FORMAT_MAJOR">SFC_GET_FORMAT_MAJOR</A></TD>
126 <TD>Retrieve information about a major format type.</TD>
127</TR>
128<TR>
129 <TD><A HREF="#SFC_GET_FORMAT_SUBTYPE_COUNT">SFC_GET_FORMAT_SUBTYPE_COUNT</A></TD>
130 <TD>Retrieve the number of subformats.</TD>
131</TR>
132<TR>
133 <TD><A HREF="#SFC_GET_FORMAT_SUBTYPE">SFC_GET_FORMAT_SUBTYPE</A></TD>
134 <TD>Retrieve information about a subformat.</TD>
135</TR>
136
137<TR>
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>
140</TR>
141
142<TR>
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>
146</TR>
147<TR>
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>
151</TR>
152
153<TR>
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>
156</TR>
157
158<TR>
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>
161</TR>
162
163<TR>
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
166 conversion.</TD>
167</TR>
168
169<TR>
170 <TD><A HREF="#SFC_GET_CLIPPING">SFC_GET_CLIPPING</A></TD>
171 <TD>Retrieve current clipping setting.</TD>
172</TR>
173
174<TR>
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>
177</TR>
178
179<TR>
180 <TD><A HREF="#SFC_WAVEX_GET_AMBISONIC">SFC_GET_AMBISONIC</A></TD>
181 <TD>Test a WAVEX file for Ambisonic format</TD>
182</TR>
183
184<TR>
185 <TD><A HREF="#SFC_WAVEX_SET_AMBISONIC">SFC_SET_AMBISONIC</A></TD>
186 <TD>Modify a WAVEX header for Ambisonic format</TD>
187</TR>
188
189<TR>
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>
192</TR>
193
194<TR>
195 <TD><A HREF="#SFC_RAW_NEEDS_ENDSWAP">SFC_RAW_NEEDS_ENDSWAP</a></td>
196 <TD>Determine if raw data needs endswapping</TD>
197</TR>
198
199<TR>
200 <TD><A HREF="#SFC_GET_BROADCAST_INFO">SFC_GET_BROADCAST_INFO</A></TD>
201 <TD>Retrieve the Broadcast Chunk info</TD>
202</TR>
203
204<TR>
205 <TD><A HREF="#SFC_SET_BROADCAST_INFO">SFC_SET_BROADCAST_INFO</A></TD>
206 <TD>Set the Broadcast Chunk info</TD>
207</TR>
208
209<TR>
210 <TD><A HREF="#SFC_GET_LOOP_INFO">SFC_GET_LOOP_INFO</A></TD>
211 <TD>Get loop info</TD>
212</TR>
213
214<TR>
215 <TD><A HREF="#SFC_GET_INSTRUMENT">SFC_GET_INSTRUMENT</A></TD>
216 <TD>Get instrument info</TD>
217</TR>
218
219<TR>
220 <TD><A HREF="#SFC_SET_INSTRUMENT">SFC_SET_INSTRUMENT</A></TD>
221 <TD>Set instrument info</TD>
222</TR>
223
224<TR>
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>
227</TR>
228
229
230
231<!--
232<TR>
233 <TD><A HREF="#add-dither">add dither</A></TD>
234 <TD>Add dither to output on write.</TD>
235</TR>
236-->
237</TABLE>
238</CENTER>
239
240<BR><BR>
241
242<HR>
243
244<!-- ========================================================================= -->
245<A NAME="SFC_GET_LIB_VERSION"></A>
246<H2><BR><B>SFC_GET_LIB_VERSION</B></H2>
247<P>
248Retrieve the version of the library as a string.
249</P>
250<P>
251Parameters:
252<PRE>
253 sndfile : Not used
254 cmd : SFC_GET_LIB_VERSION
255 data : A pointer to a char buffer
256 datasize : The size of the the buffer
257</PRE>
258<P>
259Example:
260</P>
261<PRE>
262 char buffer [128] ;
263 sf_command (NULL, SFC_GET_LIB_VERSION, buffer, sizeof (buffer)) ;
264</PRE>
265
266<DL>
267<DT>Return value:</DT>
268 <DD><DD>This call will return the length of the retrieved version string.
269</DL>
270<DL>
271<DT>Notes:</DT>
272<DD>
273The string returned in the buffer passed to this function will not overflow
274the buffer and will always be null terminated .
275</DL>
276
277<!-- ========================================================================= -->
278<A NAME="SFC_GET_LOG_INFO"></A>
279<H2><BR><B>SFC_GET_LOG_INFO</B></H2>
280<P>
281Retrieve the log buffer generated when opening a file as a string. This log
282buffer can often contain a good reason for why libsndfile failed to open a
283particular file.
284</P>
285<P>
286Parameters:
287<PRE>
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
292</PRE>
293<P>
294Example:
295</P>
296<PRE>
297 char buffer [2048] ;
298 sf_command (sndfile, SFC_GET_LOG_INFO, buffer, sizeof (buffer)) ;
299</PRE>
300
301<DL>
302<DT>Return value:</DT>
303 <DD><DD>This call will return the length of the retrieved version string.
304</DL>
305<DL>
306<DT>Notes:</DT>
307<DD>
308The string returned in the buffer passed to this function will not overflow
309the buffer and will always be null terminated .
310</DL>
311
312<!-- ========================================================================= -->
313<A NAME="SFC_CALC_SIGNAL_MAX"></A>
314<H2><BR><B>SFC_CALC_SIGNAL_MAX</B></H2>
315<P>
316Retrieve the measured maximum signal value. This involves reading through
317the whole file which can be slow on large files.
318</P>
319<P>
320Parameters:
321<PRE>
322 sndfile : A valid SNDFILE* pointer
323 cmd : SFC_CALC_SIGNAL_MAX
324 data : A pointer to a double
325 datasize : sizeof (double)
326</PRE>
327<P>
328Example:
329</P>
330<PRE>
331 double max_val ;
332 sf_command (sndfile, SFC_CALC_SIGNAL_MAX, &amp;max_val, sizeof (max_val)) ;
333</PRE>
334
335<DL>
336<DT>Return value:</DT>
337 <DD><DD>Zero on success, non-zero otherwise.
338</DL>
339
340<!-- ========================================================================= -->
341<A NAME="SFC_CALC_NORM_SIGNAL_MAX"></A>
342<H2><BR><B>SFC_CALC_NORM_SIGNAL_MAX</B></H2>
343<P>
344Retrieve the measured normalised maximum signal value. This involves reading
345through the whole file which can be slow on large files.
346</P>
347<P>
348Parameters:
349<PRE>
350 sndfile : A valid SNDFILE* pointer
351 cmd : SFC_CALC_NORM_SIGNAL_MAX
352 data : A pointer to a double
353 datasize : sizeof (double)
354</PRE>
355<P>
356Example:
357</P>
358<PRE>
359 double max_val ;
360 sf_command (sndfile, SFC_CALC_NORM_SIGNAL_MAX, &amp;max_val, sizeof (max_val)) ;
361</PRE>
362
363<DL>
364<DT>Return value:</DT>
365 <DD><DD>Zero on success, non-zero otherwise.
366</DL>
367
368<!-- ========================================================================= -->
369<A NAME="SFC_CALC_MAX_ALL_CHANNELS"></A>
370<H2><BR><B>SFC_CALC_MAX_ALL_CHANNELS</B></H2>
371<P>
372Calculate the peak value (ie a single number) for each channel.
373This involves reading through the whole file which can be slow on large files.
374</P>
375<P>
376Parameters:
377<PRE>
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
382</PRE>
383<P>
384Example:
385</P>
386<PRE>
387 double peaks [number_of_channels] ;
388 sf_command (sndfile, SFC_CALC_MAX_ALL_CHANNELS, peaks, sizeof (peaks)) ;
389</PRE>
390<DL>
391<DT>Return value:</DT>
392 <DD>Zero if peaks have been calculated successfully and non-zero otherwise.
393</DL>
394
395
396<!-- ========================================================================= -->
397<A NAME="SFC_CALC_NORM_MAX_ALL_CHANNELS"></A>
398<H2><BR><B>SFC_CALC_NORM_MAX_ALL_CHANNELS</B></H2>
399<P>
400Calculate the normalised peak for each channel.
401This involves reading through the whole file which can be slow on large files.
402</P>
403<P>
404Parameters:
405<PRE>
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
410</PRE>
411<P>
412Example:
413</P>
414<PRE>
415 double peaks [number_of_channels] ;
416 sf_command (sndfile, SFC_CALC_NORM_MAX_ALL_CHANNELS, peaks, sizeof (peaks)) ;
417</PRE>
418<DL>
419<DT>Return value:</DT>
420 <DD>Zero if peaks have been calculated successfully and non-zero otherwise.
421</DL>
422
423
424
425
426<!-- ========================================================================= -->
427<A NAME="SFC_GET_SIGNAL_MAX"></A>
428<H2><BR><B>SFC_GET_SIGNAL_MAX</B></H2>
429<P>
430Retrieve the peak value for the file as stored in the file header.
431</P>
432<P>
433Parameters:
434<PRE>
435 sndfile : A valid SNDFILE* pointer
436 cmd : SFC_GET_SIGNAL_MAX
437 data : A pointer to a double
438 datasize : sizeof (double)
439</PRE>
440<P>
441Example:
442</P>
443<PRE>
444 double max_peak ;
445 sf_command (sndfile, SFC_GET_SIGNAL_MAX, &amp;max_peak, sizeof (max_peak)) ;
446</PRE>
447<DL>
448<DT>Return value:</DT>
449 <DD>SF_TRUE if the file header contained the peak value. SF_FALSE otherwise.
450</DL>
451
452<!-- ========================================================================= -->
453<A NAME="SFC_GET_MAX_ALL_CHANNELS"></A>
454<H2><BR><B>SFC_GET_MAX_ALL_CHANNELS</B></H2>
455<P>
456Retrieve the peak value for the file as stored in the file header.
457</P>
458<P>
459Parameters:
460<PRE>
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
465</PRE>
466<P>
467Example:
468</P>
469<PRE>
470 double peaks [number_of_channels] ;
471 sf_command (sndfile, SFC_GET_MAX_ALL_CHANNELS, peaks, sizeof (peaks)) ;
472</PRE>
473<DL>
474<DT>Return value:</DT>
475 <DD>SF_TRUE if the file header contains per channel peak values for the file.
476 SF_FALSE otherwise.
477</DL>
478
479
480<!-- ========================================================================= -->
481<A NAME="SFC_SET_NORM_FLOAT"></A>
482<H2><BR><B>SFC_SET_NORM_FLOAT</B></H2>
483<P>
484This command only affects data read from or written to using the floating point functions:
485</P>
486<PRE>
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) ;
489
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) ;
492</PRE>
493<P>
494Parameters:
495</P>
496<PRE>
497 sndfile : A valid SNDFILE* pointer
498 cmd : SFC_SET_NORM_FLOAT
499 data : NULL
500 datasize : SF_TRUE or SF_FALSE
501</PRE>
502<P>
503For read operations setting normalisation to SF_TRUE means that the data from all
504subsequent reads will be be normalised to the range [-1.0, 1.0].
505</P>
506<P>
507For write operations, setting normalisation to SF_TRUE means than all data supplied
508to the float write functions should be in the range [-1.0, 1.0] and will be scaled
509for the file format as necessary.
510</P>
511<P>
512For both cases, setting normalisation to SF_FALSE means that no scaling will take place.
513</P>
514<P>
515Example:
516</P>
517<PRE>
518 sf_command (sndfile, SFC_SET_NORM_FLOAT, NULL, SF_TRUE) ;
519
520 sf_command (sndfile, SFC_SET_NORM_FLOAT, NULL, SF_FALSE) ;
521</PRE>
522<DL>
523<DT>Return value: </DT>
524 <DD>Returns the previous float normalisation mode.
525</DL>
526
527<!-- ========================================================================= -->
528<A NAME="SFC_SET_NORM_DOUBLE"></A>
529<H2><BR><B>SFC_SET_NORM_DOUBLE</B></H2>
530<P>
531This command only affects data read from or written to using the double precision
532floating point functions:
533</P>
534<PRE>
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) ;
537
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) ;
540</PRE>
541<P>
542Parameters:
543</P>
544<PRE>
545 sndfile : A valid SNDFILE* pointer
546 cmd : SFC_SET_NORM_DOUBLE
547 data : NULL
548 datasize : SF_TRUE or SF_FALSE
549</PRE>
550<P>
551For read operations setting normalisation to SF_TRUE means that the data
552from all subsequent reads will be be normalised to the range [-1.0, 1.0].
553</P>
554<P>
555For write operations, setting normalisation to SF_TRUE means than all data supplied
556to the double write functions should be in the range [-1.0, 1.0] and will be scaled
557for the file format as necessary.
558</P>
559<P>
560For both cases, setting normalisation to SF_FALSE means that no scaling will take place.
561</P>
562<P>
563Example:
564</P>
565<PRE>
566 sf_command (sndfile, SFC_SET_NORM_DOUBLE, NULL, SF_TRUE) ;
567
568 sf_command (sndfile, SFC_SET_NORM_DOUBLE, NULL, SF_FALSE) ;
569</PRE>
570<DL>
571<DT>Return value: </DT>
572 <DD>Returns the previous double normalisation mode.
573</DL>
574
575<!-- ========================================================================= -->
576<A NAME="SFC_GET_NORM_FLOAT"></A>
577<H2><BR><B>SFC_GET_NORM_FLOAT</B></H2>
578<P>
579Retrieve the current float normalisation mode.
580</P>
581<P>
582Parameters:
583</P>
584<PRE>
585 sndfile : A valid SNDFILE* pointer
586 cmd : SFC_GET_NORM_FLOAT
587 data : NULL
588 datasize : anything
589</PRE>
590<P>
591Example:
592</P>
593<PRE>
594 normalisation = sf_command (sndfile, SFC_GET_NORM_FLOAT, NULL, 0) ;
595</PRE>
596<DL>
597<DT>Return value: </DT>
598 <DD>Returns TRUE if normalisation is on and FALSE otherwise.
599</DL>
600
601<!-- ========================================================================= -->
602<A NAME="SFC_GET_NORM_DOUBLE"></A>
603<H2><BR><B>SFC_GET_NORM_DOUBLE</B></H2>
604<P>
605Retrieve the current float normalisation mode.
606</P>
607<P>
608Parameters:
609</P>
610<PRE>
611 sndfile : A valid SNDFILE* pointer
612 cmd : SFC_GET_NORM_DOUBLE
613 data : NULL
614 datasize : anything
615</PRE>
616<P>
617Example:
618</P>
619<PRE>
620 normalisation = sf_command (sndfile, SFC_GET_NORM_DOUBLE, NULL, 0) ;
621</PRE>
622<DL>
623<DT>Return value: </DT>
624 <DD>Returns TRUE if normalisation is on and FALSE otherwise.
625</DL>
626
627
628<!-- ========================================================================= -->
629<A NAME="SFC_SET_SCALE_FLOAT_INT_READ"></A>
630<H2><BR><B>SFC_SET_SCALE_FLOAT_INT_READ</B></H2>
631<P>
632Set/clear the scale factor when integer (short/int) data is read from a file
633containing floating point data.
634</P>
635<P>
636Parameters:
637</P>
638<PRE>
639 sndfile : A valid SNDFILE* pointer
640 cmd : SFC_SET_SCALE_FLOAT_INT_READ
641 data : NULL
642 datasize : TRUE or FALSE
643</PRE>
644<P>
645Example:
646</P>
647<PRE>
648 sf_command (sndfile, SFC_SET_SCALE_FLOAT_INT_READ, NULL, SF_TRUE) ;
649</PRE>
650<DL>
651<DT>Return value: </DT>
652 <DD>Returns the previous SFC_SET_SCALE_FLOAT_INT_READ setting for this file.
653</DL>
654
655
656<!-- ========================================================================= -->
657<A NAME="SFC_SET_SCALE_INT_FLOAT_WRITE"></A>
658<H2><BR><B>SFC_SET_SCALE_INT_FLOAT_WRITE</B></H2>
659<P>
660Set/clear the scale factor when integer (short/int) data is written to a file
661as floating point data.
662</P>
663<P>
664Parameters:
665</P>
666<PRE>
667 sndfile : A valid SNDFILE* pointer
668 cmd : SFC_SET_SCALE_FLOAT_INT_READ
669 data : NULL
670 datasize : TRUE or FALSE
671</PRE>
672<P>
673Example:
674</P>
675<PRE>
676 sf_command (sndfile, SFC_SET_SCALE_INT_FLOAT_WRITE, NULL, SF_TRUE) ;
677</PRE>
678<DL>
679<DT>Return value: </DT>
680 <DD>Returns the previous SFC_SET_SCALE_INT_FLOAT_WRITE setting for this file.
681</DL>
682
683<!-- ========================================================================= -->
684<A NAME="SFC_GET_SIMPLE_FORMAT_COUNT"></A>
685<H2><BR><B>SFC_GET_SIMPLE_FORMAT_COUNT</B></H2>
686<P>
687Retrieve the number of simple formats supported by libsndfile.
688</P>
689<P>
690Parameters:
691</P>
692<PRE>
693 sndfile : Not used.
694 cmd : SFC_GET_SIMPLE_FORMAT_COUNT
695 data : a pointer to an int
696 datasize : sizeof (int)
697</PRE>
698<P>
699Example:
700</P>
701<PRE>
702 int count ;
703 sf_command (sndfile, SFC_GET_SIMPLE_FORMAT_COUNT, &amp;count, sizeof (int)) ;
704</PRE>
705<DL>
706<DT>Return value: </DT>
707 <DD>0
708</DL>
709
710<!-- ========================================================================= -->
711<A NAME="SFC_GET_SIMPLE_FORMAT"></A>
712<H2><BR><B>SFC_GET_SIMPLE_FORMAT</B></H2>
713<P>
714Retrieve information about a simple format.
715</P>
716<P>
717Parameters:
718</P>
719<PRE>
720 sndfile : Not used.
721 cmd : SFC_GET_SIMPLE_FORMAT
722 data : a pointer to an SF_FORMAT_INFO struct
723 datasize : sizeof (SF_FORMAT_INFO)
724</PRE>
725<P>
726The SF_FORMAT_INFO struct is defined in &lt;sndfile.h&gt; as:
727</P>
728<PRE>
729 typedef struct
730 { int format ;
731 const char *name ;
732 const char *extension ;
733 } SF_FORMAT_INFO ;
734</PRE>
735<P>
736When sf_command() is called with SF_GET_SIMPLE_FORMAT, the value of the format
737field should be the format number (ie 0 &lt;= format &lt;= count value obtained using
738SF_GET_SIMPLE_FORMAT_COUNT).
739</P>
740<P>
741Example:
742</P>
743<PRE>
744 SF_FORMAT_INFO format_info ;
745 int k, count ;
746
747 sf_command (sndfile, SFC_GET_SIMPLE_FORMAT_COUNT, &amp;count, sizeof (int)) ;
748
749 for (k = 0 ; k &lt; count ; k++)
750 { format_info.format = k ;
751 sf_command (sndfile, SFC_GET_SIMPLE_FORMAT, &amp;format_info, sizeof (format_info)) ;
752 printf ("%08x %s %s\n", format_info.format, format_info.name, format_info.extension) ;
753 } ;
754</PRE>
755<DL>
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
760 for write.
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.
763</DL>
764
765<!-- ========================================================================= -->
766<A NAME="SFC_GET_FORMAT_INFO"></A>
767<H2><BR><B>SFC_GET_FORMAT_INFO</B></H2>
768<P>
769Retrieve information about a major or subtype format.
770</P>
771<P>
772Parameters:
773</P>
774<PRE>
775 sndfile : Not used.
776 cmd : SFC_GET_FORMAT_INFO
777 data : a pointer to an SF_FORMAT_INFO struct
778 datasize : sizeof (SF_FORMAT_INFO)
779</PRE>
780<P>
781The SF_FORMAT_INFO struct is defined in &lt;sndfile.h&gt; as:
782</P>
783<PRE>
784 typedef struct
785 { int format ;
786 const char *name ;
787 const char *extension ;
788 } SF_FORMAT_INFO ;
789</PRE>
790<P>
791When sf_command() is called with SF_GET_FORMAT_INFO, the format field is
792examined and if (format &amp; SF_FORMAT_TYPEMASK) is a valid format then the struct
793is filled in with information about the given major type.
794If (format &amp; SF_FORMAT_TYPEMASK) is FALSE and (format &amp; SF_FORMAT_SUBMASK) is a
795valid subtype format then the struct is filled in with information about the given
796subtype.
797</P>
798<P>
799Example:
800</P>
801<PRE>
802 SF_FORMAT_INFO format_info ;
803
804 format_info.format = SF_FORMAT_WAV ;
805 sf_command (sndfile, SFC_GET_FORMAT_INFO, &amp;format_info, sizeof (format_info)) ;
806 printf ("%08x %s %s\n", format_info.format, format_info.name, format_info.extension) ;
807
808 format_info.format = SF_FORMAT_ULAW ;
809 sf_command (sndfile, SFC_GET_FORMAT_INFO, &amp;format_info, sizeof (format_info)) ;
810 printf ("%08x %s\n", format_info.format, format_info.name) ;
811</PRE>
812<DL>
813<DT>Return value: </DT>
814 <DD>0 on success and non-zero otherwise.
815</DL>
816<!-- ========================================================================= -->
817<A NAME="SFC_GET_FORMAT_MAJOR_COUNT"></A>
818<H2><BR><B>SFC_GET_FORMAT_MAJOR_COUNT</B></H2>
819<P>
820Retrieve the number of major formats.
821</P>
822<P>
823Parameters:
824</P>
825<PRE>
826 sndfile : Not used.
827 cmd : SFC_GET_FORMAT_MAJOR_COUNT
828 data : a pointer to an int
829 datasize : sizeof (int)
830</PRE>
831<P>
832Example:
833</P>
834<PRE>
835 int count ;
836 sf_command (sndfile, SFC_GET_FORMAT_MAJOR_COUNT, &amp;count, sizeof (int)) ;
837</PRE>
838<DL>
839<DT>Return value: </DT>
840 <DD>0
841</DL>
842
843<!-- ========================================================================= -->
844<A NAME="SFC_GET_FORMAT_MAJOR"></A>
845<H2><BR><B>SFC_GET_FORMAT_MAJOR</B></H2>
846<P>
847Retrieve information about a major format type.
848</P>
849<P>
850Parameters:
851</P>
852<PRE>
853 sndfile : Not used.
854 cmd : SFC_GET_FORMAT_MAJOR
855 data : a pointer to an SF_FORMAT_INFO struct
856 datasize : sizeof (SF_FORMAT_INFO)
857</PRE>
858<P>
859Example:
860</P>
861<PRE>
862 SF_FORMAT_INFO format_info ;
863 int k, count ;
864
865 sf_command (sndfile, SFC_GET_FORMAT_MAJOR_COUNT, &amp;count, sizeof (int)) ;
866
867 for (k = 0 ; k &lt; count ; k++)
868 { format_info.format = k ;
869 sf_command (sndfile, SFC_GET_FORMAT_MAJOR, &amp;format_info, sizeof (format_info)) ;
870 printf ("%08x %s %s\n", format_info.format, format_info.name, format_info.extension) ;
871 } ;
872</PRE>
873<P>
874For a more comprehensive example, see the program list_formats.c in the examples/
875directory of the libsndfile source code distribution.
876</P>
877<DL>
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.
884</DL>
885
886<!-- ========================================================================= -->
887<A NAME="SFC_GET_FORMAT_SUBTYPE_COUNT"></A>
888<H2><BR><B>SFC_GET_FORMAT_SUBTYPE_COUNT</B></H2>
889<P>
890Retrieve the number of subformats.
891</P>
892<P>
893Parameters:
894</P>
895<PRE>
896 sndfile : Not used.
897 cmd : SFC_GET_FORMAT_SUBTYPE_COUNT
898 data : a pointer to an int
899 datasize : sizeof (int)
900</PRE>
901<P>
902Example:
903</P>
904<PRE>
905 int count ;
906 sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE_COUNT, &amp;count, sizeof (int)) ;
907</PRE>
908<DL>
909<DT>Return value: </DT>
910 <DD>0
911</DL>
912
913<!-- ========================================================================= -->
914<A NAME="SFC_GET_FORMAT_SUBTYPE"></A>
915<H2><BR><B>SFC_GET_FORMAT_SUBTYPE</B></H2>
916<P>
917Enumerate the subtypes (this function does not translate a subtype into
918a string describing that subtype).
919A typical use case might be retrieving a string description of all subtypes
920so that a dialog box can be filled in.
921</P>
922<P>
923
924</P>
925<P>
926Parameters:
927</P>
928<PRE>
929 sndfile : Not used.
930 cmd : SFC_GET_FORMAT_SUBTYPE
931 data : a pointer to an SF_FORMAT_INFO struct
932 datasize : sizeof (SF_FORMAT_INFO)
933</PRE>
934<P>
935Example 1: Retrieve all sybtypes supported by the WAV format.
936</P>
937<PRE>
938 SF_FORMAT_INFO format_info ;
939 int k, count ;
940
941 sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE_COUNT, &amp;count, sizeof (int)) ;
942
943 for (k = 0 ; k &lt; count ; k++)
944 { format_info.format = k ;
945 sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE, &amp;format_info, sizeof (format_info)) ;
946 if (! sf_format_check (format_info.format | SF_FORMAT_WAV))
947 continue ;
948 printf ("%08x %s\n", format_info.format, format_info.name) ;
949 } ;
950</PRE>
951<P>
952Example 2: Print a string describing the SF_FORMAT_PCM_16 subtype.
953</P>
954<PRE>
955 SF_FORMAT_INFO format_info ;
956 int k, count ;
957
958 sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE_COUNT, &amp;count, sizeof (int)) ;
959
960 for (k = 0 ; k &lt; count ; k++)
961 { format_info.format = k ;
962 sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE, &amp;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) ;
965 break ;
966 } ;
967 } ;
968</PRE>
969<P>
970For a more comprehensive example, see the program list_formats.c in the examples/
971directory of the libsndfile source code distribution.
972</P>
973<DL>
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.
981</DL>
982
983<!-- ========================================================================= -->
984<A NAME="SFC_SET_ADD_PEAK_CHUNK"></A>
985<H2><BR><B>SFC_SET_ADD_PEAK_CHUNK</B></H2>
986<P>
987By default, WAV and AIFF files which contain floating point data (subtype SF_FORMAT_FLOAT
988or SF_FORMAT_DOUBLE) have a PEAK chunk.
989By using this command, the addition of a PEAK chunk can be turned on or off.
990</P>
991<P>
992Note : This call must be made before any data is written to the file.
993</P>
994<P>
995Parameters:
996<PRE>
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.
1001</PRE>
1002<P>
1003Example:
1004</P>
1005<PRE>
1006 /* Turn on the PEAK chunk. */
1007 sf_command (sndfile, SFC_SET_ADD_PEAK_CHUNK, NULL, SF_TRUE) ;
1008
1009 /* Turn off the PEAK chunk. */
1010 sf_command (sndfile, SFC_SET_ADD_PEAK_CHUNK, NULL, SF_FALSE) ;
1011</PRE>
1012<DL>
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.
1016</DL>
1017
1018<!-- ========================================================================= -->
1019<A NAME="SFC_UPDATE_HEADER_NOW"></A>
1020<H2><BR><B>SFC_UPDATE_HEADER_NOW</B></H2>
1021<P>
1022The header of an audio file is normally written by libsndfile when the file is
1023closed using <B>sf_close()</B>.
1024</P>
1025<P>
1026There are however situations where large files are being generated and it would
1027be nice to have valid data in the header before the file is complete.
1028Using this command will update the file header to reflect the amount of data written
1029to the file so far.
1030Other programs opening the file for read (before any more data is written) will
1031then read a valid sound file header.
1032</P>
1033<P>
1034Parameters:
1035<PRE>
1036 sndfile : A valid SNDFILE* pointer
1037 cmd : SFC_UPDATE_HEADER_NOW
1038 data : Not used (should be NULL)
1039 datasize : Not used.
1040</PRE>
1041<P>
1042Example:
1043</P>
1044<PRE>
1045 /* Update the header now. */
1046 sf_command (sndfile, SFC_UPDATE_HEADER_NOW, NULL, 0) ;
1047</PRE>
1048<DL>
1049<DT>Return value:</DT>
1050<DD>0
1051</DL>
1052
1053<!-- ========================================================================= -->
1054<A NAME="SFC_SET_UPDATE_HEADER_AUTO"></A>
1055<H2><BR><B>SFC_SET_UPDATE_HEADER_AUTO</B></H2>
1056<P>
1057Similar to SFC_UPDATE_HEADER_NOW but updates the header at the end of every call
1058to the <B>sf_write*</B> functions.
1059</P>
1060<P>
1061Parameters:
1062<PRE>
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
1067</PRE>
1068<P>
1069Example:
1070</P>
1071<PRE>
1072 /* Turn on auto header update. */
1073 sf_command (sndfile, SFC_SET_UPDATE_HEADER_AUTO, NULL, SF_TRUE) ;
1074
1075 /* Turn off auto header update. */
1076 sf_command (sndfile, SFC_SET_UPDATE_HEADER_AUTO, NULL, SF_FALSE) ;
1077</PRE>
1078<DL>
1079<DT>Return value:</DT>
1080<DD>TRUE if auto update header is now on; FALSE otherwise.
1081</DL>
1082
1083<!-- ========================================================================= -->
1084<A NAME="SFC_FILE_TRUNCATE"></A>
1085<H2><BR><B>SFC_FILE_TRUNCATE</B></H2>
1086<P>
1087Truncate a file that was opened for write or read/write.
1088</P>
1089<P>
1090Parameters:
1091<PRE>
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)
1096</PRE>
1097
1098<P>
1099Truncate the file to the number of frames specified by the sf_count_t pointed
1100to by data.
1101After this command, both the read and the write pointer will be
1102at the new end of the file.
1103This command will fail (returning non-zero) if the requested truncate position
1104is beyond the end of the file.
1105</P>
1106<P>
1107Example:
1108</P>
1109<PRE>
1110 /* Truncate the file to a length of 20 frames. */
1111 sf_count_t frames = 20 ;
1112 sf_command (sndfile, SFC_FILE_TRUNCATE, &amp;frames, sizeof (frames)) ;
1113</PRE>
1114<DL>
1115<DT>Return value:</DT>
1116 <DD>Zero on sucess, non-zero otherwise.
1117</DL>
1118
1119<!-- ========================================================================= -->
1120<A NAME="SFC_SET_RAW_START_OFFSET"></A>
1121<H2><BR><B>SFC_SET_RAW_START_OFFSET</B></H2>
1122<P>
1123Change the data start offset for files opened up as SF_FORMAT_RAW.
1124</P>
1125<P>
1126Parameters:
1127<PRE>
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)
1132</PRE>
1133
1134<P>
1135For a file opened as format SF_FORMAT_RAW, set the data offset to the value
1136given by data.
1137</P>
1138<P>
1139Example:
1140</P>
1141<PRE>
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, &amp;offset, sizeof (offset)) ;
1145</PRE>
1146<DL>
1147<DT>Return value:</DT>
1148 <DD>Zero on success, non-zero otherwise.
1149</DL>
1150
1151<!-- ========================================================================= -->
1152<A NAME="SFC_SET_CLIPPING"></A>
1153<H2><BR><B>SFC_SET_CLIPPING</B></H2>
1154<P>
1155Turn on/off automatic clipping when doing floating point to integer conversion.
1156</P>
1157<P>
1158Parameters:
1159<PRE>
1160 sndfile : A valid SNDFILE* pointer
1161 cmd : SFC_SET_CLIPPING
1162 data : NULL
1163 datasize : SF_TRUE or SF_FALSE.
1164</PRE>
1165
1166<P>
1167Turn on (datasize == SF_TRUE) or off (datasize == SF_FALSE) clipping.
1168</P>
1169<P>
1170Example:
1171</P>
1172<PRE>
1173 sf_command (sndfile, SFC_SET_CLIPPING, NULL, SF_TRUE) ;
1174</PRE>
1175<DL>
1176<DT>Return value:</DT>
1177 <DD>Clipping mode (SF_TRUE or SF_FALSE).
1178</DL>
1179
1180
1181<!-- ========================================================================= -->
1182<A NAME="SFC_GET_CLIPPING"></A>
1183<H2><BR><B>SFC_GET_CLIPPING</B></H2>
1184<P>
1185Turn on/off automatic clipping when doing floating point to integer conversion.
1186</P>
1187<P>
1188Parameters:
1189<PRE>
1190 sndfile : A valid SNDFILE* pointer
1191 cmd : SFC_GET_CLIPPING
1192 data : NULL
1193 datasize : 0
1194</PRE>
1195
1196<P>
1197Retrieve the current cliiping setting.
1198</P>
1199<P>
1200Example:
1201</P>
1202<PRE>
1203 sf_command (sndfile, SFC_GET_CLIPPING, NULL, 0) ;
1204</PRE>
1205<DL>
1206<DT>Return value:</DT>
1207 <DD>Clipping mode (SF_TRUE or SF_FALSE).
1208</DL>
1209
1210<!-- ========================================================================= -->
1211<A NAME="SFC_GET_EMBED_FILE_INFO"></A>
1212<H2><BR><B>SFC_GET_EMBED_FILE_INFO</B></H2>
1213<P>
1214Get the file offset and file length of a file enbedded within another
1215larger file.
1216</P>
1217<P>
1218Parameters:
1219<PRE>
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)
1224</PRE>
1225<P>
1226The SF_EMBED_FILE_INFO struct is defined in &lt;sndfile.h&gt; as:
1227</P>
1228<PRE>
1229 typedef struct
1230 { sf_count_t offset ;
1231 sf_count_t length ;
1232 } SF_EMBED_FILE_INFO ;
1233</PRE>
1234<DL>
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
1239 the audio file.
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.
1242</DL>
1243
1244
1245
1246<!-- ========================================================================= -->
1247<A NAME="SFC_WAVEX_GET_AMBISONIC"></A>
1248<H2><BR><B>SFC_WAVEX_GET_AMBISONIC</B></H2>
1249<P>
1250Test if the current file has the GUID of a WAVEX file for any of the Ambisonic
1251formats.
1252</P>
1253<P>
1254Parameters:
1255<PRE>
1256 sndfile : A valid SNDFILE* pointer
1257 cmd : SFC_WAVEX_GET_AMBISONIC
1258 data : NULL
1259 datasize : 0
1260</PRE>
1261<P>
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>.
1265</P>
1266<DL>
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.
1270</DL>
1271
1272<!-- ========================================================================= -->
1273<A NAME="SFC_WAVEX_SET_AMBISONIC"></A>
1274<H2><BR><B>SFC_WAVEX_SET_AMBISONIC</B></H2>
1275<P>
1276Set the GUID of a new WAVEX file to indicate an Ambisonics format.
1277</P>
1278<P>
1279Parameters:
1280<PRE>
1281 sndfile : A valid SNDFILE* pointer
1282 cmd : SFC_WAVEX_SET_AMBISONIC
1283 data : NULL
1284 datasize : SF_AMBISONIC_NONE or SF_AMBISONIC_B_FORMAT
1285</PRE>
1286<P>
1287Turn on (SF_AMBISONIC_B_FORMAT) or off (SF_AMBISONIC_NONE) encoding.
1288This command is currently only supported for files with SF_FORMAT_WAVEX format.
1289</P>
1290<P>
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>.
1294</P>
1295<DL>
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.
1299</DL>
1300
1301<!-- ========================================================================= -->
1302<A NAME="SFC_SET_VBR_ENCODING_QUALITY"></A>
1303<H2><BR><B>SFC_SET_VBR_ENCODING_QUALITY</B></H2>
1304<P>
1305Set the the Variable Bit Rate encoding quality.
1306The encoding quality value should be between 0.0 (lowest quality) and 1.0
1307(highest quality).
1308</P>
1309<P>
1310Parameters:
1311<PRE>
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)
1316</PRE>
1317<P>
1318The command must be sent before any audio data is written to the file.
1319</P>
1320<P>
1321</P>
1322<DL>
1323<DT>Return value: </DT>
1324 <DD>Zero on success, non-zero otherwise.
1325</DL>
1326
1327<!-- ========================================================================= -->
1328<A NAME="SFC_RAW_NEEDS_ENDSWAP"></A>
1329<H2><BR><B>SFC_RAW_NEEDS_ENDSWAP</B></H2>
1330<P>
1331Determine if raw data read using
1332 <a href="api.html#raw">
1333 sf_read_raw</a>
1334needs to be end swapped on the host CPU.
1335</P>
1336<P>
1337For instance, will return SF_TRUE on when reading WAV containing
1338SF_FORMAT_PCM_16 data on a big endian machine and SF_FALSE on a little endian
1339machine.
1340</P>
1341<P>
1342Parameters:
1343<PRE>
1344 sndfile : A valid SNDFILE* pointer
1345 cmd : SFC_RAW_NEEDS_ENDSWAP
1346 data : NULL
1347 datasize : 0
1348</PRE>
1349
1350<DL>
1351<DT>Return value: </DT>
1352 <DD>SF_TRUE or SF_FALSE
1353</DL>
1354
1355
1356<!-- ========================================================================= -->
1357<A NAME="SFC_GET_BROADCAST_INFO"></A>
1358<H2><BR><B>SFC_GET_BROADCAST_INFO</B></H2>
1359<P>
1360Retrieve the Broadcast Extension Chunk from WAV (and related) files.
1361</P>
1362<p>
1363Parameters:
1364</p>
1365<PRE>
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)
1370</PRE>
1371<P>
1372The SF_BROADCAST_INFO struct is defined in &lt;sndfile.h&gt; as:
1373</P>
1374<PRE>
1375 typedef struct
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 ;
1383 short version ;
1384 char umid [64] ;
1385 char reserved [190] ;
1386 unsigned int coding_history_size ;
1387 char coding_history [256] ;
1388 } SF_BROADCAST_INFO ;
1389</PRE>
1390
1391<DL>
1392<DT>Return value: </DT>
1393 <DD>SF_TRUE if the file contained a Broadcast Extension chunk or SF_FALSE
1394 otherwise.
1395</DL>
1396
1397<!-- ========================================================================= -->
1398<A NAME="SFC_SET_BROADCAST_INFO"></A>
1399<H2><BR><B>SFC_SET_BROADCAST_INFO</B></H2>
1400<P>
1401Set the Broadcast Extension Chunk for WAV (and related) files.
1402</P>
1403<p>
1404Parameters:
1405</p>
1406<PRE>
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)
1411</PRE>
1412
1413<DL>
1414<DT>Return value: </DT>
1415 <DD>SF_TRUE if setting the Broadcast Extension chunk was successful and SF_FALSE
1416 otherwise.
1417</DL>
1418<!-- ========================================================================= -->
1419
1420<A NAME="SFC_GET_LOOP_INFO"></A>
1421<H2><BR><B>SFC_GET_LOOP_INFO</B></H2>
1422<P>
1423Retrieve loop information for file including time signature, length in
1424beats and original MIDI base note
1425</P>
1426<p>
1427Parameters:
1428</p>
1429<PRE>
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)
1434</PRE>
1435<P>
1436The SF_BROADCAST_INFO struct is defined in &lt;sndfile.h&gt; as:
1437</P>
1438<PRE>
1439 typedef struct
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 */
1443
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 */
1447
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 */
1451
1452 int root_key ; /* MIDI note, or -1 for None */
1453 int future [6] ;
1454 } SF_LOOP_INFO ;
1455</PRE>
1456<P>
1457Example:
1458</P>
1459<PRE>
1460 SF_LOOP_INFO loop;
1461 sf_command (sndfile, SFC_GET_LOOP_INFO, &amp;loop, sizeof (loop)) ;
1462</PRE>
1463<DL>
1464<DT>Return value:</DT>
1465 <DD>SF_TRUE if the file header contains loop information for the file.
1466 SF_FALSE otherwise.
1467</DL>
1468
1469<!-- ========================================================================= -->
1470
1471
1472<A NAME="SFC_GET_INSTRUMENT"></A>
1473<H2><BR><B>SFC_GET_INSTRUMENT</B></H2>
1474<P>
1475Retrieve instrument information from file including MIDI base note,
1476keyboard mapping and looping informations(start/stop and mode).
1477</P>
1478<p>
1479Parameters:
1480</p>
1481<PRE>
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)
1486</PRE>
1487
1488<P>
1489The SF_INSTRUMENT struct is defined in &lt;sndfile.h&gt; as:
1490</P>
1491<PRE>
1492 enum
1493 { /*
1494 ** The loop mode field in SF_INSTRUMENT will be one of the following.
1495 */
1496 SF_LOOP_NONE = 800,
1497 SF_LOOP_FORWARD,
1498 SF_LOOP_BACKWARD,
1499 SF_LOOP_ALTERNATING
1500 } ;
1501
1502 typedef struct
1503 { int gain ;
1504 char basenote, detune ;
1505 char velocity_lo, velocity_hi ;
1506 char key_lo, key_hi ;
1507 int loop_count ;
1508
1509 struct
1510 { int mode ;
1511 unsigned int start ;
1512 unsigned int end ;
1513 unsigned int count ;
1514 } loops [16] ; /* make variable in a sensible way */
1515 } SF_INSTRUMENT ;
1516</PRE>
1517
1518<P>
1519Example:
1520</P>
1521<PRE>
1522 SF_INSTRUMENT inst ;
1523 sf_command (sndfile, SFC_GET_INSTRUMENT, &amp;inst, sizeof (inst)) ;
1524</PRE>
1525<DL>
1526<DT>Return value:</DT>
1527 <dd>SF_TRUE if the file header contains instrument information for the
1528 file. SF_FALSE otherwise.
1529</DL>
1530
1531<!-- ========================================================================= -->
1532
1533
1534<A NAME="SFC_SET_INSTRUMENT"></A>
1535<H2><BR><B>SFC_SET_INSTRUMENT</B></H2>
1536<P>
1537Set the instrument information for the file.
1538</P>
1539<p>
1540Parameters:
1541</p>
1542<PRE>
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)
1547</PRE>
1548<P>
1549Example:
1550</P>
1551<PRE>
1552 SF_INSTRUMENT inst ;
1553 sf_command (sndfile, SFC_SET_INSTRUMENT, &amp;inst, sizeof (inst)) ;
1554</PRE>
1555<DL>
1556<DT>Return value:</DT>
1557 <dd>SF_TRUE if the file header contains instrument information for the
1558 file. SF_FALSE otherwise.
1559</DL>
1560
1561<!-- ========================================================================= -->
1562
1563
1564<A NAME="SFC_SET_VBR_ENCODING_QUALITY"></A>
1565<H2><BR><B>SFC_SET_VBR_ENCODING_QUALITY</B></H2>
1566<P>
1567Set the Variable Bite Rate encoding quality.
1568Currenly only implemented fro Ogg/Vorbis files.
1569</P>
1570<p>
1571Parameters:
1572</p>
1573<PRE>
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)
1578</PRE>
1579<P>
1580Example:
1581</P>
1582<PRE>
1583 double quality = 0.5 ;
1584 sf_command (sndfile, SFC_SET_VBR_ENCODING_QUALITY, &amp;quality, sizeof (double)) ;
1585</PRE>
1586<DL>
1587<DT>Return value:</DT>
1588 <dd>SF_TRUE if VBR encoding quality was set.
1589 SF_FALSE otherwise.
1590</DL>
1591
1592<!-- ========================================================================= -->
1593
1594
1595<HR>
1596<P>
1597 The libsndfile home page is here :
1598 <A HREF="http://www.mega-nerd.com/libsndfile/">
1599 http://www.mega-nerd.com/libsndfile/</A>.
1600<BR>
1601Version : 1.0.25
1602</P>
1603
1604</BODY>
1605</HTML>