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. Examples include retrieving a string containing the library version or changing the scaling applied to floating point sample data during read and write. Most of these operations are performed on a per-file basis.
The cmd parameter is an integer identifier which is defined in <sndfile.h>. All of the valid command identifiers have names beginning with "SFC_". 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 available commands are as follows:
| SFC_GET_LIB_VERSION | Retrieve the version of the library. |
| SFC_GET_LOG_INFO | Retrieve the internal per-file operation log. |
| SFC_CALC_SIGNAL_MAX | Calculate the measured maximum signal value. |
| SFC_CALC_NORM_SIGNAL_MAX | Calculate the measured normalised maximum signal value. |
| SFC_CALC_MAX_ALL_CHANNELS | Calculate the peak value for each channel. |
| SFC_CALC_NORM_MAX_ALL_CHANNELS | Calculate the normalised peak for each channel. |
| SFC_GET_SIGNAL_MAX | Retrieve the peak value for the file (as stored in the file header). |
| SFC_GET_MAX_ALL_CHANNELS | Retrieve the peak value for each channel (as stored in the file header). |
| SFC_SET_NORM_FLOAT | Modify the normalisation behaviour of the floating point reading and writing functions. |
| SFC_SET_NORM_DOUBLE | Modify the normalisation behaviour of the double precision floating point reading and writing functions. |
| SFC_GET_NORM_FLOAT | Retrieve the current normalisation behaviour of the floating point reading and writing functions. |
| SFC_GET_NORM_DOUBLE | Retrieve the current normalisation behaviour of the double precision floating point reading and writing functions. |
| SFC_SET_SCALE_FLOAT_INT_READ | Set/clear the scale factor when integer (short/int) data is read from a file containing floating point data. |
| SFC_SET_SCALE_INT_FLOAT_WRITE | Set/clear the scale factor when integer (short/int) data is written to a file as floating point data. |
| SFC_GET_SIMPLE_FORMAT_COUNT | Retrieve the number of simple formats supported by libsndfile. |
| SFC_GET_SIMPLE_FORMAT | Retrieve information about a simple format. |
| SFC_GET_FORMAT_INFO | Retrieve information about a major or subtype format. |
| SFC_GET_FORMAT_MAJOR_COUNT | Retrieve the number of major formats. |
| SFC_GET_FORMAT_MAJOR | Retrieve information about a major format type. |
| SFC_GET_FORMAT_SUBTYPE_COUNT | Retrieve the number of subformats. |
| SFC_GET_FORMAT_SUBTYPE | Retrieve information about a subformat. |
| SFC_SET_ADD_PEAK_CHUNK | Switch the code for adding the PEAK chunk to WAV and AIFF files on or off. |
| SFC_UPDATE_HEADER_NOW | Used when a file is open for write, this command will update the file header to reflect the data written so far. |
| SFC_SET_UPDATE_HEADER_AUTO | Used when a file is open for write, this command will cause the file header to be updated after each write to the file. |
| SFC_FILE_TRUNCATE | Truncate a file open for write or for read/write. |
| SFC_SET_RAW_START_OFFSET | Change the data start offset for files opened up as SF_FORMAT_RAW. |
| SFC_SET_CLIPPING | Turn on/off automatic clipping when doing floating point to integer conversion. |
| SFC_GET_CLIPPING | Retrieve current clipping setting. |
| SFC_GET_EMBED_FILE_INFO | Retrieve information about audio files embedded inside other files. |
| SFC_GET_AMBISONIC | Test a WAVEX file for Ambisonic format |
| SFC_SET_AMBISONIC | Modify a WAVEX header for Ambisonic format |
| SFC_SET_VBR_ENCODING_QUALITY | Set the the Variable Bit Rate encoding quality |
| SFC_RAW_NEEDS_ENDSWAP | Determine if raw data needs endswapping |
| SFC_GET_BROADCAST_INFO | Retrieve the Broadcast Chunk info |
| SFC_SET_BROADCAST_INFO | Set the Broadcast Chunk info |
| SFC_GET_LOOP_INFO | Get loop info |
| SFC_GET_INSTRUMENT | Get instrument info |
| SFC_SET_INSTRUMENT | Set instrument info |
| SFC_SET_VBR_ENCODING_QUALITY | Set variable bit rate encoding quality |
Retrieve the version of the library as a string.
Parameters:
sndfile : Not used
cmd : SFC_GET_LIB_VERSION
data : A pointer to a char buffer
datasize : The size of the the buffer
Example:
char buffer [128] ;
sf_command (NULL, SFC_GET_LIB_VERSION, buffer, sizeof (buffer)) ;
Retrieve the log buffer generated when opening a file as a string. This log buffer can often contain a good reason for why libsndfile failed to open a particular file.
Parameters:
sndfile : A valid SNDFILE* pointer
cmd : SFC_GET_LOG_INFO
data : A pointer to a char buffer
datasize : The size of the the buffer
Example:
char buffer [2048] ;
sf_command (sndfile, SFC_GET_LOG_INFO, buffer, sizeof (buffer)) ;
Retrieve the measured maximum signal value. This involves reading through the whole file which can be slow on large files.
Parameters:
sndfile : A valid SNDFILE* pointer
cmd : SFC_CALC_SIGNAL_MAX
data : A pointer to a double
datasize : sizeof (double)
Example:
double max_val ;
sf_command (sndfile, SFC_CALC_SIGNAL_MAX, &max_val, sizeof (max_val)) ;
Retrieve the measured normalised maximum signal value. This involves reading through the whole file which can be slow on large files.
Parameters:
sndfile : A valid SNDFILE* pointer
cmd : SFC_CALC_NORM_SIGNAL_MAX
data : A pointer to a double
datasize : sizeof (double)
Example:
double max_val ;
sf_command (sndfile, SFC_CALC_NORM_SIGNAL_MAX, &max_val, sizeof (max_val)) ;
Calculate the peak value (ie a single number) for each channel. This involves reading through the whole file which can be slow on large files.
Parameters:
sndfile : A valid SNDFILE* pointer
cmd : SFC_CALC_MAX_ALL_CHANNELS
data : A pointer to a double
datasize : sizeof (double) * number_of_channels
Example:
double peaks [number_of_channels] ;
sf_command (sndfile, SFC_CALC_MAX_ALL_CHANNELS, peaks, sizeof (peaks)) ;
Calculate the normalised peak for each channel. This involves reading through the whole file which can be slow on large files.
Parameters:
sndfile : A valid SNDFILE* pointer
cmd : SFC_CALC_NORM_MAX_ALL_CHANNELS
data : A pointer to a double
datasize : sizeof (double) * number_of_channels
Example:
double peaks [number_of_channels] ;
sf_command (sndfile, SFC_CALC_NORM_MAX_ALL_CHANNELS, peaks, sizeof (peaks)) ;
Retrieve the peak value for the file as stored in the file header.
Parameters:
sndfile : A valid SNDFILE* pointer
cmd : SFC_GET_SIGNAL_MAX
data : A pointer to a double
datasize : sizeof (double)
Example:
double max_peak ;
sf_command (sndfile, SFC_GET_SIGNAL_MAX, &max_peak, sizeof (max_peak)) ;
Retrieve the peak value for the file as stored in the file header.
Parameters:
sndfile : A valid SNDFILE* pointer
cmd : SFC_GET_SIGNAL_MAX
data : A pointer to an array of doubles
datasize : sizeof (double) * number_of_channels
Example:
double peaks [number_of_channels] ;
sf_command (sndfile, SFC_GET_MAX_ALL_CHANNELS, peaks, sizeof (peaks)) ;
This command only affects data read from or written to using the floating point functions:
size_t sf_read_float (SNDFILE *sndfile, float *ptr, size_t items) ; size_t sf_readf_float (SNDFILE *sndfile, float *ptr, size_t frames) ; size_t sf_write_float (SNDFILE *sndfile, float *ptr, size_t items) ; size_t sf_writef_float (SNDFILE *sndfile, float *ptr, size_t frames) ;
Parameters:
sndfile : A valid SNDFILE* pointer
cmd : SFC_SET_NORM_FLOAT
data : NULL
datasize : SF_TRUE or SF_FALSE
For read operations setting normalisation to SF_TRUE means that the data from all subsequent reads will be be normalised to the range [-1.0, 1.0].
For write operations, setting normalisation to SF_TRUE means than all data supplied to the float write functions should be in the range [-1.0, 1.0] and will be scaled for the file format as necessary.
For both cases, setting normalisation to SF_FALSE means that no scaling will take place.
Example:
sf_command (sndfile, SFC_SET_NORM_FLOAT, NULL, SF_TRUE) ;
sf_command (sndfile, SFC_SET_NORM_FLOAT, NULL, SF_FALSE) ;
This command only affects data read from or written to using the double precision floating point functions:
size_t sf_read_double (SNDFILE *sndfile, double *ptr, size_t items) ; size_t sf_readf_double (SNDFILE *sndfile, double *ptr, size_t frames) ; size_t sf_write_double (SNDFILE *sndfile, double *ptr, size_t items) ; size_t sf_writef_double (SNDFILE *sndfile, double *ptr, size_t frames) ;
Parameters:
sndfile : A valid SNDFILE* pointer
cmd : SFC_SET_NORM_DOUBLE
data : NULL
datasize : SF_TRUE or SF_FALSE
For read operations setting normalisation to SF_TRUE means that the data from all subsequent reads will be be normalised to the range [-1.0, 1.0].
For write operations, setting normalisation to SF_TRUE means than all data supplied to the double write functions should be in the range [-1.0, 1.0] and will be scaled for the file format as necessary.
For both cases, setting normalisation to SF_FALSE means that no scaling will take place.
Example:
sf_command (sndfile, SFC_SET_NORM_DOUBLE, NULL, SF_TRUE) ;
sf_command (sndfile, SFC_SET_NORM_DOUBLE, NULL, SF_FALSE) ;
Retrieve the current float normalisation mode.
Parameters:
sndfile : A valid SNDFILE* pointer
cmd : SFC_GET_NORM_FLOAT
data : NULL
datasize : anything
Example:
normalisation = sf_command (sndfile, SFC_GET_NORM_FLOAT, NULL, 0) ;
Retrieve the current float normalisation mode.
Parameters:
sndfile : A valid SNDFILE* pointer
cmd : SFC_GET_NORM_DOUBLE
data : NULL
datasize : anything
Example:
normalisation = sf_command (sndfile, SFC_GET_NORM_DOUBLE, NULL, 0) ;
Set/clear the scale factor when integer (short/int) data is read from a file containing floating point data.
Parameters:
sndfile : A valid SNDFILE* pointer
cmd : SFC_SET_SCALE_FLOAT_INT_READ
data : NULL
datasize : TRUE or FALSE
Example:
sf_command (sndfile, SFC_SET_SCALE_FLOAT_INT_READ, NULL, SF_TRUE) ;
Set/clear the scale factor when integer (short/int) data is written to a file as floating point data.
Parameters:
sndfile : A valid SNDFILE* pointer
cmd : SFC_SET_SCALE_FLOAT_INT_READ
data : NULL
datasize : TRUE or FALSE
Example:
sf_command (sndfile, SFC_SET_SCALE_INT_FLOAT_WRITE, NULL, SF_TRUE) ;
Retrieve the number of simple formats supported by libsndfile.
Parameters:
sndfile : Not used.
cmd : SFC_GET_SIMPLE_FORMAT_COUNT
data : a pointer to an int
datasize : sizeof (int)
Example:
int count ;
sf_command (sndfile, SFC_GET_SIMPLE_FORMAT_COUNT, &count, sizeof (int)) ;
Retrieve information about a simple format.
Parameters:
sndfile : Not used.
cmd : SFC_GET_SIMPLE_FORMAT
data : a pointer to an SF_FORMAT_INFO struct
datasize : sizeof (SF_FORMAT_INFO)
The SF_FORMAT_INFO struct is defined in <sndfile.h> as:
typedef struct
{ int format ;
const char *name ;
const char *extension ;
} SF_FORMAT_INFO ;
When sf_command() is called with SF_GET_SIMPLE_FORMAT, the value of the format field should be the format number (ie 0 <= format <= count value obtained using SF_GET_SIMPLE_FORMAT_COUNT).
Example:
SF_FORMAT_INFO format_info ;
int k, count ;
sf_command (sndfile, SFC_GET_SIMPLE_FORMAT_COUNT, &count, sizeof (int)) ;
for (k = 0 ; k < count ; k++)
{ format_info.format = k ;
sf_command (sndfile, SFC_GET_SIMPLE_FORMAT, &format_info, sizeof (format_info)) ;
printf ("%08x %s %s\n", format_info.format, format_info.name, format_info.extension) ;
} ;
Retrieve information about a major or subtype format.
Parameters:
sndfile : Not used.
cmd : SFC_GET_FORMAT_INFO
data : a pointer to an SF_FORMAT_INFO struct
datasize : sizeof (SF_FORMAT_INFO)
The SF_FORMAT_INFO struct is defined in <sndfile.h> as:
typedef struct
{ int format ;
const char *name ;
const char *extension ;
} SF_FORMAT_INFO ;
When sf_command() is called with SF_GET_FORMAT_INFO, the format field is examined and if (format & SF_FORMAT_TYPEMASK) is a valid format then the struct is filled in with information about the given major type. If (format & SF_FORMAT_TYPEMASK) is FALSE and (format & SF_FORMAT_SUBMASK) is a valid subtype format then the struct is filled in with information about the given subtype.
Example:
SF_FORMAT_INFO format_info ;
format_info.format = SF_FORMAT_WAV ;
sf_command (sndfile, SFC_GET_FORMAT_INFO, &format_info, sizeof (format_info)) ;
printf ("%08x %s %s\n", format_info.format, format_info.name, format_info.extension) ;
format_info.format = SF_FORMAT_ULAW ;
sf_command (sndfile, SFC_GET_FORMAT_INFO, &format_info, sizeof (format_info)) ;
printf ("%08x %s\n", format_info.format, format_info.name) ;
Retrieve the number of major formats.
Parameters:
sndfile : Not used.
cmd : SFC_GET_FORMAT_MAJOR_COUNT
data : a pointer to an int
datasize : sizeof (int)
Example:
int count ;
sf_command (sndfile, SFC_GET_FORMAT_MAJOR_COUNT, &count, sizeof (int)) ;
Retrieve information about a major format type.
Parameters:
sndfile : Not used.
cmd : SFC_GET_FORMAT_MAJOR
data : a pointer to an SF_FORMAT_INFO struct
datasize : sizeof (SF_FORMAT_INFO)
Example:
SF_FORMAT_INFO format_info ;
int k, count ;
sf_command (sndfile, SFC_GET_FORMAT_MAJOR_COUNT, &count, sizeof (int)) ;
for (k = 0 ; k < count ; k++)
{ format_info.format = k ;
sf_command (sndfile, SFC_GET_FORMAT_MAJOR, &format_info, sizeof (format_info)) ;
printf ("%08x %s %s\n", format_info.format, format_info.name, format_info.extension) ;
} ;
For a more comprehensive example, see the program list_formats.c in the examples/ directory of the libsndfile source code distribution.