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