The libsndfile API.

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.

SYNOPSIS

The functions of linbsndfile are defined as follows:

      #include <stdio.h>
      #include <sndfile.h>
        
      SNDFILE*  sf_open_read     (const char *path, SF_INFO *sfinfo) ;
      SNDFILE*  sf_open_write    (const char *path, const SF_INFO *sfinfo) ;
        
      int       sf_format_check  (const SF_INFO *info) ;

      off_t     sf_seek          (SNDFILE *sndfile, off_t frames, int whence) ;

      int       sf_command       (SNDFILE *sndfile, const char *cmd, void *data, int datasize) ;

      double    sf_signal_max	 (SNDFILE *sndfile) ;

      int       sf_perror        (SNDFILE *sndfile) ;
      int       sf_error_str     (SNDFILE *sndfile, char* str, size_t len) ;

      int       sf_close         (SNDFILE *sndfile) ;
	  
      size_t    sf_read_short    (SNDFILE *sndfile, short *ptr, size_t items) ;
      size_t    sf_read_int      (SNDFILE *sndfile, int *ptr, size_t items) ;
      size_t    sf_read_float    (SNDFILE *sndfile, float *ptr, size_t items) ;
      size_t    sf_read_double   (SNDFILE *sndfile, double *ptr, size_t items, int normalize) ;

      size_t    sf_readf_short   (SNDFILE *sndfile, short *ptr, size_t frames) ;
      size_t    sf_readf_int     (SNDFILE *sndfile, int *ptr, size_t frames) ;
      size_t    sf_readf_float   (SNDFILE *sndfile, float *ptr, size_t frames) ;
      size_t    sf_readf_double  (SNDFILE *sndfile, double *ptr, size_t frames, int normalize) ;

      size_t    sf_write_short   (SNDFILE *sndfile, short *ptr, size_t items) ;
      size_t    sf_write_int     (SNDFILE *sndfile, int *ptr, size_t items) ;
      size_t    sf_write_float   (SNDFILE *sndfile, float *ptr, size_t items) ;
      size_t    sf_write_double  (SNDFILE *sndfile, double *ptr, size_t items, int normalize) ;

      size_t    sf_writef_short  (SNDFILE *sndfile, short *ptr, size_t frames) ;
      size_t    sf_writef_int    (SNDFILE *sndfile, int *ptr, size_t frames) ;
      size_t    sf_writef_float  (SNDFILE *sndfile, float *ptr, size_t frames) ;
      size_t    sf_writef_double (SNDFILE *sndfile, double *ptr, size_t frames, int normalize) ;

      size_t    sf_read_raw      (SNDFILE *sndfile, void *ptr, size_t bytes) ;
      size_t    sf_write_raw     (SNDFILE *sndfile, void *ptr, size_t bytes) ;

SNDFILE* is an anonymous pointer to data which is private to the library.

File Open Functions

      SNDFILE*  sf_open_read    (const char *path, SF_INFO *wfinfo) ;
      SNDFILE*  sf_open_write   (const char *path, const SF_INFO *wfinfo) ;

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
      {    int      samplerate ;
           int      samples ;
           int      channels ;
           int      pcmbitwidth ;
           int      format ;
           int      sections ;
           int      seekable ;
       } SF_INFO ;

When opening a file for read (with the exception of RAW files where the caller has to fill in the channels, pcmbitwidth and format fields), all the structure members are filled in by the library.

When opening a file for write, the caller must fill in structure members samplerate, channels, pcmbitwidth and format. For encoded formats (ie u-law, A-law and ADPCM), pcmbitwidth is the bit width before encoding or after decoding.

