Mercurial > hg > sv-dependency-builds

annotate src/libsndfile-1.0.25/doc/dither.html @ 0:c7265573341e

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