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