libsndfile
Libsndfile is a library designed to allow the reading and writing of many different sampled sound file formats (such as MS Windows WAV and the Apple/SGI AIFF format) through one standard library interface.
During read and write operations, formats are seamless converted between the format the application program has requested or supplied and the file's data format. The application programmer can remain blissfully unaware of issues such as file endian-ness and data format. See Note 1 and Note 2.
This document covers version 1 of libsndfile only. The changes between libsndfile version 0 and version 1 can be viewed here.
Every effort is made to keep these documents up-to-date, error free and unambiguous. However, since maintaining the documentation is the least fun part of working on libsndfile, these docs can and do fall behind the behaviour of library. If any errors omissions or ambiguities are found, please notify Erik de Castro Lopo.
Finally, if you think there is some feature missing from libsndfile, check that it isn't already implemented (and documented) here.
SYNOPSIS
The functions of linbsndfile are defined as follows:
#include <stdio.h>
#include <sndfile.h>
SNDFILE* sf_open (const char *path, int mode, SF_INFO *sfinfo) ;
int sf_format_check (const SF_INFO *info) ;
sf_count_t sf_seek (SNDFILE *sndfile, sf_count_t frames, int whence) ;
int sf_command (SNDFILE *sndfile, int cmd, void *data, int datasize) ;
int sf_error (SNDFILE *sndfile) ;
const char* sf_strerror (SNDFILE *sndfile) ;
const char* sf_error_number (int errnum) ;
int sf_perror (SNDFILE *sndfile) ;
int sf_error_str (SNDFILE *sndfile, char* str, size_t len) ;
int sf_close (SNDFILE *sndfile) ;
sf_count_t sf_read_short (SNDFILE *sndfile, short *ptr, sf_count_t items) ;
sf_count_t sf_read_int (SNDFILE *sndfile, int *ptr, sf_count_t items) ;
sf_count_t sf_read_float (SNDFILE *sndfile, float *ptr, sf_count_t items) ;
sf_count_t sf_read_double (SNDFILE *sndfile, double *ptr, sf_count_t items) ;
sf_count_t sf_readf_short (SNDFILE *sndfile, short *ptr, sf_count_t frames) ;
sf_count_t sf_readf_int (SNDFILE *sndfile, int *ptr, sf_count_t frames) ;
sf_count_t sf_readf_float (SNDFILE *sndfile, float *ptr, sf_count_t frames) ;
sf_count_t sf_readf_double (SNDFILE *sndfile, double *ptr, sf_count_t frames) ;
sf_count_t sf_write_short (SNDFILE *sndfile, short *ptr, sf_count_t items) ;
sf_count_t sf_write_int (SNDFILE *sndfile, int *ptr, sf_count_t items) ;
sf_count_t sf_write_float (SNDFILE *sndfile, float *ptr, sf_count_t items) ;
sf_count_t sf_write_double (SNDFILE *sndfile, double *ptr, sf_count_t items) ;
sf_count_t sf_writef_short (SNDFILE *sndfile, short *ptr, sf_count_t frames) ;
sf_count_t sf_writef_int (SNDFILE *sndfile, int *ptr, sf_count_t frames) ;
sf_count_t sf_writef_float (SNDFILE *sndfile, float *ptr, sf_count_t frames) ;
sf_count_t sf_writef_double (SNDFILE *sndfile, double *ptr, sf_count_t frames) ;
sf_count_t sf_read_raw (SNDFILE *sndfile, void *ptr, sf_count_t bytes) ;
sf_count_t sf_write_raw (SNDFILE *sndfile, void *ptr, sf_count_t bytes) ;
SNDFILE* is an anonymous pointer to data which is private to the library.
File Open Function
SNDFILE* sf_open (const char *path, int mode, SF_INFO *sfinfo) ;
The SF_INFO structure is for passing data between the calling function and the library when opening a file for read or writing. It is defined in sndfile.h as follows:
typedef struct
{ sf_count_t frames ; /* Used to be called samples. */
int samplerate ;
int channels ;
int format ;
int sections ;
int seekable ;
} SF_INFO ;
The mode parameter for this function can be any one of the following three values:
SFM_READ - read only mode
SFM_WRITE - write only mode
SFM_RDWR - read/write mode
When opening a file for read, the format field should be set to zero before calling sf_open(). All other fields of the structure are filled in by the library. The only exception to this is the case of RAW files where the caller has to set in the channels and format fields to valid values.
When opening a file for write, the caller must fill in structure members samplerate, channels, and format.
The format field in the above SF_INFO structure is made up of the bit-wise OR of a major format type (values between 0x10000 and 0x08000000), a minor format type with (values less than 0x10000) and an optional endian-ness value. The currently understood formats are listed in sndfile.h as follows and also includes bitmasks for separating major and minor file types. Not all combinations of endian-ness and major and minor file types are valid.
enum
{ /* Major formats. */
SF_FORMAT_WAV = 0x010000, /* Microsoft WAV format (little endian). */
SF_FORMAT_AIFF = 0x020000, /* Apple/SGI AIFF format (big endian). */
SF_FORMAT_AU = 0x030000, /* Sun/NeXT AU format (big endian). */
SF_FORMAT_RAW = 0x040000, /* RAW PCM data. */
SF_FORMAT_PAF = 0x050000, /* Ensoniq PARIS file format. */
SF_FORMAT_SVX = 0x060000, /* Amiga IFF / SVX8 / SV16 format. */
SF_FORMAT_NIST = 0x070000, /* Sphere NIST format. */
SF_FORMAT_VOC = 0x080000, /* VOC files. */
SF_FORMAT_IRCAM = 0x0A0000, /* Berkeley/IRCAM/CARL */
SF_FORMAT_W64 = 0x0B0000, /* Sonic Foundry's 64 bit RIFF/WAV */
SF_FORMAT_MAT4 = 0x0C0000, /* Matlab (tm) V4.2 / GNU Octave 2.0 */
SF_FORMAT_MAT5 = 0x0D0000, /* Matlab (tm) V5.0 / GNU Octave 2.1 */
/* Subtypes from here on. */
SF_FORMAT_PCM_S8 = 0x0001, /* Signed 8 bit data */
SF_FORMAT_PCM_16 = 0x0002, /* Signed 16 bit data */
SF_FORMAT_PCM_24 = 0x0003, /* Signed 24 bit data */
SF_FORMAT_PCM_32 = 0x0004, /* Signed 32 bit data */
SF_FORMAT_PCM_U8 = 0x0005, /* Unsigned 8 bit data (WAV and RAW only) */
SF_FORMAT_FLOAT = 0x0006, /* 32 bit float data */
SF_FORMAT_DOUBLE = 0x0007, /* 64 bit float data */
SF_FORMAT_ULAW = 0x0010, /* U-Law encoded. */
SF_FORMAT_ALAW = 0x0011, /* A-Law encoded. */
SF_FORMAT_IMA_ADPCM = 0x0012, /* IMA ADPCM. */
SF_FORMAT_MS_ADPCM = 0x0013, /* Microsoft ADPCM. */
SF_FORMAT_GSM610 = 0x0020, /* GSM 6.10 encoding. */
SF_FORMAT_VOX_ADPCM = 0x0021, /* Oki Dialogic ADPCM encoding. */
SF_FORMAT_G721_32 = 0x0030, /* 32kbs G721 ADPCM encoding. */
SF_FORMAT_G723_24 = 0x0031, /* 24kbs G723 ADPCM encoding. */
SF_FORMAT_G723_40 = 0x0032, /* 40kbs G723 ADPCM encoding. */
SF_FORMAT_DWVW_12 = 0x0040, /* 12 bit Delta Width Variable Word encoding. */
SF_FORMAT_DWVW_16 = 0x0041, /* 16 bit Delta Width Variable Word encoding. */
SF_FORMAT_DWVW_24 = 0x0042, /* 24 bit Delta Width Variable Word encoding. */
SF_FORMAT_DWVW_N = 0x0043, /* N bit Delta Width Variable Word encoding. */
/* Endian-ness options. */
SF_ENDIAN_FILE = 0x00000000, /* Default file endian-ness. */
SF_ENDIAN_LITTLE = 0x10000000, /* Force little endian-ness. */
SF_ENDIAN_BIG = 0x20000000, /* Force big endian-ness. */
SF_ENDIAN_CPU = 0x30000000, /* Force CPU endian-ness. */
SF_FORMAT_SUBMASK = 0x0000FFFF,
SF_FORMAT_TYPEMASK = 0x0FFF0000,
SF_FORMAT_ENDMASK = 0x30000000
} ;
Every call to sf_open() should be matched with a call to sf_close() to free up memory allocated by during the call to sf_open().
On success, the sf_open functions return a non NULL pointer which should be passed as the first parameter to all subsequent libsndfile calls dealing with that audio file. On fail, the sf_open functions return a NULL pointer.
Format Check Function
int sf_format_check (const SF_INFO *info) ;
This function allows the caller to check if a set of parameters in the SF_INFO struct is valid before calling sf_open (SFM_WRITE).
sf_format_check returns TRUE if the parameters are valid and FALSE otherwise.
File Seek Functions
sf_count_t sf_seek (SNDFILE *sndfile, sf_count_t frames, int whence) ;
The file seek functions work much like lseek in unistd.h with the exception that the non-audio data is ignored and the seek only moves within the audio data section of the file. In addition, seeks are defined in number of (multichannel) frames. Therefore, for a seek in a stereo file from the current position forward with an offset of 1 would skip forward by one sample of both channels.
like lseek(), the whence parameter can be any one of the following three values:
SEEK_SET - The offset is set to the start of the audio data plus offset (multichannel) frames.
SEEK_CUR - The offset is set to its current location plus offset (multichannel) frames.
SEEK_END - The offset is set to the end of the data plus offset (multichannel) frames.
Internally, libsndfile keeps track of the read and write locations using separate read and write pointers. If a file has been opened with a mode of SFM_RDWR, bitwise OR-ing the standard whence values above with either SFM_READ or SFM_WRITE allows the read and write pointers to be modified separately. If the SEEK_* values are used on their own, the read and write pointers are both modified.
Note that frames offset can be negative and in fact should be when SEEK_END is used for the whence parameter.
sf_seek will return the offset in (multichannel) frames from the start of the audio data or -1 if an error occurs (ie an attempt is made to seek beyond the start or end of the file).
Command Interface
int sf_command (SNDFILE *sndfile, int cmd, void *data, int datasize) ;
This function allows the caller to retrieve information from or change aspects of the library behaviour on a per file basis. Examples include reading or writing text descriptions to a file or changing the scaling applied to sample data during read and write.
The cmd parameter is a short null terminated string which specifies which command to execute. Data is passed to and returned from the library by use of a void pointer. The library will not read or write more than datasize bytes from the void pointer. For some calls no data is required in which case data should be NULL and datasize may be used for some other purpose.
The return value of sf_command () depends on the value of the cmd parameter, but it is usually non-zero for success and zero on error.
This function is explained more fully here.
Error Reporting Functions
int sf_error (SNDFILE *sndfile) ;
This function returns the current error number for the given SNDFILE. The error number may be one of the following:
enum
{ SF_ERR_NO_ERROR = 0,
SF_ERR_UNRECOGNISED_FORMAT = 1
} ;
or any one of many other internal error values. Applications should only test the return value against error values defined in <sndfile.h> as the internal error values are subject to change at any time. For errors not in the above list, the function sf_error_number() can be used to convert it to an error string.
const char* sf_strerror (SNDFILE *sndfile) ;
const char* sf_error_number (int errnum) ;
The error functions sf_strerror() and sf_error_number() convert the library's internal error enumerations into text strings.
int sf_perror (SNDFILE *sndfile) ;
int sf_error_str (SNDFILE *sndfile, char* str, size_t len) ;
The functions sf_perror() and sf_error_str() are depricated and will be dropped from the library at some later date.
File Close Function
int sf_close (SNDFILE *sndfile) ;
The close function closes the file, deallocates it's internal buffers and returns
0 on success or an error value.
File Read Functions (Items)
sf_count_t sf_read_short (SNDFILE *sndfile, short *ptr, sf_count_t items) ;
sf_count_t sf_read_int (SNDFILE *sndfile, int *ptr, sf_count_t items) ;
sf_count_t sf_read_float (SNDFILE *sndfile, float *ptr, sf_count_t items) ;
sf_count_t sf_read_double (SNDFILE *sndfile, double *ptr, sf_count_t items) ;
The file read items functions fill the array pointed to by ptr with the requested number of items. The items parameter must be an integer product of the number of channels or an error will occur.
It is important to note that the data type used by the calling progarm and the data format of the file do not need to be the same. For instance, it is possible to open a 16 bit PCM encoded WAV file and read the data using sf_read_float(). The library seamleassly converts between the two formats on-the-fly. See Note 1.
The sf_read_XXXX functions return the number of items read. Unless the end of the file was reached during the read, the return value should equal the number of items requested. Attempts to read beyond the end of the file will not result in an error but will cause the sf_read_XXXX functions to return less than the number of items requested or 0 if already at the end of the file.
File Read Functions (Frames)
sf_count_t sf_readf_short (SNDFILE *sndfile, short *ptr, sf_count_t frames) ;
sf_count_t sf_readf_int (SNDFILE *sndfile, int *ptr, sf_count_t frames) ;
sf_count_t sf_readf_float (SNDFILE *sndfile, float *ptr, sf_count_t frames) ;
sf_count_t sf_readf_double (SNDFILE *sndfile, double *ptr, sf_count_t frames) ;
The file read frames functions fill the array pointed to by ptr with the requested number of frames of data. The array must be large enough to hold the product of frames and the number of channels.
Care must be taken insure that there is enough space in the array pointed to by ptr, to take (frames * channels) number of items (shorts, ints, floats or doubles).
The sf_readf_XXXX functions return the number of frames read. Unless the end of the file was reached during the read, the return value should equal the number of frames requested. Attempts to read beyond the end of the file will not result in an error but will cause the sf_readf_XXXX functions to return less than the number of frames requested or 0 if already at the end of the file.
File Write Functions (Items)
sf_count_t sf_write_short (SNDFILE *sndfile, short *ptr, sf_count_t items) ;
sf_count_t sf_write_int (SNDFILE *sndfile, int *ptr, sf_count_t items) ;
sf_count_t sf_write_float (SNDFILE *sndfile, float *ptr, sf_count_t items) ;
sf_count_t sf_write_double (SNDFILE *sndfile, double *ptr, sf_count_t items) ;
The file write items functions write the data in the array pointed to by ptr to the file. The items parameter must be an integer product of the number of channels or an error will occur.
It is important to note that the data type used by the calling progarm and the data format of the file do not need to be the same. For instance, it is possible to open a 16 bit PCM encoded WAV file and write the data using sf_write_float(). The library seamleassly converts between the two formats on-the-fly. See Note 1.
The sf_write_XXXX functions return the number of items written (which should be the same as the items parameter).
File Write Functions (Frames)
sf_count_t sf_writef_short (SNDFILE *sndfile, short *ptr, sf_count_t frames) ;
sf_count_t sf_writef_int (SNDFILE *sndfile, int *ptr, sf_count_t frames) ;
sf_count_t sf_writef_float (SNDFILE *sndfile, float *ptr, sf_count_t frames) ;
sf_count_t sf_writef_double (SNDFILE *sndfile, double *ptr, sf_count_t frames) ;
The file write frames functions write the data in the array pointed to by ptr to the file. The array must be large enough to hold the product of frames and the number of channels.
The sf_writef_XXXX functions return the number of frames written (which should be the same as the frames parameter).
Raw File Read and Write Functions
sf_count_t sf_read_raw (SNDFILE *sndfile, void *ptr, sf_count_t bytes) ;
sf_count_t sf_write_raw (SNDFILE *sndfile, void *ptr, sf_count_t bytes) ;
The raw write and write functions read raw audio data from the audio file (not to be confused with reading RAW header-less PCM files). The number of bytes read or written must always be an integer multiple of the number of channels multiplied by the number of bytes required to represent one sample from one channel.
The raw read and write functions return the number of bytes read or written (which should be the same as the bytes parameter).
Note 1
When converting between integer PCM formats of differing size (ie using sf_read_int() to read a 16 bit PCM encoded WAV file) libsndfile obeys one simple rule:
Whenever integer data is moved from one sized container to another sized container, the most significant bit in the source container will become the most significant bit in the destination container.
When converting between integer data and floating point data, different rules apply. The default behaviour when reading floating point data (sf_read_float() or sf_read_double ()) from a file with integer data is normalisation. Regardless of whether data in the file is 8, 16, 24 or 32 bit wide, the data will be read as floating point data in the range [-1.0, 1.0]. Similarly, data in the range [-1.0, 1.0] will be written to an integer PCM file so that a data value of 1.0 will be the largest allowable integer for the given bit width. This normalisation can be turned on or off using the sf_command interface.
Note 2
Reading a file containg floating point data (allowable with WAV, AIFF, AU and other file formats) using integer read methods (sf_read_short() or sf_read_int()) is discouraged as the library cannot guarantee sensible results. For instance the data in the file may have a maximum absolute value < 1.0 which would mean that all samples values read from the file will be zero.
The libsndfile home page is here.
Version : 1.0.4