Mercurial > hg > sv-dependency-builds

annotate src/libsndfile-1.0.27/doc/dither.html @ 169:223a55898ab9 tip default

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