interpretor/libsndfile-1.0.25/doc/dither.html

   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 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 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 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.25
1014 </P>
1015
1016 </BODY>
1017 </HTML>