The format field in the above structure is made up of the bit-wise OR of a major format type with a value of 0x10000 or greater and a minor format type with a value less than 0x10000. The currently understood formats are listed in sndfile.h as follows and also includes two bitmasks for separating major and minor file types. Not all combinations of major and minor file types are valid.

      enum
      {   SF_FORMAT_WAV       = 0x10000,       /* Microsoft WAV format (big endian). */
          SF_FORMAT_AIFF      = 0x20000,       /* Apple/SGI AIFF format (little endian). */
          SF_FORMAT_AU        = 0x30000,       /* Sun/NeXT AU format (big endian). */
          SF_FORMAT_AULE      = 0x40000,       /* DEC AU format (little endian). */
          SF_FORMAT_RAW       = 0x50000,       /* RAW PCM data. */
          SF_FORMAT_PAF       = 0x60000,       /* Ensoniq PARIS file format. */
          SF_FORMAT_SVX       = 0x70000,       /* Amiga IFF / SVX8 / SV16 format. */
          SF_FORMAT_NIST      = 0x80000,       /* Sphere NIST format. */
          SF_FORMAT_WMA       = 0x90000,       /* Windows Media Audio. */
          SF_FORMAT_SMPLTD    = 0xA0000,       /* Sekd Samplitude. */
          
          SF_FORMAT_PCM       = 0x0001,        /* PCM data in 8, 16, 24 or 32 bits. */
          SF_FORMAT_FLOAT     = 0x0002,        /* 32 bit floats. */
          SF_FORMAT_ULAW      = 0x0003,        /* U-Law encoded. */
          SF_FORMAT_ALAW      = 0x0004,        /* A-Law encoded. */
          SF_FORMAT_IMA_ADPCM = 0x0005,        /* IMA ADPCM. */
          SF_FORMAT_MS_ADPCM  = 0x0006,        /* Microsoft ADPCM. */
      
          SF_FORMAT_PCM_BE    = 0x0007,        /* Big endian PCM data. */
          SF_FORMAT_PCM_LE    = 0x0008,        /* Little endian PCM data. */
          SF_FORMAT_PCM_S8    = 0x0009,        /* Signed 8 bit PCM. */
          SF_FORMAT_PCM_U8    = 0x000A,        /* Unsigned 8 bit PCM. */

          SF_FORMAT_SVX_FIB   = 0x000B,        /* SVX Fibonacci Delta encoding. */
          SF_FORMAT_SVX_EXP   = 0x000C,        /* SVX Exponential Delta encoding. */

          SF_FORMAT_GSM610    = 0x000D,        /* GSM 6.10 encoding. */

          SF_FORMAT_G721_32   = 0x000E,        /* 32kbs G721 ADPCM encoding. */
          SF_FORMAT_G723_24   = 0x000F,        /* 24kbs G723 ADPCM encoding. */

          SF_FORMAT_SUBMASK   = 0xFFFF,        
          SF_FORMAT_TYPEMASK  = 0x7FFF0000
      } ;

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 correct before calling sf_open_write ().

sf_format_check returns TRUE if the parameters are valid and FALSE otherwise.

File Seek Functions

      off_t     sf_seek         (SNDFILE *sndfile, off_t frames, int whence) ;

The file seek functions work much like lseek in stdio.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) samples or frames. Therefor, 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.

Valid values for the whence parameter are defined to be the same as the lseek function and behave as follows:

      SEEK_SET  - The offset is set to the start of the audio data plus offset (multichannel) samples.
      SEEK_CUR  - The offset is set to its current location plus offset (multichannel) samples.
      SEEK_END  - The offset is set to the end of the data plus offset (multichannel) samples.

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) samples 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, const char *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. In version 1.0.X of the library (not released yet) this functionality will be extended.

At the moment the only function implemented is the turing on and off of float normalisation as follows:

      sf_command  (sndfile, "norm float", "on", 0) ;
      sf_command  (sndfile, "norm float", "off", 0) ;

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.

Finding the Maximum Sample

      double    sf_signal_max	 (SNDFILE *sndfile) ;

This function returns the maximum sample value of a file opened for read. For larger files, this function should be used with caution as it can take some time to scan the whole file for the maximum value.

Most WAV and AIFF sound files containing floating point data contain a chunk in the headers containing the peak value of the file. For these files, the value contained in the peak chunk is assumed to be correct and is returned to the caller as the correct value. All WAV and AIFF files generated by libsndfile will contain a PEAK chunk.

