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 <!--
 210 <TR>
 211         <TD><A HREF="#add-dither">add dither</A></TD>
 212         <TD>Add dither to output on write.</TD>
 213 </TR>
 214 -->
 215 </TABLE>
 216 </CENTER>
 217
 218 <BR><BR>
 219
 220 <HR>
 221
 222 <!-- ========================================================================= -->
 223 <A NAME="SFC_GET_LIB_VERSION"></A>
 224 <H2><BR><B>SFC_GET_LIB_VERSION</B></H2>
 225 <P>
 226 Retrieve the version of the library as a string.
 227 </P>
 228 <P>
 229 Parameters:
 230 <PRE>
 231         sndfile  : Not used
 232         cmd      : SFC_GET_LIB_VERSION
 233         data     : A pointer to a char buffer
 234         datasize : The size of the the buffer
 235 </PRE>
 236 <P>
 237 Example:
 238 </P>
 239 <PRE>
 240         char  buffer [128] ;
 241         sf_command (NULL, SFC_GET_LIB_VERSION, buffer, sizeof (buffer)) ;
 242 </PRE>
 243
 244 <DL>
 245 <DT>Return value:</DT>
 246         <DD><DD>This call will return the length of the retrieved version string.
 247 </DL>
 248 <DL>
 249 <DT>Notes:</DT>
 250 <DD>
 251 The string returned in the buffer passed to this function will not overflow
 252 the buffer and will always be null terminated .
 253 </DL>
 254
 255 <!-- ========================================================================= -->
 256 <A NAME="SFC_GET_LOG_INFO"></A>
 257 <H2><BR><B>SFC_GET_LOG_INFO</B></H2>
 258 <P>
 259 Retrieve the log buffer generated when opening a file as a string. This log
 260 buffer can often contain a good reason for why libsndfile failed to open a
 261 particular file.
 262 </P>
 263 <P>
 264 Parameters:
 265 <PRE>
 266         sndfile  : A valid SNDFILE* pointer
 267         cmd      : SFC_GET_LOG_INFO
 268         data     : A pointer to a char buffer
 269         datasize : The size of the the buffer
 270 </PRE>
 271 <P>
 272 Example:
 273 </P>
 274 <PRE>
 275         char  buffer [2048] ;
 276         sf_command (sndfile, SFC_GET_LOG_INFO, buffer, sizeof (buffer)) ;
 277 </PRE>
 278
 279 <DL>
 280 <DT>Return value:</DT>
 281         <DD><DD>This call will return the length of the retrieved version string.
 282 </DL>
 283 <DL>
 284 <DT>Notes:</DT>
 285 <DD>
 286 The string returned in the buffer passed to this function will not overflow
 287 the buffer and will always be null terminated .
 288 </DL>
 289
 290 <!-- ========================================================================= -->
 291 <A NAME="SFC_CALC_SIGNAL_MAX"></A>
 292 <H2><BR><B>SFC_CALC_SIGNAL_MAX</B></H2>
 293 <P>
 294 Retrieve the measured maximum signal value. This involves reading through
 295 the whole file which can be slow on large files.
 296 </P>
 297 <P>
 298 Parameters:
 299 <PRE>
 300         sndfile  : A valid SNDFILE* pointer
 301         cmd      : SFC_CALC_SIGNAL_MAX
 302         data     : A pointer to a double
 303         datasize : sizeof (double)
 304 </PRE>
 305 <P>
 306 Example:
 307 </P>
 308 <PRE>
 309         double   max_val ;
 310         sf_command (sndfile, SFC_CALC_SIGNAL_MAX, &amp;max_val, sizeof (max_val)) ;
 311 </PRE>
 312
 313 <DL>
 314 <DT>Return value:</DT>
 315         <DD><DD>Zero on success, non-zero otherwise.
 316 </DL>
 317
 318 <!-- ========================================================================= -->
 319 <A NAME="SFC_CALC_NORM_SIGNAL_MAX"></A>
 320 <H2><BR><B>SFC_CALC_NORM_SIGNAL_MAX</B></H2>
 321 <P>
 322 Retrieve the measured normalised maximum signal value. This involves reading
 323 through the whole file which can be slow on large files.
 324 </P>
 325 <P>
 326 Parameters:
 327 <PRE>
 328         sndfile  : A valid SNDFILE* pointer
 329         cmd      : SFC_CALC_NORM_SIGNAL_MAX
 330         data     : A pointer to a double
 331         datasize : sizeof (double)
 332 </PRE>
 333 <P>
 334 Example:
 335 </P>
 336 <PRE>
 337         double   max_val ;
 338         sf_command (sndfile, SFC_CALC_NORM_SIGNAL_MAX, &amp;max_val, sizeof (max_val)) ;
 339 </PRE>
 340
 341 <DL>
 342 <DT>Return value:</DT>
 343         <DD><DD>Zero on success, non-zero otherwise.
 344 </DL>
 345
 346 <!-- ========================================================================= -->
 347 <A NAME="SFC_CALC_MAX_ALL_CHANNELS"></A>
 348 <H2><BR><B>SFC_CALC_MAX_ALL_CHANNELS</B></H2>
 349 <P>
 350 Calculate the peak value (ie a single number) for each channel.
 351 This involves reading through the whole file which can be slow on large files.
 352 </P>
 353 <P>
 354 Parameters:
 355 <PRE>
 356         sndfile  : A valid SNDFILE* pointer
 357         cmd      : SFC_CALC_MAX_ALL_CHANNELS
 358         data     : A pointer to a double
 359         datasize : sizeof (double) * number_of_channels
 360 </PRE>
 361 <P>
 362 Example:
 363 </P>
 364 <PRE>
 365         double   peaks [number_of_channels] ;
 366         sf_command (sndfile, SFC_CALC_MAX_ALL_CHANNELS, peaks, sizeof (peaks)) ;
 367 </PRE>
 368 <DL>
 369 <DT>Return value:</DT>
 370         <DD>Zero if peaks have been calculated successfully and non-zero otherwise.
 371 </DL>
 372
 373
 374 <!-- ========================================================================= -->
 375 <A NAME="SFC_CALC_NORM_MAX_ALL_CHANNELS"></A>
 376 <H2><BR><B>SFC_CALC_NORM_MAX_ALL_CHANNELS</B></H2>
 377 <P>
 378 Calculate the normalised peak for each channel.
 379 This involves reading through the whole file which can be slow on large files.
 380 </P>
 381 <P>
 382 Parameters:
 383 <PRE>
 384         sndfile  : A valid SNDFILE* pointer
 385         cmd      : SFC_CALC_NORM_MAX_ALL_CHANNELS
 386         data     : A pointer to a double
 387         datasize : sizeof (double) * number_of_channels
 388 </PRE>
 389 <P>
 390 Example:
 391 </P>
 392 <PRE>
 393         double   peaks [number_of_channels] ;
 394         sf_command (sndfile, SFC_CALC_NORM_MAX_ALL_CHANNELS, peaks, sizeof (peaks)) ;
 395 </PRE>
 396 <DL>
 397 <DT>Return value:</DT>
 398         <DD>Zero if peaks have been calculated successfully and non-zero otherwise.
 399 </DL>
 400
 401
 402
 403
 404 <!-- ========================================================================= -->
 405 <A NAME="SFC_GET_SIGNAL_MAX"></A>
 406 <H2><BR><B>SFC_GET_SIGNAL_MAX</B></H2>
 407 <P>
 408 Retrieve the peak value for the file as stored in the file header.
 409 </P>
 410 <P>
 411 Parameters:
 412 <PRE>
 413         sndfile  : A valid SNDFILE* pointer
 414         cmd      : SFC_GET_SIGNAL_MAX
 415         data     : A pointer to a double
 416         datasize : sizeof (double)
 417 </PRE>
 418 <P>
 419 Example:
 420 </P>
 421 <PRE>
 422         double   max_peak ;
 423         sf_command (sndfile, SFC_GET_SIGNAL_MAX, &amp;max_peak, sizeof (max_peak)) ;
 424 </PRE>
 425 <DL>
 426 <DT>Return value:</DT>
 427         <DD>SF_TRUE if the file header contained the peak value. SF_FALSE otherwise.
 428 </DL>
 429
 430 <!-- ========================================================================= -->
 431 <A NAME="SFC_GET_MAX_ALL_CHANNELS"></A>
 432 <H2><BR><B>SFC_GET_MAX_ALL_CHANNELS</B></H2>
 433 <P>
 434 Retrieve the peak value for the file as stored in the file header.
 435 </P>
 436 <P>
 437 Parameters:
 438 <PRE>
 439         sndfile  : A valid SNDFILE* pointer
 440         cmd      : SFC_GET_SIGNAL_MAX
 441         data     : A pointer to an array of doubles
 442         datasize : sizeof (double) * number_of_channels
 443 </PRE>
 444 <P>
 445 Example:
 446 </P>
 447 <PRE>
 448         double   peaks [number_of_channels] ;
 449         sf_command (sndfile, SFC_GET_MAX_ALL_CHANNELS, peaks, sizeof (peaks)) ;
 450 </PRE>
 451 <DL>
 452 <DT>Return value:</DT>
 453         <DD>SF_TRUE if the file header contains per channel peak values for the file.
 454                 SF_FALSE otherwise.
 455 </DL>
 456
 457
 458 <!-- ========================================================================= -->
 459 <A NAME="SFC_SET_NORM_FLOAT"></A>
 460 <H2><BR><B>SFC_SET_NORM_FLOAT</B></H2>
 461 <P>
 462 This command only affects data read from or written to using the floating point functions:
 463 </P>
 464 <PRE>
 465         size_t    <A HREF="api.html#read">sf_read_float</A>    (SNDFILE *sndfile, float *ptr, size_t items) ;
 466         size_t    <A HREF="api.html#readf">sf_readf_float</A>   (SNDFILE *sndfile, float *ptr, size_t frames) ;
 467
 468         size_t    <A HREF="api.html#write">sf_write_float</A>   (SNDFILE *sndfile, float *ptr, size_t items) ;
 469         size_t    <A HREF="api.html#writef">sf_writef_float</A>  (SNDFILE *sndfile, float *ptr, size_t frames) ;
 470 </PRE>
 471 <P>
 472 Parameters:
 473 </P>
 474 <PRE>
 475         sndfile  : A valid SNDFILE* pointer
 476         cmd      : SFC_SET_NORM_FLOAT
 477         data     : NULL
 478         datasize : SF_TRUE or SF_FALSE
 479 </PRE>
 480 <P>
 481 For read operations setting normalisation to SF_TRUE means that the data from all
 482 subsequent reads will be be normalised to the range [-1.0, 1.0].
 483 </P>
 484 <P>
 485 For write operations, setting normalisation to SF_TRUE means than all data supplied
 486 to the float write functions should be in the range [-1.0, 1.0] and will be scaled
 487 for the file format as necessary.
 488 </P>
 489 <P>
 490 For both cases, setting normalisation to SF_FALSE means that no scaling will take place.
 491 </P>
 492 <P>
 493 Example:
 494 </P>
 495 <PRE>
 496         sf_command (sndfile, SFC_SET_NORM_FLOAT, NULL, SF_TRUE) ;
 497
 498         sf_command (sndfile, SFC_SET_NORM_FLOAT, NULL, SF_FALSE) ;
 499 </PRE>
 500 <DL>
 501 <DT>Return value: </DT>
 502         <DD>Returns the previous float normalisation mode.
 503 </DL>
 504
 505 <!-- ========================================================================= -->
 506 <A NAME="SFC_SET_NORM_DOUBLE"></A>
 507 <H2><BR><B>SFC_SET_NORM_DOUBLE</B></H2>
 508 <P>
 509 This command only affects data read from or written to using the double precision
 510 floating point functions:
 511 </P>
 512 <PRE>
 513         size_t    <A HREF="api.html#read">sf_read_double</A>    (SNDFILE *sndfile, double *ptr, size_t items) ;
 514         size_t    <A HREF="api.html#readf">sf_readf_double</A>   (SNDFILE *sndfile, double *ptr, size_t frames) ;
 515
 516         size_t    <A HREF="api.html#write">sf_write_double</A>   (SNDFILE *sndfile, double *ptr, size_t items) ;
 517         size_t    <A HREF="api.html#writef">sf_writef_double</A>  (SNDFILE *sndfile, double *ptr, size_t frames) ;
 518 </PRE>
 519 <P>
 520 Parameters:
 521 </P>
 522 <PRE>
 523         sndfile  : A valid SNDFILE* pointer
 524         cmd      : SFC_SET_NORM_DOUBLE
 525         data     : NULL
 526         datasize : SF_TRUE or SF_FALSE
 527 </PRE>
 528 <P>
 529 For read operations setting normalisation to SF_TRUE means that the data
 530 from all subsequent reads will be be normalised to the range [-1.0, 1.0].
 531 </P>
 532 <P>
 533 For write operations, setting normalisation to SF_TRUE means than all data supplied
 534 to the double write functions should be in the range [-1.0, 1.0] and will be scaled
 535 for the file format as necessary.
 536 </P>
 537 <P>
 538 For both cases, setting normalisation to SF_FALSE means that no scaling will take place.
 539 </P>
 540 <P>
 541 Example:
 542 </P>
 543 <PRE>
 544         sf_command (sndfile, SFC_SET_NORM_DOUBLE, NULL, SF_TRUE) ;
 545
 546         sf_command (sndfile, SFC_SET_NORM_DOUBLE, NULL, SF_FALSE) ;
 547 </PRE>
 548 <DL>
 549 <DT>Return value: </DT>
 550         <DD>Returns the previous double normalisation mode.
 551 </DL>
 552
 553 <!-- ========================================================================= -->
 554 <A NAME="SFC_GET_NORM_FLOAT"></A>
 555 <H2><BR><B>SFC_GET_NORM_FLOAT</B></H2>
 556 <P>
 557 Retrieve the current float normalisation mode.
 558 </P>
 559 <P>
 560 Parameters:
 561 </P>
 562 <PRE>
 563         sndfile  : A valid SNDFILE* pointer
 564         cmd      : SFC_GET_NORM_FLOAT
 565         data     : NULL
 566         datasize : anything
 567 </PRE>
 568 <P>
 569 Example:
 570 </P>
 571 <PRE>
 572         normalisation = sf_command (sndfile, SFC_GET_NORM_FLOAT, NULL, 0) ;
 573 </PRE>
 574 <DL>
 575 <DT>Return value: </DT>
 576         <DD>Returns TRUE if normalisation is on and FALSE otherwise.
 577 </DL>
 578
 579 <!-- ========================================================================= -->
 580 <A NAME="SFC_GET_NORM_DOUBLE"></A>
 581 <H2><BR><B>SFC_GET_NORM_DOUBLE</B></H2>
 582 <P>
 583 Retrieve the current float normalisation mode.
 584 </P>
 585 <P>
 586 Parameters:
 587 </P>
 588 <PRE>
 589         sndfile  : A valid SNDFILE* pointer
 590         cmd      : SFC_GET_NORM_DOUBLE
 591         data     : NULL
 592         datasize : anything
 593 </PRE>
 594 <P>
 595 Example:
 596 </P>
 597 <PRE>
 598         normalisation = sf_command (sndfile, SFC_GET_NORM_DOUBLE, NULL, 0) ;
 599 </PRE>
 600 <DL>
 601 <DT>Return value: </DT>
 602         <DD>Returns TRUE if normalisation is on and FALSE otherwise.
 603 </DL>
 604
 605
 606 <!-- ========================================================================= -->
 607 <A NAME="SFC_SET_SCALE_FLOAT_INT_READ"></A>
 608 <H2><BR><B>SFC_SET_SCALE_FLOAT_INT_READ</B></H2>
 609 <P>
 610 Set/clear the scale factor when integer (short/int) data is read from a file
 611 containing floating point data.
 612 </P>
 613 <P>
 614 Parameters:
 615 </P>
 616 <PRE>
 617         sndfile  : A valid SNDFILE* pointer
 618         cmd      : SFC_SET_SCALE_FLOAT_INT_READ
 619         data     : NULL
 620         datasize : TRUE or FALSE
 621 </PRE>
 622 <P>
 623 Example:
 624 </P>
 625 <PRE>
 626         sf_command (sndfile, SFC_SET_SCALE_FLOAT_INT_READ, NULL, SF_TRUE) ;
 627 </PRE>
 628 <DL>
 629 <DT>Return value: </DT>
 630         <DD>Returns the previous SFC_SET_SCALE_FLOAT_INT_READ setting for this file.
 631 </DL>
 632
 633
 634 <!-- ========================================================================= -->
 635 <A NAME="SFC_SET_SCALE_INT_FLOAT_WRITE"></A>
 636 <H2><BR><B>SFC_SET_SCALE_INT_FLOAT_WRITE</B></H2>
 637 <P>
 638 Set/clear the scale factor when integer (short/int) data is written to a file
 639 as floating point data.
 640 </P>
 641 <P>
 642 Parameters:
 643 </P>
 644 <PRE>
 645         sndfile  : A valid SNDFILE* pointer
 646         cmd      : SFC_SET_SCALE_FLOAT_INT_READ
 647         data     : NULL
 648         datasize : TRUE or FALSE
 649 </PRE>
 650 <P>
 651 Example:
 652 </P>
 653 <PRE>
 654         sf_command (sndfile, SFC_SET_SCALE_INT_FLOAT_WRITE, NULL, SF_TRUE) ;
 655 </PRE>
 656 <DL>
 657 <DT>Return value: </DT>
 658         <DD>Returns the previous SFC_SET_SCALE_INT_FLOAT_WRITE setting for this file.
 659 </DL>
 660
 661 <!-- ========================================================================= -->
 662 <A NAME="SFC_GET_SIMPLE_FORMAT_COUNT"></A>
 663 <H2><BR><B>SFC_GET_SIMPLE_FORMAT_COUNT</B></H2>
 664 <P>
 665 Retrieve the number of simple formats supported by libsndfile.
 666 </P>
 667 <P>
 668 Parameters:
 669 </P>
 670 <PRE>
 671         sndfile  : Not used.
 672         cmd      : SFC_GET_SIMPLE_FORMAT_COUNT
 673         data     : a pointer to an int
 674         datasize : sizeof (int)
 675 </PRE>
 676 <P>
 677 Example:
 678 </P>
 679 <PRE>
 680         int  count ;
 681         sf_command (sndfile, SFC_GET_SIMPLE_FORMAT_COUNT, &amp;count, sizeof (int)) ;
 682 </PRE>
 683 <DL>
 684 <DT>Return value: </DT>
 685         <DD>0
 686 </DL>
 687
 688 <!-- ========================================================================= -->
 689 <A NAME="SFC_GET_SIMPLE_FORMAT"></A>
 690 <H2><BR><B>SFC_GET_SIMPLE_FORMAT</B></H2>
 691 <P>
 692 Retrieve information about a simple format.
 693 </P>
 694 <P>
 695 Parameters:
 696 </P>
 697 <PRE>
 698         sndfile  : Not used.
 699         cmd      : SFC_GET_SIMPLE_FORMAT
 700         data     : a pointer to an  SF_FORMAT_INFO struct
 701         datasize : sizeof (SF_FORMAT_INFO)
 702 </PRE>
 703 <P>
 704 The SF_FORMAT_INFO struct is defined in &lt;sndfile.h&gt; as:
 705 </P>
 706 <PRE>
 707         typedef struct
 708         {   int         format ;
 709             const char  *name ;
 710             const char  *extension ;
 711         } SF_FORMAT_INFO ;
 712 </PRE>
 713 <P>
 714 When sf_command() is called with SF_GET_SIMPLE_FORMAT, the value of the format
 715 field should be the format number (ie 0 &lt;= format &lt;= count value obtained using
 716 SF_GET_SIMPLE_FORMAT_COUNT).
 717 </P>
 718 <P>
 719 Example:
 720 </P>
 721 <PRE>
 722         SF_FORMAT_INFO  format_info ;
 723         int             k, count ;
 724
 725         sf_command (sndfile, SFC_GET_SIMPLE_FORMAT_COUNT, &amp;count, sizeof (int)) ;
 726
 727         for (k = 0 ; k &lt; count ; k++)
 728         {   format_info.format = k ;
 729             sf_command (sndfile, SFC_GET_SIMPLE_FORMAT, &amp;format_info, sizeof (format_info)) ;
 730             printf ("%08x  %s %s\n", format_info.format, format_info.name, format_info.extension) ;
 731             } ;
 732 </PRE>
 733 <DL>
 734 <DT>Return value: </DT>
 735         <DD>0 on success and non-zero otherwise.
 736         <DD>The value of the format field of the SF_FORMAT_INFO struct will be a value which
 737                 can be placed in the format field of an SF_INFO struct when a file is to be opened
 738                 for write.
 739         <DD>The name field will contain a char* pointer to the name of the string, eg. "WAV (Microsoft 16 bit PCM)".
 740         <DD>The extension field will contain the most commonly used file extension for that file type.
 741 </DL>
 742
 743 <!-- ========================================================================= -->
 744 <A NAME="SFC_GET_FORMAT_INFO"></A>
 745 <H2><BR><B>SFC_GET_FORMAT_INFO</B></H2>
 746 <P>
 747 Retrieve information about a major or subtype format.
 748 </P>
 749 <P>
 750 Parameters:
 751 </P>
 752 <PRE>
 753         sndfile  : Not used.
 754         cmd      : SFC_GET_FORMAT_INFO
 755         data     : a pointer to an SF_FORMAT_INFO struct
 756         datasize : sizeof (SF_FORMAT_INFO)
 757 </PRE>
 758 <P>
 759 The SF_FORMAT_INFO struct is defined in &lt;sndfile.h&gt; as:
 760 </P>
 761 <PRE>
 762         typedef struct
 763         {   int         format ;
 764             const char  *name ;
 765             const char  *extension ;
 766         } SF_FORMAT_INFO ;
 767 </PRE>
 768 <P>
 769 When sf_command() is called with SF_GET_FORMAT_INFO, the format field is
 770 examined and if (format &amp; SF_FORMAT_TYPEMASK) is a valid format then the struct
 771 is filled in with information about the given major type.
 772 If (format &amp; SF_FORMAT_TYPEMASK) is FALSE and (format &amp; SF_FORMAT_SUBMASK) is a
 773 valid subtype format then the struct is filled in with information about the given
 774 subtype.
 775 </P>
 776 <P>
 777 Example:
 778 </P>
 779 <PRE>
 780         SF_FORMAT_INFO  format_info ;
 781
 782         format_info.format = SF_FORMAT_WAV ;
 783         sf_command (sndfile, SFC_GET_FORMAT_INFO, &amp;format_info, sizeof (format_info)) ;
 784         printf ("%08x  %s %s\n", format_info.format, format_info.name, format_info.extension) ;
 785
 786         format_info.format = SF_FORMAT_ULAW ;
 787         sf_command (sndfile, SFC_GET_FORMAT_INFO, &amp;format_info, sizeof (format_info)) ;
 788         printf ("%08x  %s\n", format_info.format, format_info.name) ;
 789 </PRE>
 790 <DL>
 791 <DT>Return value: </DT>
 792         <DD>0 on success and non-zero otherwise.
 793 </DL>
 794 <!-- ========================================================================= -->
 795 <A NAME="SFC_GET_FORMAT_MAJOR_COUNT"></A>
 796 <H2><BR><B>SFC_GET_FORMAT_MAJOR_COUNT</B></H2>
 797 <P>
 798 Retrieve the number of major formats.
 799 </P>
 800 <P>
 801 Parameters:
 802 </P>
 803 <PRE>
 804         sndfile  : Not used.
 805         cmd      : SFC_GET_FORMAT_MAJOR_COUNT
 806         data     : a pointer to an int
 807         datasize : sizeof (int)
 808 </PRE>
 809 <P>
 810 Example:
 811 </P>
 812 <PRE>
 813         int  count ;
 814         sf_command (sndfile, SFC_GET_FORMAT_MAJOR_COUNT, &amp;count, sizeof (int)) ;
 815 </PRE>
 816 <DL>
 817 <DT>Return value: </DT>
 818         <DD>0
 819 </DL>
 820
 821 <!-- ========================================================================= -->
 822 <A NAME="SFC_GET_FORMAT_MAJOR"></A>
 823 <H2><BR><B>SFC_GET_FORMAT_MAJOR</B></H2>
 824 <P>
 825 Retrieve information about a major format type.
 826 </P>
 827 <P>
 828 Parameters:
 829 </P>
 830 <PRE>
 831         sndfile  : Not used.
 832         cmd      : SFC_GET_FORMAT_MAJOR
 833         data     : a pointer to an  SF_FORMAT_INFO struct
 834         datasize : sizeof (SF_FORMAT_INFO)
 835 </PRE>
 836 <P>
 837 Example:
 838 </P>
 839 <PRE>
 840         SF_FORMAT_INFO  format_info ;
 841         int             k, count ;
 842
 843         sf_command (sndfile, SFC_GET_FORMAT_MAJOR_COUNT, &amp;count, sizeof (int)) ;
 844
 845         for (k = 0 ; k &lt; count ; k++)
 846         {   format_info.format = k ;
 847             sf_command (sndfile, SFC_GET_FORMAT_MAJOR, &amp;format_info, sizeof (format_info)) ;
 848             printf ("%08x  %s %s\n", format_info.format, format_info.name, format_info.extension) ;
 849             } ;
 850 </PRE>
 851 <P>
 852 For a more comprehensive example, see the program list_formats.c in the examples/
 853 directory of the libsndfile source code distribution.
 854 </P>
 855 <DL>
 856 <DT>Return value: </DT>
 857         <DD>0 on success and non-zero otherwise.
 858         <DD>The value of the format field will be one of the major format identifiers such as
 859                 SF_FORMAT_WAV or SF_FORMAT_AIFF.
 860         <DD>The name field will contain a char* pointer to the name of the string, eg. "WAV (Microsoft)".
 861         <DD>The extension field will contain the most commonly used file extension for that file type.
 862 </DL>
 863
 864 <!-- ========================================================================= -->
 865 <A NAME="SFC_GET_FORMAT_SUBTYPE_COUNT"></A>
 866 <H2><BR><B>SFC_GET_FORMAT_SUBTYPE_COUNT</B></H2>
 867 <P>
 868 Retrieve the number of subformats.
 869 </P>
 870 <P>
 871 Parameters:
 872 </P>
 873 <PRE>
 874         sndfile  : Not used.
 875         cmd      : SFC_GET_FORMAT_SUBTYPE_COUNT
 876         data     : a pointer to an int
 877         datasize : sizeof (int)
 878 </PRE>
 879 <P>
 880 Example:
 881 </P>
 882 <PRE>
 883         int   count ;
 884         sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE_COUNT, &amp;count, sizeof (int)) ;
 885 </PRE>
 886 <DL>
 887 <DT>Return value: </DT>
 888         <DD>0
 889 </DL>
 890
 891 <!-- ========================================================================= -->
 892 <A NAME="SFC_GET_FORMAT_SUBTYPE"></A>
 893 <H2><BR><B>SFC_GET_FORMAT_SUBTYPE</B></H2>
 894 <P>
 895 Enumerate the subtypes (this function does not translate a subtype into
 896 a string describing that subtype).
 897 A typical use case might be retrieving a string description of all subtypes
 898 so that a dialog box can be filled in.
 899 </P>
 900 <P>
 901
 902 </P>
 903 <P>
 904 Parameters:
 905 </P>
 906 <PRE>
 907         sndfile  : Not used.
 908         cmd      : SFC_GET_FORMAT_SUBTYPE
 909         data     : a pointer to an SF_FORMAT_INFO struct
 910         datasize : sizeof (SF_FORMAT_INFO)
 911 </PRE>
 912 <P>
 913 Example 1: Retrieve all sybtypes supported by the WAV format.
 914 </P>
 915 <PRE>
 916         SF_FORMAT_INFO  format_info ;
 917         int             k, count ;
 918
 919         sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE_COUNT, &amp;count, sizeof (int)) ;
 920
 921         for (k = 0 ; k &lt; count ; k++)
 922         {   format_info.format = k ;
 923             sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE, &amp;format_info, sizeof (format_info)) ;
 924             if (! sf_format_check (format_info.format | SF_FORMAT_WAV))
 925                continue ;
 926             printf ("%08x  %s\n", format_info.format, format_info.name) ;
 927             } ;
 928 </PRE>
 929 <P>
 930 Example 2: Print a string describing the SF_FORMAT_PCM_16 subtype.
 931 </P>
 932 <PRE>
 933         SF_FORMAT_INFO  format_info ;
 934         int             k, count ;
 935
 936         sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE_COUNT, &amp;count, sizeof (int)) ;
 937
 938         for (k = 0 ; k &lt; count ; k++)
 939         {   format_info.format = k ;
 940             sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE, &amp;format_info, sizeof (format_info)) ;
 941             if (format_info.format == SF_FORMAT_PCM_16)
 942             {   printf ("%08x  %s\n", format_info.format, format_info.name) ;
 943                 break ;
 944                 } ;
 945             } ;
 946 </PRE>
 947 <P>
 948 For a more comprehensive example, see the program list_formats.c in the examples/
 949 directory of the libsndfile source code distribution.
 950 </P>
 951 <DL>
 952 <DT>Return value: </DT>
 953         <DD>0 on success and non-zero otherwise.
 954         <DD>The value of the format field will be one of the major format identifiers such as
 955                 SF_FORMAT_WAV or SF_FORMAT_AIFF.
 956         <DD>The name field will contain a char* pointer to the name of the string; for instance
 957                 "WAV (Microsoft)" or "AIFF (Apple/SGI)".
 958         <DD>The extension field will be a NULL pointer.
 959 </DL>
 960
 961 <!-- ========================================================================= -->
 962 <A NAME="SFC_SET_ADD_PEAK_CHUNK"></A>
 963 <H2><BR><B>SFC_SET_ADD_PEAK_CHUNK</B></H2>
 964 <P>
 965 By default, WAV and AIFF files which contain floating point data (subtype SF_FORMAT_FLOAT
 966 or SF_FORMAT_DOUBLE) have a PEAK chunk.
 967 By using this command, the addition of a PEAK chunk can be turned on or off.
 968 </P>
 969 <P>
 970 Note : This call must be made before any data is written to the file.
 971 </P>
 972 <P>
 973 Parameters:
 974 <PRE>
 975         sndfile  : A valid SNDFILE* pointer
 976         cmd      : SFC_SET_ADD_PEAK_CHUNK
 977         data     : Not used (should be NULL)
 978         datasize : TRUE or FALSE.
 979 </PRE>
 980 <P>
 981 Example:
 982 </P>
 983 <PRE>
 984         /* Turn on the PEAK chunk. */
 985         sf_command (sndfile, SFC_SET_ADD_PEAK_CHUNK, NULL, SF_TRUE) ;
 986
 987         /* Turn off the PEAK chunk. */
 988         sf_command (sndfile, SFC_SET_ADD_PEAK_CHUNK, NULL, SF_FALSE) ;
 989 </PRE>
 990 <DL>
 991 <DT>Return value:</DT>
 992 <DD>Returns SF_TRUE if the peak chunk will be written after this call.
 993 <DD>Returns SF_FALSE if the peak chunk will not be written after this call.
 994 </DL>
 995
 996 <!-- ========================================================================= -->
 997 <A NAME="SFC_UPDATE_HEADER_NOW"></A>
 998 <H2><BR><B>SFC_UPDATE_HEADER_NOW</B></H2>
 999 <P>
