| 1 |
--- |
| 2 |
layout: page |
| 3 |
title: libsndfile : the sf_command function. |
| 4 |
--- |
| 5 |
|
| 6 |
# sf_command |
| 7 |
|
| 8 |
```c |
| 9 |
int sf_command (SNDFILE *sndfile, int cmd, void *data, int datasize) ; |
| 10 |
``` |
| 11 |
|
| 12 |
This function allows the caller to retrieve information from or change aspects |
| 13 |
of the library behaviour. Examples include retrieving a string containing the |
| 14 |
library version or changing the scaling applied to floating point sample data |
| 15 |
during read and write. Most of these operations are performed on a per-file |
| 16 |
basis. |
| 17 |
|
| 18 |
The cmd parameter is an integer identifier which is defined in *sndfile.h*. All |
| 19 |
of the valid command identifiers have names beginning with "SFC_". Data is |
| 20 |
passed to and returned from the library by use of a void pointer. The library |
| 21 |
will not read or write more than datasize bytes from the void pointer. For some |
| 22 |
calls no data is required in which case data should be NULL and datasize may be |
| 23 |
used for some other purpose. |
| 24 |
|
| 25 |
The available commands are as follows: |
| 26 |
|
| 27 |
| Name | Description | |
| 28 |
|:------------------------------------------------------------------|:--------------------------------------------------------| |
| 29 |
| [SFC_GET_LIB_VERSION](#sfc_get_lib_version) | Retrieve the version of the library as a string. | |
| 30 |
| [SFC_GET_LOG_INFO](#sfc_get_log_info) | Retrieve the internal per-file operation log. | |
| 31 |
| [SFC_GET_CURRENT_SF_INFO](#sfc_get_current_sf_info) | Retrieve `SF_INFO` struct of opened file. | |
| 32 |
| [SFC_CALC_SIGNAL_MAX](#sfc_calc_signal_max) | Calculate the measured maximum signal value. | |
| 33 |
| [SFC_CALC_NORM_SIGNAL_MAX](#sfc_calc_norm_signal_max) | Calculate the measured normalised maximum signal value. | |
| 34 |
| [SFC_CALC_MAX_ALL_CHANNELS](#sfc_calc_max_all_channels) | Calculate the peak value for each channel. | |
| 35 |
| [SFC_CALC_NORM_MAX_ALL_CHANNELS](#sfc_calc_norm_max_all_channels) | Calculate the normalised peak for each channel. | |
| 36 |
| [SFC_GET_SIGNAL_MAX](#sfc_get_signal_max) | Retrieve the peak value for the file. | |
| 37 |
| [SFC_GET_MAX_ALL_CHANNELS](#sfc_get_max_all_channels) | Retrieve the peak value for each channel. | |
| 38 |
| [SFC_SET_NORM_FLOAT](#sfc_set_norm_float) | Set float normalisation behaviour. | |
| 39 |
| [SFC_SET_NORM_DOUBLE](#sfc_set_norm_double) | Set double normalisation behaviour. | |
| 40 |
| [SFC_GET_NORM_FLOAT](#sfc_get_norm_float) | Get float normalisation behaviour. | |
| 41 |
| [SFC_GET_NORM_DOUBLE](#sfc_get_norm_double) | Get double normalisation behaviour. | |
| 42 |
| [SFC_SET_SCALE_FLOAT_INT_READ](#sfc_set_scale_float_int_read) | Control scale factor on read. | |
| 43 |
| [SFC_SET_SCALE_INT_FLOAT_WRITE](#sfc_set_scale_int_float_write) | Control scale factor on write. | |
| 44 |
| [SFC_GET_SIMPLE_FORMAT_COUNT](#sfc_get_simple_format_count) | Get simple formats count. | |
| 45 |
| [SFC_GET_SIMPLE_FORMAT](#sfc_get_simple_format) | Get information about a simple format. | |
| 46 |
| [SFC_GET_FORMAT_INFO](#sfc_get_format_info) | Get information about a major or subtype format. | |
| 47 |
| [SFC_GET_FORMAT_MAJOR_COUNT](#sfc_get_format_major_count) | Get the number of major formats. | |
| 48 |
| [SFC_GET_FORMAT_MAJOR](#sfc_get_format_major) | Get information about a major format type. | |
| 49 |
| [SFC_GET_FORMAT_SUBTYPE_COUNT](#sfc_get_format_subtype_count) | Get the number of subformats. | |
| 50 |
| [SFC_GET_FORMAT_SUBTYPE](#sfc_get_format_subtype) | Get information about a subformat. | |
| 51 |
| [SFC_SET_ADD_PEAK_CHUNK](#sfc_set_add_peak_chunk) | Control PEAK chunk write to WAV and AIFF. | |
| 52 |
| [SFC_UPDATE_HEADER_NOW](#sfc_update_header_now) | Update the file header in write mode on demand. | |
| 53 |
| [SFC_SET_UPDATE_HEADER_AUTO](#sfc_set_update_header_auto) | Update the file header on each write. | |
| 54 |
| [SFC_FILE_TRUNCATE](#sfc_file_truncate) | Truncate a file open for write or for read/write. | |
| 55 |
| [SFC_SET_RAW_START_OFFSET](#sfc_set_raw_start_offset) | Change the data start offset for raw files. | |
| 56 |
| SFC_SET_DITHER_ON_WRITE | Not implemented. | |
| 57 |
| SFC_SET_DITHER_ON_READ | Not implemented. | |
| 58 |
| SFC_GET_DITHER_INFO_COUNT | Not implemented. | |
| 59 |
| SFC_GET_DITHER_INFO | Not implemented. | |
| 60 |
| [SFC_SET_CLIPPING](#sfc_set_clipping) | Control automatic clipping behaviour. | |
| 61 |
| [SFC_GET_CLIPPING](#sfc_get_clipping) | Get current clipping setting. | |
| 62 |
| [SFC_GET_EMBED_FILE_INFO](#sfc_get_embed_file_info) | Get information about embedded audio files. | |
| 63 |
| [SFC_WAVEX_GET_AMBISONIC](#sfc_wavex_get_ambisonic) | Test a WAVEX file for Ambisonic format. | |
| 64 |
| [SFC_WAVEX_SET_AMBISONIC](#sfc_wavex_set_ambisonic) | Modify a WAVEX header for Ambisonic format. | |
| 65 |
| [SFC_SET_VBR_ENCODING_QUALITY](#sfc_set_vbr_encoding_quality) | Set the Variable Bit Rate encoding quality. | |
| 66 |
| [SFC_SET_OGG_PAGE_LATENCY_MS](#sfc_set_ogg_page_latency_ms) | Set Ogg page latency for Opus file. | |
| 67 |
| [SFC_GET_OGG_STREAM_SERIALNO](#sfc_get_ogg_stream_serialno) | Get Ogg stream serial number. | |
| 68 |
| [SFC_SET_COMPRESSION_LEVEL](#sfc_set_compression_level) | Set the compression level. | |
| 69 |
| [SFC_RAW_DATA_NEEDS_ENDSWAP](#sfc_raw_data_needs_endswap) | Determine if raw data needs endswapping. | |
| 70 |
| [SFC_GET_BROADCAST_INFO](#sfc_get_broadcast_info) | Get the Broadcast Chunk info. | |
| 71 |
| [SFC_SET_BROADCAST_INFO](#sfc_set_broadcast_info) | Set the Broadcast Chunk info. | |
| 72 |
| [SFC_GET_CHANNEL_MAP_INFO](#sfc_get_channel_map_info) | Get the channel map info. | |
| 73 |
| [SFC_SET_CHANNEL_MAP_INFO](#sfc_set_channel_map_info) | Set the channel map info. | |
| 74 |
| [SFC_SET_CART_INFO](#sfc_set_cart_info) | Set the Cart Chunk info. | |
| 75 |
| [SFC_GET_CART_INFO](#sfc_get_cart_info) | Get the Cart Chunk info. | |
| 76 |
| [SFC_GET_LOOP_INFO](#sfc_get_loop_info) | Get loop info. | |
| 77 |
| [SFC_GET_INSTRUMENT](#sfc_get_instrument) | Get instrument info. | |
| 78 |
| [SFC_SET_INSTRUMENT](#sfc_set_instrument) | Set instrument info. | |
| 79 |
| [SFC_GET_CUE_COUNT](#sfc_get_cue_count) | Get the cue marker count. | |
| 80 |
| [SFC_GET_CUE](#sfc_get_cue) | Get cue marker info. | |
| 81 |
| [SFC_SET_CUE](#sfc_set_cue) | Set cue marker info. | |
| 82 |
| [SFC_RF64_AUTO_DOWNGRADE](#sfc_rf64_auto_downgrade) | Set auto downgrade from RF64 to WAV. | |
| 83 |
| [SFC_GET_ORIGINAL_SAMPLERATE](#sfc_get_original_samplerate) | Get original samplerate metadata. | |
| 84 |
| [SFC_SET_ORIGINAL_SAMPLERATE](#sfc_set_original_samplerate) | Set original samplerate metadata. | |
| 85 |
| [SFC_GET_BITRATE_MODE](#sfc_get_bitrate_mode) | Get bitrate mode. | |
| 86 |
| [SFC_SET_BITRATE_MODE](#sfc_set_bitrate_mode) | Set bitrate mode. | |
| 87 |
|
| 88 |
--- |
| 89 |
|
| 90 |
## SFC_GET_LIB_VERSION |
| 91 |
|
| 92 |
Retrieve the version of the library as a string. |
| 93 |
|
| 94 |
### Parameters |
| 95 |
|
| 96 |
sndfile |
| 97 |
: Not used |
| 98 |
|
| 99 |
cmd |
| 100 |
: SFC_GET_LIB_VERSION |
| 101 |
|
| 102 |
data |
| 103 |
: A pointer to a char buffer |
| 104 |
|
| 105 |
datasize |
| 106 |
: The size of the buffer |
| 107 |
|
| 108 |
### Examples |
| 109 |
|
| 110 |
```c |
| 111 |
char buffer [128] ; |
| 112 |
sf_command (NULL, SFC_GET_LIB_VERSION, buffer, sizeof (buffer)) ; |
| 113 |
``` |
| 114 |
|
| 115 |
### Return value |
| 116 |
|
| 117 |
This call will return the length of the retrieved version string. |
| 118 |
|
| 119 |
### Notes |
| 120 |
|
| 121 |
The string returned in the buffer passed to this function will not overflow the |
| 122 |
buffer and will always be null terminated . |
| 123 |
|
| 124 |
## SFC_GET_LOG_INFO |
| 125 |
|
| 126 |
Retrieve the internal per-file operation log. |
| 127 |
|
| 128 |
This log buffer can often contain a good reason for why libsndfile failed to |
| 129 |
open a particular file. |
| 130 |
|
| 131 |
### Parameters |
| 132 |
|
| 133 |
sndfile |
| 134 |
: A valid SNDFILE* pointer |
| 135 |
|
| 136 |
cmd |
| 137 |
: SFC_GET_LOG_INFO |
| 138 |
|
| 139 |
data |
| 140 |
: A pointer to a char buffer |
| 141 |
|
| 142 |
datasize |
| 143 |
: The size of the buffer |
| 144 |
|
| 145 |
Example: |
| 146 |
|
| 147 |
```c |
| 148 |
char buffer [2048] ; |
| 149 |
sf_command (sndfile, SFC_GET_LOG_INFO, buffer, sizeof (buffer)) ; |
| 150 |
``` |
| 151 |
|
| 152 |
### Return value |
| 153 |
|
| 154 |
This call will return the length of the retrieved version string. |
| 155 |
|
| 156 |
### Notes |
| 157 |
|
| 158 |
The string returned in the buffer passed to this function will not overflow the |
| 159 |
buffer and will always be null terminated. |
| 160 |
|
| 161 |
## SFC_GET_CURRENT_SF_INFO |
| 162 |
|
| 163 |
Retrieve `SF_INFO` struct of opened file. |
| 164 |
|
| 165 |
`SFC_GET_CURRENT_SF_INFO` command copies `SF_INFO` struct of `sndfile` object to |
| 166 |
provided buffer. |
| 167 |
|
| 168 |
### Parameters |
| 169 |
|
| 170 |
sndfile |
| 171 |
: A valid SNDFILE* pointer |
| 172 |
|
| 173 |
cmd |
| 174 |
: SFC_GET_CURRENT_SF_INFO |
| 175 |
|
| 176 |
data |
| 177 |
: A pointer to a valid SF_INFO* pointer |
| 178 |
|
| 179 |
datasize |
| 180 |
: sizeof (SF_INFO) |
| 181 |
|
| 182 |
### Examples |
| 183 |
|
| 184 |
```c |
| 185 |
SF_INFO sfinfo ; |
| 186 |
sf_command (sndfile, SFC_GET_CURRENT_SF_INFO, sfinfo, sizeof (SF_INFO)) ; |
| 187 |
``` |
| 188 |
|
| 189 |
### Return value |
| 190 |
|
| 191 |
Zero on success, non-zero otherwise. |
| 192 |
|
| 193 |
## SFC_CALC_SIGNAL_MAX |
| 194 |
|
| 195 |
Retrieve the measured maximum signal value. This involves reading through the |
| 196 |
whole file which can be slow on large files. |
| 197 |
|
| 198 |
### Parameters |
| 199 |
|
| 200 |
sndfile |
| 201 |
: A valid SNDFILE* pointer |
| 202 |
|
| 203 |
cmd |
| 204 |
: SFC_CALC_SIGNAL_MAX |
| 205 |
|
| 206 |
data |
| 207 |
: A pointer to a double |
| 208 |
|
| 209 |
datasize |
| 210 |
: sizeof (double) |
| 211 |
|
| 212 |
### Examples |
| 213 |
|
| 214 |
```c |
| 215 |
double max_val ; |
| 216 |
sf_command (sndfile, SFC_CALC_SIGNAL_MAX, &max_val, sizeof (max_val)) ; |
| 217 |
``` |
| 218 |
|
| 219 |
### Return value |
| 220 |
|
| 221 |
Zero on success, non-zero otherwise. |
| 222 |
|
| 223 |
## SFC_CALC_NORM_SIGNAL_MAX |
| 224 |
|
| 225 |
Retrieve the measured normalised maximum signal value. This involves reading |
| 226 |
through the whole file which can be slow on large files. |
| 227 |
|
| 228 |
### Parameters |
| 229 |
|
| 230 |
sndfile |
| 231 |
: A valid SNDFILE* pointer |
| 232 |
|
| 233 |
cmd |
| 234 |
: SFC_CALC_NORM_SIGNAL_MAX |
| 235 |
|
| 236 |
data |
| 237 |
: A pointer to a double |
| 238 |
|
| 239 |
datasize |
| 240 |
: sizeof (double) |
| 241 |
|
| 242 |
### Examples |
| 243 |
|
| 244 |
```c |
| 245 |
double max_val ; |
| 246 |
sf_command (sndfile, SFC_CALC_NORM_SIGNAL_MAX, &max_val, sizeof (max_val)) ; |
| 247 |
``` |
| 248 |
|
| 249 |
### Return value |
| 250 |
|
| 251 |
Zero on success, non-zero otherwise. |
| 252 |
|
| 253 |
## SFC_CALC_MAX_ALL_CHANNELS |
| 254 |
|
| 255 |
Calculate the peak value (ie a single number) for each channel. This involves |
| 256 |
reading through the whole file which can be slow on large files. |
| 257 |
|
| 258 |
### Parameters |
| 259 |
|
| 260 |
sndfile |
| 261 |
: A valid SNDFILE* pointer |
| 262 |
|
| 263 |
cmd |
| 264 |
: SFC_CALC_MAX_ALL_CHANNELS |
| 265 |
|
| 266 |
data |
| 267 |
: A pointer to a double |
| 268 |
|
| 269 |
datasize |
| 270 |
: sizeof (double) * number_of_channels |
| 271 |
|
| 272 |
### Examples |
| 273 |
|
| 274 |
```c |
| 275 |
double peaks [number_of_channels] ; |
| 276 |
sf_command (sndfile, SFC_CALC_MAX_ALL_CHANNELS, peaks, sizeof (peaks)) ; |
| 277 |
``` |
| 278 |
|
| 279 |
### Return value |
| 280 |
|
| 281 |
Zero if peaks have been calculated successfully and non-zero otherwise. |
| 282 |
|
| 283 |
## SFC_CALC_NORM_MAX_ALL_CHANNELS |
| 284 |
|
| 285 |
Calculate the normalised peak for each channel. This involves reading through |
| 286 |
the whole file which can be slow on large files. |
| 287 |
|
| 288 |
### Parameters |
| 289 |
|
| 290 |
sndfile |
| 291 |
: A valid SNDFILE* pointer |
| 292 |
|
| 293 |
cmd |
| 294 |
: SFC_CALC_NORM_MAX_ALL_CHANNELS |
| 295 |
|
| 296 |
data |
| 297 |
: A pointer to a double |
| 298 |
|
| 299 |
datasize |
| 300 |
: sizeof (double) * number_of_channels |
| 301 |
|
| 302 |
### Examples |
| 303 |
|
| 304 |
```c |
| 305 |
double peaks [number_of_channels] ; |
| 306 |
sf_command (sndfile, SFC_CALC_NORM_MAX_ALL_CHANNELS, peaks, sizeof (peaks)) ; |
| 307 |
``` |
| 308 |
|
| 309 |
### Return value |
| 310 |
|
| 311 |
Zero if peaks have been calculated successfully and non-zero otherwise. |
| 312 |
|
| 313 |
## SFC_GET_SIGNAL_MAX |
| 314 |
|
| 315 |
Retrieve the peak value for the file as stored in the file header. |
| 316 |
|
| 317 |
### Parameters |
| 318 |
|
| 319 |
sndfile |
| 320 |
: A valid SNDFILE* pointer |
| 321 |
|
| 322 |
cmd |
| 323 |
: SFC_GET_SIGNAL_MAX |
| 324 |
|
| 325 |
data |
| 326 |
: A pointer to a double |
| 327 |
|
| 328 |
datasize |
| 329 |
: sizeof (double) |
| 330 |
|
| 331 |
### Examples |
| 332 |
|
| 333 |
```c |
| 334 |
double max_peak ; |
| 335 |
sf_command (sndfile, SFC_GET_SIGNAL_MAX, &max_peak, sizeof (max_peak)) ; |
| 336 |
``` |
| 337 |
|
| 338 |
### Return value |
| 339 |
|
| 340 |
SF_TRUE if the file header contained the peak value. SF_FALSE |
| 341 |
otherwise. |
| 342 |
|
| 343 |
## SFC_GET_MAX_ALL_CHANNELS |
| 344 |
|
| 345 |
Retrieve the peak value for the file as stored in the file header. |
| 346 |
|
| 347 |
### Parameters |
| 348 |
|
| 349 |
sndfile |
| 350 |
: A valid SNDFILE* pointer |
| 351 |
|
| 352 |
cmd |
| 353 |
: SFC_GET_SIGNAL_MAX |
| 354 |
|
| 355 |
data |
| 356 |
: A pointer to an array of doubles |
| 357 |
|
| 358 |
datasize |
| 359 |
: sizeof (double) * number_of_channels |
| 360 |
|
| 361 |
### Example |
| 362 |
|
| 363 |
```c |
| 364 |
double peaks [number_of_channels] ; |
| 365 |
sf_command (sndfile, SFC_GET_MAX_ALL_CHANNELS, peaks, sizeof (peaks)) ; |
| 366 |
``` |
| 367 |
|
| 368 |
### Return value |
| 369 |
|
| 370 |
SF_TRUE if the file header contains per channel peak values for the file, |
| 371 |
SF_FALSE otherwise. |
| 372 |
|
| 373 |
## SFC_SET_NORM_FLOAT |
| 374 |
|
| 375 |
This command only affects data read from or written to using the |
| 376 |
floating point |
| 377 |
functions: |
| 378 |
|
| 379 |
```c |
| 380 |
size_t sf_read_float (SNDFILE *sndfile, float *ptr, size_t items) ; |
| 381 |
size_t sf_readf_float (SNDFILE *sndfile, float *ptr, size_t frames) ; |
| 382 |
|
| 383 |
size_t sf_write_float (SNDFILE *sndfile, float *ptr, size_t items) ; |
| 384 |
size_t sf_writef_float (SNDFILE *sndfile, float *ptr, size_t frames) ; |
| 385 |
``` |
| 386 |
|
| 387 |
### Parameters |
| 388 |
|
| 389 |
sndfile |
| 390 |
: A valid SNDFILE* pointer |
| 391 |
|
| 392 |
cmd |
| 393 |
: SFC_SET_NORM_FLOAT |
| 394 |
|
| 395 |
data |
| 396 |
: NULL |
| 397 |
|
| 398 |
datasize |
| 399 |
: SF_TRUE or SF_FALSE |
| 400 |
|
| 401 |
For read operations setting normalisation to SF_TRUE means that the data from |
| 402 |
all subsequent reads will be be normalised to the range [-1.0, 1.0]. |
| 403 |
|
| 404 |
For write operations, setting normalisation to SF_TRUE means than all data |
| 405 |
supplied to the float write functions should be in the range [-1.0, 1.0] and |
| 406 |
will be scaled for the file format as necessary. |
| 407 |
|
| 408 |
For both cases, setting normalisation to SF_FALSE means that no scaling will |
| 409 |
take place. |
| 410 |
|
| 411 |
### Examples |
| 412 |
|
| 413 |
```c |
| 414 |
sf_command (sndfile, SFC_SET_NORM_FLOAT, NULL, SF_TRUE) ; |
| 415 |
|
| 416 |
sf_command (sndfile, SFC_SET_NORM_FLOAT, NULL, SF_FALSE) ; |
| 417 |
``` |
| 418 |
|
| 419 |
### Return value |
| 420 |
|
| 421 |
Returns the previous float normalisation mode. |
| 422 |
|
| 423 |
## SFC_SET_NORM_DOUBLE |
| 424 |
|
| 425 |
This command only affects data read from or written to using the double |
| 426 |
precision floating point |
| 427 |
functions: |
| 428 |
|
| 429 |
```c |
| 430 |
size_t sf_read_double (SNDFILE *sndfile, double *ptr, size_t items) ; |
| 431 |
size_t sf_readf_double (SNDFILE *sndfile, double *ptr, size_t frames) ; |
| 432 |
|
| 433 |
size_t sf_write_double (SNDFILE *sndfile, double *ptr, size_t items) ; |
| 434 |
size_t sf_writef_double (SNDFILE *sndfile, double *ptr, size_t frames) ; |
| 435 |
``` |
| 436 |
|
| 437 |
### Parameters |
| 438 |
|
| 439 |
sndfile |
| 440 |
: A valid SNDFILE* pointer |
| 441 |
|
| 442 |
cmd |
| 443 |
: SFC_SET_NORM_DOUBLE |
| 444 |
|
| 445 |
data |
| 446 |
: NULL |
| 447 |
|
| 448 |
datasize |
| 449 |
: SF_TRUE or SF_FALSE |
| 450 |
|
| 451 |
For read operations setting normalisation to SF_TRUE means that the data from |
| 452 |
all subsequent reads will be be normalised to the range [-1.0, 1.0]. |
| 453 |
|
| 454 |
For write operations, setting normalisation to SF_TRUE means than all data |
| 455 |
supplied to the double write functions should be in the range [-1.0, 1.0] and |
| 456 |
will be scaled for the file format as necessary. |
| 457 |
|
| 458 |
For both cases, setting normalisation to SF_FALSE means that no scaling will |
| 459 |
take place. |
| 460 |
|
| 461 |
### Examples |
| 462 |
|
| 463 |
```c |
| 464 |
sf_command (sndfile, SFC_SET_NORM_DOUBLE, NULL, SF_TRUE) ; |
| 465 |
|
| 466 |
sf_command (sndfile, SFC_SET_NORM_DOUBLE, NULL, SF_FALSE) ; |
| 467 |
``` |
| 468 |
|
| 469 |
### Return value |
| 470 |
|
| 471 |
Returns the previous double normalisation mode. |
| 472 |
|
| 473 |
## SFC_GET_NORM_FLOAT |
| 474 |
|
| 475 |
Retrieve the current float normalisation mode. |
| 476 |
|
| 477 |
### Parameters |
| 478 |
|
| 479 |
sndfile |
| 480 |
: A valid SNDFILE* pointer |
| 481 |
|
| 482 |
cmd |
| 483 |
: SFC_GET_NORM_FLOAT |
| 484 |
|
| 485 |
data |
| 486 |
: NULL |
| 487 |
|
| 488 |
datasize |
| 489 |
: anything |
| 490 |
|
| 491 |
### Examples |
| 492 |
|
| 493 |
```c |
| 494 |
normalisation = sf_command (sndfile, SFC_GET_NORM_FLOAT, NULL, 0) ; |
| 495 |
``` |
| 496 |
|
| 497 |
### Return value |
| 498 |
|
| 499 |
Returns TRUE if normalisation is on and FALSE otherwise. |
| 500 |
|
| 501 |
## SFC_GET_NORM_DOUBLE |
| 502 |
|
| 503 |
Retrieve the current float normalisation mode. |
| 504 |
|
| 505 |
### Parameters |
| 506 |
|
| 507 |
sndfile |
| 508 |
: A valid SNDFILE* pointer |
| 509 |
|
| 510 |
cmd |
| 511 |
: SFC_GET_NORM_DOUBLE |
| 512 |
|
| 513 |
data |
| 514 |
: NULL |
| 515 |
|
| 516 |
datasize |
| 517 |
: anything |
| 518 |
|
| 519 |
Example: |
| 520 |
|
| 521 |
```c |
| 522 |
normalisation = sf_command (sndfile, SFC_GET_NORM_DOUBLE, NULL, 0) ; |
| 523 |
``` |
| 524 |
|
| 525 |
### Return value |
| 526 |
|
| 527 |
Returns TRUE if normalisation is on and FALSE otherwise. |
| 528 |
|
| 529 |
## SFC_SET_SCALE_FLOAT_INT_READ |
| 530 |
|
| 531 |
Set/clear the scale factor when integer (short/int) data is read from a file |
| 532 |
containing floating point data. |
| 533 |
|
| 534 |
### Parameters |
| 535 |
|
| 536 |
sndfile |
| 537 |
: A valid SNDFILE* pointer |
| 538 |
|
| 539 |
cmd: |
| 540 |
SFC_SET_SCALE_FLOAT_INT_READ |
| 541 |
|
| 542 |
data |
| 543 |
: NULL |
| 544 |
|
| 545 |
datasize |
| 546 |
: TRUE or FALSE |
| 547 |
|
| 548 |
Example: |
| 549 |
|
| 550 |
```c |
| 551 |
sf_command (sndfile, SFC_SET_SCALE_FLOAT_INT_READ, NULL, SF_TRUE) ; |
| 552 |
``` |
| 553 |
|
| 554 |
### Return value |
| 555 |
|
| 556 |
Returns the previous `SFC_SET_SCALE_FLOAT_INT_READ` setting for this file. |
| 557 |
|
| 558 |
## SFC_SET_SCALE_INT_FLOAT_WRITE |
| 559 |
|
| 560 |
Set/clear the scale factor when integer (short/int) data is written to a file as |
| 561 |
floating point data. |
| 562 |
|
| 563 |
### Parameters |
| 564 |
|
| 565 |
sndfile |
| 566 |
: A valid SNDFILE* pointer |
| 567 |
|
| 568 |
cmd |
| 569 |
: SFC_SET_SCALE_INT_FLOAT_WRITE |
| 570 |
|
| 571 |
data |
| 572 |
: NULL |
| 573 |
|
| 574 |
datasize |
| 575 |
: TRUE or FALSE |
| 576 |
|
| 577 |
### Examples |
| 578 |
|
| 579 |
```c |
| 580 |
sf_command (sndfile, SFC_SET_SCALE_INT_FLOAT_WRITE, NULL, SF_TRUE) ; |
| 581 |
``` |
| 582 |
|
| 583 |
### Return value |
| 584 |
|
| 585 |
Returns the previous `SFC_SET_SCALE_INT_FLOAT_WRITE` setting for this file. |
| 586 |
|
| 587 |
## SFC_GET_SIMPLE_FORMAT_COUNT |
| 588 |
|
| 589 |
Retrieve the number of simple formats supported by libsndfile. |
| 590 |
|
| 591 |
### Parameters |
| 592 |
|
| 593 |
sndfile |
| 594 |
: Not used. |
| 595 |
|
| 596 |
cmd |
| 597 |
: SFC_GET_SIMPLE_FORMAT_COUNT |
| 598 |
|
| 599 |
data |
| 600 |
: a pointer to an int |
| 601 |
|
| 602 |
datasize |
| 603 |
: sizeof (int) |
| 604 |
|
| 605 |
### Examples |
| 606 |
|
| 607 |
```c |
| 608 |
int count ; |
| 609 |
sf_command (sndfile, SFC_GET_SIMPLE_FORMAT_COUNT, &count, sizeof (int)) ; |
| 610 |
``` |
| 611 |
|
| 612 |
### Return value |
| 613 |
|
| 614 |
`0`. |
| 615 |
|
| 616 |
## SFC_GET_SIMPLE_FORMAT |
| 617 |
|
| 618 |
Retrieve information about a simple format. |
| 619 |
|
| 620 |
### Parameters |
| 621 |
|
| 622 |
sndfile |
| 623 |
: Not used. |
| 624 |
|
| 625 |
cmd |
| 626 |
: SFC_GET_SIMPLE_FORMAT |
| 627 |
|
| 628 |
data |
| 629 |
: a pointer to an SF_FORMAT_INFO struct |
| 630 |
|
| 631 |
datasize |
| 632 |
: sizeof (SF_FORMAT_INFO) |
| 633 |
|
| 634 |
The SF_FORMAT_INFO struct is defined in *sndfile.h* as: |
| 635 |
|
| 636 |
```c |
| 637 |
typedef struct |
| 638 |
{ int format ; |
| 639 |
const char *name ; |
| 640 |
const char *extension ; |
| 641 |
} SF_FORMAT_INFO ; |
| 642 |
``` |
| 643 |
|
| 644 |
When `sf_command()` is called with `SF_GET_SIMPLE_FORMAT`, the value of the |
| 645 |
format field should be the format number (ie 0 \<= format \<= count value |
| 646 |
obtained using `SF_GET_SIMPLE_FORMAT_COUNT). |
| 647 |
|
| 648 |
### Examples |
| 649 |
|
| 650 |
```c |
| 651 |
SF_FORMAT_INFO format_info ; |
| 652 |
int k, count ; |
| 653 |
|
| 654 |
sf_command (sndfile, SFC_GET_SIMPLE_FORMAT_COUNT, &count, sizeof (int)) ; |
| 655 |
|
| 656 |
for (k = 0 ; k < count ; k++) |
| 657 |
{ format_info.format = k ; |
| 658 |
sf_command (sndfile, SFC_GET_SIMPLE_FORMAT, &format_info, sizeof (format_info)) ; |
| 659 |
printf ("%08x %s %s\n", format_info.format, format_info.name, format_info.extension) ; |
| 660 |
} ; |
| 661 |
``` |
| 662 |
|
| 663 |
### Return value |
| 664 |
|
| 665 |
0 on success and non-zero otherwise. |
| 666 |
|
| 667 |
The value of the format field of the `SF_FORMAT_INFO` struct will be a value |
| 668 |
which can be placed in the format field of an `SF_INFO` struct when a file is to |
| 669 |
be opened for write. The name field will contain a char\* pointer to the name of |
| 670 |
the string, eg. "WAV (Microsoft 16 bit PCM)". The extension field will contain |
| 671 |
the most commonly used file extension for that file type. |
| 672 |
|
| 673 |
## SFC_GET_FORMAT_INFO |
| 674 |
|
| 675 |
Retrieve information about a major or subtype format. |
| 676 |
|
| 677 |
### Parameters |
| 678 |
|
| 679 |
sndfile |
| 680 |
: Not used. |
| 681 |
|
| 682 |
cmd |
| 683 |
: SFC_GET_FORMAT_INFO |
| 684 |
|
| 685 |
data |
| 686 |
: a pointer to an SF_FORMAT_INFO struct |
| 687 |
|
| 688 |
datasize |
| 689 |
: sizeof (SF_FORMAT_INFO) |
| 690 |
|
| 691 |
The `SF_FORMAT_INFO` struct is defined in \<sndfile.h\> as: |
| 692 |
|
| 693 |
```c |
| 694 |
typedef struct |
| 695 |
{ int format ; |
| 696 |
const char *name ; |
| 697 |
const char *extension ; |
| 698 |
} SF_FORMAT_INFO ; |
| 699 |
``` |
| 700 |
|
| 701 |
When `sf_command()` is called with `SF_GET_FORMAT_INFO`, the format field is |
| 702 |
examined and if (format & `SF_FORMAT_TYPEMASK`) is a valid format then the |
| 703 |
struct is filled in with information about the given major type. If (format & |
| 704 |
`SF_FORMAT_TYPEMASK`) is FALSE and (format & `SF_FORMAT_SUBMASK`) is a valid |
| 705 |
subtype format then the struct is filled in with information about the given |
| 706 |
subtype. |
| 707 |
|
| 708 |
### Examples |
| 709 |
|
| 710 |
```c |
| 711 |
SF_FORMAT_INFO format_info ; |
| 712 |
|
| 713 |
format_info.format = SF_FORMAT_WAV ; |
| 714 |
sf_command (sndfile, SFC_GET_FORMAT_INFO, &format_info, sizeof (format_info)) ; |
| 715 |
printf ("%08x %s %s\n", format_info.format, format_info.name, format_info.extension) ; |
| 716 |
|
| 717 |
format_info.format = SF_FORMAT_ULAW ; |
| 718 |
sf_command (sndfile, SFC_GET_FORMAT_INFO, &format_info, sizeof (format_info)) ; |
| 719 |
printf ("%08x %s\n", format_info.format, format_info.name) ; |
| 720 |
``` |
| 721 |
|
| 722 |
### Return value |
| 723 |
|
| 724 |
0 on success and non-zero otherwise. |
| 725 |
|
| 726 |
## SFC_GET_FORMAT_MAJOR_COUNT |
| 727 |
|
| 728 |
Retrieve the number of major formats. |
| 729 |
|
| 730 |
### Parameters |
| 731 |
|
| 732 |
sndfile |
| 733 |
: Not used. |
| 734 |
|
| 735 |
cmd |
| 736 |
: SFC_GET_FORMAT_MAJOR_COUNT |
| 737 |
|
| 738 |
data |
| 739 |
: a pointer to an int |
| 740 |
|
| 741 |
datasize |
| 742 |
: sizeof (int) |
| 743 |
|
| 744 |
### Examples |
| 745 |
|
| 746 |
```c |
| 747 |
int count ; |
| 748 |
sf_command (sndfile, SFC_GET_FORMAT_MAJOR_COUNT, &count, sizeof (int)) ; |
| 749 |
``` |
| 750 |
|
| 751 |
### Return value |
| 752 |
|
| 753 |
0. |
| 754 |
|
| 755 |
## SFC_GET_FORMAT_MAJOR |
| 756 |
|
| 757 |
Retrieve information about a major format type. |
| 758 |
|
| 759 |
### Parameters |
| 760 |
|
| 761 |
sndfile |
| 762 |
: Not used. |
| 763 |
|
| 764 |
cmd |
| 765 |
: SFC_GET_FORMAT_MAJOR |
| 766 |
|
| 767 |
data |
| 768 |
: a pointer to an SF_FORMAT_INFO struct |
| 769 |
|
| 770 |
datasize |
| 771 |
: sizeof (SF_FORMAT_INFO) |
| 772 |
|
| 773 |
### Examples |
| 774 |
|
| 775 |
```c |
| 776 |
SF_FORMAT_INFO format_info ; |
| 777 |
int k, count ; |
| 778 |
|
| 779 |
sf_command (sndfile, SFC_GET_FORMAT_MAJOR_COUNT, &count, sizeof (int)) ; |
| 780 |
|
| 781 |
for (k = 0 ; k < count ; k++) |
| 782 |
{ format_info.format = k ; |
| 783 |
sf_command (sndfile, SFC_GET_FORMAT_MAJOR, &format_info, sizeof (format_info)) ; |
| 784 |
printf ("%08x %s %s\n", format_info.format, format_info.name, format_info.extension) ; |
| 785 |
} ; |
| 786 |
``` |
| 787 |
|
| 788 |
For a more comprehensive example, see the program `list_formats.c` in the |
| 789 |
`examples/` directory of the libsndfile source code distribution. |
| 790 |
|
| 791 |
### Return value |
| 792 |
|
| 793 |
0 on success and non-zero otherwise. |
| 794 |
|
| 795 |
The value of the format field will be one of the major format identifiers such |
| 796 |
as `SF_FORMAT_WAV` or `SF_FORMAT`_AIFF. The name field will contain a char\* |
| 797 |
pointer to the name of the string, eg. "WAV (Microsoft)". The extension field |
| 798 |
will contain the most commonly used file extension for that file type. |
| 799 |
|
| 800 |
## SFC_GET_FORMAT_SUBTYPE_COUNT |
| 801 |
|
| 802 |
Retrieve the number of subformats. |
| 803 |
|
| 804 |
### Parameters |
| 805 |
|
| 806 |
sndfile |
| 807 |
: Not used. |
| 808 |
|
| 809 |
cmd |
| 810 |
: SFC_GET_FORMAT_SUBTYPE_COUNT |
| 811 |
|
| 812 |
data |
| 813 |
: a pointer to an int |
| 814 |
|
| 815 |
datasize |
| 816 |
: sizeof (int) |
| 817 |
|
| 818 |
### Examples |
| 819 |
|
| 820 |
```c |
| 821 |
int count ; |
| 822 |
sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE_COUNT, &count, sizeof (int)) ; |
| 823 |
``` |
| 824 |
|
| 825 |
### Return value |
| 826 |
|
| 827 |
Returns zero. |
| 828 |
|
| 829 |
## SFC_GET_FORMAT_SUBTYPE |
| 830 |
|
| 831 |
Enumerate the subtypes (this function does not translate a subtype into a string |
| 832 |
describing that subtype). A typical use case might be retrieving a string |
| 833 |
description of all subtypes so that a dialog box can be filled in. |
| 834 |
|
| 835 |
### Parameters |
| 836 |
|
| 837 |
sndfile |
| 838 |
: Not used. |
| 839 |
|
| 840 |
cmd |
| 841 |
: SFC_GET_FORMAT_SUBTYPE |
| 842 |
|
| 843 |
data |
| 844 |
: a pointer to an SF_FORMAT_INFO struct |
| 845 |
|
| 846 |
datasize |
| 847 |
: sizeof (SF_FORMAT_INFO) |
| 848 |
|
| 849 |
### Examples |
| 850 |
|
| 851 |
Example 1: Retrieve all sybtypes supported by the WAV format. |
| 852 |
|
| 853 |
```c |
| 854 |
SF_FORMAT_INFO format_info ; |
| 855 |
int k, count ; |
| 856 |
|
| 857 |
sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE_COUNT, &count, sizeof (int)) ; |
| 858 |
|
| 859 |
for (k = 0 ; k < count ; k++) |
| 860 |
{ format_info.format = k ; |
| 861 |
sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE, &format_info, sizeof (format_info)) ; |
| 862 |
if (! sf_format_check (format_info.format | SF_FORMAT_WAV)) |
| 863 |
continue ; |
| 864 |
printf ("%08x %s\n", format_info.format, format_info.name) ; |
| 865 |
} ; |
| 866 |
``` |
| 867 |
|
| 868 |
Example 2: Print a string describing the `SF_FORMAT_PCM_16` subtype. |
| 869 |
|
| 870 |
```c |
| 871 |
SF_FORMAT_INFO format_info ; |
| 872 |
int k, count ; |
| 873 |
|
| 874 |
sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE_COUNT, &count, sizeof (int)) ; |
| 875 |
|
| 876 |
for (k = 0 ; k < count ; k++) |
| 877 |
{ format_info.format = k ; |
| 878 |
sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE, &format_info, sizeof (format_info)) ; |
| 879 |
if (format_info.format == SF_FORMAT_PCM_16) |
| 880 |
{ printf ("%08x %s\n", format_info.format, format_info.name) ; |
| 881 |
break ; |
| 882 |
} ; |
| 883 |
} ; |
| 884 |
``` |
| 885 |
|
| 886 |
For a more comprehensive example, see the program `list_formats.c` in the |
| 887 |
`examples/` directory of the libsndfile source code distribution. |
| 888 |
|
| 889 |
### Return value |
| 890 |
|
| 891 |
0 on success and non-zero otherwise. |
| 892 |
|
| 893 |
The value of the format field will be one of the major format identifiers such |
| 894 |
as `SF_FORMAT_WAV` or `SF_FORMAT_AIFF`. The name field will contain a char\* |
| 895 |
pointer to the name of the string; for instance "WAV (Microsoft)" or "AIFF |
| 896 |
(Apple/SGI)". The extension field will be a NULL pointer. |
| 897 |
|
| 898 |
## SFC_SET_ADD_PEAK_CHUNK |
| 899 |
|
| 900 |
By default, WAV and AIFF files which contain floating point data (subtype |
| 901 |
`SF_FORMAT_FLOAT` or `SF_FORMAT_DOUBLE`) have a PEAK chunk. By using this |
| 902 |
command, the addition of a PEAK chunk can be turned on or off. |
| 903 |
|
| 904 |
**Note**: This call must be made before any data is written to the file. |
| 905 |
|
| 906 |
### Parameters |
| 907 |
|
| 908 |
sndfile |
| 909 |
: A valid SNDFILE* pointer |
| 910 |
|
| 911 |
cmd |
| 912 |
: SFC_SET_ADD_PEAK_CHUNK |
| 913 |
|
| 914 |
data |
| 915 |
: Not used (should be NULL) |
| 916 |
|
| 917 |
datasize |
| 918 |
: TRUE or FALSE. |
| 919 |
|
| 920 |
### Examples |
| 921 |
|
| 922 |
```c |
| 923 |
/* Turn on the PEAK chunk. */ |
| 924 |
sf_command (sndfile, SFC_SET_ADD_PEAK_CHUNK, NULL, SF_TRUE) ; |
| 925 |
|
| 926 |
/* Turn off the PEAK chunk. */ |
| 927 |
sf_command (sndfile, SFC_SET_ADD_PEAK_CHUNK, NULL, SF_FALSE) ; |
| 928 |
``` |
| 929 |
|
| 930 |
### Return value |
| 931 |
|
| 932 |
Returns SF_TRUE if the peak chunk will be written after this call. Returns |
| 933 |
SF_FALSE if the peak chunk will not be written after this call. |
| 934 |
|
| 935 |
## SFC_UPDATE_HEADER_NOW |
| 936 |
|
| 937 |
The header of an audio file is normally written by libsndfile when the file is |
| 938 |
closed using [**sf_close()**](api.md#file-close-function). |
| 939 |
|
| 940 |
There are however situations where large files are being generated and it would |
| 941 |
be nice to have valid data in the header before the file is complete. Using this |
| 942 |
command will update the file header to reflect the amount of data written to the |
| 943 |
file so far. Other programs opening the file for read (before any more data is |
| 944 |
written) will then read a valid sound file header. |
| 945 |
|
| 946 |
### Parameters |
| 947 |
|
| 948 |
sndfile |
| 949 |
: A valid SNDFILE* pointer |
| 950 |
|
| 951 |
cmd |
| 952 |
: SFC_UPDATE_HEADER_NOW |
| 953 |
|
| 954 |
data |
| 955 |
: Not used (should be NULL) |
| 956 |
|
| 957 |
datasize |
| 958 |
: Not used. |
| 959 |
|
| 960 |
### Examples |
| 961 |
|
| 962 |
```c |
| 963 |
/* Update the header now. */ |
| 964 |
sf_command (sndfile, SFC_UPDATE_HEADER_NOW, NULL, 0) ; |
| 965 |
``` |
| 966 |
|
| 967 |
### Return value |
| 968 |
|
| 969 |
Returns zero. |
| 970 |
|
| 971 |
## SFC_SET_UPDATE_HEADER_AUTO |
| 972 |
|
| 973 |
Similar to `SFC_UPDATE_HEADER_NOW` but updates the header at the end of every |
| 974 |
call to the [sf_write\*](api.md#write) functions. |
| 975 |
|
| 976 |
### Parameters |
| 977 |
|
| 978 |
sndfile |
| 979 |
: A valid SNDFILE* pointer |
| 980 |
|
| 981 |
cmd |
| 982 |
: SFC_SET_UPDATE_HEADER_AUTO |
| 983 |
|
| 984 |
data |
| 985 |
: Not used (should be NULL) |
| 986 |
|
| 987 |
datasize |
| 988 |
: `SF_TRUE` or `SF_FALSE` |
| 989 |
|
| 990 |
### Examples |
| 991 |
|
| 992 |
```c |
| 993 |
/* Turn on auto header update. */ |
| 994 |
sf_command (sndfile, SFC_SET_UPDATE_HEADER_AUTO, NULL, SF_TRUE) ; |
| 995 |
|
| 996 |
/* Turn off auto header update. */ |
| 997 |
sf_command (sndfile, SFC_SET_UPDATE_HEADER_AUTO, NULL, SF_FALSE) ; |
| 998 |
``` |
| 999 |
|
| 1000 |
### Return value |
| 1001 |
|
| 1002 |
TRUE if auto update header is now on; FALSE otherwise. |
| 1003 |
|
| 1004 |
## SFC_FILE_TRUNCATE |
| 1005 |
|
| 1006 |
Truncate a file that was opened for write or read/write. |
| 1007 |
|
| 1008 |
### Parameters |
| 1009 |
|
| 1010 |
sndfile |
| 1011 |
: A valid SNDFILE* pointer |
| 1012 |
|
| 1013 |
cmd |
| 1014 |
: SFC_FILE_TRUNCATE |
| 1015 |
|
| 1016 |
data |
| 1017 |
: A pointer to an sf_count_t. |
| 1018 |
|
| 1019 |
datasize |
| 1020 |
: sizeof (sf_count_t) |
| 1021 |
|
| 1022 |
Truncate the file to the number of frames specified by the sf_count_t pointed to |
| 1023 |
by data. After this command, both the read and the write pointer will be at the |
| 1024 |
new end of the file. This command will fail (returning non-zero) if the |
| 1025 |
requested truncate position is beyond the end of the file. |
| 1026 |
|
| 1027 |
### Examples |
| 1028 |
|
| 1029 |
```c |
| 1030 |
/* Truncate the file to a length of 20 frames. */ |
| 1031 |
sf_count_t frames = 20 ; |
| 1032 |
sf_command (sndfile, SFC_FILE_TRUNCATE, &frames, sizeof (frames)) ; |
| 1033 |
``` |
| 1034 |
|
| 1035 |
### Return value |
| 1036 |
|
| 1037 |
Zero on success, non-zero otherwise. |
| 1038 |
|
| 1039 |
## SFC_SET_RAW_START_OFFSET |
| 1040 |
|
| 1041 |
Change the data start offset for files opened up as `SF_FORMAT_RAW`. |
| 1042 |
|
| 1043 |
### Parameters |
| 1044 |
|
| 1045 |
sndfile |
| 1046 |
: A valid SNDFILE* pointer |
| 1047 |
|
| 1048 |
cmd |
| 1049 |
: SFC_SET_RAW_START_OFFSET |
| 1050 |
|
| 1051 |
data |
| 1052 |
: A pointer to an sf_count_t. |
| 1053 |
|
| 1054 |
datasize |
| 1055 |
: sizeof (sf_count_t) |
| 1056 |
|
| 1057 |
For a file opened as format `SF_FORMAT_RAW`, set the data offset to the value |
| 1058 |
given by `data`. |
| 1059 |
|
| 1060 |
### Examples |
| 1061 |
|
| 1062 |
```c |
| 1063 |
/* Reset the data offset to 5 bytes from the start of the file. */ |
| 1064 |
sf_count_t offset = 5 ; |
| 1065 |
sf_command (sndfile, SFC_SET_RAW_START_OFFSET, &offset, sizeof (offset)) ; |
| 1066 |
``` |
| 1067 |
|
| 1068 |
### Return value |
| 1069 |
|
| 1070 |
Zero on success, non-zero otherwise. |
| 1071 |
|
| 1072 |
## SFC_SET_CLIPPING |
| 1073 |
|
| 1074 |
Turn on/off automatic clipping when doing floating point to integer conversion. |
| 1075 |
|
| 1076 |
### Parameters |
| 1077 |
|
| 1078 |
sndfile |
| 1079 |
: A valid SNDFILE* pointer |
| 1080 |
|
| 1081 |
cmd |
| 1082 |
: SFC_SET_CLIPPING |
| 1083 |
|
| 1084 |
data |
| 1085 |
: NULL |
| 1086 |
|
| 1087 |
datasize |
| 1088 |
: SF_TRUE or SF_FALSE. |
| 1089 |
|
| 1090 |
Turn on (datasize == SF_TRUE) or off (datasize == SF_FALSE) clipping. |
| 1091 |
|
| 1092 |
### Examples |
| 1093 |
|
| 1094 |
```c |
| 1095 |
sf_command (sndfile, SFC_SET_CLIPPING, NULL, SF_TRUE) ; |
| 1096 |
``` |
| 1097 |
|
| 1098 |
### Return value |
| 1099 |
|
| 1100 |
Clipping mode (SF_TRUE or SF_FALSE). |
| 1101 |
|
| 1102 |
## SFC_GET_CLIPPING |
| 1103 |
|
| 1104 |
Turn on/off automatic clipping when doing floating point to integer conversion. |
| 1105 |
|
| 1106 |
### Parameters |
| 1107 |
|
| 1108 |
sndfile |
| 1109 |
: A valid SNDFILE* pointer |
| 1110 |
|
| 1111 |
cmd |
| 1112 |
: SFC_GET_CLIPPING |
| 1113 |
|
| 1114 |
data |
| 1115 |
: NULL |
| 1116 |
|
| 1117 |
datasize |
| 1118 |
: 0 |
| 1119 |
|
| 1120 |
Retrieve the current cliiping setting. |
| 1121 |
|
| 1122 |
### Examples |
| 1123 |
|
| 1124 |
```c |
| 1125 |
sf_command (sndfile, SFC_GET_CLIPPING, NULL, 0) ; |
| 1126 |
``` |
| 1127 |
|
| 1128 |
### Return value |
| 1129 |
|
| 1130 |
Clipping mode (SF_TRUE or SF_FALSE). |
| 1131 |
|
| 1132 |
## SFC_GET_EMBED_FILE_INFO |
| 1133 |
|
| 1134 |
Get the file offset and file length of a file enbedded within another larger |
| 1135 |
file. |
| 1136 |
|
| 1137 |
### Parameters |
| 1138 |
|
| 1139 |
sndfile |
| 1140 |
: A valid SNDFILE* pointer |
| 1141 |
|
| 1142 |
cmd |
| 1143 |
: SFC_GET_EMBED_FILE_INFO |
| 1144 |
|
| 1145 |
data |
| 1146 |
: a pointer to an SF_EMBED_FILE_INFO struct |
| 1147 |
|
| 1148 |
datasize |
| 1149 |
: sizeof (SF_EMBED_FILE_INFO) |
| 1150 |
|
| 1151 |
The `SF_EMBED_FILE_INFO` struct is defined in *sndfile.h* as: |
| 1152 |
|
| 1153 |
```c |
| 1154 |
typedef struct |
| 1155 |
{ sf_count_t offset ; |
| 1156 |
sf_count_t length ; |
| 1157 |
} SF_EMBED_FILE_INFO ; |
| 1158 |
``` |
| 1159 |
|
| 1160 |
### Return value |
| 1161 |
|
| 1162 |
0 on success and non-zero otherwise. |
| 1163 |
|
| 1164 |
The value of the offset field of the `SF_EMBED_FILE_INFO` struct will be the |
| 1165 |
offsets in bytes from the start of the outer file to the start of the audio |
| 1166 |
file. The value of the offset field of the `SF_EMBED_FILE_INFO` struct will be |
| 1167 |
the length in bytes of the embedded file. |
| 1168 |
|
| 1169 |
## SFC_WAVEX_GET_AMBISONIC |
| 1170 |
|
| 1171 |
Test if the current file has the GUID of a WAVEX file for any of the Ambisonic |
| 1172 |
formats. |
| 1173 |
|
| 1174 |
### Parameters |
| 1175 |
|
| 1176 |
sndfile |
| 1177 |
: A valid SNDFILE* pointer |
| 1178 |
|
| 1179 |
cmd |
| 1180 |
: SFC_WAVEX_GET_AMBISONIC |
| 1181 |
|
| 1182 |
data |
| 1183 |
: NULL |
| 1184 |
|
| 1185 |
datasize |
| 1186 |
: 0 |
| 1187 |
|
| 1188 |
The Ambisonic WAVEX formats are defined here: |
| 1189 |
<http://dream.cs.bath.ac.uk/researchdev/wave-ex/bformat.html>. |
| 1190 |
|
| 1191 |
### Return value |
| 1192 |
|
| 1193 |
`SF_AMBISONIC_NONE(0x40)` or `SF_AMBISONIC_B_FORMAT(0x41)` or zero if the file |
| 1194 |
format does not support ambisonic formats. |
| 1195 |
|
| 1196 |
## SFC_WAVEX_SET_AMBISONIC |
| 1197 |
|
| 1198 |
Set the GUID of a new WAVEX file to indicate an Ambisonics format. |
| 1199 |
|
| 1200 |
### Parameters |
| 1201 |
|
| 1202 |
sndfile |
| 1203 |
: A valid SNDFILE* pointer |
| 1204 |
|
| 1205 |
cmd |
| 1206 |
: SFC_WAVEX_SET_AMBISONIC |
| 1207 |
|
| 1208 |
data |
| 1209 |
: NULL |
| 1210 |
|
| 1211 |
datasize |
| 1212 |
: SF_AMBISONIC_NONE or SF_AMBISONIC_B_FORMAT |
| 1213 |
|
| 1214 |
Turn on (`SF_AMBISONIC_B_FORMAT(0x41)`) or off (`SF_AMBISONIC_NONE(0x40)`) |
| 1215 |
encoding. This command is currently only supported for files with |
| 1216 |
`SF_FORMAT_WAVEX` format. |
| 1217 |
|
| 1218 |
The Ambisonic WAVEX formats are defined here: |
| 1219 |
|
| 1220 |
<http://dream.cs.bath.ac.uk/researchdev/wave-ex/bformat.html>. |
| 1221 |
|
| 1222 |
### Return value |
| 1223 |
|
| 1224 |
Return the ambisonic value that has just been set or zero if the |
| 1225 |
file format does not support ambisonic encoding. |
| 1226 |
|
| 1227 |
## SFC_SET_VBR_ENCODING_QUALITY |
| 1228 |
|
| 1229 |
Set the Variable Bit Rate encoding quality. The encoding quality value |
| 1230 |
should be between 0.0 (lowest quality) and 1.0 (highest quality). |
| 1231 |
Currently this command is only implemented for FLAC and Ogg/Vorbis files. |
| 1232 |
It has no effect on un-compressed file formats. |
| 1233 |
|
| 1234 |
### Parameters |
| 1235 |
|
| 1236 |
sndfile |
| 1237 |
: A valid SNDFILE* pointer |
| 1238 |
|
| 1239 |
cmd |
| 1240 |
: SFC_SET_VBR_ENCODING_QUALITY |
| 1241 |
|
| 1242 |
data |
| 1243 |
: A pointer to a double value |
| 1244 |
|
| 1245 |
datasize |
| 1246 |
: sizeof (double) |
| 1247 |
|
| 1248 |
The command must be sent before any audio data is written to the file. |
| 1249 |
|
| 1250 |
### Return value |
| 1251 |
|
| 1252 |
SF_TRUE if VBR encoding quality was set. SF_FALSE otherwise. |
| 1253 |
|
| 1254 |
## SFC_SET_OGG_PAGE_LATENCY_MS |
| 1255 |
|
| 1256 |
Set page latency for Ogg Opus file in milliseconds. The value should be between |
| 1257 |
50.0 and 1600.0. This command is only implemented for Ogg Opus files. |
| 1258 |
|
| 1259 |
### Parameters |
| 1260 |
|
| 1261 |
sndfile |
| 1262 |
: A valid SNDFILE* pointer |
| 1263 |
|
| 1264 |
cmd |
| 1265 |
: SFC_SET_OGG_PAGE_LATENCY_MS |
| 1266 |
|
| 1267 |
data |
| 1268 |
: A pointer to a double value |
| 1269 |
|
| 1270 |
datasize |
| 1271 |
: sizeof (double) |
| 1272 |
|
| 1273 |
### Return value |
| 1274 |
|
| 1275 |
0 on success and non-zero otherwise. |
| 1276 |
|
| 1277 |
## SFC_GET_OGG_STREAM_SERIALNO |
| 1278 |
|
| 1279 |
Get the Ogg stream serial number for files with the Ogg major format. Ogg |
| 1280 |
stream serail numbers are a randomly chosen 32-bit value, used for |
| 1281 |
differentiating logical Ogg streams. |
| 1282 |
|
| 1283 |
### Parameters |
| 1284 |
|
| 1285 |
sndfile |
| 1286 |
: A valid SNDFILE* pointer |
| 1287 |
|
| 1288 |
cmd |
| 1289 |
: SFC_SET_OGG_STREAM_SERIALNO |
| 1290 |
|
| 1291 |
data |
| 1292 |
: A pointer to a 32-bit int value |
| 1293 |
|
| 1294 |
datasize |
| 1295 |
: sizeof (int32_t) = 4 |
| 1296 |
|
| 1297 |
### Return value |
| 1298 |
|
| 1299 |
0 on success and non-zero otherwise. |
| 1300 |
|
| 1301 |
## SFC_SET_COMPRESSION_LEVEL |
| 1302 |
|
| 1303 |
Set the compression level. The compression level should be between 0.0 (minimum |
| 1304 |
compression level) and 1.0 (highest compression level). Currently this command is |
| 1305 |
only implemented for FLAC and Ogg/Vorbis files. It has no effect on |
| 1306 |
uncompressed file formats. |
| 1307 |
|
| 1308 |
### Parameters |
| 1309 |
|
| 1310 |
sndfile |
| 1311 |
: A valid SNDFILE* pointer |
| 1312 |
|
| 1313 |
cmd |
| 1314 |
: SFC_SET_COMPRESSION_LEVEL |
| 1315 |
|
| 1316 |
data |
| 1317 |
: A pointer to a double value |
| 1318 |
|
| 1319 |
datasize |
| 1320 |
: sizeof (double) |
| 1321 |
|
| 1322 |
The command must be sent before any audio data is written to the file. |
| 1323 |
|
| 1324 |
### Return value |
| 1325 |
|
| 1326 |
SF_TRUE if compression level was set. SF_FALSE otherwise. |
| 1327 |
|
| 1328 |
## SFC_RAW_DATA_NEEDS_ENDSWAP |
| 1329 |
|
| 1330 |
Determine if raw data read using [sf_read_raw()](api.md#raw) needs to be end |
| 1331 |
swapped on the host CPU. |
| 1332 |
|
| 1333 |
For instance, will return SF_TRUE on when reading WAV containing |
| 1334 |
`SF_FORMAT_PCM_16` data on a big endian machine and `SF_FALSE` on a |
| 1335 |
little endian machine. |
| 1336 |
|
| 1337 |
### Parameters |
| 1338 |
|
| 1339 |
sndfile |
| 1340 |
: A valid SNDFILE* pointer |
| 1341 |
|
| 1342 |
cmd |
| 1343 |
: SFC_RAW_DATA_NEEDS_ENDSWAP |
| 1344 |
|
| 1345 |
data |
| 1346 |
: NULL |
| 1347 |
|
| 1348 |
datasize |
| 1349 |
: 0 |
| 1350 |
|
| 1351 |
### Return value |
| 1352 |
|
| 1353 |
`SF_TRUE` or `SF_FALSE`. |
| 1354 |
|
| 1355 |
## SFC_GET_BROADCAST_INFO |
| 1356 |
|
| 1357 |
Retrieve the Broadcast Extension Chunk from WAV (and related) files. |
| 1358 |
|
| 1359 |
### Parameters |
| 1360 |
|
| 1361 |
sndfile |
| 1362 |
: A valid SNDFILE* pointer |
| 1363 |
|
| 1364 |
cmd |
| 1365 |
: SFC_GET_BROADCAST_INFO |
| 1366 |
|
| 1367 |
data |
| 1368 |
: a pointer to an SF_BROADCAST_INFO struct |
| 1369 |
|
| 1370 |
datasize |
| 1371 |
: sizeof (SF_BROADCAST_INFO) |
| 1372 |
|
| 1373 |
The SF_BROADCAST_INFO struct is defined in *sndfile.h* as: |
| 1374 |
|
| 1375 |
```c |
| 1376 |
typedef struct |
| 1377 |
{ char description [256] ; |
| 1378 |
char originator [32] ; |
| 1379 |
char originator_reference [32] ; |
| 1380 |
char origination_date [10] ; |
| 1381 |
char origination_time [8] ; |
| 1382 |
unsigned int time_reference_low ; |
| 1383 |
unsigned int time_reference_high ; |
| 1384 |
short version ; |
| 1385 |
char umid [64] ; |
| 1386 |
char reserved [190] ; |
| 1387 |
unsigned int coding_history_size ; |
| 1388 |
char coding_history [256] ; |
| 1389 |
} SF_BROADCAST_INFO ; |
| 1390 |
``` |
| 1391 |
|
| 1392 |
### Return value |
| 1393 |
|
| 1394 |
`SF_TRUE` if the file contained a Broadcast Extension chunk or `SF_FALSE` |
| 1395 |
otherwise. |
| 1396 |
|
| 1397 |
## SFC_SET_BROADCAST_INFO |
| 1398 |
|
| 1399 |
Set the Broadcast Extension Chunk for WAV (and related) files. |
| 1400 |
|
| 1401 |
### Parameters |
| 1402 |
|
| 1403 |
sndfile |
| 1404 |
: A valid SNDFILE* pointer |
| 1405 |
|
| 1406 |
cmd |
| 1407 |
: SFC_SET_BROADCAST_INFO |
| 1408 |
|
| 1409 |
data |
| 1410 |
: a pointer to an SF_BROADCAST_INFO struct |
| 1411 |
|
| 1412 |
datasize |
| 1413 |
: sizeof (SF_BROADCAST_INFO) |
| 1414 |
|
| 1415 |
### Return value |
| 1416 |
|
| 1417 |
`SF_TRUE` if setting the Broadcast Extension chunk was successful and `SF_FALSE` |
| 1418 |
otherwise. |
| 1419 |
|
| 1420 |
## SFC_GET_CHANNEL_MAP_INFO |
| 1421 |
|
| 1422 |
Retrieve the channel map contained in an AIFF or CAF Channel Layout chunk. |
| 1423 |
|
| 1424 |
### Parameters |
| 1425 |
|
| 1426 |
sndfile |
| 1427 |
: A valid SNDFILE* pointer |
| 1428 |
|
| 1429 |
cmd |
| 1430 |
: SFC_GET_CHANNEL_MAP_INFO |
| 1431 |
|
| 1432 |
data |
| 1433 |
: a pointer to an array of int, the same size as the number of channels in the |
| 1434 |
file |
| 1435 |
|
| 1436 |
datasize |
| 1437 |
: number of channels * sizeof (int) |
| 1438 |
|
| 1439 |
Channel map positions are defined in an enum in *sndfile.h*: |
| 1440 |
|
| 1441 |
| Name | Value | Description | |
| 1442 |
|:-------------------------------------|:------|:------------------------------------------------------------------| |
| 1443 |
| SF_CHANNEL_MAP_INVALID | 0 | | |
| 1444 |
| SF_CHANNEL_MAP_MONO | 1 | | |
| 1445 |
| SF_CHANNEL_MAP_LEFT | 2 | Apple calls this 'Left' | |
| 1446 |
| SF_CHANNEL_MAP_RIGHT | 3 | Apple calls this 'Right' | |
| 1447 |
| SF_CHANNEL_MAP_CENTER | 4 | Apple calls this 'Center' | |
| 1448 |
| SF_CHANNEL_MAP_FRONT_LEFT | 5 | | |
| 1449 |
| SF_CHANNEL_MAP_FRONT_RIGHT | 6 | | |
| 1450 |
| SF_CHANNEL_MAP_FRONT_CENTER | 7 | | |
| 1451 |
| SF_CHANNEL_MAP_REAR_CENTER | 8 | Apple calls this 'Center Surround', Msft calls this 'Back Center' | |
| 1452 |
| SF_CHANNEL_MAP_REAR_LEFT | 9 | Apple calls this 'Left Surround', Msft calls this 'Back Left' | |
| 1453 |
| SF_CHANNEL_MAP_REAR_RIGHT | 10 | Apple calls this 'Right Surround', Msft calls this 'Back Right' | |
| 1454 |
| SF_CHANNEL_MAP_LFE | 11 | Apple calls this 'LFEScreen', Msft calls this 'Low Frequency' | |
| 1455 |
| SF_CHANNEL_MAP_FRONT_LEFT_OF_CENTER | 12 | Apple calls this 'Left Center' | |
| 1456 |
| SF_CHANNEL_MAP_FRONT_RIGHT_OF_CENTER | 13 | Apple calls this 'Right Center' | |
| 1457 |
| SF_CHANNEL_MAP_SIDE_LEFT | 14 | Apple calls this 'Left Surround Direct' | |
| 1458 |
| SF_CHANNEL_MAP_SIDE_RIGHT | 15 | Apple calls this 'Right Surround Direct' | |
| 1459 |
| SF_CHANNEL_MAP_TOP_CENTER | 16 | Apple calls this 'Top Center Surround' | |
| 1460 |
| SF_CHANNEL_MAP_TOP_FRONT_LEFT | 17 | Apple calls this 'Vertical Height Left' | |
| 1461 |
| SF_CHANNEL_MAP_TOP_FRONT_RIGHT | 18 | Apple calls this 'Vertical Height Right' | |
| 1462 |
| SF_CHANNEL_MAP_TOP_FRONT_CENTER | 19 | Apple calls this 'Vertical Height Center' | |
| 1463 |
| SF_CHANNEL_MAP_TOP_REAR_LEFT | 20 | Apple and MS call this 'Top Back Left' | |
| 1464 |
| SF_CHANNEL_MAP_TOP_REAR_RIGHT | 21 | Apple and MS call this 'Top Back Right' | |
| 1465 |
| SF_CHANNEL_MAP_TOP_REAR_CENTER | 22 | Apple and MS call this 'Top Back Center' | |
| 1466 |
| SF_CHANNEL_MAP_AMBISONIC_B_W | 23 | | |
| 1467 |
| SF_CHANNEL_MAP_AMBISONIC_B_X | 24 | | |
| 1468 |
| SF_CHANNEL_MAP_AMBISONIC_B_Y | 25 | | |
| 1469 |
| SF_CHANNEL_MAP_AMBISONIC_B_Z | 26 | | |
| 1470 |
| SF_CHANNEL_MAP_MAX | 27 | | |
| 1471 |
|
| 1472 |
### Return value |
| 1473 |
|
| 1474 |
`SF_TRUE` if the file contained a Channel Layout chunk or `SF_FALSE` otherwise. |
| 1475 |
|
| 1476 |
## SFC_SET_CHANNEL_MAP_INFO |
| 1477 |
|
| 1478 |
Set the channel map contained in an AIFF or CAF Channel Layout chunk. |
| 1479 |
|
| 1480 |
### Parameters |
| 1481 |
|
| 1482 |
sndfile |
| 1483 |
: A valid SNDFILE* pointer |
| 1484 |
|
| 1485 |
cmd |
| 1486 |
: SFC_SET_CHANNEL_MAP_INFO |
| 1487 |
|
| 1488 |
data |
| 1489 |
: a pointer to an array of int, the same size as the number of channels in the |
| 1490 |
file |
| 1491 |
|
| 1492 |
datasize |
| 1493 |
: number of channels * sizeof (int) |
| 1494 |
|
| 1495 |
### Return value |
| 1496 |
|
| 1497 |
`SF_TRUE` if setting the Channel Layout chunk was successful and `SF_FALSE` |
| 1498 |
otherwise. |
| 1499 |
|
| 1500 |
## SFC_GET_CART_INFO |
| 1501 |
|
| 1502 |
Retrieve the Cart Chunk from WAV (and related) files. Based on AES46 standard |
| 1503 |
for CartChunk (see [CartChunk.org](http://www.cartchunk.org/) for more |
| 1504 |
information. |
| 1505 |
|
| 1506 |
### Parameters |
| 1507 |
|
| 1508 |
sndfile |
| 1509 |
: A valid SNDFILE* pointer |
| 1510 |
|
| 1511 |
cmd |
| 1512 |
: SFC_GET_CART_INFO |
| 1513 |
|
| 1514 |
data |
| 1515 |
: a pointer to an SF_CART_INFO struct |
| 1516 |
|
| 1517 |
datasize |
| 1518 |
: sizeof (SF_CART_INFO) |
| 1519 |
|
| 1520 |
The SF_CART_INFO struct is defined in *sndfile.h* as: |
| 1521 |
|
| 1522 |
```c |
| 1523 |
#define SF_CART_INFO_VAR(p_tag_text_size) \ |
| 1524 |
struct |
| 1525 |
{ char version [4] ; |
| 1526 |
char title [64] ; |
| 1527 |
char artist [64] ; |
| 1528 |
char cut_id [64] ; |
| 1529 |
char client_id [64] ; |
| 1530 |
char category [64] ; |
| 1531 |
char classification [64] ; |
| 1532 |
char out_cue [64] ; |
| 1533 |
char start_date [10] ; |
| 1534 |
char start_time [8] ; |
| 1535 |
char end_date [10] ; |
| 1536 |
char end_time [8] ; |
| 1537 |
char producer_app_id [64] ; |
| 1538 |
char producer_app_version [64] ; |
| 1539 |
char user_def [64] ; |
| 1540 |
long level_reference ; |
| 1541 |
SF_CART_TIMER post_timers [8] ; |
| 1542 |
char reserved [276] ; |
| 1543 |
char url [1024] ; |
| 1544 |
unsigned int tag_text_size ; |
| 1545 |
char tag_text[p_tag_text_size] ; |
| 1546 |
} |
| 1547 |
``` |
| 1548 |
|
| 1549 |
### Return value |
| 1550 |
|
| 1551 |
`SF_TRUE` if the file contained a Cart chunk or `SF_FALSE` otherwise. |
| 1552 |
|
| 1553 |
## SFC_SET_CART_INFO |
| 1554 |
|
| 1555 |
Set the Cart Chunk for WAV (and related) files. |
| 1556 |
|
| 1557 |
### Parameters |
| 1558 |
|
| 1559 |
sndfile |
| 1560 |
: A valid SNDFILE* pointer |
| 1561 |
|
| 1562 |
cmd |
| 1563 |
: SFC_SET_CART_INFO |
| 1564 |
|
| 1565 |
data |
| 1566 |
: a pointer to an SF_CART_INFO struct |
| 1567 |
|
| 1568 |
datasize |
| 1569 |
: sizeof (SF_CART_INFO) |
| 1570 |
|
| 1571 |
### Return value |
| 1572 |
|
| 1573 |
SF_TRUE if setting the Cart chunk was successful and SF_FALSE otherwise. |
| 1574 |
|
| 1575 |
## SFC_GET_LOOP_INFO |
| 1576 |
|
| 1577 |
Retrieve loop information for file including time signature, length in beats and |
| 1578 |
original MIDI base note |
| 1579 |
|
| 1580 |
### Parameters |
| 1581 |
|
| 1582 |
sndfile |
| 1583 |
: A valid SNDFILE* pointer |
| 1584 |
|
| 1585 |
cmd |
| 1586 |
: SFC_GET_LOOP_INFO |
| 1587 |
|
| 1588 |
data |
| 1589 |
: a pointer to an SF_LOOP_INFO struct |
| 1590 |
|
| 1591 |
datasize |
| 1592 |
: sizeof (SF_LOOP_INFO) |
| 1593 |
|
| 1594 |
The SF_LOOP_INFO struct is defined in *sndfile.h* as: |
| 1595 |
|
| 1596 |
```c |
| 1597 |
typedef struct |
| 1598 |
{ short time_sig_num ; /* any positive integer > 0 */ |
| 1599 |
short time_sig_den ; /* any positive power of 2 > 0 */ |
| 1600 |
int loop_mode ; /* see SF_LOOP enum */ |
| 1601 |
|
| 1602 |
int num_beats ; /* this is NOT the amount of quarter notes !!!*/ |
| 1603 |
/* a full bar of 4/4 is 4 beats */ |
| 1604 |
/* a full bar of 7/8 is 7 beats */ |
| 1605 |
|
| 1606 |
float bpm ; /* suggestion, as it can be calculated using other fields:*/ |
| 1607 |
/* file's length, file's sampleRate and our time_sig_den*/ |
| 1608 |
/* -> bpms are always the amount of _quarter notes_ per minute */ |
| 1609 |
|
| 1610 |
int root_key ; /* MIDI note, or -1 for None */ |
| 1611 |
int future [6] ; |
| 1612 |
} SF_LOOP_INFO ; |
| 1613 |
``` |
| 1614 |
|
| 1615 |
### Examples |
| 1616 |
|
| 1617 |
```c |
| 1618 |
SF_LOOP_INFO loop; |
| 1619 |
sf_command (sndfile, SFC_GET_LOOP_INFO, &loop, sizeof (loop)) ; |
| 1620 |
``` |
| 1621 |
|
| 1622 |
### Return value |
| 1623 |
|
| 1624 |
`SF_TRUE` if the file header contains loop information for the file, `SF_FALSE` |
| 1625 |
otherwise. |
| 1626 |
|
| 1627 |
## SFC_GET_INSTRUMENT |
| 1628 |
|
| 1629 |
Retrieve instrument information from file including MIDI base note, keyboard |
| 1630 |
mapping and looping information (start/stop and mode). |
| 1631 |
|
| 1632 |
### Parameters |
| 1633 |
|
| 1634 |
sndfile |
| 1635 |
: A valid SNDFILE* pointer |
| 1636 |
|
| 1637 |
cmd |
| 1638 |
: SFC_GET_INSTRUMENT |
| 1639 |
|
| 1640 |
data |
| 1641 |
: a pointer to an SF_INSTRUMENT struct |
| 1642 |
|
| 1643 |
datasize |
| 1644 |
: sizeof (SF_INSTRUMENT) |
| 1645 |
|
| 1646 |
The `SF_INSTRUMENT` struct is defined in *sndfile.h* as: |
| 1647 |
|
| 1648 |
```c |
| 1649 |
typedef struct |
| 1650 |
{ int gain ; |
| 1651 |
char basenote, detune ; |
| 1652 |
char velocity_lo, velocity_hi ; |
| 1653 |
char key_lo, key_hi ; |
| 1654 |
int loop_count ; |
| 1655 |
|
| 1656 |
struct |
| 1657 |
{ int mode ; |
| 1658 |
unsigned int start ; |
| 1659 |
unsigned int end ; |
| 1660 |
unsigned int count ; |
| 1661 |
} loops [16] ; /* make variable in a sensible way */ |
| 1662 |
} SF_INSTRUMENT ; |
| 1663 |
``` |
| 1664 |
|
| 1665 |
`mode` values are defined as: |
| 1666 |
|
| 1667 |
| Name | Value | Description | |
| 1668 |
|:--------------------|:------|:------------| |
| 1669 |
| SF_LOOP_NONE | 800 | | |
| 1670 |
| SF_LOOP_FORWARD | 801 | | |
| 1671 |
| SF_LOOP_BACKWARD | 802 | | |
| 1672 |
| SF_LOOP_ALTERNATING | 803 | | |
| 1673 |
|
| 1674 |
### Examples |
| 1675 |
|
| 1676 |
```c |
| 1677 |
SF_INSTRUMENT inst ; |
| 1678 |
sf_command (sndfile, SFC_GET_INSTRUMENT, &inst, sizeof (inst)) ; |
| 1679 |
``` |
| 1680 |
|
| 1681 |
### Return value |
| 1682 |
|
| 1683 |
`SF_TRUE` if the file header contains instrument information for the file, |
| 1684 |
`SF_FALSE` otherwise. |
| 1685 |
|
| 1686 |
## SFC_SET_INSTRUMENT |
| 1687 |
|
| 1688 |
Set the instrument information for the file. |
| 1689 |
|
| 1690 |
### Parameters |
| 1691 |
|
| 1692 |
sndfile |
| 1693 |
: A valid SNDFILE* pointer |
| 1694 |
|
| 1695 |
cmd |
| 1696 |
: SFC_SET_INSTRUMENT |
| 1697 |
|
| 1698 |
data |
| 1699 |
: a pointer to an SF_INSTRUMENT struct |
| 1700 |
|
| 1701 |
datasize |
| 1702 |
: sizeof (SF_INSTRUMENT) |
| 1703 |
|
| 1704 |
### Examples |
| 1705 |
|
| 1706 |
```c |
| 1707 |
SF_INSTRUMENT inst ; |
| 1708 |
sf_command (sndfile, SFC_SET_INSTRUMENT, &inst, sizeof (inst)) ; |
| 1709 |
``` |
| 1710 |
|
| 1711 |
### Return value |
| 1712 |
|
| 1713 |
`SF_TRUE` if the file header contains instrument information for the file, |
| 1714 |
`SF_FALSE` otherwise. |
| 1715 |
|
| 1716 |
## SFC_GET_CUE_COUNT |
| 1717 |
|
| 1718 |
Retrieve the number of cue markers available for retrieval using the |
| 1719 |
[SFC_GET_CUE](#sfc_get_cue) command. |
| 1720 |
|
| 1721 |
### Parameters |
| 1722 |
|
| 1723 |
sndfile |
| 1724 |
: A valid SNDFILE* pointer |
| 1725 |
|
| 1726 |
cmd |
| 1727 |
: SFC_GET_CUE_COUNT |
| 1728 |
|
| 1729 |
data |
| 1730 |
: a pointer to a uint32_t |
| 1731 |
|
| 1732 |
datasize |
| 1733 |
: sizeof (uint32_t) |
| 1734 |
|
| 1735 |
### Examples |
| 1736 |
|
| 1737 |
```c |
| 1738 |
uint32_t cue_count ; |
| 1739 |
sf_command (sndfile, SFC_GET_CUE_COUNT, &cue_count, sizeof (cue_count)) ; |
| 1740 |
``` |
| 1741 |
|
| 1742 |
### Return value |
| 1743 |
|
| 1744 |
`SF_TRUE` if the file header contains cue marker information for the file, |
| 1745 |
`SF_FALSE` otherwise. |
| 1746 |
|
| 1747 |
## SFC_GET_CUE |
| 1748 |
|
| 1749 |
Retrieve cue marker information from file. |
| 1750 |
|
| 1751 |
### Parameters |
| 1752 |
|
| 1753 |
sndfile |
| 1754 |
: A valid SNDFILE* pointer |
| 1755 |
|
| 1756 |
cmd |
| 1757 |
: SFC_GET_CUE |
| 1758 |
|
| 1759 |
data |
| 1760 |
: a pointer to an SF_CUES struct |
| 1761 |
|
| 1762 |
datasize |
| 1763 |
: sizeof (SF_CUES) |
| 1764 |
|
| 1765 |
The SF_CUES struct is defined in *sndfile.h* as: |
| 1766 |
|
| 1767 |
```c |
| 1768 |
typedef struct |
| 1769 |
{ int cue_count ; |
| 1770 |
|
| 1771 |
struct |
| 1772 |
{ int32_t indx ; |
| 1773 |
uint32_t position ; |
| 1774 |
int32_t fcc_chunk ; |
| 1775 |
int32_t chunk_start ; |
| 1776 |
int32_t block_start ; |
| 1777 |
uint32_t sample_offset ; |
| 1778 |
char name [256] ; |
| 1779 |
} cue_points [100] ; |
| 1780 |
} SF_CUES ; |
| 1781 |
``` |
| 1782 |
|
| 1783 |
There is also an SF_CUES_VAR \#define that allows reading/writing more than 100 |
| 1784 |
cue markers. |
| 1785 |
|
| 1786 |
### Examples |
| 1787 |
|
| 1788 |
```c |
| 1789 |
SF_CUES cues ; |
| 1790 |
sf_command (sndfile, SFC_GET_CUE, &cues, sizeof (cues)) ; |
| 1791 |
``` |
| 1792 |
|
| 1793 |
### Return value |
| 1794 |
|
| 1795 |
`SF_TRUE` if the file header contains cue marker information for the file, |
| 1796 |
`SF_FALSE` otherwise. |
| 1797 |
|
| 1798 |
## SFC_SET_CUE |
| 1799 |
|
| 1800 |
Set the cue marker information for the file. |
| 1801 |
|
| 1802 |
### Parameters |
| 1803 |
|
| 1804 |
sndfile |
| 1805 |
: A valid SNDFILE* pointer |
| 1806 |
|
| 1807 |
cmd |
| 1808 |
: SFC_SET_CUE |
| 1809 |
|
| 1810 |
data |
| 1811 |
: a pointer to an SF_CUES struct |
| 1812 |
|
| 1813 |
datasize |
| 1814 |
: sizeof (SF_CUES) |
| 1815 |
|
| 1816 |
### Examples |
| 1817 |
|
| 1818 |
```c |
| 1819 |
SF_CUES cues ; |
| 1820 |
sf_command (sndfile, SFC_SET_CUE, &cues, sizeof (cues)) ; |
| 1821 |
``` |
| 1822 |
|
| 1823 |
### Return value |
| 1824 |
|
| 1825 |
`SF_TRUE` if the file header contains cue marker information for the file, |
| 1826 |
`SF_FALSE` otherwise. |
| 1827 |
|
| 1828 |
## SFC_RF64_AUTO_DOWNGRADE |
| 1829 |
|
| 1830 |
Enable auto downgrade from RF64 to WAV. |
| 1831 |
|
| 1832 |
The EBU recommendation is that when writing RF64 files and the resulting file is |
| 1833 |
less than 4Gig in size, it should be downgraded to a WAV file (WAV files have a |
| 1834 |
maximum size of 4Gig). libsndfile doesn't follow the EBU recommendations |
| 1835 |
exactly, mainly because the test suite needs to be able test reading/writing |
| 1836 |
RF64 files without having to generate files larger than 4 gigabytes. |
| 1837 |
|
| 1838 |
Note: This command should be issued before the first bit of audio data has been |
| 1839 |
written to the file. Calling this command after audio data has been written will |
| 1840 |
return the current value of this setting, but will not allow it to be changed. |
| 1841 |
|
| 1842 |
### Parameters |
| 1843 |
|
| 1844 |
sndfile |
| 1845 |
: A valid SNDFILE* pointer |
| 1846 |
|
| 1847 |
cmd |
| 1848 |
: SFC_RF64_AUTO_DOWNGRADE |
| 1849 |
|
| 1850 |
data |
| 1851 |
: NULL |
| 1852 |
|
| 1853 |
datasize |
| 1854 |
: SF_TRUE or SF_FALSE |
| 1855 |
|
| 1856 |
### Examples |
| 1857 |
|
| 1858 |
```c |
| 1859 |
/* Enable auto downgrade on file close. */ |
| 1860 |
sf_command (sndfile, SFC_RF64_AUTO_DOWNGRADE, NULL, SF_TRUE) ; |
| 1861 |
``` |
| 1862 |
|
| 1863 |
### Return value |
| 1864 |
|
| 1865 |
Returns `SF_TRUE` if `SFC_RF64_AUTO_DOWNGRADE` is set and `SF_FALSE` otherwise. |
| 1866 |
|
| 1867 |
## SFC_GET_ORIGINAL_SAMPLERATE |
| 1868 |
|
| 1869 |
Get original samplerate metadata. |
| 1870 |
|
| 1871 |
The Opus audio codec stores audio data independent of samplerate, but only |
| 1872 |
supports encoding or decoding at 8000Hz, 12000Hz, 16000Hz, 24000Hz or 48000Hz. |
| 1873 |
Opus includes a header field to record the original source input samplerate, and |
| 1874 |
a samplerate converter may be used if needed. |
| 1875 |
|
| 1876 |
This command gets the original samplerate header field. It does not enable any |
| 1877 |
(non-existent) samplerate conversion, nor change the current decoder samplerate. |
| 1878 |
|
| 1879 |
### Parameters |
| 1880 |
|
| 1881 |
sndfile |
| 1882 |
: A valid SNDFILE* pointer |
| 1883 |
|
| 1884 |
cmd |
| 1885 |
: SFC_GET_ORIGINAL_SAMPLERATE |
| 1886 |
|
| 1887 |
data |
| 1888 |
: pointer to an integer |
| 1889 |
|
| 1890 |
datasize |
| 1891 |
: sizeof (int) |
| 1892 |
|
| 1893 |
### Examples |
| 1894 |
|
| 1895 |
```c |
| 1896 |
/* Get the original sample rate */ |
| 1897 |
int original_samplerate ; |
| 1898 |
sf_command (sndfile, SFC_GET_ORIGINAL_SAMPLERATE, &original_samplerate, sizeof (original_samplerate)) ; |
| 1899 |
``` |
| 1900 |
|
| 1901 |
### Return value |
| 1902 |
|
| 1903 |
Returns `SF_TRUE` on success, `SF_FALSE` otherwise. |
| 1904 |
|
| 1905 |
The passed integer is set to the value of the original samplerate. |
| 1906 |
|
| 1907 |
## SFC_SET_ORIGINAL_SAMPLERATE |
| 1908 |
|
| 1909 |
Set original samplerate metadata. |
| 1910 |
|
| 1911 |
The Opus audio codec stores audio data independent of samplerate, but only |
| 1912 |
supports encoding or decoding at 8000Hz, 12000Hz, 16000Hz, 24000Hz or 48000Hz. |
| 1913 |
Opus includes a header field to record the original source input samplerate, and |
| 1914 |
a samplerate converter may be used if needed. |
| 1915 |
|
| 1916 |
When writing an Opus file this command sets the original samplerate header field |
| 1917 |
to the provided value, which is then stored in the file. This has no effect on |
| 1918 |
the current encoder samplerate. |
| 1919 |
|
| 1920 |
When reading an Opus file this command overrides the original samplerate value |
| 1921 |
as read from the file. libsndfile uses this value to choose what samplerate to |
| 1922 |
decode at, rounding up to the nearest valid Opus samplerate. After a successful |
| 1923 |
call, the file samplerate and frames count may have changed. |
| 1924 |
|
| 1925 |
Note: This command should be issued before the first bit of audio data has been |
| 1926 |
read from or written to the file. |
| 1927 |
|
| 1928 |
### Parameters |
| 1929 |
|
| 1930 |
sndfile |
| 1931 |
: A valid SNDFILE* pointer |
| 1932 |
|
| 1933 |
cmd |
| 1934 |
: SFC_SET_ORIGINAL_SAMPLERATE |
| 1935 |
|
| 1936 |
data |
| 1937 |
: pointer to an integer |
| 1938 |
|
| 1939 |
datasize |
| 1940 |
: sizeof (int) |
| 1941 |
|
| 1942 |
### Examples |
| 1943 |
|
| 1944 |
```c |
| 1945 |
/* Store the original sample rate as 44100 */ |
| 1946 |
int original_samplerate 44100; |
| 1947 |
sf_command (sndfile, SFC_SET_ORIGINAL_SAMPLERATE, &original_samplerate, sizeof (input_samplerate)) ; |
| 1948 |
``` |
| 1949 |
|
| 1950 |
### Return value |
| 1951 |
|
| 1952 |
Returns SF_TRUE on success, SF_FALSE otherwise. |
| 1953 |
|
| 1954 |
On write, can only succeed if no data has been written. On read, if successful, |
| 1955 |
[SFC_GET_CURRENT_SF_INFO](#sfc_get_current_sf_info) should be called to |
| 1956 |
determine the new frames count and samplerate |
| 1957 |
|
| 1958 |
## SFC_GET_BITRATE_MODE |
| 1959 |
|
| 1960 |
Get bitrate mode. |
| 1961 |
|
| 1962 |
The bitrate mode is one of: |
| 1963 |
|
| 1964 |
| Name | Value | Description | |
| 1965 |
|:-------------------------|:------|:------------------| |
| 1966 |
| SF_BITRATE_MODE_CONSTANT | 800 | Constant bitrate. | |
| 1967 |
| SF_BITRATE_MODE_AVERAGE | 801 | Average bitrate. | |
| 1968 |
| SF_BITRATE_MODE_VARIABLE | 802 | Variable bitrate. | |
| 1969 |
|
| 1970 |
### Parameters |
| 1971 |
|
| 1972 |
sndfile |
| 1973 |
: A valid SNDFILE* pointer |
| 1974 |
|
| 1975 |
cmd |
| 1976 |
: SFC_GET_BITRATE_MODE |
| 1977 |
|
| 1978 |
data |
| 1979 |
: NULL |
| 1980 |
|
| 1981 |
datasize |
| 1982 |
: anything |
| 1983 |
|
| 1984 |
### Return value |
| 1985 |
|
| 1986 |
Returns one of `SF_BITRATE_MODE_XXX` on success, `-1` otherwise. |
| 1987 |
|
| 1988 |
## SFC_SET_BITRATE_MODE |
| 1989 |
|
| 1990 |
Set bitrate mode. |
| 1991 |
|
| 1992 |
The bitrate mode is one of: |
| 1993 |
|
| 1994 |
| Name | Value | Description | |
| 1995 |
|:-------------------------|:------|:------------------| |
| 1996 |
| SF_BITRATE_MODE_CONSTANT | 800 | Constant bitrate. | |
| 1997 |
| SF_BITRATE_MODE_AVERAGE | 801 | Average bitrate. | |
| 1998 |
| SF_BITRATE_MODE_VARIABLE | 802 | Variable bitrate. | |
| 1999 |
|
| 2000 |
### Parameters |
| 2001 |
|
| 2002 |
sndfile |
| 2003 |
: A valid SNDFILE* pointer |
| 2004 |
|
| 2005 |
cmd |
| 2006 |
: SFC_SET_BITRATE_MODE |
| 2007 |
|
| 2008 |
data |
| 2009 |
: pointer to an integer |
| 2010 |
|
| 2011 |
datasize |
| 2012 |
: sizeof (int) |
| 2013 |
|
| 2014 |
### Return value |
| 2015 |
|
| 2016 |
Returns `SF_TRUE` on success, `SF_FALSE` otherwise. |