Mercurial > hg > sv-dependency-builds

comparison src/libsndfile-1.0.25/doc/command.html @ 0:c7265573341e

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import initial set of sources
author Chris Cannam
date Mon, 18 Mar 2013 14:12:14 +0000
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:c7265573341e
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>
248 Retrieve the version of the library as a string.
249 </P>
250 <P>
251 Parameters:
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>
259 Example:
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>
273 The string returned in the buffer passed to this function will not overflow
274 the 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>
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
283 particular file.
284 </P>
285 <P>
286 Parameters:
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>
294 Example:
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>
308 The string returned in the buffer passed to this function will not overflow
309 the 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>
316 Retrieve the measured maximum signal value. This involves reading through
317 the whole file which can be slow on large files.
318 </P>
319 <P>
320 Parameters:
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>
328 Example:
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>
344 Retrieve the measured normalised maximum signal value. This involves reading
345 through the whole file which can be slow on large files.
346 </P>
347 <P>
348 Parameters:
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>
356 Example:
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>
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.
374 </P>
375 <P>
376 Parameters:
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>
384 Example:
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>
400 Calculate the normalised peak for each channel.
401 This involves reading through the whole file which can be slow on large files.
402 </P>
403 <P>
404 Parameters:
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>
412 Example:
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>
430 Retrieve the peak value for the file as stored in the file header.
431 </P>
432 <P>
433 Parameters:
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>
441 Example:
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>
456 Retrieve the peak value for the file as stored in the file header.
457 </P>
458 <P>
459 Parameters:
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>
467 Example:
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>
484 This 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>
494 Parameters:
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>
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].
505 </P>
506 <P>
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.
510 </P>
511 <P>
512 For both cases, setting normalisation to SF_FALSE means that no scaling will take place.
513 </P>
514 <P>
515 Example:
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>
531 This command only affects data read from or written to using the double precision
532 floating 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>
542 Parameters:
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>
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].
553 </P>
554 <P>
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.
558 </P>
559 <P>
560 For both cases, setting normalisation to SF_FALSE means that no scaling will take place.
561 </P>
562 <P>
563 Example:
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>
579 Retrieve the current float normalisation mode.
580 </P>
581 <P>
582 Parameters:
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>
591 Example:
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>
605 Retrieve the current float normalisation mode.
606 </P>
607 <P>
608 Parameters:
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>
617 Example:
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>
632 Set/clear the scale factor when integer (short/int) data is read from a file
633 containing floating point data.
634 </P>
635 <P>
636 Parameters:
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>
645 Example:
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>
660 Set/clear the scale factor when integer (short/int) data is written to a file
661 as floating point data.
662 </P>
663 <P>
664 Parameters:
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>
673 Example:
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>
687 Retrieve the number of simple formats supported by libsndfile.
688 </P>
689 <P>
690 Parameters:
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>
699 Example:
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>
714 Retrieve information about a simple format.
715 </P>
716 <P>
717 Parameters:
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>
726 The 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>
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 &lt;= format &lt;= count value obtained using
738 SF_GET_SIMPLE_FORMAT_COUNT).
739 </P>
740 <P>
741 Example:
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>
769 Retrieve information about a major or subtype format.
770 </P>
771 <P>
772 Parameters:
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>
781 The 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>
791 When sf_command() is called with SF_GET_FORMAT_INFO, the format field is
792 examined and if (format &amp; SF_FORMAT_TYPEMASK) is a valid format then the struct
793 is filled in with information about the given major type.
794 If (format &amp; SF_FORMAT_TYPEMASK) is FALSE and (format &amp; SF_FORMAT_SUBMASK) is a
795 valid subtype format then the struct is filled in with information about the given
796 subtype.
797 </P>
798 <P>
799 Example:
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>
820 Retrieve the number of major formats.
821 </P>
822 <P>
823 Parameters:
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>
832 Example:
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>
847 Retrieve information about a major format type.
848 </P>
849 <P>
850 Parameters:
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>
859 Example:
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>
874 For a more comprehensive example, see the program list_formats.c in the examples/
875 directory 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>
890 Retrieve the number of subformats.
891 </P>
892 <P>
893 Parameters:
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>
902 Example:
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>
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.
921 </P>
922 <P>
923
924 </P>
925 <P>
926 Parameters:
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>
935 Example 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>
952 Example 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>
970 For a more comprehensive example, see the program list_formats.c in the examples/
971 directory 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>
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.
990 </P>
991 <P>
992 Note : This call must be made before any data is written to the file.
993 </P>
994 <P>
995 Parameters:
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>
1003 Example:
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>
1022 The header of an audio file is normally written by libsndfile when the file is
1023 closed using <B>sf_close()</B>.
1024 </P>
1025 <P>
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
1029 to the file so far.
1030 Other programs opening the file for read (before any more data is written) will
1031 then read a valid sound file header.
1032 </P>
1033 <P>
1034 Parameters:
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>
1042 Example:
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>
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.
1059 </P>
1060 <P>
1061 Parameters:
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>
1069 Example:
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>
1087 Truncate a file that was opened for write or read/write.
1088 </P>
1089 <P>
1090 Parameters:
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>
1099 Truncate the file to the number of frames specified by the sf_count_t pointed
1100 to by data.
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.
1105 </P>
1106 <P>
1107 Example:
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>
1123 Change the data start offset for files opened up as SF_FORMAT_RAW.
1124 </P>
1125 <P>
1126 Parameters:
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>
1135 For a file opened as format SF_FORMAT_RAW, set the data offset to the value
1136 given by data.
1137 </P>
1138 <P>
1139 Example:
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>
1155 Turn on/off automatic clipping when doing floating point to integer conversion.
1156 </P>
1157 <P>
1158 Parameters:
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>
1167 Turn on (datasize == SF_TRUE) or off (datasize == SF_FALSE) clipping.
1168 </P>
1169 <P>
1170 Example:
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>
1185 Turn on/off automatic clipping when doing floating point to integer conversion.
1186 </P>
1187 <P>
1188 Parameters:
1189 <PRE>
1190 sndfile : A valid SNDFILE* pointer
1191 cmd : SFC_GET_CLIPPING
1192 data : NULL
1193 datasize : 0
1194 </PRE>
1195
1196 <P>
1197 Retrieve the current cliiping setting.
1198 </P>
1199 <P>
1200 Example:
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>
1214 Get the file offset and file length of a file enbedded within another
1215 larger file.
1216 </P>
1217 <P>
1218 Parameters:
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>
1226 The 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>
1250 Test if the current file has the GUID of a WAVEX file for any of the Ambisonic
1251 formats.
1252 </P>
1253 <P>
1254 Parameters:
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>
1276 Set the GUID of a new WAVEX file to indicate an Ambisonics format.
1277 </P>
1278 <P>
1279 Parameters:
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>
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.
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>
1305 Set the the Variable Bit Rate encoding quality.
1306 The encoding quality value should be between 0.0 (lowest quality) and 1.0
1307 (highest quality).
1308 </P>
1309 <P>
1310 Parameters:
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>
1318 The 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>
1331 Determine if raw data read using
1332 <a href="api.html#raw">
1333 sf_read_raw</a>
1334 needs to be end swapped on the host CPU.
1335 </P>
1336 <P>
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
1339 machine.
1340 </P>
1341 <P>
1342 Parameters:
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>
1360 Retrieve the Broadcast Extension Chunk from WAV (and related) files.
1361 </P>
1362 <p>
1363 Parameters:
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>
1372 The 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>
1401 Set the Broadcast Extension Chunk for WAV (and related) files.
1402 </P>
1403 <p>
1404 Parameters:
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>
1423 Retrieve loop information for file including time signature, length in
1424 beats and original MIDI base note
1425 </P>
1426 <p>
1427 Parameters:
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>
1436 The 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>
1457 Example:
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>
1475 Retrieve instrument information from file including MIDI base note,
1476 keyboard mapping and looping informations(start/stop and mode).
1477 </P>
1478 <p>
1479 Parameters:
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>
1489 The 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>
1519 Example:
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>
1537 Set the instrument information for the file.
1538 </P>
1539 <p>
1540 Parameters:
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>
1549 Example:
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>
1567 Set the Variable Bite Rate encoding quality.
1568 Currenly only implemented fro Ogg/Vorbis files.
1569 </P>
1570 <p>
1571 Parameters:
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>
1580 Example:
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>
1601 Version : 1.0.25
1602 </P>
1603
1604 </BODY>
1605 </HTML>