Mercurial > hg > sv-dependency-builds

annotate src/libsndfile-1.0.25/doc/command.html @ 83:ae30d91d2ffe

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