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 100**Note:** The libsndfile library will reject values for field **channels** that 101are greater than `1024`. These value represent the maximum theoretical limit 102and may be less for specific formats. 103 104When opening a file for write, the caller must fill in structure members 105**samplerate**, **channels**, and **format**. 106 107The **format** field in the above **SF_INFO** structure is made up of the 108bit-wise OR of a major format type (values between 0x10000 and 0x08000000), a 109minor format type (with values less than 0x10000) and an optional endian-ness 110value. The currently understood formats are listed in *sndfile.h* as follows and 111also include bitmasks for separating major and minor file types. Not all 112combinations 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 187Every 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 190On success, the sf_open function returns a non-NULL pointer which should be passed as the first parameter to all 191subsequent libsndfile calls dealing with that audio file. On fail, the sf_open function returns a NULL pointer. An 192explanation of the error can obtained by passing NULL to [**sf_strerror**()](#error). 193 194### File Descriptor Open {#open_fd} 195 196```c 197SNDFILE* 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 201and the libsndfile DLL are linked to different versions of the Microsoft C 202runtime DLL. 203 204The second open function takes a file descriptor of a file that has already been 205opened. Care should be taken to ensure that the mode of the file represented by 206the descriptor matches the mode argument. This function is useful in the 207following 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 216Every call to `sf_open_fd`() should be matched with a call to sf_close() to free 217up memory allocated during the call to sf_open_fd(). 218 219When 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 222On success, the sf_open_fd() function returns a non-NULL pointer which should be 223passed as the first parameter to all subsequent libsndfile calls dealing with 224that audio file. On fail, the sf_open_fd() function returns a NULL pointer. 225 226### Virtual File Open Function {#open_virtual} 227 228```c 229SNDFILE* sf_open_virtual (SF_VIRTUAL_IO *sfvirtual, int mode, SF_INFO *sfinfo, void *user_data) ; 230``` 231 232Opens a soundfile from a virtual file I/O context which is provided by the 233caller. This is usually used to interface libsndfile to write/read from memory 234with a stream or buffer based system. Apart from the sfvirtual and the user_data 235parameters 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 247Libsndfile calls the callbacks provided by the SF_VIRTUAL_IO structure when 248opening, reading and writing to the virtual file context. The user_data pointer 249is a user defined context which will be available in the callbacks. 250 251```c 252typedef sf_count_t (*sf_vio_get_filelen) (void *user_data) ; 253typedef sf_count_t (*sf_vio_seek) (sf_count_t offset, int whence, void *user_data) ; 254typedef sf_count_t (*sf_vio_read) (void *ptr, sf_count_t count, void *user_data) ; 255typedef sf_count_t (*sf_vio_write) (const void *ptr, sf_count_t count, void *user_data) ; 256typedef sf_count_t (*sf_vio_tell) (void *user_data) ; 257``` 258 259#### sf_vio_get_filelen 260 261```c 262typedef sf_count_t (*sf_vio_get_filelen) (void *user_data) ; 263``` 264 265The virtual file contex must return the length of the virtual file in bytes. 266 267#### sf_vio_seek 268 269```c 270typedef sf_count_t (*sf_vio_seek) (sf_count_t offset, int whence, void *user_data) ; 271``` 272 273The virtual file context must seek to offset using the seek mode provided by 274whence which is one of SEEK_CUR, SEEK_SET, SEEK_END. 275 276The return value must contain the new offset in the file. 277 278#### sf_vio_read 279 280```c 281typedef sf_count_t (*sf_vio_read) (void *ptr, sf_count_t count, void *user_data) ; 282``` 283 284The virtual file context must copy ("read") "count" bytes into the buffer 285provided by ptr and return the count of actually copied bytes. 286 287#### sf_vio_write 288 289```c 290typedef sf_count_t (*sf_vio_write) (const void *ptr, sf_count_t count, void *user_data) ; 291``` 292 293The virtual file context must process "count" bytes stored in the buffer passed 294with ptr and return the count of actually processed bytes. 295 296#### sf_vio_tell 297 298```c 299typedef sf_count_t (*sf_vio_tell) (void *user_data) ; 300``` 301 302Return the current position of the virtual file context. 303 304## Format Check Function {#chek} 305 306```c 307int sf_format_check (const SF_INFO *info) ; 308``` 309 310This function allows the caller to check if a set of parameters in the SF_INFO 311struct is valid before calling [sf_open](#open) (SFM_WRITE). 312 313sf_format_check() returns TRUE if the parameters are valid and FALSE otherwise. 314 315## File Seek Functions 316 317```c 318sf_count_t sf_seek (SNDFILE *sndfile, sf_count_t frames, int whence) ; 319``` 320 321The file seek functions work much like lseek in unistd.h with the exception that 322the non-audio data is ignored and the seek only moves within the audio data 323section of the file. In addition, seeks are defined in number of (multichannel) 324frames. Therefore, a seek in a stereo file from the current position forward 325with an offset of 1 would skip forward by one sample of both channels. 326 327like lseek(), the whence parameter can be any one of the following three values: 328 329SEEK_SET 330: The offset is set to the start of the audio data plus offset (multichannel) 331frames. 332 333SEEK_CUR 334: The offset is set to its current location plus offset (multichannel) frames. 335 336SEEK_END 337: The offset is set to the end of the data plus offset (multichannel) frames. 338 339Internally, libsndfile keeps track of the read and write locations using 340separate read and write pointers. If a file has been opened with a mode of 341SFM_RDWR, bitwise OR-ing the standard whence values above with either SFM_READ 342or SFM_WRITE allows the read and write pointers to be modified separately. 343If the SEEK_* values are used on their own, the read and write pointers are 344both modified. 345 346Note that the frames offset can be negative and in fact should be when SEEK_END 347is used for the whence parameter. 348 349sf_seek will return the offset in (multichannel) frames from the start of the 350audio data or -1 if an error occured (ie an attempt is made to seek beyond the 351start or end of the file). 352 353## Error Reporting Functions {#error} 354 355```c 356int sf_error (SNDFILE *sndfile) ; 357``` 358 359This function returns the current error number for the given SNDFILE. 360 361The 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 371or any one of many other internal error values. 372Applications 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. 374For errors not in the above list, the function sf_error_number() can be used to 375convert it to an error string. 376 377```c 378const char* sf_strerror (SNDFILE *sndfile) ; 379const char* sf_error_number (int errnum) ; 380``` 381 382The error functions sf_strerror () and sf_error_number () convert the library's 383internal error enumerations into text strings. 384 385```c 386int sf_perror (SNDFILE *sndfile) ; 387int sf_error_str (SNDFILE *sndfile, char* str, size_t len) ; 388``` 389 390The functions sf_perror() and sf_error_str() are deprecated and will be dropped 391from the library at some later date. 392 393## File Close Function {#close} 394 395```c 396int sf_close (SNDFILE *sndfile) ; 397``` 398 399The close function closes the file, deallocates its internal buffers and returns 4000 on success or an error value otherwise. 401 402## Write Sync Function {#write_sync} 403 404```c 405void sf_write_sync (SNDFILE *sndfile) ; 406``` 407 408If the file is opened SFM_WRITE or SFM_RDWR, call the operating system's 409function to force the writing of all file cache buffers to disk. If the file is 410opened SFM_READ no action is taken. 411 412## File Read Functions {#read} 413 414```c 415sf_count_t sf_read_short (SNDFILE *sndfile, short *ptr, sf_count_t items) ; 416sf_count_t sf_read_int (SNDFILE *sndfile, int *ptr, sf_count_t items) ; 417sf_count_t sf_read_float (SNDFILE *sndfile, float *ptr, sf_count_t items) ; 418sf_count_t sf_read_double (SNDFILE *sndfile, double *ptr, sf_count_t items) ; 419``` 420 421{: #readf} 422```c 423sf_count_t sf_readf_short (SNDFILE *sndfile, short *ptr, sf_count_t frames) ; 424sf_count_t sf_readf_int (SNDFILE *sndfile, int *ptr, sf_count_t frames) ; 425sf_count_t sf_readf_float (SNDFILE *sndfile, float *ptr, sf_count_t frames) ; 426sf_count_t sf_readf_double (SNDFILE *sndfile, double *ptr, sf_count_t frames) ; 427``` 428 429The file read functions fill the array pointed to by ptr with the requested 430number of items or frames. 431 432For the frames-count functions, the frames parameter specifies the number of 433frames. 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 436to by ptr, to take (frames \* channels) number of items (shorts, ints, floats or 437doubles).** 438 439For the items-count functions, the items parameter must be an integer product 440of the number of channels or an error will occur. Here, an item is just a 441sample. 442 443Note: The only difference between the "items" and "frames" versions of each read 444function is the units in which the object count is specified - calling 445sf_readf_short() with a count argument of N, on a SNDFILE with C channels, is 446the same as calling sf_read_short with a count argument of N\*C. The buffer 447pointed to by "ptr" should be the same number of bytes in each case. 448 449Note: The data type used by the calling program and the data format of the file 450do not need to be the same. For instance, it is possible to open a 16 bit PCM 451encoded WAV file and read the data using sf_read_float(). The library seamlessly 452converts between the two formats on-the-fly. See [Note 1](#note-1). 453 454The sf_read_XXXX and sf_readf_XXXX functions return the number of items or 455frames read, respectively. Unless the end of the file was reached during the 456read, the return value should equal the number of objects requested. Attempts to 457read beyond the end of the file will not result in an error but will cause the 458read functions to return less than the number of objects requested or 0 if 459already at the end of the file. When the buffer is not is not completely filled, 460unused buffer space is filled by zeroes. 461 462## File Write Functions {#write} 463 464```c 465sf_count_t sf_write_short (SNDFILE *sndfile, short *ptr, sf_count_t items) ; 466sf_count_t sf_write_int (SNDFILE *sndfile, int *ptr, sf_count_t items) ; 467sf_count_t sf_write_float (SNDFILE *sndfile, float *ptr, sf_count_t items) ; 468sf_count_t sf_write_double (SNDFILE *sndfile, double *ptr, sf_count_t items) ; 469``` 470 471{: #writef} 472```c 473sf_count_t sf_writef_short (SNDFILE *sndfile, short *ptr, sf_count_t frames) ; 474sf_count_t sf_writef_int (SNDFILE *sndfile, int *ptr, sf_count_t frames) ; 475sf_count_t sf_writef_float (SNDFILE *sndfile, float *ptr, sf_count_t frames) ; 476sf_count_t sf_writef_double (SNDFILE *sndfile, double *ptr, sf_count_t frames) ; 477``` 478 479The file write functions write the data in the array pointed to by ptr to the 480file. 481 482For items-count functions, the items parameter specifies the size of the array 483and must be an integer product of the number of channels or an error will occur. 484 485For the frames-count functions, the array is expected to be large enough to hold 486a number of items equal to the product of frames and the number of channels. 487 488As with the read functions [above](#read), the only difference in the items and 489frames version of each write function is the units in which the buffer size is 490specified. Again, the data type used by the calling program and the data format 491of the file do not need to be the same ([Note 1](#note-1)). 492 493The sf_write_XXXX and sf_writef_XXXX functions respectively return the number of 494items or frames written (which should be the same as the items or frames 495parameter). 496 497## Raw File Read and Write Functions {#raw} 498 499```c 500sf_count_t sf_read_raw (SNDFILE *sndfile, void *ptr, sf_count_t bytes) ; 501sf_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 505to handle the file headers, you should not be using these functions. 506 507The raw read and write functions read raw audio data from the audio file (not to 508be confused with reading RAW header-less PCM files). The number of bytes read or 509written must always be an integer multiple of the number of channels multiplied 510by the number of bytes required to represent one sample from one channel. 511 512The 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 516on compressed file formats other than SF_FORMAT_ALAW and SF_FORMAT_ULAW is 517undefined.** 518 519See also : [SFC_RAW_NEEDS_ENDSWAP](command.md#sfc_raw_needs_endswap). 520 521## Functions for Reading and Writing String Data {#string} 522 523```c 524const char* sf_get_string (SNDFILE *sndfile, int str_type) ; 525int sf_set_string (SNDFILE *sndfile, int str_type, const char* str) ; 526``` 527 528These functions allow strings to be set on files opened for write and to be 529retrieved 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 545The sf_get_string() function returns the specified string if it exists and a 546NULL pointer otherwise. In addition to the string ids above, SF_STR_FIRST (== 547SF_STR_TITLE) and SF_STR_LAST (always the same as the highest numbers string id) 548are also available to allow iteration over all the available string ids. 549 550The sf_set_string() function sets the string data. It returns zero on success 551and non-zero on error.The error code can be converted to a string using 552sf_error_number(). 553 554Strings passed to and retrieved from these two functions are assumed to be 555utf-8. However, while formats like Ogg/Vorbis and FLAC fully support utf-8, 556others like WAV and AIFF officially only support ASCII. Writing utf-8 strings to 557WAV and AIF files with libsndfile will work when read back with libsndfile, but 558may not work with other programs. 559 560The suggested method of dealing with tags retrived using sf_get_string() is to 561assume they are utf-8. Similarly if you have a string in some exotic format like 562utf-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 567const char *sf_version_string (void) ; 568``` 569 570Return the library version string. 571 572## Function for retrieving current byterate {#current_byterate} 573 574```c 575int sf_current_byterate (SNDFILE *sndfile) ; 576``` 577 578Return the current byterate at this point in the file. The byte rate in this 579case is the number of bytes per second of audio data. For instance, for a 580stereo, 18 bit PCM encoded file with an 16kHz sample rate, the byte rate 581would be 2 (stereo) \* 2 (two bytes per sample) * 16000 => 64000 bytes/sec. 582 583For some file formats the returned value will be accurate and exact, for some 584it will be a close approximation, for some it will be the average bitrate for 585the whole file and for some it will be a time varying value that was accurate 586when the file was most recently read or written. 587 588To get the bitrate, multiple this value by 8. 589 590`sf_current_byterate` returns byte per second or -1 if byterate is 591unknown. 592 593## Functions to get and set chunks from within a sound file 594 595These functions allow the getting and setting of chunks within a sound file (for 596those formats which allow it). 597 598These functions fail safely. Specifically, they will not allow you to overwrite 599existing chunks or add extra versions of format specific reserved chunks but 600should allow you to retrieve any and all chunks (may not be implemented for all 601chunks or all file formats). 602 603### sf_set_chunk 604 605```c 606int sf_set_chunk (SNDFILE *sndfile, const SF_CHUNK_INFO *chunk_info) ; 607``` 608 609Set the specified chunk info (must be done before any audio data is written to 610the file). This will fail for format specific reserved chunks. The 611`chunk_info->data` pointer must be valid until the file is closed. 612 613The `SF_CHUNK_INFO` struct is documented as follows: 614 615```c 616struct 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 630SF_CHUNK_ITERATOR * 631sf_get_chunk_iterator (SNDFILE *sndfile, const SF_CHUNK_INFO *chunk_info) ; 632``` 633 634Get 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 637a given id and defined as follows: 638 639```c 640typedef struct SF_CHUNK_ITERATOR SF_CHUNK_ITERATOR ; 641``` 642 643The iterator will point to the first chunk matching `chunk_info`. Chunks are 644matching, if (`chunk_info->id`) matches the first (`chunk_info->id_size`) bytes 645of a chunk found in the `SNDFILE*` handle. If `chunk_info` is `NULL`, an 646iterator 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 648are found in the sndfile, `NULL` is returned. 649 650The 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 657The 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 663sf_next_chunk_iterator (SF_CHUNK_ITERATOR * iterator) ; 664``` 665 666Iterate through chunks by incrementing the iterator. 667 668Increments the iterator and returns a handle to the new one. After this call, 669iterator will no longer be valid, and you must use the newly returned handle 670from now on. The returned handle can be used to access the next chunk matching 671the criteria as defined in [sf_get_chunk_iterator](#sf_get_chunk_iterator). 672If iterator points to the last chunk, this will free all resources associated 673with 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 675chunk us added. 676 677### sf_get_chunk_size 678 679```c 680int 681sf_get_chunk_size (const SF_CHUNK_ITERATOR * it, SF_CHUNK_INFO * chunk_info) ; 682``` 683 684Get the size of the specified chunk. 685 686If the specified chunk exists, the size will be returned in the `datalen` field 687of the `SF_CHUNK_INFO` struct. Additionally, the id of the chunk will be copied 688to the `id` field of the `SF_CHUNK_INFO` struct and it's `id_size` field will be 689updated accordingly. 690 691If the chunk doesn't exist `chunk_info->datalen` will be zero, and the `id` and 692`id_size` fields will be undefined. 693 694The function will return `SF_ERR_NO_ERROR` on success or non-zero on failure. 695 696### sf_get_chunk_data 697 698```c 699int 700sf_get_chunk_data (const SF_CHUNK_ITERATOR *it, SF_CHUNK_INFO *chunk_info) ; 701``` 702 703Get the specified chunk data. 704 705If the specified chunk exists, up to `chunk_info->datalen` bytes of the chunk 706data will be copied into the `chunk_info->data` buffer (allocated by the caller) 707and 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 709the chunk doesn't exist `chunk_info->datalen` will be zero, and the `id` and 710`id_size` fields will be undefined. 711 712The function will return `SF_ERR_NO_ERROR` on success or non-zero on failure. 713 714## Note 1 715 716When converting between integer PCM formats of differing size (e.g. using 717sf_read_int() to read a 16 bit PCM encoded WAV file) libsndfile obeys one simple 718rule: 719 720Whenever integer data is moved from one sized container to another sized 721container, the most significant bit in the source container will become the most 722significant bit in the destination container. 723 724When converting between integer data and floating point data, different rules 725apply. The default behaviour when reading floating point data (sf_read_float() 726or sf_read_double ()) from a file with integer data is normalisation. Regardless 727of whether data in the file is 8, 16, 24 or 32 bit wide, the data will be read 728as 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 730will be the largest allowable integer for the given bit width. This 731normalisation can be turned on or off using the [sf_command](command.md) 732interface. 733 734## Note 2 735 736Reading a file containg floating point data (allowable with WAV, AIFF, AU and 737other file formats) using integer read methods (sf_read_short() or 738sf_read_int()) can produce unexpected results. For instance the data in the file 739may have a maximum absolute value < 1.0 which would mean that all sample 740values read from the file will be zero. In order to read these files correctly 741using 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 744parameter of SF_TRUE to force correct scaling. 745