Mercurial > hg > sv-dependency-builds

comparison src/libsndfile-1.0.27/doc/command.html @ 125:cd6cdf86811e

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Current libsndfile source
author Chris Cannam <cannam@all-day-breakfast.com>
date Tue, 18 Oct 2016 13:22:47 +0100
parents
children
comparison
equal deleted inserted replaced
124:e3d5853d5918 125:cd6cdf86811e
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 Variable Bit Rate encoding quality</TD>
192 </TR>
193
194 <TR>
195 <TD><A HREF="#SFC_SET_COMPRESSION_LEVEL">SFC_SET_COMPRESSION_LEVEL</A></TD>
196 <TD>Set the compression level.</TD>
197 </TR>
198
199 <TR>
200 <TD><A HREF="#SFC_RAW_NEEDS_ENDSWAP">SFC_RAW_NEEDS_ENDSWAP</a></td>
201 <TD>Determine if raw data needs endswapping</TD>
202 </TR>
203
204 <TR>
205 <TD><A HREF="#SFC_GET_BROADCAST_INFO">SFC_GET_BROADCAST_INFO</A></TD>
206 <TD>Retrieve the Broadcast Chunk info</TD>
207 </TR>
208
209 <TR>
210 <TD><A HREF="#SFC_SET_BROADCAST_INFO">SFC_SET_BROADCAST_INFO</A></TD>
211 <TD>Set the Broadcast Chunk info</TD>
212 </TR>
213
214 <TR>
215 <TD><A HREF="#SFC_SET_CART_INFO">SFC_SET_CART_INFO</A></TD>
216 <TD>Set the Cart Chunk info</TD>
217 </TR>
218
219 <TR>
220 <TD><A HREF="#SFC_GET_CART_INFO">SFC_GET_CART_INFO</A></TD>
221 <TD>Retrieve the Cart Chunk info</TD>
222 </TR>
223
224 <TR>
225 <TD><A HREF="#SFC_GET_LOOP_INFO">SFC_GET_LOOP_INFO</A></TD>
226 <TD>Get loop info</TD>
227 </TR>
228
229 <TR>
230 <TD><A HREF="#SFC_GET_INSTRUMENT">SFC_GET_INSTRUMENT</A></TD>
231 <TD>Get instrument info</TD>
232 </TR>
233
234 <TR>
235 <TD><A HREF="#SFC_SET_INSTRUMENT">SFC_SET_INSTRUMENT</A></TD>
236 <TD>Set instrument info</TD>
237 </TR>
238
239 <TR>
240 <TD><A HREF="#SFC_GET_CUE_COUNT">SFC_GET_CUE_COUNT</A></TD>
241 <TD>Get the cue marker count</TD>
242 </TR>
243
244 <TR>
245 <TD><A HREF="#SFC_GET_CUE">SFC_GET_CUE</A></TD>
246 <TD>Get cue marker info</TD>
247 </TR>
248
249 <TR>
250 <TD><A HREF="#SFC_SET_CUE">SFC_SET_CUE</A></TD>
251 <TD>Set cue marker info</TD>
252 </TR>
253
254 <TR>
255 <TD><A HREF="#SFC_RF64_AUTO_DOWNGRADE">SFC_RF64_AUTO_DOWNGRADE</A></TD>
256 <TD>Enable auto downgrade from RF64 to WAV</TD>
257 </TR>
258
259 <!--
260 <TR>
261 <TD><A HREF="#add-dither">add dither</A></TD>
262 <TD>Add dither to output on write.</TD>
263 </TR>
264 -->
265 </TABLE>
266 </CENTER>
267
268 <BR><BR>
269
270 <HR>
271
272 <!-- ========================================================================= -->
273 <A NAME="SFC_GET_LIB_VERSION"></A>
274 <H2><BR><B>SFC_GET_LIB_VERSION</B></H2>
275 <P>
276 Retrieve the version of the library as a string.
277 </P>
278 <P>
279 Parameters:
280 <PRE>
281 sndfile : Not used
282 cmd : SFC_GET_LIB_VERSION
283 data : A pointer to a char buffer
284 datasize : The size of the buffer
285 </PRE>
286 <P>
287 Example:
288 </P>
289 <PRE>
290 char buffer [128] ;
291 sf_command (NULL, SFC_GET_LIB_VERSION, buffer, sizeof (buffer)) ;
292 </PRE>
293
294 <DL>
295 <DT>Return value:</DT>
296 <DD><DD>This call will return the length of the retrieved version string.
297 </DL>
298 <DL>
299 <DT>Notes:</DT>
300 <DD>
301 The string returned in the buffer passed to this function will not overflow
302 the buffer and will always be null terminated .
303 </DL>
304
305 <!-- ========================================================================= -->
306 <A NAME="SFC_GET_LOG_INFO"></A>
307 <H2><BR><B>SFC_GET_LOG_INFO</B></H2>
308 <P>
309 Retrieve the log buffer generated when opening a file as a string. This log
310 buffer can often contain a good reason for why libsndfile failed to open a
311 particular file.
312 </P>
313 <P>
314 Parameters:
315 <PRE>
316 sndfile : A valid SNDFILE* pointer
317 cmd : SFC_GET_LOG_INFO
318 data : A pointer to a char buffer
319 datasize : The size of the buffer
320 </PRE>
321 <P>
322 Example:
323 </P>
324 <PRE>
325 char buffer [2048] ;
326 sf_command (sndfile, SFC_GET_LOG_INFO, buffer, sizeof (buffer)) ;
327 </PRE>
328
329 <DL>
330 <DT>Return value:</DT>
331 <DD><DD>This call will return the length of the retrieved version string.
332 </DL>
333 <DL>
334 <DT>Notes:</DT>
335 <DD>
336 The string returned in the buffer passed to this function will not overflow
337 the buffer and will always be null terminated .
338 </DL>
339
340 <!-- ========================================================================= -->
341 <A NAME="SFC_CALC_SIGNAL_MAX"></A>
342 <H2><BR><B>SFC_CALC_SIGNAL_MAX</B></H2>
343 <P>
344 Retrieve the measured maximum signal value. This involves reading through
345 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_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_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_NORM_SIGNAL_MAX"></A>
370 <H2><BR><B>SFC_CALC_NORM_SIGNAL_MAX</B></H2>
371 <P>
372 Retrieve the measured normalised maximum signal value. This involves reading
373 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_NORM_SIGNAL_MAX
380 data : A pointer to a double
381 datasize : sizeof (double)
382 </PRE>
383 <P>
384 Example:
385 </P>
386 <PRE>
387 double max_val ;
388 sf_command (sndfile, SFC_CALC_NORM_SIGNAL_MAX, &amp;max_val, sizeof (max_val)) ;
389 </PRE>
390
391 <DL>
392 <DT>Return value:</DT>
393 <DD><DD>Zero on success, non-zero otherwise.
394 </DL>
395
396 <!-- ========================================================================= -->
397 <A NAME="SFC_CALC_MAX_ALL_CHANNELS"></A>
398 <H2><BR><B>SFC_CALC_MAX_ALL_CHANNELS</B></H2>
399 <P>
400 Calculate the peak value (ie a single number) 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_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_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 <A NAME="SFC_CALC_NORM_MAX_ALL_CHANNELS"></A>
426 <H2><BR><B>SFC_CALC_NORM_MAX_ALL_CHANNELS</B></H2>
427 <P>
428 Calculate the normalised peak for each channel.
429 This involves reading through the whole file which can be slow on large files.
430 </P>
431 <P>
432 Parameters:
433 <PRE>
434 sndfile : A valid SNDFILE* pointer
435 cmd : SFC_CALC_NORM_MAX_ALL_CHANNELS
436 data : A pointer to a double
437 datasize : sizeof (double) * number_of_channels
438 </PRE>
439 <P>
440 Example:
441 </P>
442 <PRE>
443 double peaks [number_of_channels] ;
444 sf_command (sndfile, SFC_CALC_NORM_MAX_ALL_CHANNELS, peaks, sizeof (peaks)) ;
445 </PRE>
446 <DL>
447 <DT>Return value:</DT>
448 <DD>Zero if peaks have been calculated successfully and non-zero otherwise.
449 </DL>
450
451
452
453
454 <!-- ========================================================================= -->
455 <A NAME="SFC_GET_SIGNAL_MAX"></A>
456 <H2><BR><B>SFC_GET_SIGNAL_MAX</B></H2>
457 <P>
458 Retrieve the peak value for the file as stored in the file header.
459 </P>
460 <P>
461 Parameters:
462 <PRE>
463 sndfile : A valid SNDFILE* pointer
464 cmd : SFC_GET_SIGNAL_MAX
465 data : A pointer to a double
466 datasize : sizeof (double)
467 </PRE>
468 <P>
469 Example:
470 </P>
471 <PRE>
472 double max_peak ;
473 sf_command (sndfile, SFC_GET_SIGNAL_MAX, &amp;max_peak, sizeof (max_peak)) ;
474 </PRE>
475 <DL>
476 <DT>Return value:</DT>
477 <DD>SF_TRUE if the file header contained the peak value. SF_FALSE otherwise.
478 </DL>
479
480 <!-- ========================================================================= -->
481 <A NAME="SFC_GET_MAX_ALL_CHANNELS"></A>
482 <H2><BR><B>SFC_GET_MAX_ALL_CHANNELS</B></H2>
483 <P>
484 Retrieve the peak value for the file as stored in the file header.
485 </P>
486 <P>
487 Parameters:
488 <PRE>
489 sndfile : A valid SNDFILE* pointer
490 cmd : SFC_GET_SIGNAL_MAX
491 data : A pointer to an array of doubles
492 datasize : sizeof (double) * number_of_channels
493 </PRE>
494 <P>
495 Example:
496 </P>
497 <PRE>
498 double peaks [number_of_channels] ;
499 sf_command (sndfile, SFC_GET_MAX_ALL_CHANNELS, peaks, sizeof (peaks)) ;
500 </PRE>
501 <DL>
502 <DT>Return value:</DT>
503 <DD>SF_TRUE if the file header contains per channel peak values for the file.
504 SF_FALSE otherwise.
505 </DL>
506
507
508 <!-- ========================================================================= -->
509 <A NAME="SFC_SET_NORM_FLOAT"></A>
510 <H2><BR><B>SFC_SET_NORM_FLOAT</B></H2>
511 <P>
512 This command only affects data read from or written to using the floating point functions:
513 </P>
514 <PRE>
515 size_t <A HREF="api.html#read">sf_read_float</A> (SNDFILE *sndfile, float *ptr, size_t items) ;
516 size_t <A HREF="api.html#readf">sf_readf_float</A> (SNDFILE *sndfile, float *ptr, size_t frames) ;
517
518 size_t <A HREF="api.html#write">sf_write_float</A> (SNDFILE *sndfile, float *ptr, size_t items) ;
519 size_t <A HREF="api.html#writef">sf_writef_float</A> (SNDFILE *sndfile, float *ptr, size_t frames) ;
520 </PRE>
521 <P>
522 Parameters:
523 </P>
524 <PRE>
525 sndfile : A valid SNDFILE* pointer
526 cmd : SFC_SET_NORM_FLOAT
527 data : NULL
528 datasize : SF_TRUE or SF_FALSE
529 </PRE>
530 <P>
531 For read operations setting normalisation to SF_TRUE means that the data from all
532 subsequent reads will be be normalised to the range [-1.0, 1.0].
533 </P>
534 <P>
535 For write operations, setting normalisation to SF_TRUE means than all data supplied
536 to the float write functions should be in the range [-1.0, 1.0] and will be scaled
537 for the file format as necessary.
538 </P>
539 <P>
540 For both cases, setting normalisation to SF_FALSE means that no scaling will take place.
541 </P>
542 <P>
543 Example:
544 </P>
545 <PRE>
546 sf_command (sndfile, SFC_SET_NORM_FLOAT, NULL, SF_TRUE) ;
547
548 sf_command (sndfile, SFC_SET_NORM_FLOAT, NULL, SF_FALSE) ;
549 </PRE>
550 <DL>
551 <DT>Return value: </DT>
552 <DD>Returns the previous float normalisation mode.
553 </DL>
554
555 <!-- ========================================================================= -->
556 <A NAME="SFC_SET_NORM_DOUBLE"></A>
557 <H2><BR><B>SFC_SET_NORM_DOUBLE</B></H2>
558 <P>
559 This command only affects data read from or written to using the double precision
560 floating point functions:
561 </P>
562 <PRE>
563 size_t <A HREF="api.html#read">sf_read_double</A> (SNDFILE *sndfile, double *ptr, size_t items) ;
564 size_t <A HREF="api.html#readf">sf_readf_double</A> (SNDFILE *sndfile, double *ptr, size_t frames) ;
565
566 size_t <A HREF="api.html#write">sf_write_double</A> (SNDFILE *sndfile, double *ptr, size_t items) ;
567 size_t <A HREF="api.html#writef">sf_writef_double</A> (SNDFILE *sndfile, double *ptr, size_t frames) ;
568 </PRE>
569 <P>
570 Parameters:
571 </P>
572 <PRE>
573 sndfile : A valid SNDFILE* pointer
574 cmd : SFC_SET_NORM_DOUBLE
575 data : NULL
576 datasize : SF_TRUE or SF_FALSE
577 </PRE>
578 <P>
579 For read operations setting normalisation to SF_TRUE means that the data
580 from all subsequent reads will be be normalised to the range [-1.0, 1.0].
581 </P>
582 <P>
583 For write operations, setting normalisation to SF_TRUE means than all data supplied
584 to the double write functions should be in the range [-1.0, 1.0] and will be scaled
585 for the file format as necessary.
586 </P>
587 <P>
588 For both cases, setting normalisation to SF_FALSE means that no scaling will take place.
589 </P>
590 <P>
591 Example:
592 </P>
593 <PRE>
594 sf_command (sndfile, SFC_SET_NORM_DOUBLE, NULL, SF_TRUE) ;
595
596 sf_command (sndfile, SFC_SET_NORM_DOUBLE, NULL, SF_FALSE) ;
597 </PRE>
598 <DL>
599 <DT>Return value: </DT>
600 <DD>Returns the previous double normalisation mode.
601 </DL>
602
603 <!-- ========================================================================= -->
604 <A NAME="SFC_GET_NORM_FLOAT"></A>
605 <H2><BR><B>SFC_GET_NORM_FLOAT</B></H2>
606 <P>
607 Retrieve the current float normalisation mode.
608 </P>
609 <P>
610 Parameters:
611 </P>
612 <PRE>
613 sndfile : A valid SNDFILE* pointer
614 cmd : SFC_GET_NORM_FLOAT
615 data : NULL
616 datasize : anything
617 </PRE>
618 <P>
619 Example:
620 </P>
621 <PRE>
622 normalisation = sf_command (sndfile, SFC_GET_NORM_FLOAT, NULL, 0) ;
623 </PRE>
624 <DL>
625 <DT>Return value: </DT>
626 <DD>Returns TRUE if normalisation is on and FALSE otherwise.
627 </DL>
628
629 <!-- ========================================================================= -->
630 <A NAME="SFC_GET_NORM_DOUBLE"></A>
631 <H2><BR><B>SFC_GET_NORM_DOUBLE</B></H2>
632 <P>
633 Retrieve the current float normalisation mode.
634 </P>
635 <P>
636 Parameters:
637 </P>
638 <PRE>
639 sndfile : A valid SNDFILE* pointer
640 cmd : SFC_GET_NORM_DOUBLE
641 data : NULL
642 datasize : anything
643 </PRE>
644 <P>
645 Example:
646 </P>
647 <PRE>
648 normalisation = sf_command (sndfile, SFC_GET_NORM_DOUBLE, NULL, 0) ;
649 </PRE>
650 <DL>
651 <DT>Return value: </DT>
652 <DD>Returns TRUE if normalisation is on and FALSE otherwise.
653 </DL>
654
655
656 <!-- ========================================================================= -->
657 <A NAME="SFC_SET_SCALE_FLOAT_INT_READ"></A>
658 <H2><BR><B>SFC_SET_SCALE_FLOAT_INT_READ</B></H2>
659 <P>
660 Set/clear the scale factor when integer (short/int) data is read from a file
661 containing 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_FLOAT_INT_READ, NULL, SF_TRUE) ;
677 </PRE>
678 <DL>
679 <DT>Return value: </DT>
680 <DD>Returns the previous SFC_SET_SCALE_FLOAT_INT_READ setting for this file.
681 </DL>
682
683
684 <!-- ========================================================================= -->
685 <A NAME="SFC_SET_SCALE_INT_FLOAT_WRITE"></A>
686 <H2><BR><B>SFC_SET_SCALE_INT_FLOAT_WRITE</B></H2>
687 <P>
688 Set/clear the scale factor when integer (short/int) data is written to a file
689 as floating point data.
690 </P>
691 <P>
692 Parameters:
693 </P>
694 <PRE>
695 sndfile : A valid SNDFILE* pointer
696 cmd : SFC_SET_SCALE_FLOAT_INT_READ
697 data : NULL
698 datasize : TRUE or FALSE
699 </PRE>
700 <P>
701 Example:
702 </P>
703 <PRE>
704 sf_command (sndfile, SFC_SET_SCALE_INT_FLOAT_WRITE, NULL, SF_TRUE) ;
705 </PRE>
706 <DL>
707 <DT>Return value: </DT>
708 <DD>Returns the previous SFC_SET_SCALE_INT_FLOAT_WRITE setting for this file.
709 </DL>
710
711 <!-- ========================================================================= -->
712 <A NAME="SFC_GET_SIMPLE_FORMAT_COUNT"></A>
713 <H2><BR><B>SFC_GET_SIMPLE_FORMAT_COUNT</B></H2>
714 <P>
715 Retrieve the number of simple formats supported by libsndfile.
716 </P>
717 <P>
718 Parameters:
719 </P>
720 <PRE>
721 sndfile : Not used.
722 cmd : SFC_GET_SIMPLE_FORMAT_COUNT
723 data : a pointer to an int
724 datasize : sizeof (int)
725 </PRE>
726 <P>
727 Example:
728 </P>
729 <PRE>
730 int count ;
731 sf_command (sndfile, SFC_GET_SIMPLE_FORMAT_COUNT, &amp;count, sizeof (int)) ;
732 </PRE>
733 <DL>
734 <DT>Return value: </DT>
735 <DD>0
736 </DL>
737
738 <!-- ========================================================================= -->
739 <A NAME="SFC_GET_SIMPLE_FORMAT"></A>
740 <H2><BR><B>SFC_GET_SIMPLE_FORMAT</B></H2>
741 <P>
742 Retrieve information about a simple format.
743 </P>
744 <P>
745 Parameters:
746 </P>
747 <PRE>
748 sndfile : Not used.
749 cmd : SFC_GET_SIMPLE_FORMAT
750 data : a pointer to an SF_FORMAT_INFO struct
751 datasize : sizeof (SF_FORMAT_INFO)
752 </PRE>
753 <P>
754 The SF_FORMAT_INFO struct is defined in &lt;sndfile.h&gt; as:
755 </P>
756 <PRE>
757 typedef struct
758 { int format ;
759 const char *name ;
760 const char *extension ;
761 } SF_FORMAT_INFO ;
762 </PRE>
763 <P>
764 When sf_command() is called with SF_GET_SIMPLE_FORMAT, the value of the format
765 field should be the format number (ie 0 &lt;= format &lt;= count value obtained using
766 SF_GET_SIMPLE_FORMAT_COUNT).
767 </P>
768 <P>
769 Example:
770 </P>
771 <PRE>
772 SF_FORMAT_INFO format_info ;
773 int k, count ;
774
775 sf_command (sndfile, SFC_GET_SIMPLE_FORMAT_COUNT, &amp;count, sizeof (int)) ;
776
777 for (k = 0 ; k &lt; count ; k++)
778 { format_info.format = k ;
779 sf_command (sndfile, SFC_GET_SIMPLE_FORMAT, &amp;format_info, sizeof (format_info)) ;
780 printf ("%08x %s %s\n", format_info.format, format_info.name, format_info.extension) ;
781 } ;
782 </PRE>
783 <DL>
784 <DT>Return value: </DT>
785 <DD>0 on success and non-zero otherwise.
786 <DD>The value of the format field of the SF_FORMAT_INFO struct will be a value which
787 can be placed in the format field of an SF_INFO struct when a file is to be opened
788 for write.
789 <DD>The name field will contain a char* pointer to the name of the string, eg. "WAV (Microsoft 16 bit PCM)".
790 <DD>The extension field will contain the most commonly used file extension for that file type.
791 </DL>
792
793 <!-- ========================================================================= -->
794 <A NAME="SFC_GET_FORMAT_INFO"></A>
795 <H2><BR><B>SFC_GET_FORMAT_INFO</B></H2>
796 <P>
797 Retrieve information about a major or subtype format.
798 </P>
799 <P>
800 Parameters:
801 </P>
802 <PRE>
803 sndfile : Not used.
804 cmd : SFC_GET_FORMAT_INFO
805 data : a pointer to an SF_FORMAT_INFO struct
806 datasize : sizeof (SF_FORMAT_INFO)
807 </PRE>
808 <P>
809 The SF_FORMAT_INFO struct is defined in &lt;sndfile.h&gt; as:
810 </P>
811 <PRE>
812 typedef struct
813 { int format ;
814 const char *name ;
815 const char *extension ;
816 } SF_FORMAT_INFO ;
817 </PRE>
818 <P>
819 When sf_command() is called with SF_GET_FORMAT_INFO, the format field is
820 examined and if (format &amp; SF_FORMAT_TYPEMASK) is a valid format then the struct
821 is filled in with information about the given major type.
822 If (format &amp; SF_FORMAT_TYPEMASK) is FALSE and (format &amp; SF_FORMAT_SUBMASK) is a
823 valid subtype format then the struct is filled in with information about the given
824 subtype.
825 </P>
826 <P>
827 Example:
828 </P>
829 <PRE>
830 SF_FORMAT_INFO format_info ;
831
832 format_info.format = SF_FORMAT_WAV ;
833 sf_command (sndfile, SFC_GET_FORMAT_INFO, &amp;format_info, sizeof (format_info)) ;
834 printf ("%08x %s %s\n", format_info.format, format_info.name, format_info.extension) ;
835
836 format_info.format = SF_FORMAT_ULAW ;
837 sf_command (sndfile, SFC_GET_FORMAT_INFO, &amp;format_info, sizeof (format_info)) ;
838 printf ("%08x %s\n", format_info.format, format_info.name) ;
839 </PRE>
840 <DL>
841 <DT>Return value: </DT>
842 <DD>0 on success and non-zero otherwise.
843 </DL>
844 <!-- ========================================================================= -->
845 <A NAME="SFC_GET_FORMAT_MAJOR_COUNT"></A>
846 <H2><BR><B>SFC_GET_FORMAT_MAJOR_COUNT</B></H2>
847 <P>
848 Retrieve the number of major formats.
849 </P>
850 <P>
851 Parameters:
852 </P>
853 <PRE>
854 sndfile : Not used.
855 cmd : SFC_GET_FORMAT_MAJOR_COUNT
856 data : a pointer to an int
857 datasize : sizeof (int)
858 </PRE>
859 <P>
860 Example:
861 </P>
862 <PRE>
863 int count ;
864 sf_command (sndfile, SFC_GET_FORMAT_MAJOR_COUNT, &amp;count, sizeof (int)) ;
865 </PRE>
866 <DL>
867 <DT>Return value: </DT>
868 <DD>0
869 </DL>
870
871 <!-- ========================================================================= -->
872 <A NAME="SFC_GET_FORMAT_MAJOR"></A>
873 <H2><BR><B>SFC_GET_FORMAT_MAJOR</B></H2>
874 <P>
875 Retrieve information about a major format type.
876 </P>
877 <P>
878 Parameters:
879 </P>
880 <PRE>
881 sndfile : Not used.
882 cmd : SFC_GET_FORMAT_MAJOR
883 data : a pointer to an SF_FORMAT_INFO struct
884 datasize : sizeof (SF_FORMAT_INFO)
885 </PRE>
886 <P>
887 Example:
888 </P>
889 <PRE>
890 SF_FORMAT_INFO format_info ;
891 int k, count ;
892
893 sf_command (sndfile, SFC_GET_FORMAT_MAJOR_COUNT, &amp;count, sizeof (int)) ;
894
895 for (k = 0 ; k &lt; count ; k++)
896 { format_info.format = k ;
897 sf_command (sndfile, SFC_GET_FORMAT_MAJOR, &amp;format_info, sizeof (format_info)) ;
898 printf ("%08x %s %s\n", format_info.format, format_info.name, format_info.extension) ;
899 } ;
900 </PRE>
901 <P>
902 For a more comprehensive example, see the program list_formats.c in the examples/
903 directory of the libsndfile source code distribution.
904 </P>
905 <DL>
906 <DT>Return value: </DT>
907 <DD>0 on success and non-zero otherwise.
908 <DD>The value of the format field will be one of the major format identifiers such as
909 SF_FORMAT_WAV or SF_FORMAT_AIFF.
910 <DD>The name field will contain a char* pointer to the name of the string, eg. "WAV (Microsoft)".
911 <DD>The extension field will contain the most commonly used file extension for that file type.
912 </DL>
913
914 <!-- ========================================================================= -->
915 <A NAME="SFC_GET_FORMAT_SUBTYPE_COUNT"></A>
916 <H2><BR><B>SFC_GET_FORMAT_SUBTYPE_COUNT</B></H2>
917 <P>
918 Retrieve the number of subformats.
919 </P>
920 <P>
921 Parameters:
922 </P>
923 <PRE>
924 sndfile : Not used.
925 cmd : SFC_GET_FORMAT_SUBTYPE_COUNT
926 data : a pointer to an int
927 datasize : sizeof (int)
928 </PRE>
929 <P>
930 Example:
931 </P>
932 <PRE>
933 int count ;
934 sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE_COUNT, &amp;count, sizeof (int)) ;
935 </PRE>
936 <DL>
937 <DT>Return value: </DT>
938 <DD>0
939 </DL>
940
941 <!-- ========================================================================= -->
942 <A NAME="SFC_GET_FORMAT_SUBTYPE"></A>
943 <H2><BR><B>SFC_GET_FORMAT_SUBTYPE</B></H2>
944 <P>
945 Enumerate the subtypes (this function does not translate a subtype into
946 a string describing that subtype).
947 A typical use case might be retrieving a string description of all subtypes
948 so that a dialog box can be filled in.
949 </P>
950 <P>
951
952 </P>
953 <P>
954 Parameters:
955 </P>
956 <PRE>
957 sndfile : Not used.
958 cmd : SFC_GET_FORMAT_SUBTYPE
959 data : a pointer to an SF_FORMAT_INFO struct
960 datasize : sizeof (SF_FORMAT_INFO)
961 </PRE>
962 <P>
963 Example 1: Retrieve all sybtypes supported by the WAV format.
964 </P>
965 <PRE>
966 SF_FORMAT_INFO format_info ;
967 int k, count ;
968
969 sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE_COUNT, &amp;count, sizeof (int)) ;
970
971 for (k = 0 ; k &lt; count ; k++)
972 { format_info.format = k ;
973 sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE, &amp;format_info, sizeof (format_info)) ;
974 if (! sf_format_check (format_info.format | SF_FORMAT_WAV))
975 continue ;
976 printf ("%08x %s\n", format_info.format, format_info.name) ;
977 } ;
978 </PRE>
979 <P>
980 Example 2: Print a string describing the SF_FORMAT_PCM_16 subtype.
981 </P>
982 <PRE>
983 SF_FORMAT_INFO format_info ;
984 int k, count ;
985
986 sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE_COUNT, &amp;count, sizeof (int)) ;
987
988 for (k = 0 ; k &lt; count ; k++)
989 { format_info.format = k ;
990 sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE, &amp;format_info, sizeof (format_info)) ;
991 if (format_info.format == SF_FORMAT_PCM_16)
992 { printf ("%08x %s\n", format_info.format, format_info.name) ;
993 break ;
994 } ;
995 } ;
996 </PRE>
997 <P>
998 For a more comprehensive example, see the program list_formats.c in the examples/
999 directory of the libsndfile source code distribution.
1000 </P>
1001 <DL>
1002 <DT>Return value: </DT>
1003 <DD>0 on success and non-zero otherwise.
1004 <DD>The value of the format field will be one of the major format identifiers such as
1005 SF_FORMAT_WAV or SF_FORMAT_AIFF.
1006 <DD>The name field will contain a char* pointer to the name of the string; for instance
1007 "WAV (Microsoft)" or "AIFF (Apple/SGI)".
1008 <DD>The extension field will be a NULL pointer.
1009 </DL>
1010
1011 <!-- ========================================================================= -->
1012 <A NAME="SFC_SET_ADD_PEAK_CHUNK"></A>
1013 <H2><BR><B>SFC_SET_ADD_PEAK_CHUNK</B></H2>
1014 <P>
1015 By default, WAV and AIFF files which contain floating point data (subtype SF_FORMAT_FLOAT
1016 or SF_FORMAT_DOUBLE) have a PEAK chunk.
1017 By using this command, the addition of a PEAK chunk can be turned on or off.
1018 </P>
1019 <P>
1020 Note : This call must be made before any data is written to the file.
1021 </P>
1022 <P>
1023 Parameters:
1024 <PRE>
1025 sndfile : A valid SNDFILE* pointer
1026 cmd : SFC_SET_ADD_PEAK_CHUNK
1027 data : Not used (should be NULL)
1028 datasize : TRUE or FALSE.
1029 </PRE>
1030 <P>
1031 Example:
1032 </P>
1033 <PRE>
1034 /* Turn on the PEAK chunk. */
1035 sf_command (sndfile, SFC_SET_ADD_PEAK_CHUNK, NULL, SF_TRUE) ;
1036
1037 /* Turn off the PEAK chunk. */
1038 sf_command (sndfile, SFC_SET_ADD_PEAK_CHUNK, NULL, SF_FALSE) ;
1039 </PRE>
1040 <DL>
1041 <DT>Return value:</DT>
1042 <DD>Returns SF_TRUE if the peak chunk will be written after this call.
1043 <DD>Returns SF_FALSE if the peak chunk will not be written after this call.
1044 </DL>
1045
1046 <!-- ========================================================================= -->
1047 <A NAME="SFC_UPDATE_HEADER_NOW"></A>
1048 <H2><BR><B>SFC_UPDATE_HEADER_NOW</B></H2>
1049 <P>
1050 The header of an audio file is normally written by libsndfile when the file is
1051 closed using <B>sf_close()</B>.
1052 </P>
1053 <P>
1054 There are however situations where large files are being generated and it would
1055 be nice to have valid data in the header before the file is complete.
1056 Using this command will update the file header to reflect the amount of data written
1057 to the file so far.
1058 Other programs opening the file for read (before any more data is written) will
1059 then read a valid sound file header.
1060 </P>
1061 <P>
1062 Parameters:
1063 <PRE>
1064 sndfile : A valid SNDFILE* pointer
1065 cmd : SFC_UPDATE_HEADER_NOW
1066 data : Not used (should be NULL)
1067 datasize : Not used.
1068 </PRE>
1069 <P>
1070 Example:
1071 </P>
1072 <PRE>
1073 /* Update the header now. */
1074 sf_command (sndfile, SFC_UPDATE_HEADER_NOW, NULL, 0) ;
1075 </PRE>
1076 <DL>
1077 <DT>Return value:</DT>
1078 <DD>0
1079 </DL>
1080
1081 <!-- ========================================================================= -->
1082 <A NAME="SFC_SET_UPDATE_HEADER_AUTO"></A>
1083 <H2><BR><B>SFC_SET_UPDATE_HEADER_AUTO</B></H2>
1084 <P>
1085 Similar to SFC_UPDATE_HEADER_NOW but updates the header at the end of every call
1086 to the <B>sf_write*</B> functions.
1087 </P>
1088 <P>
1089 Parameters:
1090 <PRE>
1091 sndfile : A valid SNDFILE* pointer
1092 cmd : SFC_UPDATE_HEADER_NOW
1093 data : Not used (should be NULL)
1094 datasize : SF_TRUE or SF_FALSE
1095 </PRE>
1096 <P>
1097 Example:
1098 </P>
1099 <PRE>
1100 /* Turn on auto header update. */
1101 sf_command (sndfile, SFC_SET_UPDATE_HEADER_AUTO, NULL, SF_TRUE) ;
1102
1103 /* Turn off auto header update. */
1104 sf_command (sndfile, SFC_SET_UPDATE_HEADER_AUTO, NULL, SF_FALSE) ;
1105 </PRE>
1106 <DL>
1107 <DT>Return value:</DT>
1108 <DD>TRUE if auto update header is now on; FALSE otherwise.
1109 </DL>
1110
1111 <!-- ========================================================================= -->
1112 <A NAME="SFC_FILE_TRUNCATE"></A>
1113 <H2><BR><B>SFC_FILE_TRUNCATE</B></H2>
1114 <P>
1115 Truncate a file that was opened for write or read/write.
1116 </P>
1117 <P>
1118 Parameters:
1119 <PRE>
1120 sndfile : A valid SNDFILE* pointer
1121 cmd : SFC_FILE_TRUNCATE
1122 data : A pointer to an sf_count_t.
1123 datasize : sizeof (sf_count_t)
1124 </PRE>
1125
1126 <P>
1127 Truncate the file to the number of frames specified by the sf_count_t pointed
1128 to by data.
1129 After this command, both the read and the write pointer will be
1130 at the new end of the file.
1131 This command will fail (returning non-zero) if the requested truncate position
1132 is beyond the end of the file.
1133 </P>
1134 <P>
1135 Example:
1136 </P>
1137 <PRE>
1138 /* Truncate the file to a length of 20 frames. */
1139 sf_count_t frames = 20 ;
1140 sf_command (sndfile, SFC_FILE_TRUNCATE, &amp;frames, sizeof (frames)) ;
1141 </PRE>
1142 <DL>
1143 <DT>Return value:</DT>
1144 <DD>Zero on sucess, non-zero otherwise.
1145 </DL>
1146
1147 <!-- ========================================================================= -->
1148 <A NAME="SFC_SET_RAW_START_OFFSET"></A>
1149 <H2><BR><B>SFC_SET_RAW_START_OFFSET</B></H2>
1150 <P>
1151 Change the data start offset for files opened up as SF_FORMAT_RAW.
1152 </P>
1153 <P>
1154 Parameters:
1155 <PRE>
1156 sndfile : A valid SNDFILE* pointer
1157 cmd : SFC_SET_RAW_START_OFFSET
1158 data : A pointer to an sf_count_t.
1159 datasize : sizeof (sf_count_t)
1160 </PRE>
1161
1162 <P>
1163 For a file opened as format SF_FORMAT_RAW, set the data offset to the value
1164 given by data.
1165 </P>
1166 <P>
1167 Example:
1168 </P>
1169 <PRE>
1170 /* Reset the data offset to 5 bytes from the start of the file. */
1171 sf_count_t offset = 5 ;
1172 sf_command (sndfile, SFC_SET_RAW_START_OFFSET, &amp;offset, sizeof (offset)) ;
1173 </PRE>
1174 <DL>
1175 <DT>Return value:</DT>
1176 <DD>Zero on success, non-zero otherwise.
1177 </DL>
1178
1179 <!-- ========================================================================= -->
1180 <A NAME="SFC_SET_CLIPPING"></A>
1181 <H2><BR><B>SFC_SET_CLIPPING</B></H2>
1182 <P>
1183 Turn on/off automatic clipping when doing floating point to integer conversion.
1184 </P>
1185 <P>
1186 Parameters:
1187 <PRE>
1188 sndfile : A valid SNDFILE* pointer
1189 cmd : SFC_SET_CLIPPING
1190 data : NULL
1191 datasize : SF_TRUE or SF_FALSE.
1192 </PRE>
1193
1194 <P>
1195 Turn on (datasize == SF_TRUE) or off (datasize == SF_FALSE) clipping.
1196 </P>
1197 <P>
1198 Example:
1199 </P>
1200 <PRE>
1201 sf_command (sndfile, SFC_SET_CLIPPING, NULL, SF_TRUE) ;
1202 </PRE>
1203 <DL>
1204 <DT>Return value:</DT>
1205 <DD>Clipping mode (SF_TRUE or SF_FALSE).
1206 </DL>
1207
1208
1209 <!-- ========================================================================= -->
1210 <A NAME="SFC_GET_CLIPPING"></A>
1211 <H2><BR><B>SFC_GET_CLIPPING</B></H2>
1212 <P>
1213 Turn on/off automatic clipping when doing floating point to integer conversion.
1214 </P>
1215 <P>
1216 Parameters:
1217 <PRE>
1218 sndfile : A valid SNDFILE* pointer
1219 cmd : SFC_GET_CLIPPING
1220 data : NULL
1221 datasize : 0
1222 </PRE>
1223
1224 <P>
1225 Retrieve the current cliiping setting.
1226 </P>
1227 <P>
1228 Example:
1229 </P>
1230 <PRE>
1231 sf_command (sndfile, SFC_GET_CLIPPING, NULL, 0) ;
1232 </PRE>
1233 <DL>
1234 <DT>Return value:</DT>
1235 <DD>Clipping mode (SF_TRUE or SF_FALSE).
1236 </DL>
1237
1238 <!-- ========================================================================= -->
1239 <A NAME="SFC_GET_EMBED_FILE_INFO"></A>
1240 <H2><BR><B>SFC_GET_EMBED_FILE_INFO</B></H2>
1241 <P>
1242 Get the file offset and file length of a file enbedded within another
1243 larger file.
1244 </P>
1245 <P>
1246 Parameters:
1247 <PRE>
1248 sndfile : A valid SNDFILE* pointer
1249 cmd : SFC_GET_CLIPPING
1250 data : a pointer to an SF_EMBED_FILE_INFO struct
1251 datasize : sizeof (SF_EMBED_FILE_INFO)
1252 </PRE>
1253 <P>
1254 The SF_EMBED_FILE_INFO struct is defined in &lt;sndfile.h&gt; as:
1255 </P>
1256 <PRE>
1257 typedef struct
1258 { sf_count_t offset ;
1259 sf_count_t length ;
1260 } SF_EMBED_FILE_INFO ;
1261 </PRE>
1262 <DL>
1263 <DT>Return value: </DT>
1264 <DD>0 on success and non-zero otherwise.
1265 <DD>The value of the offset field of the SF_EMBED_FILE_INFO struct will be
1266 the offsets in bytes from the start of the outer file to the start of
1267 the audio file.
1268 <DD>The value of the offset field of the SF_EMBED_FILE_INFO struct will be
1269 the length in bytes of the embedded file.
1270 </DL>
1271
1272
1273
1274 <!-- ========================================================================= -->
1275 <A NAME="SFC_WAVEX_GET_AMBISONIC"></A>
1276 <H2><BR><B>SFC_WAVEX_GET_AMBISONIC</B></H2>
1277 <P>
1278 Test if the current file has the GUID of a WAVEX file for any of the Ambisonic
1279 formats.
1280 </P>
1281 <P>
1282 Parameters:
1283 <PRE>
1284 sndfile : A valid SNDFILE* pointer
1285 cmd : SFC_WAVEX_GET_AMBISONIC
1286 data : NULL
1287 datasize : 0
1288 </PRE>
1289 <P>
1290 The Ambisonic WAVEX formats are defined here :
1291 <A HREF="http://dream.cs.bath.ac.uk/researchdev/wave-ex/bformat.html">
1292 http://dream.cs.bath.ac.uk/researchdev/wave-ex/bformat.html</A>.
1293 </P>
1294 <DL>
1295 <DT>Return value: </DT>
1296 <DD>SF_AMBISONIC_NONE or SF_AMBISONIC_B_FORMAT or zero if the file format
1297 does not support ambisonic formats.
1298 </DL>
1299
1300 <!-- ========================================================================= -->
1301 <A NAME="SFC_WAVEX_SET_AMBISONIC"></A>
1302 <H2><BR><B>SFC_WAVEX_SET_AMBISONIC</B></H2>
1303 <P>
1304 Set the GUID of a new WAVEX file to indicate an Ambisonics format.
1305 </P>
1306 <P>
1307 Parameters:
1308 <PRE>
1309 sndfile : A valid SNDFILE* pointer
1310 cmd : SFC_WAVEX_SET_AMBISONIC
1311 data : NULL
1312 datasize : SF_AMBISONIC_NONE or SF_AMBISONIC_B_FORMAT
1313 </PRE>
1314 <P>
1315 Turn on (SF_AMBISONIC_B_FORMAT) or off (SF_AMBISONIC_NONE) encoding.
1316 This command is currently only supported for files with SF_FORMAT_WAVEX format.
1317 </P>
1318 <P>
1319 The Ambisonic WAVEX formats are defined here :
1320 <A HREF="http://dream.cs.bath.ac.uk/researchdev/wave-ex/bformat.html">
1321 http://dream.cs.bath.ac.uk/researchdev/wave-ex/bformat.html</A>.
1322 </P>
1323 <DL>
1324 <DT>Return value: </DT>
1325 <DD>Return the ambisonic value that has just been set or zero if the file
1326 format does not support ambisonic encoding.
1327 </DL>
1328
1329 <!-- ========================================================================= -->
1330 <A NAME="SFC_SET_VBR_ENCODING_QUALITY"></A>
1331 <H2><BR><B>SFC_SET_VBR_ENCODING_QUALITY</B></H2>
1332 <P>
1333 Set the Variable Bit Rate encoding quality.
1334 The encoding quality value should be between 0.0 (lowest quality) and 1.0
1335 (highest quality).
1336 Currenly this command is only implemented for FLAC and Ogg/Vorbis files.
1337 It has no effect on un-compressed file formats.
1338 </P>
1339 <P>
1340 Parameters:
1341 <PRE>
1342 sndfile : A valid SNDFILE* pointer
1343 cmd : SFC_SET_VBR_ENCODING_QUALITY
1344 data : A pointer to a double value
1345 datasize : sizeof (double)
1346 </PRE>
1347 <P>
1348 The command must be sent before any audio data is written to the file.
1349 </P>
1350 <P>
1351 </P>
1352 <DL>
1353 <DT>Return value:</DT>
1354 <dd>SF_TRUE if VBR encoding quality was set.
1355 SF_FALSE otherwise.
1356 </DL>
1357
1358 <!-- ========================================================================= -->
1359 <A NAME="SFC_SET_COMPRESSION_LEVEL"></A>
1360 <H2><BR><B>SFC_SET_COMPRESSION_LEVEL</B></H2>
1361 <P>
1362 Set the compression level.
1363 The compression level should be between 0.0 (minimum compression level) and 1.0
1364 (highest compression level).
1365 Currenly this command is only implemented for FLAC and Ogg/Vorbis files.
1366 It has no effect on un-compressed file formats.
1367 </P>
1368 <P>
1369 Parameters:
1370 <PRE>
1371 sndfile : A valid SNDFILE* pointer
1372 cmd : SFC_SET_COMPRESSION_LEVEL
1373 data : A pointer to a double value
1374 datasize : sizeof (double)
1375 </PRE>
1376 <P>
1377 The command must be sent before any audio data is written to the file.
1378 </P>
1379 <P>
1380 </P>
1381 <DL>
1382 <DT>Return value:</DT>
1383 <dd>SF_TRUE if compression level was set.
1384 SF_FALSE otherwise.
1385 </DL>
1386
1387 <!-- ========================================================================= -->
1388 <A NAME="SFC_RAW_NEEDS_ENDSWAP"></A>
1389 <H2><BR><B>SFC_RAW_NEEDS_ENDSWAP</B></H2>
1390 <P>
1391 Determine if raw data read using
1392 <a href="api.html#raw">
1393 sf_read_raw</a>
1394 needs to be end swapped on the host CPU.
1395 </P>
1396 <P>
1397 For instance, will return SF_TRUE on when reading WAV containing
1398 SF_FORMAT_PCM_16 data on a big endian machine and SF_FALSE on a little endian
1399 machine.
1400 </P>
1401 <P>
1402 Parameters:
1403 <PRE>
1404 sndfile : A valid SNDFILE* pointer
1405 cmd : SFC_RAW_NEEDS_ENDSWAP
1406 data : NULL
1407 datasize : 0
1408 </PRE>
1409
1410 <DL>
1411 <DT>Return value: </DT>
1412 <DD>SF_TRUE or SF_FALSE
1413 </DL>
1414
1415
1416 <!-- ========================================================================= -->
1417 <A NAME="SFC_GET_BROADCAST_INFO"></A>
1418 <H2><BR><B>SFC_GET_BROADCAST_INFO</B></H2>
1419 <P>
1420 Retrieve the Broadcast Extension Chunk from WAV (and related) files.
1421 </P>
1422 <p>
1423 Parameters:
1424 </p>
1425 <PRE>
1426 sndfile : A valid SNDFILE* pointer
1427 cmd : SFC_GET_BROADCAST_INFO
1428 data : a pointer to an SF_BROADCAST_INFO struct
1429 datasize : sizeof (SF_BROADCAST_INFO)
1430 </PRE>
1431 <P>
1432 The SF_BROADCAST_INFO struct is defined in &lt;sndfile.h&gt; as:
1433 </P>
1434 <PRE>
1435 typedef struct
1436 { char description [256] ;
1437 char originator [32] ;
1438 char originator_reference [32] ;
1439 char origination_date [10] ;
1440 char origination_time [8] ;
1441 unsigned int time_reference_low ;
1442 unsigned int time_reference_high ;
1443 short version ;
1444 char umid [64] ;
1445 char reserved [190] ;
1446 unsigned int coding_history_size ;
1447 char coding_history [256] ;
1448 } SF_BROADCAST_INFO ;
1449 </PRE>
1450
1451 <DL>
1452 <DT>Return value: </DT>
1453 <DD>SF_TRUE if the file contained a Broadcast Extension chunk or SF_FALSE
1454 otherwise.
1455 </DL>
1456
1457 <!-- ========================================================================= -->
1458 <A NAME="SFC_SET_BROADCAST_INFO"></A>
1459 <H2><BR><B>SFC_SET_BROADCAST_INFO</B></H2>
1460 <P>
1461 Set the Broadcast Extension Chunk for WAV (and related) files.
1462 </P>
1463 <p>
1464 Parameters:
1465 </p>
1466 <PRE>
1467 sndfile : A valid SNDFILE* pointer
1468 cmd : SFC_SET_BROADCAST_INFO
1469 data : a pointer to an SF_BROADCAST_INFO struct
1470 datasize : sizeof (SF_BROADCAST_INFO)
1471 </PRE>
1472
1473 <DL>
1474 <DT>Return value: </DT>
1475 <DD>SF_TRUE if setting the Broadcast Extension chunk was successful and SF_FALSE
1476 otherwise.
1477
1478 </DL>
1479
1480 <!-- ========================================================================= -->
1481 <A NAME="SFC_GET_CART_INFO"></A>
1482 <H2><BR><B>SFC_GET_CART_INFO</B></H2>
1483 <P>Retrieve the Cart Chunk from WAV (and related) files. Based on AES46 standard for CartChunk (see <a href="http://www.cartchunk.org/">CartChunk.org</a> for more information.
1484 </P>
1485 <p>
1486 Parameters:
1487 </p>
1488 <PRE>
1489 sndfile : A valid SNDFILE* pointer
1490 cmd : SFC_GET_CART_INFO
1491 data : a pointer to an SF_CART_INFO struct
1492 datasize : sizeof (SF_CART_INFO)
1493 </PRE>
1494 <P>
1495 The SF_CART_INFO struct is defined in &lt;sndfile.h&gt; as:
1496 </P>
1497 <PRE>
1498 #define SF_CART_INFO_VAR(p_tag_text_size) \
1499 struct
1500 { char version [4] ;
1501 char title [64] ;
1502 char artist [64] ;
1503 char cut_id [64] ;
1504 char client_id [64] ;
1505 char category [64] ;
1506 char classification [64] ;
1507 char out_cue [64] ;
1508 char start_date [10] ;
1509 char start_time [8] ;
1510 char end_date [10] ;
1511 char end_time [8] ;
1512 char producer_app_id [64] ;
1513 char producer_app_version [64] ;
1514 char user_def [64] ;
1515 long level_reference ;
1516 SF_CART_TIMER post_timers [8] ;
1517 char reserved [276] ;
1518 char url [1024] ;
1519 unsigned int tag_text_size ;
1520 char tag_text[p_tag_text_size] ;
1521 }
1522 </PRE>
1523
1524 <DL>
1525 <DT>Return value: </DT>
1526 <DD>SF_TRUE if the file contained a Cart chunk or SF_FALSE
1527 otherwise.
1528 </DL>
1529
1530 <!-- ========================================================================= -->
1531 <A NAME="SFC_SET_CART_INFO"></A>
1532 <H2><BR><B>SFC_SET_CART_INFO</B></H2>
1533 <P>
1534 Set the Cart Chunk for WAV (and related) files.
1535 </P>
1536 <p>
1537 Parameters:
1538 </p>
1539 <PRE>
1540 sndfile : A valid SNDFILE* pointer
1541 cmd : SFC_SET_CART_INFO
1542 data : a pointer to an SF_CART_INFO struct
1543 datasize : sizeof (SF_CART_INFO)
1544 </PRE>
1545
1546 <DL>
1547 <DT>Return value: </DT>
1548 <DD>SF_TRUE if setting the Cart chunk was successful and SF_FALSE
1549 otherwise.
1550 </DL>
1551 <!-- ========================================================================= -->
1552
1553 <A NAME="SFC_GET_LOOP_INFO"></A>
1554 <H2><BR><B>SFC_GET_LOOP_INFO</B></H2>
1555 <P>
1556 Retrieve loop information for file including time signature, length in
1557 beats and original MIDI base note
1558 </P>
1559 <p>
1560 Parameters:
1561 </p>
1562 <PRE>
1563 sndfile : A valid SNDFILE* pointer
1564 cmd : SFC_GET_LOOP_INFO
1565 data : a pointer to an SF_LOOP_INFO struct
1566 datasize : sizeof (SF_LOOP_INFO)
1567 </PRE>
1568 <P>
1569 The SF_BROADCAST_INFO struct is defined in &lt;sndfile.h&gt; as:
1570 </P>
1571 <PRE>
1572 typedef struct
1573 { short time_sig_num ; /* any positive integer > 0 */
1574 short time_sig_den ; /* any positive power of 2 > 0 */
1575 int loop_mode ; /* see SF_LOOP enum */
1576
1577 int num_beats ; /* this is NOT the amount of quarter notes !!!*/
1578 /* a full bar of 4/4 is 4 beats */
1579 /* a full bar of 7/8 is 7 beats */
1580
1581 float bpm ; /* suggestion, as it can be calculated using other fields:*/
1582 /* file's lenght, file's sampleRate and our time_sig_den*/
1583 /* -> bpms are always the amount of _quarter notes_ per minute */
1584
1585 int root_key ; /* MIDI note, or -1 for None */
1586 int future [6] ;
1587 } SF_LOOP_INFO ;
1588 </PRE>
1589 <P>
1590 Example:
1591 </P>
1592 <PRE>
1593 SF_LOOP_INFO loop;
1594 sf_command (sndfile, SFC_GET_LOOP_INFO, &amp;loop, sizeof (loop)) ;
1595 </PRE>
1596 <DL>
1597 <DT>Return value:</DT>
1598 <DD>SF_TRUE if the file header contains loop information for the file.
1599 SF_FALSE otherwise.
1600 </DL>
1601
1602 <!-- ========================================================================= -->
1603
1604
1605 <A NAME="SFC_GET_INSTRUMENT"></A>
1606 <H2><BR><B>SFC_GET_INSTRUMENT</B></H2>
1607 <P>
1608 Retrieve instrument information from file including MIDI base note,
1609 keyboard mapping and looping informations(start/stop and mode).
1610 </P>
1611 <p>
1612 Parameters:
1613 </p>
1614 <PRE>
1615 sndfile : A valid SNDFILE* pointer
1616 cmd : SFC_GET_INSTRUMENT
1617 data : a pointer to an SF_INSTRUMENT struct
1618 datasize : sizeof (SF_INSTRUMENT)
1619 </PRE>
1620
1621 <P>
1622 The SF_INSTRUMENT struct is defined in &lt;sndfile.h&gt; as:
1623 </P>
1624 <PRE>
1625 enum
1626 { /*
1627 ** The loop mode field in SF_INSTRUMENT will be one of the following.
1628 */
1629 SF_LOOP_NONE = 800,
1630 SF_LOOP_FORWARD,
1631 SF_LOOP_BACKWARD,
1632 SF_LOOP_ALTERNATING
1633 } ;
1634
1635 typedef struct
1636 { int gain ;
1637 char basenote, detune ;
1638 char velocity_lo, velocity_hi ;
1639 char key_lo, key_hi ;
1640 int loop_count ;
1641
1642 struct
1643 { int mode ;
1644 unsigned int start ;
1645 unsigned int end ;
1646 unsigned int count ;
1647 } loops [16] ; /* make variable in a sensible way */
1648 } SF_INSTRUMENT ;
1649 </PRE>
1650
1651 <P>
1652 Example:
1653 </P>
1654 <PRE>
1655 SF_INSTRUMENT inst ;
1656 sf_command (sndfile, SFC_GET_INSTRUMENT, &amp;inst, sizeof (inst)) ;
1657 </PRE>
1658 <DL>
1659 <DT>Return value:</DT>
1660 <dd>SF_TRUE if the file header contains instrument information for the
1661 file. SF_FALSE otherwise.
1662 </DL>
1663
1664 <!-- ========================================================================= -->
1665
1666
1667 <A NAME="SFC_SET_INSTRUMENT"></A>
1668 <H2><BR><B>SFC_SET_INSTRUMENT</B></H2>
1669 <P>
1670 Set the instrument information for the file.
1671 </P>
1672 <p>
1673 Parameters:
1674 </p>
1675 <PRE>
1676 sndfile : A valid SNDFILE* pointer
1677 cmd : SFC_SET_INSTRUMENT
1678 data : a pointer to an SF_INSTRUMENT struct
1679 datasize : sizeof (SF_INSTRUMENT)
1680 </PRE>
1681 <P>
1682 Example:
1683 </P>
1684 <PRE>
1685 SF_INSTRUMENT inst ;
1686 sf_command (sndfile, SFC_SET_INSTRUMENT, &amp;inst, sizeof (inst)) ;
1687 </PRE>
1688 <DL>
1689 <DT>Return value:</DT>
1690 <dd>SF_TRUE if the file header contains instrument information for the
1691 file. SF_FALSE otherwise.
1692 </DL>
1693
1694
1695 <!-- ========================================================================= -->
1696
1697 <A NAME="SFC_GET_CUE"></A>
1698 <H2><BR><B>SFC_GET_CUE_COUNT</B></H2>
1699 <P>
1700 Retrieve the number of cue markers available for retrieval using the
1701 SFC_GET_CUE command.
1702 </P>
1703 <P>
1704 Parameters:
1705 </P>
1706 <PRE>
1707 sndfile : A valid SNDFILE* pointer
1708 cmd : SFC_GET_CUE
1709 data : a pointer to a uint32_t
1710 datasize : sizeof (uint32_t)
1711 </PRE>
1712
1713
1714 <P>
1715 Example:
1716 </P>
1717 <PRE>
1718 uint32_t cue_count ;
1719 sf_command (sndfile, SFC_GET_CUE_COUNT, &amp;cue_count, sizeof (cue_count)) ;
1720 </PRE>
1721 <DL>
1722 <DT>Return value:</DT>
1723 <dd>SF_TRUE if the file header contains cue marker information for the
1724 file. SF_FALSE otherwise.
1725 </DL>
1726
1727 <!-- ========================================================================= -->
1728
1729 <A NAME="SFC_GET_CUE"></A>
1730 <H2><BR><B>SFC_GET_CUE</B></H2>
1731 <P>
1732 Retrieve cue marker information from file.
1733 </P>
1734 <P>
1735 Parameters:
1736 </P>
1737 <PRE>
1738 sndfile : A valid SNDFILE* pointer
1739 cmd : SFC_GET_CUE
1740 data : a pointer to an SF_CUES struct
1741 datasize : sizeof (SF_CUES)
1742 </PRE>
1743
1744 <P>
1745 The SF_CUES struct is defined in &lt;sndfile.h&gt; as:
1746 </P>
1747 <PRE>
1748 typedef struct
1749 { int cue_count ;
1750
1751 struct
1752 { int32_t indx ;
1753 uint32_t position ;
1754 int32_t fcc_chunk ;
1755 int32_t chunk_start ;
1756 int32_t block_start ;
1757 uint32_t sample_offset ;
1758 char name [256] ;
1759 } cue_points [100] ;
1760 } SF_CUES ;
1761 </PRE>
1762
1763 <P>
1764 There is also an SF_CUES_VAR #define that allows reading/writing more than 100
1765 cue markers.
1766 </P>
1767
1768 <P>
1769 Example:
1770 </P>
1771 <PRE>
1772 SF_CUES cues ;
1773 sf_command (sndfile, SFC_GET_CUE, &amp;cues, sizeof (cues)) ;
1774 </PRE>
1775 <DL>
1776 <DT>Return value:</DT>
1777 <dd>SF_TRUE if the file header contains cue marker information for the
1778 file. SF_FALSE otherwise.
1779 </DL>
1780
1781
1782 <!-- ========================================================================= -->
1783
1784
1785 <A NAME="SFC_SET_CUE"></A>
1786 <H2><BR><B>SFC_SET_CUE</B></H2>
1787 <P>
1788 Set the cue marker information for the file.
1789 </P>
1790 <P>
1791 Parameters:
1792 </P>
1793 <PRE>
1794 sndfile : A valid SNDFILE* pointer
1795 cmd : SFC_SET_CUE
1796 data : a pointer to an SF_CUES struct
1797 datasize : sizeof (SF_CUES)
1798 </PRE>
1799 <P>
1800 Example:
1801 </P>
1802 <PRE>
1803 SF_CUES cues ;
1804 sf_command (sndfile, SFC_SET_CUE, &amp;cues, sizeof (cues)) ;
1805 </PRE>
1806 <DL>
1807 <DT>Return value:</DT>
1808 <dd>SF_TRUE if the file header contains cue marker information for the
1809 file. SF_FALSE otherwise.
1810 </DL>
1811
1812
1813 <!-- ========================================================================= -->
1814
1815
1816 <A NAME="SFC_RF64_AUTO_DOWNGRADE"></A>
1817 <H2><BR><B>SFC_RF64_AUTO_DOWNGRADE</B></H2>
1818 <P>
1819 Enable auto downgrade from RF64 to WAV.
1820 </P>
1821 <P>
1822 The EBU recomendation is that when writing RF64 files and the resulting file is
1823 less than 4Gig in size, it should be downgraded to a WAV file (WAV files have a
1824 maximum size of 4Gig).
1825 libsndfile doesn't follow the EBU recommendations exactly, , mainly because the
1826 test suite needs to be able test reading/writing RF64 files without having to
1827 generate files larger than 4 gigabytes.
1828 </P>
1829 <p>
1830 Note: This command should be issued before the first bit of audio data has been
1831 written to the file.
1832 Calling this command after audio data has been written will return the current
1833 value of this setting, but will not allow it to be changed.
1834 </p>
1835 <p>
1836 Parameters:
1837 </p>
1838 <PRE>
1839 sndfile : A valid SNDFILE* pointer
1840 cmd : SFC_RF64_AUTO_DOWNGRADE
1841 data : NULL
1842 datasize : SF_TRUE or SF_FALSE
1843 </PRE>
1844 <P>
1845 Example:
1846 </P>
1847 <PRE>
1848 /* Enable auto downgrade on file close. */
1849 sf_command (sndfile, SFC_RF64_AUTO_DOWNGRADE, NULL, SF_TRUE) ;
1850 </PRE>
1851 <DL>
1852 <DT>Return value:</DT>
1853 <dd>Returns SF_TRUE if SFC_RF64_AUTO_DOWNGRADE is set and SF_FALSE
1854 otherwise.
1855 </DL>
1856
1857
1858
1859 <!-- ========================================================================= -->
1860
1861
1862 <HR>
1863 <P>
1864 The libsndfile home page is here :
1865 <A HREF="http://www.mega-nerd.com/libsndfile/">
1866 http://www.mega-nerd.com/libsndfile/</A>.
1867 <BR>
1868 Version : 1.0.25
1869 </P>
1870
1871 </BODY>
1872 </HTML>