Mercurial > hg > sv-dependency-builds

annotate src/libsndfile-1.0.25/doc/command.html @ 88:fe7c3a0b0259

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