| 1 |
--- |
| 2 |
layout: page |
| 3 |
title: The libsndfile API |
| 4 |
--- |
| 5 |
|
| 6 |
# libsndfile |
| 7 |
|
| 8 |
Libsndfile is a library designed to allow the reading and writing of many different sampled sound file formats (such as |
| 9 |
MS Windows WAV and the Apple/SGI AIFF format) through one standard library interface. |
| 10 |
|
| 11 |
During read and write operations, formats are seamlessly converted between the format the application program has |
| 12 |
requested or supplied and the file's data format. The application programmer can remain blissfully unaware of issues |
| 13 |
such as file endian-ness and data format. See [Note 1](#note-1) and [Note 2](#note-2). |
| 14 |
|
| 15 |
Every effort is made to keep these documents up-to-date, error free and unambiguous. However, since maintaining the |
| 16 |
documentation is the least fun part of working on libsndfile, these docs can and do fall behind the behaviour of the |
| 17 |
library. If any errors, omissions or ambiguities are found, please notify me (erikd) at mega-nerd dot com. |
| 18 |
|
| 19 |
To supplement this reference documentation, there are simple example programs included in the source code tarball. The |
| 20 |
test suite which is also part of the source code tarball is also a good place to look for the correct usage of the |
| 21 |
library functions. |
| 22 |
|
| 23 |
**Finally, if you think there is some feature missing from libsndfile, check that it isn't already implemented (and |
| 24 |
documented) [here](command.md).** |
| 25 |
|
| 26 |
## Synopsis |
| 27 |
|
| 28 |
```c |
| 29 |
#include <stdio.h>; |
| 30 |
#include <sndfile.h>; |
| 31 |
``` |
| 32 |
|
| 33 |
| Name | Description | |
| 34 |
|:------------------------------------------------------------------------------------------------------------|:--------------------------------------- | |
| 35 |
| [sf_open, sf_wchar_open](#open) | File open functions. | |
| 36 |
| [sf_open_fd](#open_fd) | Open sound file using file descriptor. | |
| 37 |
| [sf_open_virtual](#open_virtual) | Open sound file using virtual API. | |
| 38 |
| [sf_format_check](#check) | Validate sound file info. | |
| 39 |
| [sf_seek](#seek) | Seek position in sound file. | |
| 40 |
| [sf_command](command.md) | Command interface. | |
| 41 |
| [sf_error, sf_strerror, sf_error_number, sf_perror, sf_error_str](#error) | Error functions. | |
| 42 |
| [sf_close](#close) | File close function. | |
| 43 |
| [sf_write_sync](#write_sync) | Write sync function. | |
| 44 |
| [sf_read_short, sf_read_int, sf_read_float, sf_read_double](#read) | File items read functions. | |
| 45 |
| [sf_readf_short, sf_readf_int, sf_readf_float, sf_readf_double](#readf) | File frames read functions. | |
| 46 |
| [sf_write_short, sf_write_int, sf_write_float, sf_write_double](#write) | File items write functions. | |
| 47 |
| [sf_writef_short, sf_writef_int, sf_writef_float, sf_writef_double](#writef) | File frames write functions. | |
| 48 |
| [sf_read_raw, sf_write_raw](#raw) | Raw read/write functions. | |
| 49 |
| [sf_get_string, sf_set_string](#string) | Functions for reading and writing string data. | |
| 50 |
| [sf_version_string](#version_string) | Retrieve library version string. | |
| 51 |
| [sf_current_byterate](#current_byterate) | Retrieve current byterate. | |
| 52 |
| [sf_set_chunk, sf_get_chunk_iterator, sf_next_chunk_iterator, sf_get_chunk_size, sf_get_chunk_data](#chunk) | RIFF chunks API. | |
| 53 |
|
| 54 |
SNDFILE* is an anonymous pointer to data which is private to the library. |
| 55 |
|
| 56 |
## File Open Function {#open} |
| 57 |
|
| 58 |
```c |
| 59 |
SNDFILE* sf_open (const char *path, int mode, SF_INFO *sfinfo) ; |
| 60 |
``` |
| 61 |
|
| 62 |
The sf_open() function opens the sound file at the specified path. The filename is byte encoded, but may be utf-8 on |
| 63 |
Linux, while on Mac OS X it will use the filesystem character set. On Windows, there is also a Windows specific |
| 64 |
sf_wchar_open() that takes a UTF16_BE encoded filename. |
| 65 |
|
| 66 |
```c |
| 67 |
SNDFILE* sf_wchar_open (LPCWSTR wpath, int mode, SF_INFO *sfinfo) ; |
| 68 |
``` |
| 69 |
|
| 70 |
The SF_INFO structure is for passing data between the calling function and the library when opening a file for reading |
| 71 |
or writing. It is defined in sndfile.h as follows: |
| 72 |
|
| 73 |
```c |
| 74 |
typedef struct |
| 75 |
{ sf_count_t frames ; /* Used to be called samples. */ |
| 76 |
int samplerate ; |
| 77 |
int channels ; |
| 78 |
int format ; |
| 79 |
int sections ; |
| 80 |
int seekable ; |
| 81 |
} SF_INFO ; |
| 82 |
``` |
| 83 |
|
| 84 |
The mode parameter for this function can be any one of the following three values: |
| 85 |
|
| 86 |
SFM_READ |
| 87 |
: read only mode |
| 88 |
|
| 89 |
SFM_WRITE |
| 90 |
: write only mode |
| 91 |
|
| 92 |
SFM_RDWR |
| 93 |
: read/write mode |
| 94 |
|
| 95 |
When opening a file for read, the **format** field should be set to zero before |
| 96 |
calling **sf_open**(). The only exception to this is the case of RAW files where |
| 97 |
the caller has to set the **samplerate**, **channels** and **format** fields to |
| 98 |
valid values. All other fields of the structure are filled in by the library. |
| 99 |
|
| 100 |
**Note:** The libsndfile library will reject values for field **channels** that |
| 101 |
are greater than `1024`. These value represent the maximum theoretical limit |
| 102 |
and may be less for specific formats. |
| 103 |
|
| 104 |
When opening a file for write, the caller must fill in structure members |
| 105 |
**samplerate**, **channels**, and **format**. |
| 106 |
|
| 107 |
The **format** field in the above **SF_INFO** structure is made up of the |
| 108 |
bit-wise OR of a major format type (values between 0x10000 and 0x08000000), a |
| 109 |
minor format type (with values less than 0x10000) and an optional endian-ness |
| 110 |
value. The currently understood formats are listed in *sndfile.h* as follows and |
| 111 |
also include bitmasks for separating major and minor file types. Not all |
| 112 |
combinations of endian-ness and major and minor file types are valid. |
| 113 |
|
| 114 |
| Name | Value | Description | |
| 115 |
|:-------------------------|:-----------|:-------------------------------------------| |
| 116 |
| **Major formats.** | |
| 117 |
| SF_FORMAT_WAV | 0x010000 | Microsoft WAV format (little endian). | |
| 118 |
| SF_FORMAT_AIFF | 0x020000 | Apple/SGI AIFF format (big endian). | |
| 119 |
| SF_FORMAT_AU | 0x030000 | Sun/NeXT AU format (big endian). | |
| 120 |
| SF_FORMAT_RAW | 0x040000 | RAW PCM data. | |
| 121 |
| SF_FORMAT_PAF | 0x050000 | Ensoniq PARIS file format. | |
| 122 |
| SF_FORMAT_SVX | 0x060000 | Amiga IFF / SVX8 / SV16 format. | |
| 123 |
| SF_FORMAT_NIST | 0x070000 | Sphere NIST format. | |
| 124 |
| SF_FORMAT_VOC | 0x080000 | VOC files. | |
| 125 |
| SF_FORMAT_IRCAM | 0x0A0000 | Berkeley/IRCAM/CARL | |
| 126 |
| SF_FORMAT_W64 | 0x0B0000 | Sonic Foundry's 64 bit RIFF/WAV | |
| 127 |
| SF_FORMAT_MAT4 | 0x0C0000 | Matlab (tm) V4.2 / GNU Octave 2.0 | |
| 128 |
| SF_FORMAT_MAT5 | 0x0D0000 | Matlab (tm) V5.0 / GNU Octave 2.1 | |
| 129 |
| SF_FORMAT_PVF | 0x0E0000 | Portable Voice Format | |
| 130 |
| SF_FORMAT_XI | 0x0F0000 | Fasttracker 2 Extended Instrument | |
| 131 |
| SF_FORMAT_HTK | 0x100000 | HMM Tool Kit format | |
| 132 |
| SF_FORMAT_SDS | 0x110000 | Midi Sample Dump Standard | |
| 133 |
| SF_FORMAT_AVR | 0x120000 | Audio Visual Research | |
| 134 |
| SF_FORMAT_WAVEX | 0x130000 | MS WAVE with WAVEFORMATEX | |
| 135 |
| SF_FORMAT_SD2 | 0x160000 | Sound Designer 2 | |
| 136 |
| SF_FORMAT_FLAC | 0x170000 | FLAC lossless file format | |
| 137 |
| SF_FORMAT_CAF | 0x180000 | Core Audio File format | |
| 138 |
| SF_FORMAT_WVE | 0x190000 | Psion WVE format | |
| 139 |
| SF_FORMAT_OGG | 0x200000 | Xiph OGG container | |
| 140 |
| SF_FORMAT_MPC2K | 0x210000 | Akai MPC 2000 sampler | |
| 141 |
| SF_FORMAT_RF64 | 0x220000 | RF64 WAV file | |
| 142 |
| SF_FORMAT_MPEG | 0x230000 | MPEG-1/2 audio stream | |
| 143 |
| **Subtypes.** | |
| 144 |
| SF_FORMAT_PCM_S8 | 0x0001 | Signed 8 bit data | |
| 145 |
| SF_FORMAT_PCM_16 | 0x0002 | Signed 16 bit data | |
| 146 |
| SF_FORMAT_PCM_24 | 0x0003 | Signed 24 bit data | |
| 147 |
| SF_FORMAT_PCM_32 | 0x0004 | Signed 32 bit data | |
| 148 |
| SF_FORMAT_PCM_U8 | 0x0005 | Unsigned 8 bit data (WAV and RAW only) | |
| 149 |
| SF_FORMAT_FLOAT | 0x0006 | 32 bit float data | |
| 150 |
| SF_FORMAT_DOUBLE | 0x0007 | 64 bit float data | |
| 151 |
| SF_FORMAT_ULAW | 0x0010 | U-Law encoded. | |
| 152 |
| SF_FORMAT_ALAW | 0x0011 | A-Law encoded. | |
| 153 |
| SF_FORMAT_IMA_ADPCM | 0x0012 | IMA ADPCM. | |
| 154 |
| SF_FORMAT_MS_ADPCM | 0x0013 | Microsoft ADPCM. | |
| 155 |
| SF_FORMAT_GSM610 | 0x0020 | GSM 6.10 encoding. | |
| 156 |
| SF_FORMAT_VOX_ADPCM | 0x0021 | OKI / Dialogix ADPCM | |
| 157 |
| SF_FORMAT_NMS_ADPCM_16 | 0x0022 | 16kbs NMS G721-variant encoding. | |
| 158 |
| SF_FORMAT_NMS_ADPCM_24 | 0x0023 | 24kbs NMS G721-variant encoding. | |
| 159 |
| SF_FORMAT_NMS_ADPCM_32 | 0x0024 | 32kbs NMS G721-variant encoding. | |
| 160 |
| SF_FORMAT_G721_32 | 0x0030 | 32kbs G721 ADPCM encoding. | |
| 161 |
| SF_FORMAT_G723_24 | 0x0031 | 24kbs G723 ADPCM encoding. | |
| 162 |
| SF_FORMAT_G723_40 | 0x0032 | 40kbs G723 ADPCM encoding. | |
| 163 |
| SF_FORMAT_DWVW_12 | 0x0040 | 12 bit Delta Width Variable Word encoding. | |
| 164 |
| SF_FORMAT_DWVW_16 | 0x0041 | 16 bit Delta Width Variable Word encoding. | |
| 165 |
| SF_FORMAT_DWVW_24 | 0x0042 | 24 bit Delta Width Variable Word encoding. | |
| 166 |
| SF_FORMAT_DWVW_N | 0x0043 | N bit Delta Width Variable Word encoding. | |
| 167 |
| SF_FORMAT_DPCM_8 | 0x0050 | 8 bit differential PCM (XI only) | |
| 168 |
| SF_FORMAT_DPCM_16 | 0x0051 | 16 bit differential PCM (XI only) | |
| 169 |
| SF_FORMAT_VORBIS | 0x0060 | Xiph Vorbis encoding. | |
| 170 |
| SF_FORMAT_OPUS | 0x0064 | Xiph/Skype Opus encoding. | |
| 171 |
| SF_FORMAT_ALAC_16 | 0x0070 | Apple Lossless Audio Codec (16 bit). | |
| 172 |
| SF_FORMAT_ALAC_20 | 0x0071 | Apple Lossless Audio Codec (20 bit). | |
| 173 |
| SF_FORMAT_ALAC_24 | 0x0072 | Apple Lossless Audio Codec (24 bit). | |
| 174 |
| SF_FORMAT_ALAC_32 | 0x0073 | Apple Lossless Audio Codec (32 bit). | |
| 175 |
| SF_FORMAT_MPEG_LAYER_I | 0x0080 | MPEG-1 Audio Layer I. | |
| 176 |
| SF_FORMAT_MPEG_LAYER_II | 0x0081 | MPEG-1 Audio Layer II. | |
| 177 |
| SF_FORMAT_MPEG_LAYER_III | 0x0082 | MPEG-2 Audio Layer III. | |
| 178 |
| **Endian-ness options.** | |
| 179 |
| SF_ENDIAN_FILE | 0x00000000 | Default file endian-ness. | |
| 180 |
| SF_ENDIAN_LITTLE | 0x10000000 | Force little endian-ness. | |
| 181 |
| SF_ENDIAN_BIG | 0x20000000 | Force big endian-ness. | |
| 182 |
| SF_ENDIAN_CPU | 0x30000000 | Force CPU endian-ness. | |
| 183 |
| SF_FORMAT_SUBMASK | 0x0000FFFF | | |
| 184 |
| SF_FORMAT_TYPEMASK | 0x0FFF0000 | | |
| 185 |
| SF_FORMAT_ENDMASK | 0x30000000 | | |
| 186 |
|
| 187 |
Every call to **sf_open**() should be matched with a call to |
| 188 |
[**sf_close**()](#close) to free up memory allocated during the call to **sf_open**(). |
| 189 |
|
| 190 |
On success, the sf_open function returns a non-NULL pointer which should be passed as the first parameter to all |
| 191 |
subsequent libsndfile calls dealing with that audio file. On fail, the sf_open function returns a NULL pointer. An |
| 192 |
explanation of the error can obtained by passing NULL to [**sf_strerror**()](#error). |
| 193 |
|
| 194 |
### File Descriptor Open {#open_fd} |
| 195 |
|
| 196 |
```c |
| 197 |
SNDFILE* sf_open_fd (int fd, int mode, SF_INFO *sfinfo, int close_desc) ; |
| 198 |
``` |
| 199 |
|
| 200 |
**Note:** On Microsoft Windows, this function does not work if the application |
| 201 |
and the libsndfile DLL are linked to different versions of the Microsoft C |
| 202 |
runtime DLL. |
| 203 |
|
| 204 |
The second open function takes a file descriptor of a file that has already been |
| 205 |
opened. Care should be taken to ensure that the mode of the file represented by |
| 206 |
the descriptor matches the mode argument. This function is useful in the |
| 207 |
following circumstances: |
| 208 |
|
| 209 |
* Opening temporary files securely (ie use the **tmpfile**() to return a FILE* |
| 210 |
pointer and then using fileno() to retrieve the file descriptor which is then |
| 211 |
passed to libsndfile). |
| 212 |
* Opening files with file names using OS specific character encodings and then |
| 213 |
passing the file descriptor to **sf_open_fd**(). |
| 214 |
* Opening sound files embedded within larger files. [More info](embedded_files.md). |
| 215 |
|
| 216 |
Every call to `sf_open_fd`() should be matched with a call to sf_close() to free |
| 217 |
up memory allocated during the call to sf_open_fd(). |
| 218 |
|
| 219 |
When sf_close() is called, the file descriptor is only closed if the |
| 220 |
**close_desc** parameter was TRUE when the sf_open_fd() function was called. |
| 221 |
|
| 222 |
On success, the sf_open_fd() function returns a non-NULL pointer which should be |
| 223 |
passed as the first parameter to all subsequent libsndfile calls dealing with |
| 224 |
that audio file. On fail, the sf_open_fd() function returns a NULL pointer. |
| 225 |
|
| 226 |
### Virtual File Open Function {#open_virtual} |
| 227 |
|
| 228 |
```c |
| 229 |
SNDFILE* sf_open_virtual (SF_VIRTUAL_IO *sfvirtual, int mode, SF_INFO *sfinfo, void *user_data) ; |
| 230 |
``` |
| 231 |
|
| 232 |
Opens a soundfile from a virtual file I/O context which is provided by the |
| 233 |
caller. This is usually used to interface libsndfile to write/read from memory |
| 234 |
with a stream or buffer based system. Apart from the sfvirtual and the user_data |
| 235 |
parameters this function behaves like [sf_open()](#open). |
| 236 |
|
| 237 |
```c |
| 238 |
typedef struct |
| 239 |
{ sf_vio_get_filelen get_filelen ; |
| 240 |
sf_vio_seek seek ; |
| 241 |
sf_vio_read read ; |
| 242 |
sf_vio_write write ; |
| 243 |
sf_vio_tell tell ; |
| 244 |
} SF_VIRTUAL_IO ; |
| 245 |
``` |
| 246 |
|
| 247 |
Libsndfile calls the callbacks provided by the SF_VIRTUAL_IO structure when |
| 248 |
opening, reading and writing to the virtual file context. The user_data pointer |
| 249 |
is a user defined context which will be available in the callbacks. |
| 250 |
|
| 251 |
```c |
| 252 |
typedef sf_count_t (*sf_vio_get_filelen) (void *user_data) ; |
| 253 |
typedef sf_count_t (*sf_vio_seek) (sf_count_t offset, int whence, void *user_data) ; |
| 254 |
typedef sf_count_t (*sf_vio_read) (void *ptr, sf_count_t count, void *user_data) ; |
| 255 |
typedef sf_count_t (*sf_vio_write) (const void *ptr, sf_count_t count, void *user_data) ; |
| 256 |
typedef sf_count_t (*sf_vio_tell) (void *user_data) ; |
| 257 |
``` |
| 258 |
|
| 259 |
#### sf_vio_get_filelen |
| 260 |
|
| 261 |
```c |
| 262 |
typedef sf_count_t (*sf_vio_get_filelen) (void *user_data) ; |
| 263 |
``` |
| 264 |
|
| 265 |
The virtual file context must return the length of the virtual file in bytes. |
| 266 |
|
| 267 |
#### sf_vio_seek |
| 268 |
|
| 269 |
```c |
| 270 |
typedef sf_count_t (*sf_vio_seek) (sf_count_t offset, int whence, void *user_data) ; |
| 271 |
``` |
| 272 |
|
| 273 |
The virtual file context must seek to offset using the seek mode provided by |
| 274 |
whence which is one of SEEK_CUR, SEEK_SET, SEEK_END. |
| 275 |
|
| 276 |
The return value must contain the new offset in the file. |
| 277 |
|
| 278 |
#### sf_vio_read |
| 279 |
|
| 280 |
```c |
| 281 |
typedef sf_count_t (*sf_vio_read) (void *ptr, sf_count_t count, void *user_data) ; |
| 282 |
``` |
| 283 |
|
| 284 |
The virtual file context must copy ("read") "count" bytes into the buffer |
| 285 |
provided by ptr and return the count of actually copied bytes. |
| 286 |
|
| 287 |
#### sf_vio_write |
| 288 |
|
| 289 |
```c |
| 290 |
typedef sf_count_t (*sf_vio_write) (const void *ptr, sf_count_t count, void *user_data) ; |
| 291 |
``` |
| 292 |
|
| 293 |
The virtual file context must process "count" bytes stored in the buffer passed |
| 294 |
with ptr and return the count of actually processed bytes. |
| 295 |
|
| 296 |
#### sf_vio_tell |
| 297 |
|
| 298 |
```c |
| 299 |
typedef sf_count_t (*sf_vio_tell) (void *user_data) ; |
| 300 |
``` |
| 301 |
|
| 302 |
Return the current position of the virtual file context. |
| 303 |
|
| 304 |
## Format Check Function {#chek} |
| 305 |
|
| 306 |
```c |
| 307 |
int sf_format_check (const SF_INFO *info) ; |
| 308 |
``` |
| 309 |
|
| 310 |
This function allows the caller to check if a set of parameters in the SF_INFO |
| 311 |
struct is valid before calling [sf_open](#open) (SFM_WRITE). |
| 312 |
|
| 313 |
sf_format_check() returns TRUE if the parameters are valid and FALSE otherwise. |
| 314 |
|
| 315 |
## File Seek Functions |
| 316 |
|
| 317 |
```c |
| 318 |
sf_count_t sf_seek (SNDFILE *sndfile, sf_count_t frames, int whence) ; |
| 319 |
``` |
| 320 |
|
| 321 |
The file seek functions work much like lseek in unistd.h with the exception that |
| 322 |
the non-audio data is ignored and the seek only moves within the audio data |
| 323 |
section of the file. In addition, seeks are defined in number of (multichannel) |
| 324 |
frames. Therefore, a seek in a stereo file from the current position forward |
| 325 |
with an offset of 1 would skip forward by one sample of both channels. |
| 326 |
|
| 327 |
like lseek(), the whence parameter can be any one of the following three values: |
| 328 |
|
| 329 |
SEEK_SET |
| 330 |
: The offset is set to the start of the audio data plus offset (multichannel) |
| 331 |
frames. |
| 332 |
|
| 333 |
SEEK_CUR |
| 334 |
: The offset is set to its current location plus offset (multichannel) frames. |
| 335 |
|
| 336 |
SEEK_END |
| 337 |
: The offset is set to the end of the data plus offset (multichannel) frames. |
| 338 |
|
| 339 |
Internally, libsndfile keeps track of the read and write locations using |
| 340 |
separate read and write pointers. If a file has been opened with a mode of |
| 341 |
SFM_RDWR, bitwise OR-ing the standard whence values above with either SFM_READ |
| 342 |
or SFM_WRITE allows the read and write pointers to be modified separately. |
| 343 |
If the SEEK_* values are used on their own, the read and write pointers are |
| 344 |
both modified. |
| 345 |
|
| 346 |
Note that the frames offset can be negative and in fact should be when SEEK_END |
| 347 |
is used for the whence parameter. |
| 348 |
|
| 349 |
sf_seek will return the offset in (multichannel) frames from the start of the |
| 350 |
audio data or -1 if an error occurred (ie an attempt is made to seek beyond the |
| 351 |
start or end of the file). |
| 352 |
|
| 353 |
## Error Reporting Functions {#error} |
| 354 |
|
| 355 |
```c |
| 356 |
int sf_error (SNDFILE *sndfile) ; |
| 357 |
``` |
| 358 |
|
| 359 |
This function returns the current error number for the given SNDFILE. |
| 360 |
|
| 361 |
The error number may be one of the following: |
| 362 |
|
| 363 |
| Name | Value | |
| 364 |
|:----------------------------|:------| |
| 365 |
| SF_ERR_NO_ERROR | 0 | |
| 366 |
| SF_ERR_UNRECOGNISED_FORMAT | 1 | |
| 367 |
| SF_ERR_SYSTEM | 2 | |
| 368 |
| SF_ERR_MALFORMED_FILE | 3 | |
| 369 |
| SF_ERR_UNSUPPORTED_ENCODING | 4 | |
| 370 |
|
| 371 |
or any one of many other internal error values. |
| 372 |
Applications should only test the return value against error values defined in |
| 373 |
\<sndfile.h\>; as the internal error values are subject to change at any time. |
| 374 |
For errors not in the above list, the function sf_error_number() can be used to |
| 375 |
convert it to an error string. |
| 376 |
|
| 377 |
```c |
| 378 |
const char* sf_strerror (SNDFILE *sndfile) ; |
| 379 |
const char* sf_error_number (int errnum) ; |
| 380 |
``` |
| 381 |
|
| 382 |
The error functions sf_strerror () and sf_error_number () convert the library's |
| 383 |
internal error enumerations into text strings. |
| 384 |
|
| 385 |
```c |
| 386 |
int sf_perror (SNDFILE *sndfile) ; |
| 387 |
int sf_error_str (SNDFILE *sndfile, char* str, size_t len) ; |
| 388 |
``` |
| 389 |
|
| 390 |
The functions sf_perror() and sf_error_str() are deprecated and will be dropped |
| 391 |
from the library at some later date. |
| 392 |
|
| 393 |
## File Close Function {#close} |
| 394 |
|
| 395 |
```c |
| 396 |
int sf_close (SNDFILE *sndfile) ; |
| 397 |
``` |
| 398 |
|
| 399 |
The close function closes the file, deallocates its internal buffers and returns |
| 400 |
0 on success or an error value otherwise. |
| 401 |
|
| 402 |
## Write Sync Function {#write_sync} |
| 403 |
|
| 404 |
```c |
| 405 |
void sf_write_sync (SNDFILE *sndfile) ; |
| 406 |
``` |
| 407 |
|
| 408 |
If the file is opened SFM_WRITE or SFM_RDWR, call the operating system's |
| 409 |
function to force the writing of all file cache buffers to disk. If the file is |
| 410 |
opened SFM_READ no action is taken. |
| 411 |
|
| 412 |
## File Read Functions {#read} |
| 413 |
|
| 414 |
```c |
| 415 |
sf_count_t sf_read_short (SNDFILE *sndfile, short *ptr, sf_count_t items) ; |
| 416 |
sf_count_t sf_read_int (SNDFILE *sndfile, int *ptr, sf_count_t items) ; |
| 417 |
sf_count_t sf_read_float (SNDFILE *sndfile, float *ptr, sf_count_t items) ; |
| 418 |
sf_count_t sf_read_double (SNDFILE *sndfile, double *ptr, sf_count_t items) ; |
| 419 |
``` |
| 420 |
|
| 421 |
{: #readf} |
| 422 |
```c |
| 423 |
sf_count_t sf_readf_short (SNDFILE *sndfile, short *ptr, sf_count_t frames) ; |
| 424 |
sf_count_t sf_readf_int (SNDFILE *sndfile, int *ptr, sf_count_t frames) ; |
| 425 |
sf_count_t sf_readf_float (SNDFILE *sndfile, float *ptr, sf_count_t frames) ; |
| 426 |
sf_count_t sf_readf_double (SNDFILE *sndfile, double *ptr, sf_count_t frames) ; |
| 427 |
``` |
| 428 |
|
| 429 |
The file read functions fill the array pointed to by ptr with the requested |
| 430 |
number of items or frames. |
| 431 |
|
| 432 |
For the frames-count functions, the frames parameter specifies the number of |
| 433 |
frames. A frame is just a block of samples, one for each channel. |
| 434 |
|
| 435 |
**Care must be taken to ensure that there is enough space in the array pointed |
| 436 |
to by ptr, to take (frames \* channels) number of items (shorts, ints, floats or |
| 437 |
doubles).** |
| 438 |
|
| 439 |
For the items-count functions, the items parameter must be an integer product |
| 440 |
of the number of channels or an error will occur. Here, an item is just a |
| 441 |
sample. |
| 442 |
|
| 443 |
Note: The only difference between the "items" and "frames" versions of each read |
| 444 |
function is the units in which the object count is specified - calling |
| 445 |
sf_readf_short() with a count argument of N, on a SNDFILE with C channels, is |
| 446 |
the same as calling sf_read_short with a count argument of N\*C. The buffer |
| 447 |
pointed to by "ptr" should be the same number of bytes in each case. |
| 448 |
|
| 449 |
Note: The data type used by the calling program and the data format of the file |
| 450 |
do not need to be the same. For instance, it is possible to open a 16 bit PCM |
| 451 |
encoded WAV file and read the data using sf_read_float(). The library seamlessly |
| 452 |
converts between the two formats on-the-fly. See [Note 1](#note-1). |
| 453 |
|
| 454 |
The sf_read_XXXX and sf_readf_XXXX functions return the number of items or |
| 455 |
frames read, respectively. Unless the end of the file was reached during the |
| 456 |
read, the return value should equal the number of objects requested. Attempts to |
| 457 |
read beyond the end of the file will not result in an error but will cause the |
| 458 |
read functions to return less than the number of objects requested or 0 if |
| 459 |
already at the end of the file. When the buffer is not is not completely filled, |
| 460 |
unused buffer space is filled by zeroes. |
| 461 |
|
| 462 |
## File Write Functions {#write} |
| 463 |
|
| 464 |
```c |
| 465 |
sf_count_t sf_write_short (SNDFILE *sndfile, short *ptr, sf_count_t items) ; |
| 466 |
sf_count_t sf_write_int (SNDFILE *sndfile, int *ptr, sf_count_t items) ; |
| 467 |
sf_count_t sf_write_float (SNDFILE *sndfile, float *ptr, sf_count_t items) ; |
| 468 |
sf_count_t sf_write_double (SNDFILE *sndfile, double *ptr, sf_count_t items) ; |
| 469 |
``` |
| 470 |
|
| 471 |
{: #writef} |
| 472 |
```c |
| 473 |
sf_count_t sf_writef_short (SNDFILE *sndfile, short *ptr, sf_count_t frames) ; |
| 474 |
sf_count_t sf_writef_int (SNDFILE *sndfile, int *ptr, sf_count_t frames) ; |
| 475 |
sf_count_t sf_writef_float (SNDFILE *sndfile, float *ptr, sf_count_t frames) ; |
| 476 |
sf_count_t sf_writef_double (SNDFILE *sndfile, double *ptr, sf_count_t frames) ; |
| 477 |
``` |
| 478 |
|
| 479 |
The file write functions write the data in the array pointed to by ptr to the |
| 480 |
file. |
| 481 |
|
| 482 |
For items-count functions, the items parameter specifies the size of the array |
| 483 |
and must be an integer product of the number of channels or an error will occur. |
| 484 |
|
| 485 |
For the frames-count functions, the array is expected to be large enough to hold |
| 486 |
a number of items equal to the product of frames and the number of channels. |
| 487 |
|
| 488 |
As with the read functions [above](#read), the only difference in the items and |
| 489 |
frames version of each write function is the units in which the buffer size is |
| 490 |
specified. Again, the data type used by the calling program and the data format |
| 491 |
of the file do not need to be the same ([Note 1](#note-1)). |
| 492 |
|
| 493 |
The sf_write_XXXX and sf_writef_XXXX functions respectively return the number of |
| 494 |
items or frames written (which should be the same as the items or frames |
| 495 |
parameter). |
| 496 |
|
| 497 |
## Raw File Read and Write Functions {#raw} |
| 498 |
|
| 499 |
```c |
| 500 |
sf_count_t sf_read_raw (SNDFILE *sndfile, void *ptr, sf_count_t bytes) ; |
| 501 |
sf_count_t sf_write_raw (SNDFILE *sndfile, void *ptr, sf_count_t bytes) ; |
| 502 |
``` |
| 503 |
|
| 504 |
**Note:** Unless you are writing an external decoder/encode that uses libsndfile |
| 505 |
to handle the file headers, you should not be using these functions. |
| 506 |
|
| 507 |
The raw read and write functions read raw audio data from the audio file (not to |
| 508 |
be confused with reading RAW header-less PCM files). The number of bytes read or |
| 509 |
written must always be an integer multiple of the number of channels multiplied |
| 510 |
by the number of bytes required to represent one sample from one channel. |
| 511 |
|
| 512 |
The raw read and write functions return the number of bytes read or written |
| 513 |
(which should be the same as the bytes parameter). |
| 514 |
|
| 515 |
**Note : The result of using of both regular reads/writes and raw reads/writes |
| 516 |
on compressed file formats other than SF_FORMAT_ALAW and SF_FORMAT_ULAW is |
| 517 |
undefined.** |
| 518 |
|
| 519 |
See also : [SFC_RAW_NEEDS_ENDSWAP](command.md#sfc_raw_needs_endswap). |
| 520 |
|
| 521 |
## Functions for Reading and Writing String Data {#string} |
| 522 |
|
| 523 |
```c |
| 524 |
const char* sf_get_string (SNDFILE *sndfile, int str_type) ; |
| 525 |
int sf_set_string (SNDFILE *sndfile, int str_type, const char* str) ; |
| 526 |
``` |
| 527 |
|
| 528 |
These functions allow strings to be set on files opened for write and to be |
| 529 |
retrieved from files opened for read where supported by the given file type. The |
| 530 |
**str_type** parameter can be any one of the following string types: |
| 531 |
|
| 532 |
| Name | Value | Description | |
| 533 |
|:-------------------|:------|:--------------| |
| 534 |
| SF_STR_TITLE | 0x01 | Title. | |
| 535 |
| SF_STR_COPYRIGHT | 0x02 | Copyright. | |
| 536 |
| SF_STR_SOFTWARE | 0x03 | Software. | |
| 537 |
| SF_STR_ARTIST | 0x04 | Artist. | |
| 538 |
| SF_STR_COMMENT | 0x05 | Comment. | |
| 539 |
| SF_STR_DATE | 0x06 | Date. | |
| 540 |
| SF_STR_ALBUM | 0x07 | Album. | |
| 541 |
| SF_STR_LICENSE | 0x08 | License. | |
| 542 |
| SF_STR_TRACKNUMBER | 0x09 | Track number. | |
| 543 |
| SF_STR_GENRE | 0x10 | Genre. | |
| 544 |
|
| 545 |
The sf_get_string() function returns the specified string if it exists and a |
| 546 |
NULL pointer otherwise. In addition to the string ids above, SF_STR_FIRST (== |
| 547 |
SF_STR_TITLE) and SF_STR_LAST (always the same as the highest numbers string id) |
| 548 |
are also available to allow iteration over all the available string ids. |
| 549 |
|
| 550 |
The sf_set_string() function sets the string data. It returns zero on success |
| 551 |
and non-zero on error.The error code can be converted to a string using |
| 552 |
sf_error_number(). |
| 553 |
|
| 554 |
Strings passed to and retrieved from these two functions are assumed to be |
| 555 |
utf-8. However, while formats like Ogg/Vorbis and FLAC fully support utf-8, |
| 556 |
others like WAV and AIFF officially only support ASCII. Writing utf-8 strings to |
| 557 |
WAV and AIF files with libsndfile will work when read back with libsndfile, but |
| 558 |
may not work with other programs. |
| 559 |
|
| 560 |
The suggested method of dealing with tags retrieved using sf_get_string() is to |
| 561 |
assume they are utf-8. Similarly if you have a string in some exotic format like |
| 562 |
utf-16, it should be encoded to utf-8 before being written using libsndfile. |
| 563 |
|
| 564 |
## Function for retrieving library version {#version_string} |
| 565 |
|
| 566 |
```c |
| 567 |
const char *sf_version_string (void) ; |
| 568 |
``` |
| 569 |
|
| 570 |
Return the library version string. |
| 571 |
|
| 572 |
## Function for retrieving current byterate {#current_byterate} |
| 573 |
|
| 574 |
```c |
| 575 |
int sf_current_byterate (SNDFILE *sndfile) ; |
| 576 |
``` |
| 577 |
|
| 578 |
Return the current byterate at this point in the file. The byte rate in this |
| 579 |
case is the number of bytes per second of audio data. For instance, for a |
| 580 |
stereo, 18 bit PCM encoded file with an 16kHz sample rate, the byte rate |
| 581 |
would be 2 (stereo) \* 2 (two bytes per sample) * 16000 => 64000 bytes/sec. |
| 582 |
|
| 583 |
For some file formats the returned value will be accurate and exact, for some |
| 584 |
it will be a close approximation, for some it will be the average bitrate for |
| 585 |
the whole file and for some it will be a time varying value that was accurate |
| 586 |
when the file was most recently read or written. |
| 587 |
|
| 588 |
To get the bitrate, multiple this value by 8. |
| 589 |
|
| 590 |
`sf_current_byterate` returns byte per second or -1 if byterate is |
| 591 |
unknown. |
| 592 |
|
| 593 |
## Functions to get and set chunks from within a sound file |
| 594 |
|
| 595 |
These functions allow the getting and setting of chunks within a sound file (for |
| 596 |
those formats which allow it). |
| 597 |
|
| 598 |
These functions fail safely. Specifically, they will not allow you to overwrite |
| 599 |
existing chunks or add extra versions of format specific reserved chunks but |
| 600 |
should allow you to retrieve any and all chunks (may not be implemented for all |
| 601 |
chunks or all file formats). |
| 602 |
|
| 603 |
### sf_set_chunk |
| 604 |
|
| 605 |
```c |
| 606 |
int sf_set_chunk (SNDFILE *sndfile, const SF_CHUNK_INFO *chunk_info) ; |
| 607 |
``` |
| 608 |
|
| 609 |
Set the specified chunk info (must be done before any audio data is written to |
| 610 |
the file). This will fail for format specific reserved chunks. The |
| 611 |
`chunk_info->data` pointer must be valid until the file is closed. |
| 612 |
|
| 613 |
The `SF_CHUNK_INFO` struct is documented as follows: |
| 614 |
|
| 615 |
```c |
| 616 |
struct SF_CHUNK_INFO |
| 617 |
{ char id [64] ; /* The chunk identifier. */ |
| 618 |
unsigned id_size ; /* The size of the chunk identifier. */ |
| 619 |
unsigned datalen ; /* The size of that data. */ |
| 620 |
void *data ; /* Pointer to the data. */ |
| 621 |
} ; |
| 622 |
typedef struct SF_CHUNK_INFO SF_CHUNK_INFO ; |
| 623 |
``` |
| 624 |
|
| 625 |
`sf_set_chunk` returns `SF_ERR_NO_ERROR` on success or non-zero on failure. |
| 626 |
|
| 627 |
### sf_get_chunk_iterator |
| 628 |
|
| 629 |
```c |
| 630 |
SF_CHUNK_ITERATOR * |
| 631 |
sf_get_chunk_iterator (SNDFILE *sndfile, const SF_CHUNK_INFO *chunk_info) ; |
| 632 |
``` |
| 633 |
|
| 634 |
Get an iterator for all chunks matching `chunk_info`. |
| 635 |
|
| 636 |
`SF_CHUNK_ITERATOR` is an opaque structure to an iterator over the all chunks of |
| 637 |
a given id and defined as follows: |
| 638 |
|
| 639 |
```c |
| 640 |
typedef struct SF_CHUNK_ITERATOR SF_CHUNK_ITERATOR ; |
| 641 |
``` |
| 642 |
|
| 643 |
The iterator will point to the first chunk matching `chunk_info`. Chunks are |
| 644 |
matching, if (`chunk_info->id`) matches the first (`chunk_info->id_size`) bytes |
| 645 |
of a chunk found in the `SNDFILE*` handle. If `chunk_info` is `NULL`, an |
| 646 |
iterator to all chunks in the `SNDFILE*` handle is returned. The values of |
| 647 |
`chunk_info->datalen` and `chunk_info->data` are ignored. If no matching chunks |
| 648 |
are found in the sndfile, `NULL` is returned. |
| 649 |
|
| 650 |
The returned iterator will stay valid until one of the following occurs: |
| 651 |
|
| 652 |
* The sndfile is closed. |
| 653 |
* A new chunk is added using [`sf_set_chunk()`](#sf_set_chunk). |
| 654 |
* Another chunk iterator function is called on the same `SNDFILE*` |
| 655 |
handle that causes the iterator to be modified. |
| 656 |
|
| 657 |
The memory for the iterator belongs to the SNDFILE* handle and is freed when |
| 658 |
[sf_close](#close) is called. |
| 659 |
|
| 660 |
### sf_next_chunk_iterator |
| 661 |
|
| 662 |
```c |
| 663 |
sf_next_chunk_iterator (SF_CHUNK_ITERATOR * iterator) ; |
| 664 |
``` |
| 665 |
|
| 666 |
Iterate through chunks by incrementing the iterator. |
| 667 |
|
| 668 |
Increments the iterator and returns a handle to the new one. After this call, |
| 669 |
iterator will no longer be valid, and you must use the newly returned handle |
| 670 |
from now on. The returned handle can be used to access the next chunk matching |
| 671 |
the criteria as defined in [sf_get_chunk_iterator](#sf_get_chunk_iterator). |
| 672 |
If iterator points to the last chunk, this will free all resources associated |
| 673 |
with iterator and return `NULL`. The returned iterator will stay valid until |
| 674 |
`sf_get_next_chunk_iterator` is called again, the sndfile is closed or a new |
| 675 |
chunk us added. |
| 676 |
|
| 677 |
### sf_get_chunk_size |
| 678 |
|
| 679 |
```c |
| 680 |
int |
| 681 |
sf_get_chunk_size (const SF_CHUNK_ITERATOR * it, SF_CHUNK_INFO * chunk_info) ; |
| 682 |
``` |
| 683 |
|
| 684 |
Get the size of the specified chunk. |
| 685 |
|
| 686 |
If the specified chunk exists, the size will be returned in the `datalen` field |
| 687 |
of the `SF_CHUNK_INFO` struct. Additionally, the id of the chunk will be copied |
| 688 |
to the `id` field of the `SF_CHUNK_INFO` struct and it's `id_size` field will be |
| 689 |
updated accordingly. |
| 690 |
|
| 691 |
If the chunk doesn't exist `chunk_info->datalen` will be zero, and the `id` and |
| 692 |
`id_size` fields will be undefined. |
| 693 |
|
| 694 |
The function will return `SF_ERR_NO_ERROR` on success or non-zero on failure. |
| 695 |
|
| 696 |
### sf_get_chunk_data |
| 697 |
|
| 698 |
```c |
| 699 |
int |
| 700 |
sf_get_chunk_data (const SF_CHUNK_ITERATOR *it, SF_CHUNK_INFO *chunk_info) ; |
| 701 |
``` |
| 702 |
|
| 703 |
Get the specified chunk data. |
| 704 |
|
| 705 |
If the specified chunk exists, up to `chunk_info->datalen` bytes of the chunk |
| 706 |
data will be copied into the `chunk_info->data` buffer (allocated by the caller) |
| 707 |
and the `chunk_info->datalen` field updated to reflect the size of the data. The |
| 708 |
`id` and `id_size` field will be updated according to the retrieved chunk. If |
| 709 |
the chunk doesn't exist `chunk_info->datalen` will be zero, and the `id` and |
| 710 |
`id_size` fields will be undefined. |
| 711 |
|
| 712 |
The function will return `SF_ERR_NO_ERROR` on success or non-zero on failure. |
| 713 |
|
| 714 |
## Note 1 |
| 715 |
|
| 716 |
When converting between integer PCM formats of differing size (e.g. using |
| 717 |
sf_read_int() to read a 16 bit PCM encoded WAV file) libsndfile obeys one simple |
| 718 |
rule: |
| 719 |
|
| 720 |
Whenever integer data is moved from one sized container to another sized |
| 721 |
container, the most significant bit in the source container will become the most |
| 722 |
significant bit in the destination container. |
| 723 |
|
| 724 |
When converting between integer data and floating point data, different rules |
| 725 |
apply. The default behaviour when reading floating point data (sf_read_float() |
| 726 |
or sf_read_double ()) from a file with integer data is normalisation. Regardless |
| 727 |
of whether data in the file is 8, 16, 24 or 32 bit wide, the data will be read |
| 728 |
as floating point data in the range [-1.0, 1.0]. Similarly, data in the range |
| 729 |
[-1.0, 1.0] will be written to an integer PCM file so that a data value of 1.0 |
| 730 |
will be the largest allowable integer for the given bit width. This |
| 731 |
normalisation can be turned on or off using the [sf_command](command.md) |
| 732 |
interface. |
| 733 |
|
| 734 |
## Note 2 |
| 735 |
|
| 736 |
Reading a file containing floating point data (allowable with WAV, AIFF, AU and |
| 737 |
other file formats) using integer read methods (sf_read_short() or |
| 738 |
sf_read_int()) can produce unexpected results. For instance the data in the file |
| 739 |
may have a maximum absolute value < 1.0 which would mean that all sample |
| 740 |
values read from the file will be zero. In order to read these files correctly |
| 741 |
using integer read methods, it is recommended that you use the |
| 742 |
[sf_command](command.md) interface, a command of |
| 743 |
[SFC_SET_SCALE_FLOAT_INT_READ](command.md#sfc_set_scale_float_int_read) and a |
| 744 |
parameter of SF_TRUE to force correct scaling. |