Mercurial > hg > sv-dependency-builds

comparison src/libsndfile-1.0.27/doc/dither.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 a integer identifier which is defined in &lt;sndfile.h&gt;.
32 All of the valid command identifiers have names begining with "SFC_".
33 Data is passed to and returned from the library by use of a void pointer.
34 The library will not read or write more than datasize bytes from the void pointer.
35 For some calls no data is required in which case data should be NULL and datasize
36 may be used for some other purpose.
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>Retrieve 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>Retrieve 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 peaks for all channels.</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 normalised peaks for all channels.</TD>
67 </TR>
68
69 <TR>
70 <TD><A HREF="#SFC_SET_NORM_FLOAT">SFC_SET_NORM_FLOAT</A></TD>
71 <TD>Modify the normalisation behaviour of the floating point reading and writing functions.</TD>
72 </TR>
73 <TR>
74 <TD><A HREF="#SFC_SET_NORM_DOUBLE">SFC_SET_NORM_DOUBLE</A></TD>
75 <TD>Modify the normalisation behaviour of the double precision floating point reading and writing functions.</TD>
76 </TR>
77 <TR>
78 <TD><A HREF="#SFC_GET_NORM_FLOAT">SFC_GET_NORM_FLOAT</A></TD>
79 <TD>Retrieve the current normalisation behaviour of the floating point reading and writing functions.</TD>
80 </TR>
81 <TR>
82 <TD><A HREF="#SFC_GET_NORM_DOUBLE">SFC_GET_NORM_DOUBLE</A></TD>
83 <TD>Retrieve the current normalisation behaviour of the double precision floating point reading and writing functions.</TD>
84 </TR>
85 <TR>
86 <TD><A HREF="#SFC_GET_SIMPLE_FORMAT_COUNT">SFC_GET_SIMPLE_FORMAT_COUNT</A></TD>
87 <TD>Retrieve the number of simple formats supported by libsndfile.</TD>
88 </TR>
89 <TR>
90 <TD><A HREF="#SFC_GET_SIMPLE_FORMAT">SFC_GET_SIMPLE_FORMAT</A></TD>
91 <TD>Retrieve information about a simple format.</TD>
92 </TR>
93
94 <TR>
95 <TD><A HREF="#SFC_GET_FORMAT_INFO">SFC_GET_FORMAT_INFO</A></TD>
96 <TD>Retrieve information about a major or subtype format.</TD>
97 </TR>
98
99 <TR>
100 <TD><A HREF="#SFC_GET_FORMAT_MAJOR_COUNT">SFC_GET_FORMAT_MAJOR_COUNT</A></TD>
101 <TD>Retrieve the number of major formats.</TD>
102 </TR>
103 <TR>
104 <TD><A HREF="#SFC_GET_FORMAT_MAJOR">SFC_GET_FORMAT_MAJOR</A></TD>
105 <TD>Retrieve information about a major format type.</TD>
106 </TR>
107 <TR>
108 <TD><A HREF="#SFC_GET_FORMAT_SUBTYPE_COUNT">SFC_GET_FORMAT_SUBTYPE_COUNT</A></TD>
109 <TD>Retrieve the number of subformats.</TD>
110 </TR>
111 <TR>
112 <TD><A HREF="#SFC_GET_FORMAT_SUBTYPE">SFC_GET_FORMAT_SUBTYPE</A></TD>
113 <TD>Retrieve information about a subformat.</TD>
114 </TR>
115
116 <TR>
117 <TD><A HREF="#SFC_SET_ADD_PEAK_CHUNK">SFC_SET_ADD_PEAK_CHUNK</A></TD>
118 <TD>Switch the code for adding the PEAK chunk to WAV and AIFF files on or off.</TD>
119 </TR>
120
121 <TR>
122 <TD><A HREF="#SFC_UPDATE_HEADER_NOW">SFC_UPDATE_HEADER_NOW</A></TD>
123 <TD>Used when a file is open for write, this command will update the file
124 header to reflect the data written so far.</TD>
125 </TR>
126 <TR>
127 <TD><A HREF="#SFC_SET_UPDATE_HEADER_AUTO">SFC_SET_UPDATE_HEADER_AUTO</A></TD>
128 <TD>Used when a file is open for write, this command will cause the file header
129 to be updated after each write to the file.</TD>
130 </TR>
131
132 <TR>
133 <TD><A HREF="#SFC_FILE_TRUNCATE">SFC_FILE_TRUNCATE</A></TD>
134 <TD>Truncate a file open for write or for read/write.</TD>
135 </TR>
136
137 <TR>
138 <TD><A HREF="#SFC_SET_RAW_START_OFFSET">SFC_SET_RAW_START_OFFSET</A></TD>
139 <TD>Change the data start offset for files opened up as SF_FORMAT_RAW.</TD>
140 </TR>
141
142
143
144 <!--
145 <TR>
146 <TD><A HREF="#add-dither">add dither</A></TD>
147 <TD>Add dither to output on write.</TD>
148 </TR>
149 -->
150 </TABLE>
151 </CENTER>
152
153 <BR><BR>
154
155 <HR>
156
157 <!-- ========================================================================= -->
158 <A NAME="SFC_GET_LIB_VERSION"></A>
159 <H2><BR><B>SFC_GET_LIB_VERSION</B></H2>
160 <P>
161 Retrieve the version of the library as a string.
162 </P>
163 <P>
164 Parameters:
165 <PRE>
166 sndfile : Not used
167 cmd : SFC_GET_LIB_VERSION
168 data : A pointer to a char buffer
169 datasize : The size of the buffer
170 </PRE>
171 <P>
172 Example:
173 </P>
174 <PRE>
175 char buffer [128] ;
176 sf_command (NULL, SFC_GET_LIB_VERSION, buffer, sizeof (buffer)) ;
177 </PRE>
178
179 <DL>
180 <DT>Return value:</DT>
181 <DD><DD>This call will return the length of the retrieved version string.
182 </DL>
183 <DL>
184 <DT>Notes:</DT>
185 <DD>
186 The string returned in the buffer passed to this function will not overflow
187 the buffer and will always be null terminated .
188 </DL>
189
190 <!-- ========================================================================= -->
191 <A NAME="SFC_GET_LOG_INFO"></A>
192 <H2><BR><B>SFC_GET_LOG_INFO</B></H2>
193 <P>
194 Retrieve the log buffer generated when opening a file as a string. This log
195 buffer can often contain a good reason for why libsndfile failed to open a
196 particular file.
197 </P>
198 <P>
199 Parameters:
200 <PRE>
201 sndfile : A valid SNDFILE* pointer
202 cmd : SFC_GET_LOG_INFO
203 data : A pointer to a char buffer
204 datasize : The size of the buffer
205 </PRE>
206 <P>
207 Example:
208 </P>
209 <PRE>
210 char buffer [2048] ;
211 sf_command (sndfile, SFC_GET_LOG_INFO, buffer, sizeof (buffer)) ;
212 </PRE>
213
214 <DL>
215 <DT>Return value:</DT>
216 <DD><DD>This call will return the length of the retrieved version string.
217 </DL>
218 <DL>
219 <DT>Notes:</DT>
220 <DD>
221 The string returned in the buffer passed to this function will not overflow
222 the buffer and will always be null terminated .
223 </DL>
224
225 <!-- ========================================================================= -->
226 <A NAME="SFC_CALC_SIGNAL_MAX"></A>
227 <H2><BR><B>SFC_CALC_SIGNAL_MAX</B></H2>
228 <P>
229 Retrieve the measured maximum signal value. This involves reading through
230 the whole file which can be slow on large files.
231 </P>
232 <P>
233 Parameters:
234 <PRE>
235 sndfile : A valid SNDFILE* pointer
236 cmd : SFC_CALC_SIGNAL_MAX
237 data : A pointer to a double
238 datasize : sizeof (double)
239 </PRE>
240 <P>
241 Example:
242 </P>
243 <PRE>
244 double max_val ;
245 sf_command (sndfile, SFC_CALC_SIGNAL_MAX, &amp;max_val, sizeof (max_val)) ;
246 </PRE>
247
248 <DL>
249 <DT>Return value:</DT>
250 <DD><DD>Zero on success, non-zero otherwise.
251 </DL>
252
253 <!-- ========================================================================= -->
254 <A NAME="SFC_CALC_NORM_SIGNAL_MAX"></A>
255 <H2><BR><B>SFC_CALC_NORM_SIGNAL_MAX</B></H2>
256 <P>
257 Retrieve the measured normailised maximum signal value. This involves reading
258 through the whole file which can be slow on large files.
259 </P>
260 <P>
261 Parameters:
262 <PRE>
263 sndfile : A valid SNDFILE* pointer
264 cmd : SFC_CALC_NORM_SIGNAL_MAX
265 data : A pointer to a double
266 datasize : sizeof (double)
267 </PRE>
268 <P>
269 Example:
270 </P>
271 <PRE>
272 double max_val ;
273 sf_command (sndfile, SFC_CALC_NORM_SIGNAL_MAX, &amp;max_val, sizeof (max_val)) ;
274 </PRE>
275
276 <DL>
277 <DT>Return value:</DT>
278 <DD><DD>Zero on success, non-zero otherwise.
279 </DL>
280
281 <!-- ========================================================================= -->
282 <A NAME="SFC_CALC_MAX_ALL_CHANNELS"></A>
283 <H2><BR><B>SFC_CALC_MAX_ALL_CHANNELS</B></H2>
284 <P>
285 Calculate peaks for all channels. This involves reading through
286 the whole file which can be slow on large files.
287 </P>
288 <P>
289 Parameters:
290 <PRE>
291 sndfile : A valid SNDFILE* pointer
292 cmd : SFC_CALC_MAX_ALL_CHANNELS
293 data : A pointer to a double
294 datasize : sizeof (double) * number_of_channels
295 </PRE>
296 <P>
297 Example:
298 </P>
299 <PRE>
300 double peaks [number_of_channels] ;
301 sf_command (sndfile, SFC_CALC_MAX_ALL_CHANNELS, peaks, sizeof (peaks)) ;
302 </PRE>
303 <DL>
304 <DT>Return value:</DT>
305 <DD>Zero if peaks have been calculated successfully and non-zero otherwise.
306 </DL>
307
308
309 <!-- ========================================================================= -->
310 <A NAME="SFC_CALC_NORM_MAX_ALL_CHANNELS"></A>
311 <H2><BR><B>SFC_CALC_NORM_MAX_ALL_CHANNELS</B></H2>
312 <P>
313 Calculate normalised peaks for all channels. This involves reading through
314 the whole file which can be slow on large files.
315 </P>
316 <P>
317 Parameters:
318 <PRE>
319 sndfile : A valid SNDFILE* pointer
320 cmd : SFC_CALC_NORM_MAX_ALL_CHANNELS
321 data : A pointer to a double
322 datasize : sizeof (double) * number_of_channels
323 </PRE>
324 <P>
325 Example:
326 </P>
327 <PRE>
328 double peaks [number_of_channels] ;
329 sf_command (sndfile, SFC_CALC_NORM_MAX_ALL_CHANNELS, peaks, sizeof (peaks)) ;
330 </PRE>
331 <DL>
332 <DT>Return value:</DT>
333 <DD>Zero if peaks have been calculated successfully and non-zero otherwise.
334 </DL>
335
336
337
338
339
340 <!-- ========================================================================= -->
341 <!--
342 <A NAME="read-text"></A>
343 <H2><BR><B>Read text</B></H2>
344 <P>
345 Many sound file formats contain allow the inclusion of a text string describing the nature
346 of the file. If a file contains such a string, this functions will return it to the caller.
347 </P>
348 <P>
349 It should be noted that the way the string is added to the file is file format dependant
350 but that any string added with <A HREF="#write-text">write text</A> will be returned by
351 <A HREF="#read-text">read text</A>.
352 </P>
353 <P>
354 <P>
355 Parameters:
356 </P>
357 <PRE>
358 sndfile : A valid SNDFILE* pointer
359 cmd : The text string "read text".
360 data : A pointer to a char buffer.
361 datasize : The size of the buffer.
362 </PRE>
363 <P>
364 Example:
365 </P>
366 <PRE>
367 char buffer [128] ;
368 sf_command (sndfile, "read text", buffer, sizeof (buffer)) ;
369 </PRE>
370 <DL>
371 <DT>Return value:</DT>
372 <DD>If a text string is found, this call will return the length of the retrieved text
373 string.
374 <DD>If no text string is found, zero will be returned and the first element in the
375 buffer will be set to the null character.
376 <DT>Notes:</DT>
377 <DD>The string returned in the buffer passed to this function will not overflow
378 the buffer and will be correctly null terminated .
379 </DL>
380
381 <A NAME="write-text"></A>
382 <H2><BR><B>Write text</B></H2>
383 <P>
384 Add a text string to a file. The text string added can be retrieved when the file is
385 read using <A HREF="#read-text">read text</A>.
386 </P>
387 <P>
388 Parameters:
389 </P>
390 <PRE>
391 sndfile : A valid SNDFILE* pointer
392 cmd : The text string "write text".
393 data : A pointer to the string to be added.
394 datasize : Not used.
395 </PRE>
396 <P>
397 Example:
398 </P>
399 <PRE>
400 char text = "The sound of one hand clapping." ;
401 sf_command (sndfile, "write text", text, strlen (text)) ;
402 </PRE>
403 <DL>
404 <DT>Return value: </DT>
405 <DD>If the current file format allows the addition of text strings, the string will
406 be added and the length of the string will be returned.
407 <DD>If the file format does not allow the addition of text strings zero will be returned.
408 <DD>If this function is called after the file is openned but before
409 </DL>
410 -->
411
412
413 <!-- ========================================================================= -->
414 <A NAME="SFC_SET_NORM_FLOAT"></A>
415 <H2><BR><B>SFC_SET_NORM_FLOAT</B></H2>
416 <P>
417 This command only affects data read from or written to using the floating point functions:
418 </P>
419 <PRE>
420 size_t <A HREF="api.html#read">sf_read_float</A> (SNDFILE *sndfile, float *ptr, size_t items) ;
421 size_t <A HREF="api.html#readf">sf_readf_float</A> (SNDFILE *sndfile, float *ptr, size_t frames) ;
422
423 size_t <A HREF="api.html#write">sf_write_float</A> (SNDFILE *sndfile, float *ptr, size_t items) ;
424 size_t <A HREF="api.html#writef">sf_writef_float</A> (SNDFILE *sndfile, float *ptr, size_t frames) ;
425 </PRE>
426 <P>
427 Parameters:
428 </P>
429 <PRE>
430 sndfile : A valid SNDFILE* pointer
431 cmd : SFC_SET_NORM_FLOAT
432 data : NULL
433 datasize : SF_TRUE or SF_FALSE
434 </PRE>
435 <P>
436 For read operations setting normalisation to SF_TRUE means that the data from all
437 subsequent reads will be be normalised to the range [-1.0, 1.0].
438 </P>
439 <P>
440 For write operations, setting normalisation to SF_TRUE means than all data supplied
441 to the float write functions should be in the range [-1.0, 1.0] and will be scaled
442 for the file format as necessary.
443 </P>
444 <P>
445 For both cases, setting normalisation to SF_FALSE means that no scaling will take place.
446 </P>
447 <P>
448 Example:
449 </P>
450 <PRE>
451 sf_command (sndfile, SFC_SET_NORM_FLOAT, NULL, SF_TRUE) ;
452
453 sf_command (sndfile, SFC_SET_NORM_FLOAT, NULL, SF_FALSE) ;
454 </PRE>
455 <DL>
456 <DT>Return value: </DT>
457 <DD>Returns 1 on success or 0 for failure.
458 </DL>
459
460 <!-- ========================================================================= -->
461 <A NAME="SFC_SET_NORM_DOUBLE"></A>
462 <H2><BR><B>SFC_SET_NORM_DOUBLE</B></H2>
463 <P>
464 This command only affects data read from or written to using the double precision
465 floating point functions:
466 </P>
467 <PRE>
468 size_t <A HREF="api.html#read">sf_read_double</A> (SNDFILE *sndfile, double *ptr, size_t items) ;
469 size_t <A HREF="api.html#readf">sf_readf_double</A> (SNDFILE *sndfile, double *ptr, size_t frames) ;
470
471 size_t <A HREF="api.html#write">sf_write_double</A> (SNDFILE *sndfile, double *ptr, size_t items) ;
472 size_t <A HREF="api.html#writef">sf_writef_double</A> (SNDFILE *sndfile, double *ptr, size_t frames) ;
473 </PRE>
474 <P>
475 Parameters:
476 </P>
477 <PRE>
478 sndfile : A valid SNDFILE* pointer
479 cmd : SFC_SET_NORM_DOUBLE
480 data : NULL
481 datasize : SF_TRUE or SF_FALSE
482 </PRE>
483 <P>
484 For read operations setting normalisation to SF_TRUE means that the data
485 from all subsequent reads will be be normalised to the range [-1.0, 1.0].
486 </P>
487 <P>
488 For write operations, setting normalisation to SF_TRUE means than all data supplied
489 to the double write functions should be in the range [-1.0, 1.0] and will be scaled
490 for the file format as necessary.
491 </P>
492 <P>
493 For both cases, setting normalisation to SF_FALSE means that no scaling will take place.
494 </P>
495 <P>
496 Example:
497 </P>
498 <PRE>
499 sf_command (sndfile, SFC_SET_NORM_DOUBLE, NULL, SF_TRUE) ;
500
501 sf_command (sndfile, SFC_SET_NORM_DOUBLE, NULL, SF_FALSE) ;
502 </PRE>
503 <DL>
504 <DT>Return value: </DT>
505 <DD>Returns 1 on success or 0 for failure.
506 </DL>
507
508 <!-- ========================================================================= -->
509 <A NAME="SFC_GET_NORM_FLOAT"></A>
510 <H2><BR><B>SFC_GET_NORM_FLOAT</B></H2>
511 <P>
512 Retrieve the current float normalisation mode.
513 </P>
514 <P>
515 Parameters:
516 </P>
517 <PRE>
518 sndfile : A valid SNDFILE* pointer
519 cmd : SFC_GET_NORM_FLOAT
520 data : NULL
521 datasize : anything
522 </PRE>
523 <P>
524 Example:
525 </P>
526 <PRE>
527 normalisation = sf_command (sndfile, SFC_GET_NORM_FLOAT, NULL, 0) ;
528 </PRE>
529 <DL>
530 <DT>Return value: </DT>
531 <DD>Returns TRUE if normaisation is on and FALSE otherwise.
532 </DL>
533
534 <!-- ========================================================================= -->
535 <A NAME="SFC_GET_NORM_DOUBLE"></A>
536 <H2><BR><B>SFC_GET_NORM_DOUBLE</B></H2>
537 <P>
538 Retrieve the current float normalisation mode.
539 </P>
540 <P>
541 Parameters:
542 </P>
543 <PRE>
544 sndfile : A valid SNDFILE* pointer
545 cmd : SFC_GET_NORM_DOUBLE
546 data : NULL
547 datasize : anything
548 </PRE>
549 <P>
550 Example:
551 </P>
552 <PRE>
553 normalisation = sf_command (sndfile, SFC_GET_NORM_DOUBLE, NULL, 0) ;
554 </PRE>
555 <DL>
556 <DT>Return value: </DT>
557 <DD>Returns TRUE if normalisation is on and FALSE otherwise.
558 </DL>
559
560 <!-- ========================================================================= -->
561 <A NAME="SFC_GET_SIMPLE_FORMAT_COUNT"></A>
562 <H2><BR><B>SFC_GET_SIMPLE_FORMAT_COUNT</B></H2>
563 <P>
564 Retrieve the number of simple formats supported by libsndfile.
565 </P>
566 <P>
567 Parameters:
568 </P>
569 <PRE>
570 sndfile : Not used.
571 cmd : SFC_GET_SIMPLE_FORMAT_COUNT
572 data : a pointer to an int
573 datasize : sizeof (int)
574 </PRE>
575 <P>
576 Example:
577 </P>
578 <PRE>
579 int count ;
580 sf_command (sndfile, SFC_GET_SIMPLE_FORMAT_COUNT, &amp;count, sizeof (int)) ;
581 </PRE>
582 <DL>
583 <DT>Return value: </DT>
584 <DD>0
585 </DL>
586
587 <!-- ========================================================================= -->
588 <A NAME="SFC_GET_SIMPLE_FORMAT"></A>
589 <H2><BR><B>SFC_GET_SIMPLE_FORMAT</B></H2>
590 <P>
591 Retrieve information about a simple format.
592 </P>
593 <P>
594 Parameters:
595 </P>
596 <PRE>
597 sndfile : Not used.
598 cmd : SFC_GET_SIMPLE_FORMAT
599 data : a pointer to an SF_FORMAT_INFO struct
600 datasize : sizeof (SF_FORMAT_INFO)
601 </PRE>
602 <P>
603 The SF_FORMAT_INFO struct is defined in &lt;sndfile.h&gt; as:
604 </P>
605 <PRE>
606 typedef struct
607 { int format ;
608 const char *name ;
609 const char *extension ;
610 } SF_FORMAT_INFO ;
611 </PRE>
612 <P>
613 When sf_command() is called with SF_GET_SIMPLE_FORMAT, the value of the format
614 field should be the format number (ie 0 <= format <= count value obtained using
615 SF_GET_SIMPLE_FORMAT_COUNT).
616 </P>
617 <P>
618 Example:
619 </P>
620 <PRE>
621 SF_FORMAT_INFO format_info ;
622 int k, count ;
623
624 sf_command (sndfile, SFC_GET_SIMPLE_FORMAT_COUNT, &amp;count, sizeof (int)) ;
625
626 for (k = 0 ; k < count ; k++)
627 { format_info.format = k ;
628 sf_command (sndfile, SFC_GET_SIMPLE_FORMAT, &amp;format_info, sizeof (format_info)) ;
629 printf ("%08x %s %s\n", format_info.format, format_info.name, format_info.extension) ;
630 } ;
631 </PRE>
632 <DL>
633 <DT>Return value: </DT>
634 <DD>0 on success and non-zero otherwise.
635 <DD>The value of the format field of the SF_FORMAT_INFO struct will be an value which
636 can be placed in the format field of an SF_INFO struct when a file is to be opened
637 for write.
638 <DD>The name field will contain a char* pointer to the name of the string ie "WAV (Microsoft 16 bit PCM)".
639 <DD>The extention field will contain the most commonly used file extension for that file type.
640 </DL>
641
642 <!-- ========================================================================= -->
643 <A NAME="SFC_GET_FORMAT_INFO"></A>
644 <H2><BR><B>SFC_GET_FORMAT_INFO</B></H2>
645 <P>
646 Retrieve information about a major or subtype format.
647 </P>
648 <P>
649 Parameters:
650 </P>
651 <PRE>
652 sndfile : Not used.
653 cmd : SFC_GET_FORMAT_INFO
654 data : a pointer to an SF_FORMAT_INFO struct
655 datasize : sizeof (SF_FORMAT_INFO)
656 </PRE>
657 <P>
658 The SF_FORMAT_INFO struct is defined in &lt;sndfile.h&gt; as:
659 </P>
660 <PRE>
661 typedef struct
662 { int format ;
663 const char *name ;
664 const char *extension ;
665 } SF_FORMAT_INFO ;
666 </PRE>
667 <P>
668 When sf_command() is called with SF_GET_FORMAT_INFO, the format field is
669 examined and if (format & SF_FORMAT_TYPEMASK) is a valid format then the struct
670 is filled in with information about the given major type.
671 If (format & SF_FORMAT_TYPEMASK) is FALSE and (format & SF_FORMAT_SUBMASK) is a
672 valid subtype format then the struct is filled in with information about the given
673 subtype.
674 </P>
675 <P>
676 Example:
677 </P>
678 <PRE>
679 SF_FORMAT_INFO format_info ;
680
681 format_info.format = SF_FORMAT_WAV ;
682 sf_command (sndfile, SFC_GET_FORMAT_INFO, &amp;format_info, sizeof (format_info)) ;
683 printf ("%08x %s %s\n", format_info.format, format_info.name, format_info.extension) ;
684
685 format_info.format = SF_FORMAT_ULAW ;
686 sf_command (sndfile, SFC_GET_FORMAT_INFO, &amp;format_info, sizeof (format_info)) ;
687 printf ("%08x %s\n", format_info.format, format_info.name) ;
688 </PRE>
689 <DL>
690 <DT>Return value: </DT>
691 <DD>0 on success and non-zero otherwise.
692 </DL>
693 <!-- ========================================================================= -->
694 <A NAME="SFC_GET_FORMAT_MAJOR_COUNT"></A>
695 <H2><BR><B>SFC_GET_FORMAT_MAJOR_COUNT</B></H2>
696 <P>
697 Retrieve the number of major formats.
698 </P>
699 <P>
700 Parameters:
701 </P>
702 <PRE>
703 sndfile : Not used.
704 cmd : SFC_GET_FORMAT_MAJOR_COUNT
705 data : a pointer to an int
706 datasize : sizeof (int)
707 </PRE>
708 <P>
709 Example:
710 </P>
711 <PRE>
712 int count ;
713 sf_command (sndfile, SFC_GET_FORMAT_MAJOR_COUNT, &amp;count, sizeof (int)) ;
714 </PRE>
715 <DL>
716 <DT>Return value: </DT>
717 <DD>0
718 </DL>
719
720 <!-- ========================================================================= -->
721 <A NAME="SFC_GET_FORMAT_MAJOR"></A>
722 <H2><BR><B>SFC_GET_FORMAT_MAJOR</B></H2>
723 <P>
724 Retrieve information about a major format type.
725 </P>
726 <P>
727 Parameters:
728 </P>
729 <PRE>
730 sndfile : Not used.
731 cmd : SFC_GET_FORMAT_MAJOR
732 data : a pointer to an SF_FORMAT_INFO struct
733 datasize : sizeof (SF_FORMAT_INFO)
734 </PRE>
735 <P>
736 Example:
737 </P>
738 <PRE>
739 SF_FORMAT_INFO format_info ;
740 int k, count ;
741
742 sf_command (sndfile, SFC_GET_FORMAT_MAJOR_COUNT, &amp;count, sizeof (int)) ;
743
744 for (k = 0 ; k < count ; k++)
745 { format_info.format = k ;
746 sf_command (sndfile, SFC_GET_FORMAT_MAJOR, &amp;format_info, sizeof (format_info)) ;
747 printf ("%08x %s %s\n", format_info.format, format_info.name, format_info.extension) ;
748 } ;
749 </PRE>
750 <P>
751 For a more comprehensive example, see the program list_formats.c in the examples/
752 directory of the libsndfile source code distribution.
753 </P>
754 <DL>
755 <DT>Return value: </DT>
756 <DD>0 on success and non-zero otherwise.
757 <DD>The value of the format field will one of the major format identifiers suc as SF_FORMAT_WAV
758 SF_FORMAT_AIFF.
759 <DD>The name field will contain a char* pointer to the name of the string ie "WAV (Microsoft)".
760 <DD>The extention field will contain the most commonly used file extension for that file type.
761 </DL>
762
763 <!-- ========================================================================= -->
764 <A NAME="SFC_GET_FORMAT_SUBTYPE_COUNT"></A>
765 <H2><BR><B>SFC_GET_FORMAT_SUBTYPE_COUNT</B></H2>
766 <P>
767 Retrieve the number of subformats.
768 </P>
769 <P>
770 Parameters:
771 </P>
772 <PRE>
773 sndfile : Not used.
774 cmd : SFC_GET_FORMAT_SUBTYPE_COUNT
775 data : a pointer to an int
776 datasize : sizeof (int)
777 </PRE>
778 <P>
779 Example:
780 </P>
781 <PRE>
782 int count ;
783 sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE_COUNT, &amp;count, sizeof (int)) ;
784 </PRE>
785 <DL>
786 <DT>Return value: </DT>
787 <DD>0
788 </DL>
789
790 <!-- ========================================================================= -->
791 <A NAME="SFC_GET_FORMAT_SUBTYPE"></A>
792 <H2><BR><B>SFC_GET_FORMAT_SUBTYPE</B></H2>
793 <P>
794 Retrieve information about a subformat.
795 </P>
796 <P>
797 Parameters:
798 </P>
799 <PRE>
800 sndfile : Not used.
801 cmd : SFC_GET_FORMAT_SUBTYPE
802 data : a pointer to an SF_FORMAT_INFO struct
803 datasize : sizeof (SF_FORMAT_INFO)
804 </PRE>
805 <P>
806 Example:
807 </P>
808 <PRE>
809 SF_FORMAT_INFO format_info ;
810 int k, count ;
811
812 sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE_COUNT, &amp;count, sizeof (int)) ;
813
814 /* Retrieve all the subtypes supported by the WAV format. */
815 for (k = 0 ; k < count ; k++)
816 { format_info.format = k ;
817 sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE, &amp;format_info, sizeof (format_info)) ;
818 if (! sf_format_check (format.info | SF_FORMAT_WAV))
819 continue ;
820 printf ("%08x %s\n", format_info.format, format_info.name) ;
821 } ;
822 </PRE>
823 <P>
824 For a more comprehensive example, see the program list_formats.c in the examples/
825 directory of the libsndfile source code distribution.
826 </P>
827 <DL>
828 <DT>Return value: </DT>
829 <DD>0 on success and non-zero otherwise.
830 <DD>The value of the format field will one of the major format identifiers such as SF_FORMAT_WAV
831 SF_FORMAT_AIFF.
832 <DD>The name field will contain a char* pointer to the name of the string; for instance
833 "WAV (Microsoft)" or "AIFF (Apple/SGI)".
834 <DD>The extention field will be a NULL pointer.
835 </DL>
836
837 <!-- ========================================================================= -->
838 <A NAME="SFC_SET_ADD_PEAK_CHUNK"></A>
839 <H2><BR><B>SFC_SET_ADD_PEAK_CHUNK</B></H2>
840 <P>
841 By default, WAV and AIFF files which contain floating point data (subtype SF_FORMAT_FLOAT
842 or SF_FORMAT_DOUBLE) have a PEAK chunk.
843 By using this command, the addition of a PEAK chunk can be turned on or off.
844 </P>
845 <P>
846 Note : This call must be made before any data is written to the file.
847 </P>
848 <P>
849 Parameters:
850 <PRE>
851 sndfile : A valid SNDFILE* pointer
852 cmd : SFC_SET_ADD_PEAK_CHUNK
853 data : Not used (should be NULL)
854 datasize : TRUE or FALSE.
855 </PRE>
856 <P>
857 Example:
858 </P>
859 <PRE>
860 /* Turn on the PEAK chunk. */
861 sf_command (sndfile, SFC_SET_ADD_PEAK_CHUNK, NULL, SF_TRUE) ;
862
863 /* Turn off the PEAK chunk. */
864 sf_command (sndfile, SFC_SET_ADD_PEAK_CHUNK, NULL, SF_FALSE) ;
865 </PRE>
866 <DL>
867 <DT>Return value:</DT>
868 <DD>Returns SF_TRUE if the peak chunk will be written after this call.
869 <DD>Returns SF_FALSE if the peak chunk will not be written after this call.
870 </DL>
871
872 <!-- ========================================================================= -->
873 <A NAME="SFC_UPDATE_HEADER_NOW"></A>
874 <H2><BR><B>SFC_UPDATE_HEADER_NOW</B></H2>
875 <P>
876 The header of an audio file is normally written by libsndfile when the file is
877 closed using <B>sf_close()</B>.
878 </P>
879 <P>
880 There are however situations where large files are being generated and it would
881 be nice to have valid data in the header before the file is complete.
882 Using this command will update the file header to reflect the amount of data written
883 to the file so far.
884 Other programs opening the file for read (before any more data is written) will
885 then read a valid sound file header.
886 </P>
887 <P>
888 Parameters:
889 <PRE>
890 sndfile : A valid SNDFILE* pointer
891 cmd : SFC_UPDATE_HEADER_NOW
892 data : Not used (should be NULL)
893 datasize : Not used.
894 </PRE>
895 <P>
896 Example:
897 </P>
898 <PRE>
899 /* Update the header now. */
900 sf_command (sndfile, SFC_UPDATE_HEADER_NOW, NULL, 0) ;
901 </PRE>
902 <DL>
903 <DT>Return value:</DT>
904 <DD>0
905 </DL>
906
907 <!-- ========================================================================= -->
908 <A NAME="SFC_SET_UPDATE_HEADER_AUTO"></A>
909 <H2><BR><B>SFC_SET_UPDATE_HEADER_AUTO</B></H2>
910 <P>
911 Similar to SFC_UPDATE_HEADER_NOW but updates the header at the end of every call
912 to the <B>sf_write*</B> functions.
913 </P>
914 <P>
915 Parameters:
916 <PRE>
917 sndfile : A valid SNDFILE* pointer
918 cmd : SFC_UPDATE_HEADER_NOW
919 data : Not used (should be NULL)
920 datasize : SF_TRUE or SF_FALSE
921 </PRE>
922 <P>
923 Example:
924 </P>
925 <PRE>
926 /* Turn on auto header update. */
927 sf_command (sndfile, SFC_SET_UPDATE_HEADER_AUTO, NULL, SF_TRUE) ;
928
929 /* Turn off auto header update. */
930 sf_command (sndfile, SFC_SET_UPDATE_HEADER_AUTO, NULL, SF_FALSE) ;
931 </PRE>
932 <DL>
933 <DT>Return value:</DT>
934 <DD>TRUE if auto update header is now on; FALSE otherwise.
935 </DL>
936
937 <!-- ========================================================================= -->
938 <A NAME="SFC_FILE_TRUNCATE"></A>
939 <H2><BR><B>SFC_FILE_TRUNCATE</B></H2>
940 <P>
941 Truncate a file open for write or for read/write.
942 </P>
943 <P>
944 Parameters:
945 <PRE>
946 sndfile : A valid SNDFILE* pointer
947 cmd : SFC_FILE_TRUNCATE
948 data : A pointer to an sf_count_t.
949 datasize : sizeof (sf_count_t)
950 </PRE>
951
952 <P>
953 Truncate the file to the number of frames specified by the sf_count_t pointed
954 to by data.
955 After this command, both the read and the write pointer will be
956 at the new end of the file.
957 This command will fail (returning non-zero) if the requested truncate position
958 is beyond the end of the file.
959 </P>
960 <P>
961 Example:
962 </P>
963 <PRE>
964 /* Truncate the file to a length of 20 frames. */
965 sf_count_t frames = 20 ;
966 sf_command (sndfile, SFC_FILE_TRUNCATE, &amp;frames, sizeof (frames)) ;
967 </PRE>
968 <DL>
969 <DT>Return value:</DT>
970 <DD>Zero on sucess, non-zero otherwise.
971 </DL>
972
973 <!-- ========================================================================= -->
974 <A NAME="SFC_SET_RAW_START_OFFSET"></A>
975 <H2><BR><B>SFC_SET_RAW_START_OFFSET</B></H2>
976 <P>
977 Change the data start offset for files opened up as SF_FORMAT_RAW.
978 </P>
979 <P>
980 Parameters:
981 <PRE>
982 sndfile : A valid SNDFILE* pointer
983 cmd : SFC_SET_RAW_START_OFFSET
984 data : A pointer to an sf_count_t.
985 datasize : sizeof (sf_count_t)
986 </PRE>
987
988 <P>
989 For a file opened as format SF_FORMAT_RAW, set the data offset to the value
990 given by data.
991 </P>
992 <P>
993 Example:
994 </P>
995 <PRE>
996 /* Reset the data offset to 5 bytes from the start of the file. */
997 sf_count_t offset = 5 ;
998 sf_command (sndfile, SFC_SET_RAW_START_OFFSET, &amp;offset, sizeof (offset)) ;
999 </PRE>
1000 <DL>
1001 <DT>Return value:</DT>
1002 <DD>Zero on sucess, non-zero otherwise.
1003 </DL>
1004
1005 <!-- ========================================================================= -->
1006
1007 <HR>
1008 <P>
1009 The libsndfile home page is here :
1010 <A HREF="http://www.mega-nerd.com/libsndfile/">
1011 http://www.mega-nerd.com/libsndfile/</A>.
1012 <BR>
1013 Version : 1.0.27
1014 </P>
1015
1016 </BODY>
1017 </HTML>