Of course files which are piped into the library will not be able to scan the whole file and will therefore return a maximum sample value of 0.0.

Error Reporting Functions

      int       sf_perror       (SNDFILE *sndfile) ;
      int       sf_error_str    (SNDFILE *sndfile, char* str, size_t len) ;

The error functions convert the library's internal error enumerations into text strings. The function sf_perror function simply prints the error message to stdio, while sf_error_str copies it into a buffer of a given length supplied by the caller.

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)

      size_t    sf_read_short   (SNDFILE *sndfile, short *ptr, size_t items) ;
      size_t    sf_read_int     (SNDFILE *sndfile, int *ptr, size_t items) ;
      size_t    sf_read_float   (SNDFILE *sndfile, double *ptr, size_t items) ;
      size_t    sf_read_double  (SNDFILE *sndfile, double *ptr, size_t items, int normalize) ;

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.

The sf_read_double function has an extra parameter. If normalize is 1, the read operation will return data that is normalized so that the maximum possible full scale sample value of the file on disk will result in a sample value of 1.0 in the array, with all other sample values scaled accordingly.

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 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. On error, a value of -1 is returned.

File Read Functions (Frames)

      size_t    sf_readf_short   (SNDFILE *sndfile, short *ptr, size_t frames) ;
      size_t    sf_readf_int     (SNDFILE *sndfile, int *ptr, size_t frames) ;
      size_t    sf_readf_float   (SNDFILE *sndfile, double *ptr, size_t frames) ;
      size_t    sf_readf_double  (SNDFILE *sndfile, double *ptr, size_t frames, int normalize) ;

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.

The sf_readf_double function has an extra parameter. If normalize is 1, the read operation will return data that is normalized so that the maximum possible full scale sample value of the file on disk will result in a sample value of 1.0 in the array, with all other sample values scaled accordingly.

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 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. On error, a value of -1 is returned.

File Write Functions (Items)

      size_t    sf_write_short   (SNDFILE *sndfile, short *ptr, size_t items) ;
      size_t    sf_write_int     (SNDFILE *sndfile, int *ptr, size_t items) ;
      size_t    sf_write_float   (SNDFILE *sndfile, double *ptr, size_t items) ;
      size_t    sf_write_double  (SNDFILE *sndfile, double *ptr, size_t items, int normalize) ;

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.

The sf_write_double function has an extra parameter. If normalize is 1, the write operation will assume that data in the array is normalize so that all values are between -1 and 1 and will scale the samples to fill the bitwidth of the disk file format. If normalize is zero, no scaling will take place and the samples will be truncated and written to disk as integers of 8, 16, 24 or 32 bits.

The sf_write_XXXX functions return the number of items written (which should be the same as the items parameter) or -1 if an error has occurred.

File Write Functions (Frames)

      size_t    sf_writef_short  (SNDFILE *sndfile, short *ptr, size_t frames) ;
      size_t    sf_writef_int    (SNDFILE *sndfile, int *ptr, size_t frames) ;
      size_t    sf_writef_float  (SNDFILE *sndfile, double *ptr, size_t frames) ;
      size_t    sf_writef_double (SNDFILE *sndfile, double *ptr, size_t frames, int normalize) ;

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_double function has an extra parameter. If normalize is 1, the write operation will assume that data in the array is normalize so that all values are between -1 and 1 and will scale the samples to fill the bitwidth of the disk file format. If normalize is zero, no scaling will take place and the samples will be truncated and written to disk as integers of 8, 16, 24 or 32 bits.

The sf_writef_XXXX functions return the number of frames written (which should be the same as the frames parameter) or -1 if an error has occurred.

Raw File Read and Write Functions

      size_t    sf_read_raw     (SNDFILE *sndfile, void *ptr, size_t bytes) ;
      size_t    sf_write_raw    (SNDFILE *sndfile, void *ptr, size_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) or -1 if an error has occurred.

The libsndfile home page is here.

Version : 0.0.25