Mercurial > hg > sv-dependency-builds

annotate src/libsndfile-1.0.27/doc/dither.html @ 40:1df64224f5ac

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