1000 The header of an audio file is normally written by libsndfile when the file is
1001 closed using <B>sf_close()</B>.
1002 </P>
1003 <P>
1004 There are however situations where large files are being generated and it would
1005 be nice to have valid data in the header before the file is complete.
1006 Using this command will update the file header to reflect the amount of data written
1007 to the file so far.
1008 Other programs opening the file for read (before any more data is written) will
1009 then read a valid sound file header.
1010 </P>
1011 <P>
1012 Parameters:
1013 <PRE>
1014         sndfile  : A valid SNDFILE* pointer
1015         cmd      : SFC_UPDATE_HEADER_NOW
1016         data     : Not used (should be NULL)
1017         datasize : Not used.
1018 </PRE>
1019 <P>
1020 Example:
1021 </P>
1022 <PRE>
1023         /* Update the header now. */
1024         sf_command (sndfile, SFC_UPDATE_HEADER_NOW, NULL, 0) ;
1025 </PRE>
1026 <DL>
1027 <DT>Return value:</DT>
1028 <DD>0
1029 </DL>
1030
1031 <!-- ========================================================================= -->
1032 <A NAME="SFC_SET_UPDATE_HEADER_AUTO"></A>
1033 <H2><BR><B>SFC_SET_UPDATE_HEADER_AUTO</B></H2>
1034 <P>
1035 Similar to SFC_UPDATE_HEADER_NOW but updates the header at the end of every call
1036 to the <B>sf_write*</B> functions.
1037 </P>
1038 <P>
1039 Parameters:
1040 <PRE>
1041         sndfile  : A valid SNDFILE* pointer
1042         cmd      : SFC_UPDATE_HEADER_NOW
1043         data     : Not used (should be NULL)
1044         datasize : SF_TRUE or SF_FALSE
1045 </PRE>
1046 <P>
1047 Example:
1048 </P>
1049 <PRE>
1050         /* Turn on auto header update. */
1051         sf_command (sndfile, SFC_SET_UPDATE_HEADER_AUTO, NULL, SF_TRUE) ;
1052
1053         /* Turn off auto header update. */
1054         sf_command (sndfile, SFC_SET_UPDATE_HEADER_AUTO, NULL, SF_FALSE) ;
1055 </PRE>
1056 <DL>
1057 <DT>Return value:</DT>
1058 <DD>TRUE if auto update header is now on; FALSE otherwise.
1059 </DL>
1060
1061 <!-- ========================================================================= -->
1062 <A NAME="SFC_FILE_TRUNCATE"></A>
1063 <H2><BR><B>SFC_FILE_TRUNCATE</B></H2>
1064 <P>
1065 Truncate a file that was opened for write or read/write.
1066 </P>
1067 <P>
1068 Parameters:
1069 <PRE>
1070         sndfile  : A valid SNDFILE* pointer
1071         cmd      : SFC_FILE_TRUNCATE
1072         data     : A pointer to an sf_count_t.
1073         datasize : sizeof (sf_count_t)
1074 </PRE>
1075
1076 <P>
1077 Truncate the file to the number of frames specified by the sf_count_t pointed
1078 to by data.
1079 After this command, both the read and the write pointer will be
1080 at the new end of the file.
1081 This command will fail (returning non-zero) if the requested truncate position
1082 is beyond the end of the file.
1083 </P>
1084 <P>
1085 Example:
1086 </P>
1087 <PRE>
1088         /* Truncate the file to a length of 20 frames. */
1089         sf_count_t  frames = 20 ;
1090         sf_command (sndfile, SFC_FILE_TRUNCATE, &amp;frames, sizeof (frames)) ;
1091 </PRE>
1092 <DL>
1093 <DT>Return value:</DT>
1094         <DD>Zero on sucess, non-zero otherwise.
1095 </DL>
1096
1097 <!-- ========================================================================= -->
1098 <A NAME="SFC_SET_RAW_START_OFFSET"></A>
1099 <H2><BR><B>SFC_SET_RAW_START_OFFSET</B></H2>
1100 <P>
1101 Change the data start offset for files opened up as SF_FORMAT_RAW.
1102 </P>
1103 <P>
1104 Parameters:
1105 <PRE>
1106         sndfile  : A valid SNDFILE* pointer
1107         cmd      : SFC_SET_RAW_START_OFFSET
1108         data     : A pointer to an sf_count_t.
1109         datasize : sizeof (sf_count_t)
1110 </PRE>
1111
1112 <P>
1113 For a file opened as format SF_FORMAT_RAW, set the data offset to the value
1114 given by data.
1115 </P>
1116 <P>
1117 Example:
1118 </P>
1119 <PRE>
1120         /* Reset the data offset to 5 bytes from the start of the file. */
1121         sf_count_t  offset = 5 ;
1122         sf_command (sndfile, SFC_SET_RAW_START_OFFSET, &amp;offset, sizeof (offset)) ;
1123 </PRE>
1124 <DL>
1125 <DT>Return value:</DT>
1126         <DD>Zero on success, non-zero otherwise.
1127 </DL>
1128
1129 <!-- ========================================================================= -->
1130 <A NAME="SFC_SET_CLIPPING"></A>
1131 <H2><BR><B>SFC_SET_CLIPPING</B></H2>
1132 <P>
1133 Turn on/off automatic clipping when doing floating point to integer conversion.
1134 </P>
1135 <P>
1136 Parameters:
1137 <PRE>
1138         sndfile  : A valid SNDFILE* pointer
1139         cmd      : SFC_SET_CLIPPING
1140         data     : NULL
1141         datasize : SF_TRUE or SF_FALSE.
1142 </PRE>
1143
1144 <P>
1145 Turn on (datasize == SF_TRUE) or off (datasize == SF_FALSE) clipping.
1146 </P>
1147 <P>
1148 Example:
1149 </P>
1150 <PRE>
1151         sf_command (sndfile, SFC_SET_CLIPPING, NULL, SF_TRUE) ;
1152 </PRE>
1153 <DL>
1154 <DT>Return value:</DT>
1155         <DD>Clipping mode (SF_TRUE or SF_FALSE).
1156 </DL>
1157
1158
1159 <!-- ========================================================================= -->
1160 <A NAME="SFC_GET_CLIPPING"></A>
1161 <H2><BR><B>SFC_GET_CLIPPING</B></H2>
1162 <P>
1163 Turn on/off automatic clipping when doing floating point to integer conversion.
1164 </P>
1165 <P>
1166 Parameters:
1167 <PRE>
1168         sndfile  : A valid SNDFILE* pointer
1169         cmd      : SFC_GET_CLIPPING
1170         data     : NULL
1171         datasize : 0
1172 </PRE>
1173
1174 <P>
1175 Retrieve the current cliiping setting.
1176 </P>
1177 <P>
1178 Example:
1179 </P>
1180 <PRE>
1181         sf_command (sndfile, SFC_GET_CLIPPING, NULL, 0) ;
1182 </PRE>
1183 <DL>
1184 <DT>Return value:</DT>
1185         <DD>Clipping mode (SF_TRUE or SF_FALSE).
1186 </DL>
1187
1188 <!-- ========================================================================= -->
1189 <A NAME="SFC_GET_EMBED_FILE_INFO"></A>
1190 <H2><BR><B>SFC_GET_EMBED_FILE_INFO</B></H2>
1191 <P>
1192 Get the file offset and file length of a file enbedded within another
1193 larger file.
1194 </P>
1195 <P>
1196 Parameters:
1197 <PRE>
1198         sndfile  : A valid SNDFILE* pointer
1199         cmd      : SFC_GET_CLIPPING
1200         data     : a pointer to an  SF_EMBED_FILE_INFO struct
1201         datasize : sizeof (SF_EMBED_FILE_INFO)
1202 </PRE>
1203 <P>
1204 The SF_EMBED_FILE_INFO struct is defined in &lt;sndfile.h&gt; as:
1205 </P>
1206 <PRE>
1207         typedef struct
1208         {   sf_count_t  offset ;
1209             sf_count_t  length ;
1210         } SF_EMBED_FILE_INFO ;
1211 </PRE>
1212 <DL>
1213 <DT>Return value: </DT>
1214         <DD>0 on success and non-zero otherwise.
1215         <DD>The value of the offset field of the SF_EMBED_FILE_INFO struct will be
1216                 the offsets in bytes from the start of the outer file to the start of
1217                 the audio file.
1218         <DD>The value of the offset field of the SF_EMBED_FILE_INFO struct will be
1219                 the length in bytes of the embedded file.
1220 </DL>
1221
1222
1223
1224 <!-- ========================================================================= -->
1225 <A NAME="SFC_WAVEX_GET_AMBISONIC"></A>
1226 <H2><BR><B>SFC_WAVEX_GET_AMBISONIC</B></H2>
1227 <P>
1228 Test if the current file has the GUID of a WAVEX file for any of the Ambisonic
1229 formats.
1230 </P>
1231 <P>
1232 Parameters:
1233 <PRE>
1234         sndfile  : A valid SNDFILE* pointer
1235         cmd      : SFC_WAVEX_GET_AMBISONIC
1236         data     : NULL
1237         datasize : 0
1238 </PRE>
1239 <P>
1240         The Ambisonic WAVEX formats are defined here :
1241                 <A HREF="http://dream.cs.bath.ac.uk/researchdev/wave-ex/bformat.html">
1242                         http://dream.cs.bath.ac.uk/researchdev/wave-ex/bformat.html</A>.
1243 </P>
1244 <DL>
1245 <DT>Return value: </DT>
1246         <DD>SF_AMBISONIC_NONE or SF_AMBISONIC_B_FORMAT or zero if the file format
1247                 does not support ambisonic formats.
1248 </DL>
1249
1250 <!-- ========================================================================= -->
1251 <A NAME="SFC_WAVEX_SET_AMBISONIC"></A>
1252 <H2><BR><B>SFC_WAVEX_SET_AMBISONIC</B></H2>
1253 <P>
1254 Set the GUID of a new WAVEX file to indicate an Ambisonics format.
1255 </P>
1256 <P>
1257 Parameters:
1258 <PRE>
1259         sndfile  : A valid SNDFILE* pointer
1260         cmd      : SFC_WAVEX_SET_AMBISONIC
1261         data     : NULL
1262         datasize : SF_AMBISONIC_NONE or SF_AMBISONIC_B_FORMAT
1263 </PRE>
1264 <P>
1265 Turn on (SF_AMBISONIC_B_FORMAT) or off (SF_AMBISONIC_NONE) encoding.
1266 This command is currently only supported for files with SF_FORMAT_WAVEX format.
1267 </P>
1268 <P>
1269         The Ambisonic WAVEX formats are defined here :
1270                 <A HREF="http://dream.cs.bath.ac.uk/researchdev/wave-ex/bformat.html">
1271                         http://dream.cs.bath.ac.uk/researchdev/wave-ex/bformat.html</A>.
1272 </P>
1273 <DL>
1274 <DT>Return value: </DT>
1275         <DD>Return the ambisonic value that has just been set or zero if the file
1276                 format does not support ambisonic encoding.
1277 </DL>
1278
1279 <!-- ========================================================================= -->
1280 <A NAME="SFC_SET_VBR_ENCODING_QUALITY"></A>
1281 <H2><BR><B>SFC_SET_VBR_ENCODING_QUALITY</B></H2>
1282 <P>
1283 Set the the Variable Bit Rate encoding quality.
1284 The encoding quality value should be between 0.0 (lowest quality) and 1.0
1285 (highest quality).
1286 </P>
1287 <P>
1288 Parameters:
1289 <PRE>
1290         sndfile  : A valid SNDFILE* pointer
1291         cmd      : SFC_SET_VBR_ENCODING_QUALITY
1292         data     : A pointer to a double value
1293         datasize : sizeof (double)
1294 </PRE>
1295 <P>
1296 The command must be sent before any audio data is written to the file.
1297 </P>
1298 <P>
1299 </P>
1300 <DL>
1301 <DT>Return value: </DT>
1302         <DD>Zero on success, non-zero otherwise.
1303 </DL>
1304
1305 <!-- ========================================================================= -->
1306 <A NAME="SFC_RAW_NEEDS_ENDSWAP"></A>
1307 <H2><BR><B>SFC_RAW_NEEDS_ENDSWAP</B></H2>
1308 <P>
1309 Determine if raw data read using
1310         <a href="api.html#raw">
1311         sf_read_raw</a>
1312 needs to be end swapped on the host CPU.
1313 </P>
1314 <P>
1315 For instance, will return SF_TRUE on when reading WAV containing
1316 SF_FORMAT_PCM_16 data on a big endian machine and SF_FALSE on a little endian
1317 machine.
1318 </P>
1319 <P>
1320 Parameters:
1321 <PRE>
1322         sndfile  : A valid SNDFILE* pointer
1323         cmd      : SFC_RAW_NEEDS_ENDSWAP
1324         data     : NULL
1325         datasize : 0
1326 </PRE>
1327
1328 <DL>
1329 <DT>Return value: </DT>
1330         <DD>SF_TRUE or SF_FALSE
1331 </DL>
1332
1333
1334 <!-- ========================================================================= -->
1335 <A NAME="SFC_GET_BROADCAST_INFO"></A>
1336 <H2><BR><B>SFC_GET_BROADCAST_INFO</B></H2>
1337 <P>
1338 Retrieve the Broadcast Extension Chunk from WAV (and related) files.
1339 </P>
1340 <p>
1341 Parameters:
1342 </p>
1343 <PRE>
1344         sndfile  : A valid SNDFILE* pointer
1345         cmd      : SFC_GET_BROADCAST_INFO
1346         data     : a pointer to an SF_BROADCAST_INFO struct
1347         datasize : sizeof (SF_BROADCAST_INFO)
1348 </PRE>
1349 <P>
1350 The SF_BROADCAST_INFO struct is defined in &lt;sndfile.h&gt; as:
1351 </P>
1352 <PRE>
1353     typedef struct
1354     {   char            description [256] ;
1355         char            originator [32] ;
1356         char            originator_reference [32] ;
1357         char            origination_date [10] ;
1358         char            origination_time [8] ;
1359         unsigned int    time_reference_low ;
1360         unsigned int    time_reference_high ;
1361         short           version ;
1362         char            umid [64] ;
1363         char            reserved [190] ;
1364         unsigned int    coding_history_size ;
1365         char            coding_history [256] ;
1366     } SF_BROADCAST_INFO ;
1367 </PRE>
1368
1369 <DL>
1370 <DT>Return value: </DT>
1371         <DD>SF_TRUE if the file contained a Broadcast Extension chunk or SF_FALSE
1372         otherwise.
1373 </DL>
1374
1375 <!-- ========================================================================= -->
1376 <A NAME="SFC_SET_BROADCAST_INFO"></A>
1377 <H2><BR><B>SFC_SET_BROADCAST_INFO</B></H2>
1378 <P>
1379 Set the Broadcast Extension Chunk for WAV (and related) files.
1380 </P>
1381 <p>
1382 Parameters:
1383 </p>
1384 <PRE>
1385         sndfile  : A valid SNDFILE* pointer
1386         cmd      : SFC_SET_BROADCAST_INFO
1387         data     : a pointer to an SF_BROADCAST_INFO struct
1388         datasize : sizeof (SF_BROADCAST_INFO)
1389 </PRE>
1390
1391 <DL>
1392 <DT>Return value: </DT>
1393         <DD>SF_TRUE if setting the Broadcast Extension chunk was successful and SF_FALSE
1394         otherwise.
1395 </DL>
1396 <!-- ========================================================================= -->
1397
1398
1399 <HR>
1400 <P>
1401         The libsndfile home page is here :
1402                 <A HREF="http://www.mega-nerd.com/libsndfile/">
1403                         http://www.mega-nerd.com/libsndfile/</A>.
1404 <BR>
1405 Version : 1.0.21
1406 </P>
1407
1408 </BODY>
1409 </HTML>