cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: libsndfile : the sf_command function. cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125:

sf_command

cannam@125: 
cannam@125: 
cannam@125:         int    sf_command (SNDFILE *sndfile, int cmd, void *data, int datasize) ;
cannam@125:
cannam@125:

cannam@125: This function allows the caller to retrieve information from or change aspects of the cannam@125: library behaviour. cannam@125: Examples include retrieving a string containing the library version or changing the cannam@125: scaling applied to floating point sample data during read and write. cannam@125: Most of these operations are performed on a per-file basis. cannam@125:

cannam@125:

cannam@125: The cmd parameter is an integer identifier which is defined in <sndfile.h>. cannam@125: All of the valid command identifiers have names beginning with "SFC_". cannam@125: Data is passed to and returned from the library by use of a void pointer. cannam@125: The library will not read or write more than datasize bytes from the void pointer. cannam@125: For some calls no data is required in which case data should be NULL and datasize cannam@125: may be used for some other purpose. cannam@125:

cannam@125:

cannam@125: The available commands are as follows: cannam@125:

cannam@125: cannam@125:
cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125:
SFC_GET_LIB_VERSIONRetrieve the version of the library.
SFC_GET_LOG_INFORetrieve the internal per-file operation log.
SFC_CALC_SIGNAL_MAXCalculate the measured maximum signal value.
SFC_CALC_NORM_SIGNAL_MAXCalculate the measured normalised maximum signal value.
SFC_CALC_MAX_ALL_CHANNELSCalculate the peak value for each channel.
SFC_CALC_NORM_MAX_ALL_CHANNELSCalculate the normalised peak for each channel.
SFC_GET_SIGNAL_MAXRetrieve the peak value for the file (as stored in the file header).
SFC_GET_MAX_ALL_CHANNELSRetrieve the peak value for each channel (as stored in the file header).
SFC_SET_NORM_FLOATModify the normalisation behaviour of the floating point reading and writing functions.
SFC_SET_NORM_DOUBLEModify the normalisation behaviour of the double precision floating point reading and writing functions.
SFC_GET_NORM_FLOATRetrieve the current normalisation behaviour of the floating point reading and writing functions.
SFC_GET_NORM_DOUBLERetrieve the current normalisation behaviour of the double precision floating point reading and writing functions.
SFC_SET_SCALE_FLOAT_INT_READSet/clear the scale factor when integer (short/int) data is read from a file cannam@125: containing floating point data.
SFC_SET_SCALE_INT_FLOAT_WRITESet/clear the scale factor when integer (short/int) data is written to a file cannam@125: as floating point data.
SFC_GET_SIMPLE_FORMAT_COUNTRetrieve the number of simple formats supported by libsndfile.
SFC_GET_SIMPLE_FORMATRetrieve information about a simple format.
SFC_GET_FORMAT_INFORetrieve information about a major or subtype format.
SFC_GET_FORMAT_MAJOR_COUNTRetrieve the number of major formats.
SFC_GET_FORMAT_MAJORRetrieve information about a major format type.
SFC_GET_FORMAT_SUBTYPE_COUNTRetrieve the number of subformats.
SFC_GET_FORMAT_SUBTYPERetrieve information about a subformat.
SFC_SET_ADD_PEAK_CHUNKSwitch the code for adding the PEAK chunk to WAV and AIFF files on or off.
SFC_UPDATE_HEADER_NOWUsed when a file is open for write, this command will update the file cannam@125: header to reflect the data written so far.
SFC_SET_UPDATE_HEADER_AUTOUsed when a file is open for write, this command will cause the file header cannam@125: to be updated after each write to the file.
SFC_FILE_TRUNCATETruncate a file open for write or for read/write.
SFC_SET_RAW_START_OFFSETChange the data start offset for files opened up as SF_FORMAT_RAW.
SFC_SET_CLIPPINGTurn on/off automatic clipping when doing floating point to integer cannam@125: conversion.
SFC_GET_CLIPPINGRetrieve current clipping setting.
SFC_GET_EMBED_FILE_INFORetrieve information about audio files embedded inside other files.
SFC_GET_AMBISONICTest a WAVEX file for Ambisonic format
SFC_SET_AMBISONICModify a WAVEX header for Ambisonic format
SFC_SET_VBR_ENCODING_QUALITYSet the Variable Bit Rate encoding quality
SFC_SET_COMPRESSION_LEVELSet the compression level.
SFC_RAW_NEEDS_ENDSWAPDetermine if raw data needs endswapping
SFC_GET_BROADCAST_INFORetrieve the Broadcast Chunk info
SFC_SET_BROADCAST_INFOSet the Broadcast Chunk info
SFC_SET_CART_INFOSet the Cart Chunk info
SFC_GET_CART_INFORetrieve the Cart Chunk info
SFC_GET_LOOP_INFOGet loop info
SFC_GET_INSTRUMENTGet instrument info
SFC_SET_INSTRUMENTSet instrument info
SFC_GET_CUE_COUNTGet the cue marker count
SFC_GET_CUEGet cue marker info
SFC_SET_CUESet cue marker info
SFC_RF64_AUTO_DOWNGRADEEnable auto downgrade from RF64 to WAV
cannam@125:
cannam@125: cannam@125:

cannam@125: cannam@125:
cannam@125: cannam@125: cannam@125: cannam@125:


SFC_GET_LIB_VERSION

cannam@125:

cannam@125: Retrieve the version of the library as a string. cannam@125:

cannam@125:

cannam@125: Parameters: cannam@125: 

cannam@125:         sndfile  : Not used
cannam@125:         cmd      : SFC_GET_LIB_VERSION
cannam@125:         data     : A pointer to a char buffer
cannam@125:         datasize : The size of the buffer
cannam@125:
cannam@125:

cannam@125: Example: cannam@125:

cannam@125: 
cannam@125:         char  buffer [128] ;
cannam@125:         sf_command (NULL, SFC_GET_LIB_VERSION, buffer, sizeof (buffer)) ;
cannam@125:
cannam@125: cannam@125:
cannam@125:
Return value:
cannam@125:
This call will return the length of the retrieved version string. cannam@125:
cannam@125:
cannam@125:
Notes:
cannam@125:
cannam@125: The string returned in the buffer passed to this function will not overflow cannam@125: the buffer and will always be null terminated . cannam@125:
cannam@125: cannam@125: cannam@125: cannam@125:


SFC_GET_LOG_INFO

cannam@125:

cannam@125: Retrieve the log buffer generated when opening a file as a string. This log cannam@125: buffer can often contain a good reason for why libsndfile failed to open a cannam@125: particular file. cannam@125:

cannam@125:

cannam@125: Parameters: cannam@125: 

cannam@125:         sndfile  : A valid SNDFILE* pointer
cannam@125:         cmd      : SFC_GET_LOG_INFO
cannam@125:         data     : A pointer to a char buffer
cannam@125:         datasize : The size of the buffer
cannam@125:
cannam@125:

cannam@125: Example: cannam@125:

cannam@125: 
cannam@125:         char  buffer [2048] ;
cannam@125:         sf_command (sndfile, SFC_GET_LOG_INFO, buffer, sizeof (buffer)) ;
cannam@125:
cannam@125: cannam@125:
cannam@125:
Return value:
cannam@125:
This call will return the length of the retrieved version string. cannam@125:
cannam@125:
cannam@125:
Notes:
cannam@125:
cannam@125: The string returned in the buffer passed to this function will not overflow cannam@125: the buffer and will always be null terminated . cannam@125:
cannam@125: cannam@125: cannam@125: cannam@125:


SFC_CALC_SIGNAL_MAX

cannam@125:

cannam@125: Retrieve the measured maximum signal value. This involves reading through cannam@125: the whole file which can be slow on large files. cannam@125:

cannam@125:

cannam@125: Parameters: cannam@125: 

cannam@125:         sndfile  : A valid SNDFILE* pointer
cannam@125:         cmd      : SFC_CALC_SIGNAL_MAX
cannam@125:         data     : A pointer to a double
cannam@125:         datasize : sizeof (double)
cannam@125:
cannam@125:

cannam@125: Example: cannam@125:

cannam@125: 
cannam@125:         double   max_val ;
cannam@125:         sf_command (sndfile, SFC_CALC_SIGNAL_MAX, &max_val, sizeof (max_val)) ;
cannam@125:
cannam@125: cannam@125:
cannam@125:
Return value:
cannam@125:
Zero on success, non-zero otherwise. cannam@125:
cannam@125: cannam@125: cannam@125: cannam@125:


SFC_CALC_NORM_SIGNAL_MAX

cannam@125:

cannam@125: Retrieve the measured normalised maximum signal value. This involves reading cannam@125: through the whole file which can be slow on large files. cannam@125:

cannam@125:

cannam@125: Parameters: cannam@125: 

cannam@125:         sndfile  : A valid SNDFILE* pointer
cannam@125:         cmd      : SFC_CALC_NORM_SIGNAL_MAX
cannam@125:         data     : A pointer to a double
cannam@125:         datasize : sizeof (double)
cannam@125:
cannam@125:

cannam@125: Example: cannam@125:

cannam@125: 
cannam@125:         double   max_val ;
cannam@125:         sf_command (sndfile, SFC_CALC_NORM_SIGNAL_MAX, &max_val, sizeof (max_val)) ;
cannam@125:
cannam@125: cannam@125:
cannam@125:
Return value:
cannam@125:
Zero on success, non-zero otherwise. cannam@125:
cannam@125: cannam@125: cannam@125: cannam@125:


SFC_CALC_MAX_ALL_CHANNELS

cannam@125:

cannam@125: Calculate the peak value (ie a single number) for each channel. cannam@125: This involves reading through the whole file which can be slow on large files. cannam@125:

cannam@125:

cannam@125: Parameters: cannam@125: 

cannam@125:         sndfile  : A valid SNDFILE* pointer
cannam@125:         cmd      : SFC_CALC_MAX_ALL_CHANNELS
cannam@125:         data     : A pointer to a double
cannam@125:         datasize : sizeof (double) * number_of_channels
cannam@125:
cannam@125:

cannam@125: Example: cannam@125:

cannam@125: 
cannam@125:         double   peaks [number_of_channels] ;
cannam@125:         sf_command (sndfile, SFC_CALC_MAX_ALL_CHANNELS, peaks, sizeof (peaks)) ;
cannam@125:
cannam@125:
cannam@125:
Return value:
cannam@125:
Zero if peaks have been calculated successfully and non-zero otherwise. cannam@125:
cannam@125: cannam@125: cannam@125: cannam@125: cannam@125:


SFC_CALC_NORM_MAX_ALL_CHANNELS

cannam@125:

cannam@125: Calculate the normalised peak for each channel. cannam@125: This involves reading through the whole file which can be slow on large files. cannam@125:

cannam@125:

cannam@125: Parameters: cannam@125: 

cannam@125:         sndfile  : A valid SNDFILE* pointer
cannam@125:         cmd      : SFC_CALC_NORM_MAX_ALL_CHANNELS
cannam@125:         data     : A pointer to a double
cannam@125:         datasize : sizeof (double) * number_of_channels
cannam@125:
cannam@125:

cannam@125: Example: cannam@125:

cannam@125: 
cannam@125:         double   peaks [number_of_channels] ;
cannam@125:         sf_command (sndfile, SFC_CALC_NORM_MAX_ALL_CHANNELS, peaks, sizeof (peaks)) ;
cannam@125:
cannam@125:
cannam@125:
Return value:
cannam@125:
Zero if peaks have been calculated successfully and non-zero otherwise. cannam@125:
cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125:


SFC_GET_SIGNAL_MAX

cannam@125:

cannam@125: Retrieve the peak value for the file as stored in the file header. cannam@125:

cannam@125:

cannam@125: Parameters: cannam@125: 

cannam@125:         sndfile  : A valid SNDFILE* pointer
cannam@125:         cmd      : SFC_GET_SIGNAL_MAX
cannam@125:         data     : A pointer to a double
cannam@125:         datasize : sizeof (double)
cannam@125:
cannam@125:

cannam@125: Example: cannam@125:

cannam@125: 
cannam@125:         double   max_peak ;
cannam@125:         sf_command (sndfile, SFC_GET_SIGNAL_MAX, &max_peak, sizeof (max_peak)) ;
cannam@125:
cannam@125:
cannam@125:
Return value:
cannam@125:
SF_TRUE if the file header contained the peak value. SF_FALSE otherwise. cannam@125:
cannam@125: cannam@125: cannam@125: cannam@125:


SFC_GET_MAX_ALL_CHANNELS

cannam@125:

cannam@125: Retrieve the peak value for the file as stored in the file header. cannam@125:

cannam@125:

cannam@125: Parameters: cannam@125: 

cannam@125:         sndfile  : A valid SNDFILE* pointer
cannam@125:         cmd      : SFC_GET_SIGNAL_MAX
cannam@125:         data     : A pointer to an array of doubles
cannam@125:         datasize : sizeof (double) * number_of_channels
cannam@125:
cannam@125:

cannam@125: Example: cannam@125:

cannam@125: 
cannam@125:         double   peaks [number_of_channels] ;
cannam@125:         sf_command (sndfile, SFC_GET_MAX_ALL_CHANNELS, peaks, sizeof (peaks)) ;
cannam@125:
cannam@125:
cannam@125:
Return value:
cannam@125:
SF_TRUE if the file header contains per channel peak values for the file. cannam@125: SF_FALSE otherwise. cannam@125:
cannam@125: cannam@125: cannam@125: cannam@125: cannam@125:


SFC_SET_NORM_FLOAT

cannam@125:

cannam@125: This command only affects data read from or written to using the floating point functions: cannam@125:

cannam@125: 
cannam@125: 	size_t    sf_read_float    (SNDFILE *sndfile, float *ptr, size_t items) ;
cannam@125: 	size_t    sf_readf_float   (SNDFILE *sndfile, float *ptr, size_t frames) ;
cannam@125: 
cannam@125: 	size_t    sf_write_float   (SNDFILE *sndfile, float *ptr, size_t items) ;
cannam@125: 	size_t    sf_writef_float  (SNDFILE *sndfile, float *ptr, size_t frames) ;
cannam@125:
cannam@125:

cannam@125: Parameters: cannam@125:

cannam@125: 
cannam@125:         sndfile  : A valid SNDFILE* pointer
cannam@125:         cmd      : SFC_SET_NORM_FLOAT
cannam@125:         data     : NULL
cannam@125:         datasize : SF_TRUE or SF_FALSE
cannam@125:
cannam@125:

cannam@125: For read operations setting normalisation to SF_TRUE means that the data from all cannam@125: subsequent reads will be be normalised to the range [-1.0, 1.0]. cannam@125:

cannam@125:

cannam@125: For write operations, setting normalisation to SF_TRUE means than all data supplied cannam@125: to the float write functions should be in the range [-1.0, 1.0] and will be scaled cannam@125: for the file format as necessary. cannam@125:

cannam@125:

cannam@125: For both cases, setting normalisation to SF_FALSE means that no scaling will take place. cannam@125:

cannam@125:

cannam@125: Example: cannam@125:

cannam@125: 
cannam@125:         sf_command (sndfile, SFC_SET_NORM_FLOAT, NULL, SF_TRUE) ;
cannam@125: 
cannam@125:         sf_command (sndfile, SFC_SET_NORM_FLOAT, NULL, SF_FALSE) ;
cannam@125:
cannam@125:
cannam@125:
Return value:
cannam@125:
Returns the previous float normalisation mode. cannam@125:
cannam@125: cannam@125: cannam@125: cannam@125:


SFC_SET_NORM_DOUBLE

cannam@125:

cannam@125: This command only affects data read from or written to using the double precision cannam@125: floating point functions: cannam@125:

cannam@125: 
cannam@125: 	size_t    sf_read_double    (SNDFILE *sndfile, double *ptr, size_t items) ;
cannam@125: 	size_t    sf_readf_double   (SNDFILE *sndfile, double *ptr, size_t frames) ;
cannam@125: 
cannam@125: 	size_t    sf_write_double   (SNDFILE *sndfile, double *ptr, size_t items) ;
cannam@125: 	size_t    sf_writef_double  (SNDFILE *sndfile, double *ptr, size_t frames) ;
cannam@125:
cannam@125:

cannam@125: Parameters: cannam@125:

cannam@125: 
cannam@125:         sndfile  : A valid SNDFILE* pointer
cannam@125:         cmd      : SFC_SET_NORM_DOUBLE
cannam@125:         data     : NULL
cannam@125:         datasize : SF_TRUE or SF_FALSE
cannam@125:
cannam@125:

cannam@125: For read operations setting normalisation to SF_TRUE means that the data cannam@125: from all subsequent reads will be be normalised to the range [-1.0, 1.0]. cannam@125:

cannam@125:

cannam@125: For write operations, setting normalisation to SF_TRUE means than all data supplied cannam@125: to the double write functions should be in the range [-1.0, 1.0] and will be scaled cannam@125: for the file format as necessary. cannam@125:

cannam@125:

cannam@125: For both cases, setting normalisation to SF_FALSE means that no scaling will take place. cannam@125:

cannam@125:

cannam@125: Example: cannam@125:

cannam@125: 
cannam@125:         sf_command (sndfile, SFC_SET_NORM_DOUBLE, NULL, SF_TRUE) ;
cannam@125: 
cannam@125:         sf_command (sndfile, SFC_SET_NORM_DOUBLE, NULL, SF_FALSE) ;
cannam@125:
cannam@125:
cannam@125:
Return value:
cannam@125:
Returns the previous double normalisation mode. cannam@125:
cannam@125: cannam@125: cannam@125: cannam@125:


SFC_GET_NORM_FLOAT

cannam@125:

cannam@125: Retrieve the current float normalisation mode. cannam@125:

cannam@125:

cannam@125: Parameters: cannam@125:

cannam@125: 
cannam@125:         sndfile  : A valid SNDFILE* pointer
cannam@125:         cmd      : SFC_GET_NORM_FLOAT
cannam@125:         data     : NULL
cannam@125:         datasize : anything
cannam@125:
cannam@125:

cannam@125: Example: cannam@125:

cannam@125: 
cannam@125:         normalisation = sf_command (sndfile, SFC_GET_NORM_FLOAT, NULL, 0) ;
cannam@125:
cannam@125:
cannam@125:
Return value:
cannam@125:
Returns TRUE if normalisation is on and FALSE otherwise. cannam@125:
cannam@125: cannam@125: cannam@125: cannam@125:


SFC_GET_NORM_DOUBLE

cannam@125:

cannam@125: Retrieve the current float normalisation mode. cannam@125:

cannam@125:

cannam@125: Parameters: cannam@125:

cannam@125: 
cannam@125:         sndfile  : A valid SNDFILE* pointer
cannam@125:         cmd      : SFC_GET_NORM_DOUBLE
cannam@125:         data     : NULL
cannam@125:         datasize : anything
cannam@125:
cannam@125:

cannam@125: Example: cannam@125:

cannam@125: 
cannam@125:         normalisation = sf_command (sndfile, SFC_GET_NORM_DOUBLE, NULL, 0) ;
cannam@125:
cannam@125:
cannam@125:
Return value:
cannam@125:
Returns TRUE if normalisation is on and FALSE otherwise. cannam@125:
cannam@125: cannam@125: cannam@125: cannam@125: cannam@125:


SFC_SET_SCALE_FLOAT_INT_READ

cannam@125:

cannam@125: Set/clear the scale factor when integer (short/int) data is read from a file cannam@125: containing floating point data. cannam@125:

cannam@125:

cannam@125: Parameters: cannam@125:

cannam@125: 
cannam@125:         sndfile  : A valid SNDFILE* pointer
cannam@125:         cmd      : SFC_SET_SCALE_FLOAT_INT_READ
cannam@125:         data     : NULL
cannam@125:         datasize : TRUE or FALSE
cannam@125:
cannam@125:

cannam@125: Example: cannam@125:

cannam@125: 
cannam@125:         sf_command (sndfile, SFC_SET_SCALE_FLOAT_INT_READ, NULL, SF_TRUE) ;
cannam@125:
cannam@125:
cannam@125:
Return value:
cannam@125:
Returns the previous SFC_SET_SCALE_FLOAT_INT_READ setting for this file. cannam@125:
cannam@125: cannam@125: cannam@125: cannam@125: cannam@125:


SFC_SET_SCALE_INT_FLOAT_WRITE

cannam@125:

cannam@125: Set/clear the scale factor when integer (short/int) data is written to a file cannam@125: as floating point data. cannam@125:

cannam@125:

cannam@125: Parameters: cannam@125:

cannam@125: 
cannam@125:         sndfile  : A valid SNDFILE* pointer
cannam@125:         cmd      : SFC_SET_SCALE_FLOAT_INT_READ
cannam@125:         data     : NULL
cannam@125:         datasize : TRUE or FALSE
cannam@125:
cannam@125:

cannam@125: Example: cannam@125:

cannam@125: 
cannam@125:         sf_command (sndfile, SFC_SET_SCALE_INT_FLOAT_WRITE, NULL, SF_TRUE) ;
cannam@125:
cannam@125:
cannam@125:
Return value:
cannam@125:
Returns the previous SFC_SET_SCALE_INT_FLOAT_WRITE setting for this file. cannam@125:
cannam@125: cannam@125: cannam@125: cannam@125:


SFC_GET_SIMPLE_FORMAT_COUNT

cannam@125:

cannam@125: Retrieve the number of simple formats supported by libsndfile. cannam@125:

cannam@125:

cannam@125: Parameters: cannam@125:

cannam@125: 
cannam@125:         sndfile  : Not used.
cannam@125:         cmd      : SFC_GET_SIMPLE_FORMAT_COUNT
cannam@125:         data     : a pointer to an int
cannam@125:         datasize : sizeof (int)
cannam@125:
cannam@125:

cannam@125: Example: cannam@125:

cannam@125: 
cannam@125:         int  count ;
cannam@125:         sf_command (sndfile, SFC_GET_SIMPLE_FORMAT_COUNT, &count, sizeof (int)) ;
cannam@125:
cannam@125:
cannam@125:
Return value:
cannam@125:
0 cannam@125:
cannam@125: cannam@125: cannam@125: cannam@125:


SFC_GET_SIMPLE_FORMAT

cannam@125:

cannam@125: Retrieve information about a simple format. cannam@125:

cannam@125:

cannam@125: Parameters: cannam@125:

cannam@125: 
cannam@125:         sndfile  : Not used.
cannam@125:         cmd      : SFC_GET_SIMPLE_FORMAT
cannam@125:         data     : a pointer to an  SF_FORMAT_INFO struct
cannam@125:         datasize : sizeof (SF_FORMAT_INFO)
cannam@125:
cannam@125:

cannam@125: The SF_FORMAT_INFO struct is defined in <sndfile.h> as: cannam@125:

cannam@125: 
cannam@125:         typedef struct
cannam@125:         {   int         format ;
cannam@125:             const char  *name ;
cannam@125:             const char  *extension ;
cannam@125:         } SF_FORMAT_INFO ;
cannam@125:
cannam@125:

cannam@125: When sf_command() is called with SF_GET_SIMPLE_FORMAT, the value of the format cannam@125: field should be the format number (ie 0 <= format <= count value obtained using cannam@125: SF_GET_SIMPLE_FORMAT_COUNT). cannam@125:

cannam@125:

cannam@125: Example: cannam@125:

cannam@125: 
cannam@125:         SF_FORMAT_INFO	format_info ;
cannam@125:         int             k, count ;
cannam@125: 
cannam@125:         sf_command (sndfile, SFC_GET_SIMPLE_FORMAT_COUNT, &count, sizeof (int)) ;
cannam@125: 
cannam@125:         for (k = 0 ; k < count ; k++)
cannam@125:         {   format_info.format = k ;
cannam@125:             sf_command (sndfile, SFC_GET_SIMPLE_FORMAT, &format_info, sizeof (format_info)) ;
cannam@125:             printf ("%08x  %s %s\n", format_info.format, format_info.name, format_info.extension) ;
cannam@125:             } ;
cannam@125:
cannam@125:
cannam@125:
Return value:
cannam@125:
0 on success and non-zero otherwise. cannam@125:
The value of the format field of the SF_FORMAT_INFO struct will be a value which cannam@125: can be placed in the format field of an SF_INFO struct when a file is to be opened cannam@125: for write. cannam@125:
The name field will contain a char* pointer to the name of the string, eg. "WAV (Microsoft 16 bit PCM)". cannam@125:
The extension field will contain the most commonly used file extension for that file type. cannam@125:
cannam@125: cannam@125: cannam@125: cannam@125:


SFC_GET_FORMAT_INFO

cannam@125:

cannam@125: Retrieve information about a major or subtype format. cannam@125:

cannam@125:

cannam@125: Parameters: cannam@125:

cannam@125: 
cannam@125:         sndfile  : Not used.
cannam@125:         cmd      : SFC_GET_FORMAT_INFO
cannam@125:         data     : a pointer to an SF_FORMAT_INFO struct
cannam@125:         datasize : sizeof (SF_FORMAT_INFO)
cannam@125:
cannam@125:

cannam@125: The SF_FORMAT_INFO struct is defined in <sndfile.h> as: cannam@125:

cannam@125: 
cannam@125:         typedef struct
cannam@125:         {   int         format ;
cannam@125:             const char  *name ;
cannam@125:             const char  *extension ;
cannam@125:         } SF_FORMAT_INFO ;
cannam@125:
cannam@125:

cannam@125: When sf_command() is called with SF_GET_FORMAT_INFO, the format field is cannam@125: examined and if (format & SF_FORMAT_TYPEMASK) is a valid format then the struct cannam@125: is filled in with information about the given major type. cannam@125: If (format & SF_FORMAT_TYPEMASK) is FALSE and (format & SF_FORMAT_SUBMASK) is a cannam@125: valid subtype format then the struct is filled in with information about the given cannam@125: subtype. cannam@125:

cannam@125:

cannam@125: Example: cannam@125:

cannam@125: 
cannam@125:         SF_FORMAT_INFO	format_info ;
cannam@125: 
cannam@125:         format_info.format = SF_FORMAT_WAV ;
cannam@125:         sf_command (sndfile, SFC_GET_FORMAT_INFO, &format_info, sizeof (format_info)) ;
cannam@125:         printf ("%08x  %s %s\n", format_info.format, format_info.name, format_info.extension) ;
cannam@125: 
cannam@125:         format_info.format = SF_FORMAT_ULAW ;
cannam@125:         sf_command (sndfile, SFC_GET_FORMAT_INFO, &format_info, sizeof (format_info)) ;
cannam@125:         printf ("%08x  %s\n", format_info.format, format_info.name) ;
cannam@125:
cannam@125:
cannam@125:
Return value:
cannam@125:
0 on success and non-zero otherwise. cannam@125:
cannam@125: cannam@125: cannam@125:


SFC_GET_FORMAT_MAJOR_COUNT

cannam@125:

cannam@125: Retrieve the number of major formats. cannam@125:

cannam@125:

cannam@125: Parameters: cannam@125:

cannam@125: 
cannam@125:         sndfile  : Not used.
cannam@125:         cmd      : SFC_GET_FORMAT_MAJOR_COUNT
cannam@125:         data     : a pointer to an int
cannam@125:         datasize : sizeof (int)
cannam@125:
cannam@125:

cannam@125: Example: cannam@125:

cannam@125: 
cannam@125:         int  count ;
cannam@125:         sf_command (sndfile, SFC_GET_FORMAT_MAJOR_COUNT, &count, sizeof (int)) ;
cannam@125:
cannam@125:
cannam@125:
Return value:
cannam@125:
0 cannam@125:
cannam@125: cannam@125: cannam@125: cannam@125:


SFC_GET_FORMAT_MAJOR

cannam@125:

cannam@125: Retrieve information about a major format type. cannam@125:

cannam@125:

cannam@125: Parameters: cannam@125:

cannam@125: 
cannam@125:         sndfile  : Not used.
cannam@125:         cmd      : SFC_GET_FORMAT_MAJOR
cannam@125:         data     : a pointer to an  SF_FORMAT_INFO struct
cannam@125:         datasize : sizeof (SF_FORMAT_INFO)
cannam@125:
cannam@125:

cannam@125: Example: cannam@125:

cannam@125: 
cannam@125:         SF_FORMAT_INFO	format_info ;
cannam@125:         int             k, count ;
cannam@125: 
cannam@125:         sf_command (sndfile, SFC_GET_FORMAT_MAJOR_COUNT, &count, sizeof (int)) ;
cannam@125: 
cannam@125:         for (k = 0 ; k < count ; k++)
cannam@125:         {   format_info.format = k ;
cannam@125:             sf_command (sndfile, SFC_GET_FORMAT_MAJOR, &format_info, sizeof (format_info)) ;
cannam@125:             printf ("%08x  %s %s\n", format_info.format, format_info.name, format_info.extension) ;
cannam@125:             } ;
cannam@125:
cannam@125:

cannam@125: For a more comprehensive example, see the program list_formats.c in the examples/ cannam@125: directory of the libsndfile source code distribution. cannam@125:

cannam@125:
cannam@125:
Return value:
cannam@125:
0 on success and non-zero otherwise. cannam@125:
The value of the format field will be one of the major format identifiers such as cannam@125: SF_FORMAT_WAV or SF_FORMAT_AIFF. cannam@125:
The name field will contain a char* pointer to the name of the string, eg. "WAV (Microsoft)". cannam@125:
The extension field will contain the most commonly used file extension for that file type. cannam@125:
cannam@125: cannam@125: cannam@125: cannam@125:


SFC_GET_FORMAT_SUBTYPE_COUNT

cannam@125:

cannam@125: Retrieve the number of subformats. cannam@125:

cannam@125:

cannam@125: Parameters: cannam@125:

cannam@125: 
cannam@125:         sndfile  : Not used.
cannam@125:         cmd      : SFC_GET_FORMAT_SUBTYPE_COUNT
cannam@125:         data     : a pointer to an int
cannam@125:         datasize : sizeof (int)
cannam@125:
cannam@125:

cannam@125: Example: cannam@125:

cannam@125: 
cannam@125:         int   count ;
cannam@125:         sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE_COUNT, &count, sizeof (int)) ;
cannam@125:
cannam@125:
cannam@125:
Return value:
cannam@125:
0 cannam@125:
cannam@125: cannam@125: cannam@125: cannam@125:


SFC_GET_FORMAT_SUBTYPE

cannam@125:

cannam@125: Enumerate the subtypes (this function does not translate a subtype into cannam@125: a string describing that subtype). cannam@125: A typical use case might be retrieving a string description of all subtypes cannam@125: so that a dialog box can be filled in. cannam@125:

cannam@125:

cannam@125: cannam@125:

cannam@125:

cannam@125: Parameters: cannam@125:

cannam@125: 
cannam@125:         sndfile  : Not used.
cannam@125:         cmd      : SFC_GET_FORMAT_SUBTYPE
cannam@125:         data     : a pointer to an SF_FORMAT_INFO struct
cannam@125:         datasize : sizeof (SF_FORMAT_INFO)
cannam@125:
cannam@125:

cannam@125: Example 1: Retrieve all sybtypes supported by the WAV format. cannam@125:

cannam@125: 
cannam@125:         SF_FORMAT_INFO	format_info ;
cannam@125:         int             k, count ;
cannam@125: 
cannam@125:         sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE_COUNT, &count, sizeof (int)) ;
cannam@125: 
cannam@125:         for (k = 0 ; k < count ; k++)
cannam@125:         {   format_info.format = k ;
cannam@125:             sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE, &format_info, sizeof (format_info)) ;
cannam@125:             if (! sf_format_check (format_info.format | SF_FORMAT_WAV))
cannam@125:                continue ;
cannam@125:             printf ("%08x  %s\n", format_info.format, format_info.name) ;
cannam@125:             } ;
cannam@125:
cannam@125:

cannam@125: Example 2: Print a string describing the SF_FORMAT_PCM_16 subtype. cannam@125:

cannam@125: 
cannam@125:         SF_FORMAT_INFO	format_info ;
cannam@125:         int             k, count ;
cannam@125: 
cannam@125:         sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE_COUNT, &count, sizeof (int)) ;
cannam@125: 
cannam@125:         for (k = 0 ; k < count ; k++)
cannam@125:         {   format_info.format = k ;
cannam@125:             sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE, &format_info, sizeof (format_info)) ;
cannam@125:             if (format_info.format == SF_FORMAT_PCM_16)
cannam@125:             {   printf ("%08x  %s\n", format_info.format, format_info.name) ;
cannam@125:                 break ;
cannam@125:                 } ;
cannam@125:             } ;
cannam@125:
cannam@125:

cannam@125: For a more comprehensive example, see the program list_formats.c in the examples/ cannam@125: directory of the libsndfile source code distribution. cannam@125:

cannam@125:
cannam@125:
Return value:
cannam@125:
0 on success and non-zero otherwise. cannam@125:
The value of the format field will be one of the major format identifiers such as cannam@125: SF_FORMAT_WAV or SF_FORMAT_AIFF. cannam@125:
The name field will contain a char* pointer to the name of the string; for instance cannam@125: "WAV (Microsoft)" or "AIFF (Apple/SGI)". cannam@125:
The extension field will be a NULL pointer. cannam@125:
cannam@125: cannam@125: cannam@125: cannam@125:


SFC_SET_ADD_PEAK_CHUNK

cannam@125:

cannam@125: By default, WAV and AIFF files which contain floating point data (subtype SF_FORMAT_FLOAT cannam@125: or SF_FORMAT_DOUBLE) have a PEAK chunk. cannam@125: By using this command, the addition of a PEAK chunk can be turned on or off. cannam@125:

cannam@125:

cannam@125: Note : This call must be made before any data is written to the file. cannam@125:

cannam@125:

cannam@125: Parameters: cannam@125: 

cannam@125:         sndfile  : A valid SNDFILE* pointer
cannam@125:         cmd      : SFC_SET_ADD_PEAK_CHUNK
cannam@125:         data     : Not used (should be NULL)
cannam@125:         datasize : TRUE or FALSE.
cannam@125:
cannam@125:

cannam@125: Example: cannam@125:

cannam@125: 
cannam@125:         /* Turn on the PEAK chunk. */
cannam@125:         sf_command (sndfile, SFC_SET_ADD_PEAK_CHUNK, NULL, SF_TRUE) ;
cannam@125: 
cannam@125:         /* Turn off the PEAK chunk. */
cannam@125:         sf_command (sndfile, SFC_SET_ADD_PEAK_CHUNK, NULL, SF_FALSE) ;
cannam@125:
cannam@125:
cannam@125:
Return value:
cannam@125:
Returns SF_TRUE if the peak chunk will be written after this call. cannam@125:
Returns SF_FALSE if the peak chunk will not be written after this call. cannam@125:
cannam@125: cannam@125: cannam@125: cannam@125:


SFC_UPDATE_HEADER_NOW

cannam@125:

cannam@125: The header of an audio file is normally written by libsndfile when the file is cannam@125: closed using sf_close(). cannam@125:

cannam@125:

cannam@125: There are however situations where large files are being generated and it would cannam@125: be nice to have valid data in the header before the file is complete. cannam@125: Using this command will update the file header to reflect the amount of data written cannam@125: to the file so far. cannam@125: Other programs opening the file for read (before any more data is written) will cannam@125: then read a valid sound file header. cannam@125:

cannam@125:

cannam@125: Parameters: cannam@125: 

cannam@125:         sndfile  : A valid SNDFILE* pointer
cannam@125:         cmd      : SFC_UPDATE_HEADER_NOW
cannam@125:         data     : Not used (should be NULL)
cannam@125:         datasize : Not used.
cannam@125:
cannam@125:

cannam@125: Example: cannam@125:

cannam@125: 
cannam@125:         /* Update the header now. */
cannam@125:         sf_command (sndfile, SFC_UPDATE_HEADER_NOW, NULL, 0) ;
cannam@125:
cannam@125:
cannam@125:
Return value:
cannam@125:
0 cannam@125:
cannam@125: cannam@125: cannam@125: cannam@125:


SFC_SET_UPDATE_HEADER_AUTO

cannam@125:

cannam@125: Similar to SFC_UPDATE_HEADER_NOW but updates the header at the end of every call cannam@125: to the sf_write* functions. cannam@125:

cannam@125:

cannam@125: Parameters: cannam@125: 

cannam@125:         sndfile  : A valid SNDFILE* pointer
cannam@125:         cmd      : SFC_UPDATE_HEADER_NOW
cannam@125:         data     : Not used (should be NULL)
cannam@125:         datasize : SF_TRUE or SF_FALSE
cannam@125:
cannam@125:

cannam@125: Example: cannam@125:

cannam@125: 
cannam@125:         /* Turn on auto header update. */
cannam@125:         sf_command (sndfile, SFC_SET_UPDATE_HEADER_AUTO, NULL, SF_TRUE) ;
cannam@125: 
cannam@125:         /* Turn off auto header update. */
cannam@125:         sf_command (sndfile, SFC_SET_UPDATE_HEADER_AUTO, NULL, SF_FALSE) ;
cannam@125:
cannam@125:
cannam@125:
Return value:
cannam@125:
TRUE if auto update header is now on; FALSE otherwise. cannam@125:
cannam@125: cannam@125: cannam@125: cannam@125:


SFC_FILE_TRUNCATE

cannam@125:

cannam@125: Truncate a file that was opened for write or read/write. cannam@125:

cannam@125:

cannam@125: Parameters: cannam@125: 

cannam@125:         sndfile  : A valid SNDFILE* pointer
cannam@125:         cmd      : SFC_FILE_TRUNCATE
cannam@125:         data     : A pointer to an sf_count_t.
cannam@125:         datasize : sizeof (sf_count_t)
cannam@125:
cannam@125: cannam@125:

cannam@125: Truncate the file to the number of frames specified by the sf_count_t pointed cannam@125: to by data. cannam@125: After this command, both the read and the write pointer will be cannam@125: at the new end of the file. cannam@125: This command will fail (returning non-zero) if the requested truncate position cannam@125: is beyond the end of the file. cannam@125:

cannam@125:

cannam@125: Example: cannam@125:

cannam@125: 
cannam@125:         /* Truncate the file to a length of 20 frames. */
cannam@125:         sf_count_t  frames = 20 ;
cannam@125:         sf_command (sndfile, SFC_FILE_TRUNCATE, &frames, sizeof (frames)) ;
cannam@125:
cannam@125:
cannam@125:
Return value:
cannam@125:
Zero on sucess, non-zero otherwise. cannam@125:
cannam@125: cannam@125: cannam@125: cannam@125:


SFC_SET_RAW_START_OFFSET

cannam@125:

cannam@125: Change the data start offset for files opened up as SF_FORMAT_RAW. cannam@125:

cannam@125:

cannam@125: Parameters: cannam@125: 

cannam@125:         sndfile  : A valid SNDFILE* pointer
cannam@125:         cmd      : SFC_SET_RAW_START_OFFSET
cannam@125:         data     : A pointer to an sf_count_t.
cannam@125:         datasize : sizeof (sf_count_t)
cannam@125:
cannam@125: cannam@125:

cannam@125: For a file opened as format SF_FORMAT_RAW, set the data offset to the value cannam@125: given by data. cannam@125:

cannam@125:

cannam@125: Example: cannam@125:

cannam@125: 
cannam@125:         /* Reset the data offset to 5 bytes from the start of the file. */
cannam@125:         sf_count_t  offset = 5 ;
cannam@125:         sf_command (sndfile, SFC_SET_RAW_START_OFFSET, &offset, sizeof (offset)) ;
cannam@125:
cannam@125:
cannam@125:
Return value:
cannam@125:
Zero on success, non-zero otherwise. cannam@125:
cannam@125: cannam@125: cannam@125: cannam@125:


SFC_SET_CLIPPING

cannam@125:

cannam@125: Turn on/off automatic clipping when doing floating point to integer conversion. cannam@125:

cannam@125:

cannam@125: Parameters: cannam@125: 

cannam@125:         sndfile  : A valid SNDFILE* pointer
cannam@125:         cmd      : SFC_SET_CLIPPING
cannam@125:         data     : NULL
cannam@125:         datasize : SF_TRUE or SF_FALSE.
cannam@125:
cannam@125: cannam@125:

cannam@125: Turn on (datasize == SF_TRUE) or off (datasize == SF_FALSE) clipping. cannam@125:

cannam@125:

cannam@125: Example: cannam@125:

cannam@125: 
cannam@125:         sf_command (sndfile, SFC_SET_CLIPPING, NULL, SF_TRUE) ;
cannam@125:
cannam@125:
cannam@125:
Return value:
cannam@125:
Clipping mode (SF_TRUE or SF_FALSE). cannam@125:
cannam@125: cannam@125: cannam@125: cannam@125: cannam@125:


SFC_GET_CLIPPING

cannam@125:

cannam@125: Turn on/off automatic clipping when doing floating point to integer conversion. cannam@125:

cannam@125:

cannam@125: Parameters: cannam@125: 

cannam@125:         sndfile  : A valid SNDFILE* pointer
cannam@125:         cmd      : SFC_GET_CLIPPING
cannam@125:         data     : NULL
cannam@125:         datasize : 0
cannam@125:
cannam@125: cannam@125:

cannam@125: Retrieve the current cliiping setting. cannam@125:

cannam@125:

cannam@125: Example: cannam@125:

cannam@125: 
cannam@125:         sf_command (sndfile, SFC_GET_CLIPPING, NULL, 0) ;
cannam@125:
cannam@125:
cannam@125:
Return value:
cannam@125:
Clipping mode (SF_TRUE or SF_FALSE). cannam@125:
cannam@125: cannam@125: cannam@125: cannam@125:


SFC_GET_EMBED_FILE_INFO

cannam@125:

cannam@125: Get the file offset and file length of a file enbedded within another cannam@125: larger file. cannam@125:

cannam@125:

cannam@125: Parameters: cannam@125: 

cannam@125:         sndfile  : A valid SNDFILE* pointer
cannam@125:         cmd      : SFC_GET_CLIPPING
cannam@125:         data     : a pointer to an  SF_EMBED_FILE_INFO struct
cannam@125:         datasize : sizeof (SF_EMBED_FILE_INFO)
cannam@125:
cannam@125:

cannam@125: The SF_EMBED_FILE_INFO struct is defined in <sndfile.h> as: cannam@125:

cannam@125: 
cannam@125:         typedef struct
cannam@125:         {   sf_count_t	offset ;
cannam@125:             sf_count_t	length ;
cannam@125:         } SF_EMBED_FILE_INFO ;
cannam@125:
cannam@125:
cannam@125:
Return value:
cannam@125:
0 on success and non-zero otherwise. cannam@125:
The value of the offset field of the SF_EMBED_FILE_INFO struct will be cannam@125: the offsets in bytes from the start of the outer file to the start of cannam@125: the audio file. cannam@125:
The value of the offset field of the SF_EMBED_FILE_INFO struct will be cannam@125: the length in bytes of the embedded file. cannam@125:
cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125:


SFC_WAVEX_GET_AMBISONIC

cannam@125:

cannam@125: Test if the current file has the GUID of a WAVEX file for any of the Ambisonic cannam@125: formats. cannam@125:

cannam@125:

cannam@125: Parameters: cannam@125: 

cannam@125:         sndfile  : A valid SNDFILE* pointer
cannam@125:         cmd      : SFC_WAVEX_GET_AMBISONIC
cannam@125:         data     : NULL
cannam@125:         datasize : 0
cannam@125:
cannam@125:

cannam@125: The Ambisonic WAVEX formats are defined here : cannam@125: cannam@125: http://dream.cs.bath.ac.uk/researchdev/wave-ex/bformat.html. cannam@125:

cannam@125:
cannam@125:
Return value:
cannam@125:
SF_AMBISONIC_NONE or SF_AMBISONIC_B_FORMAT or zero if the file format cannam@125: does not support ambisonic formats. cannam@125:
cannam@125: cannam@125: cannam@125: cannam@125:


SFC_WAVEX_SET_AMBISONIC

cannam@125:

cannam@125: Set the GUID of a new WAVEX file to indicate an Ambisonics format. cannam@125:

cannam@125:

cannam@125: Parameters: cannam@125: 

cannam@125:         sndfile  : A valid SNDFILE* pointer
cannam@125:         cmd      : SFC_WAVEX_SET_AMBISONIC
cannam@125:         data     : NULL
cannam@125:         datasize : SF_AMBISONIC_NONE or SF_AMBISONIC_B_FORMAT
cannam@125:
cannam@125:

cannam@125: Turn on (SF_AMBISONIC_B_FORMAT) or off (SF_AMBISONIC_NONE) encoding. cannam@125: This command is currently only supported for files with SF_FORMAT_WAVEX format. cannam@125:

cannam@125:

cannam@125: The Ambisonic WAVEX formats are defined here : cannam@125: cannam@125: http://dream.cs.bath.ac.uk/researchdev/wave-ex/bformat.html. cannam@125:

cannam@125:
cannam@125:
Return value:
cannam@125:
Return the ambisonic value that has just been set or zero if the file cannam@125: format does not support ambisonic encoding. cannam@125:
cannam@125: cannam@125: cannam@125: cannam@125:


SFC_SET_VBR_ENCODING_QUALITY

cannam@125:

cannam@125: Set the Variable Bit Rate encoding quality. cannam@125: The encoding quality value should be between 0.0 (lowest quality) and 1.0 cannam@125: (highest quality). cannam@125: Currenly this command is only implemented for FLAC and Ogg/Vorbis files. cannam@125: It has no effect on un-compressed file formats. cannam@125:

cannam@125:

cannam@125: Parameters: cannam@125: 

cannam@125:         sndfile  : A valid SNDFILE* pointer
cannam@125:         cmd      : SFC_SET_VBR_ENCODING_QUALITY
cannam@125:         data     : A pointer to a double value
cannam@125:         datasize : sizeof (double)
cannam@125:
cannam@125:

cannam@125: The command must be sent before any audio data is written to the file. cannam@125:

cannam@125:

cannam@125:

cannam@125:
cannam@125:
Return value:
cannam@125:
SF_TRUE if VBR encoding quality was set. cannam@125: SF_FALSE otherwise. cannam@125:
cannam@125: cannam@125: cannam@125: cannam@125:


SFC_SET_COMPRESSION_LEVEL

cannam@125:

cannam@125: Set the compression level. cannam@125: The compression level should be between 0.0 (minimum compression level) and 1.0 cannam@125: (highest compression level). cannam@125: Currenly this command is only implemented for FLAC and Ogg/Vorbis files. cannam@125: It has no effect on un-compressed file formats. cannam@125:

cannam@125:

cannam@125: Parameters: cannam@125: 

cannam@125:         sndfile  : A valid SNDFILE* pointer
cannam@125:         cmd      : SFC_SET_COMPRESSION_LEVEL
cannam@125:         data     : A pointer to a double value
cannam@125:         datasize : sizeof (double)
cannam@125:
cannam@125:

cannam@125: The command must be sent before any audio data is written to the file. cannam@125:

cannam@125:

cannam@125:

cannam@125:
cannam@125:
Return value:
cannam@125:
SF_TRUE if compression level was set. cannam@125: SF_FALSE otherwise. cannam@125:
cannam@125: cannam@125: cannam@125: cannam@125:


SFC_RAW_NEEDS_ENDSWAP

cannam@125:

cannam@125: Determine if raw data read using cannam@125: cannam@125: sf_read_raw cannam@125: needs to be end swapped on the host CPU. cannam@125:

cannam@125:

cannam@125: For instance, will return SF_TRUE on when reading WAV containing cannam@125: SF_FORMAT_PCM_16 data on a big endian machine and SF_FALSE on a little endian cannam@125: machine. cannam@125:

cannam@125:

cannam@125: Parameters: cannam@125: 

cannam@125:         sndfile  : A valid SNDFILE* pointer
cannam@125:         cmd      : SFC_RAW_NEEDS_ENDSWAP
cannam@125:         data     : NULL
cannam@125:         datasize : 0
cannam@125:
cannam@125: cannam@125:
cannam@125:
Return value:
cannam@125:
SF_TRUE or SF_FALSE cannam@125:
cannam@125: cannam@125: cannam@125: cannam@125: cannam@125:


SFC_GET_BROADCAST_INFO

cannam@125:

cannam@125: Retrieve the Broadcast Extension Chunk from WAV (and related) files. cannam@125:

cannam@125:

cannam@125: Parameters: cannam@125:

cannam@125: 
cannam@125:         sndfile  : A valid SNDFILE* pointer
cannam@125:         cmd      : SFC_GET_BROADCAST_INFO
cannam@125:         data     : a pointer to an SF_BROADCAST_INFO struct
cannam@125:         datasize : sizeof (SF_BROADCAST_INFO)
cannam@125:
cannam@125:

cannam@125: The SF_BROADCAST_INFO struct is defined in <sndfile.h> as: cannam@125:

cannam@125: 
cannam@125:     typedef struct
cannam@125:     {   char            description [256] ;
cannam@125:         char            originator [32] ;
cannam@125:         char            originator_reference [32] ;
cannam@125:         char            origination_date [10] ;
cannam@125:         char            origination_time [8] ;
cannam@125:         unsigned int    time_reference_low ;
cannam@125:         unsigned int    time_reference_high ;
cannam@125:         short           version ;
cannam@125:         char            umid [64] ;
cannam@125:         char            reserved [190] ;
cannam@125:         unsigned int    coding_history_size ;
cannam@125:         char            coding_history [256] ;
cannam@125:     } SF_BROADCAST_INFO ;
cannam@125:
cannam@125: cannam@125:
cannam@125:
Return value:
cannam@125:
SF_TRUE if the file contained a Broadcast Extension chunk or SF_FALSE cannam@125: otherwise. cannam@125:
cannam@125: cannam@125: cannam@125: cannam@125:


SFC_SET_BROADCAST_INFO

cannam@125:

cannam@125: Set the Broadcast Extension Chunk for WAV (and related) files. cannam@125:

cannam@125:

cannam@125: Parameters: cannam@125:

cannam@125: 
cannam@125:         sndfile  : A valid SNDFILE* pointer
cannam@125:         cmd      : SFC_SET_BROADCAST_INFO
cannam@125:         data     : a pointer to an SF_BROADCAST_INFO struct
cannam@125:         datasize : sizeof (SF_BROADCAST_INFO)
cannam@125:
cannam@125: cannam@125:
cannam@125:
Return value:
cannam@125:
SF_TRUE if setting the Broadcast Extension chunk was successful and SF_FALSE cannam@125: otherwise. cannam@125: cannam@125:
cannam@125: cannam@125: cannam@125: cannam@125:


SFC_GET_CART_INFO

cannam@125:

Retrieve the Cart Chunk from WAV (and related) files. Based on AES46 standard for CartChunk (see CartChunk.org for more information. cannam@125:

cannam@125:

cannam@125: Parameters: cannam@125:

cannam@125: 
cannam@125:         sndfile  : A valid SNDFILE* pointer
cannam@125:         cmd      : SFC_GET_CART_INFO
cannam@125:         data     : a pointer to an SF_CART_INFO struct
cannam@125:         datasize : sizeof (SF_CART_INFO)
cannam@125:
cannam@125:

cannam@125: The SF_CART_INFO struct is defined in <sndfile.h> as: cannam@125:

cannam@125: 
cannam@125: #define SF_CART_INFO_VAR(p_tag_text_size) \
cannam@125:                         struct
cannam@125:                         {       char            version [4] ;
cannam@125:                                 char            title [64] ;
cannam@125:                                 char            artist [64] ;
cannam@125:                                 char            cut_id [64] ;
cannam@125:                                 char            client_id [64] ;
cannam@125:                                 char            category [64] ;
cannam@125:                                 char            classification [64] ;
cannam@125:                                 char            out_cue [64] ;
cannam@125:                                 char            start_date [10] ;
cannam@125:                                 char            start_time [8] ;
cannam@125:                                 char            end_date [10] ;
cannam@125:                                 char            end_time [8] ;
cannam@125:                                 char            producer_app_id [64] ;
cannam@125:                                 char            producer_app_version [64] ;
cannam@125:                                 char            user_def [64] ;
cannam@125:                                 long    level_reference ;
cannam@125:                                 SF_CART_TIMER   post_timers [8] ;
cannam@125:                                 char            reserved [276] ;
cannam@125:                                 char            url [1024] ;
cannam@125:                                 unsigned int    tag_text_size ;
cannam@125:                                 char            tag_text[p_tag_text_size] ;
cannam@125:                         }
cannam@125:
cannam@125: cannam@125:
cannam@125:
Return value:
cannam@125:
SF_TRUE if the file contained a Cart chunk or SF_FALSE cannam@125: otherwise. cannam@125:
cannam@125: cannam@125: cannam@125: cannam@125:


SFC_SET_CART_INFO

cannam@125:

cannam@125: Set the Cart Chunk for WAV (and related) files. cannam@125:

cannam@125:

cannam@125: Parameters: cannam@125:

cannam@125: 
cannam@125:         sndfile  : A valid SNDFILE* pointer
cannam@125:         cmd      : SFC_SET_CART_INFO
cannam@125:         data     : a pointer to an SF_CART_INFO struct
cannam@125:         datasize : sizeof (SF_CART_INFO)
cannam@125:
cannam@125: cannam@125:
cannam@125:
Return value:
cannam@125:
SF_TRUE if setting the Cart chunk was successful and SF_FALSE cannam@125: otherwise. cannam@125:
cannam@125: cannam@125: cannam@125: cannam@125:


SFC_GET_LOOP_INFO

cannam@125:

cannam@125: Retrieve loop information for file including time signature, length in cannam@125: beats and original MIDI base note cannam@125:

cannam@125:

cannam@125: Parameters: cannam@125:

cannam@125: 
cannam@125:          sndfile  : A valid SNDFILE* pointer
cannam@125:          cmd      : SFC_GET_LOOP_INFO
cannam@125:          data     : a pointer to an SF_LOOP_INFO struct
cannam@125:          datasize : sizeof (SF_LOOP_INFO)
cannam@125:
cannam@125:

cannam@125: The SF_BROADCAST_INFO struct is defined in <sndfile.h> as: cannam@125:

cannam@125: 
cannam@125:         typedef struct
cannam@125:         {   short    time_sig_num ;   /* any positive integer    > 0  */
cannam@125:             short    time_sig_den ;   /* any positive power of 2 > 0  */
cannam@125:             int        loop_mode ;    /* see SF_LOOP enum             */
cannam@125: 
cannam@125:             int        num_beats ;    /* this is NOT the amount of quarter notes !!!*/
cannam@125:                                       /* a full bar of 4/4 is 4 beats */
cannam@125:                                       /* a full bar of 7/8 is 7 beats */
cannam@125: 
cannam@125:             float    bpm ;            /* suggestion, as it can be calculated using other fields:*/
cannam@125:                                       /* file's lenght, file's sampleRate and our time_sig_den*/
cannam@125:                                       /* -> bpms are always the amount of _quarter notes_ per minute */
cannam@125: 
cannam@125:             int    root_key ;         /* MIDI note, or -1 for None */
cannam@125:             int future [6] ;
cannam@125:         } SF_LOOP_INFO ;
cannam@125:
cannam@125:

cannam@125: Example: cannam@125:

cannam@125: 
cannam@125:          SF_LOOP_INFO loop;
cannam@125:          sf_command (sndfile, SFC_GET_LOOP_INFO, &loop, sizeof (loop)) ;
cannam@125:
cannam@125:
cannam@125:
Return value:
cannam@125:
SF_TRUE if the file header contains loop information for the file. cannam@125: SF_FALSE otherwise. cannam@125:
cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125:


SFC_GET_INSTRUMENT

cannam@125:

cannam@125: Retrieve instrument information from file including MIDI base note, cannam@125: keyboard mapping and looping informations(start/stop and mode). cannam@125:

cannam@125:

cannam@125: Parameters: cannam@125:

cannam@125: 
cannam@125:          sndfile  : A valid SNDFILE* pointer
cannam@125:          cmd      : SFC_GET_INSTRUMENT
cannam@125:          data     : a pointer to an SF_INSTRUMENT struct
cannam@125:          datasize : sizeof (SF_INSTRUMENT)
cannam@125:
cannam@125: cannam@125:

cannam@125: The SF_INSTRUMENT struct is defined in <sndfile.h> as: cannam@125:

cannam@125: 
cannam@125:         enum
cannam@125:         {    /*
cannam@125:             **    The loop mode field in SF_INSTRUMENT will be one of the following.
cannam@125:             */
cannam@125:             SF_LOOP_NONE = 800,
cannam@125:             SF_LOOP_FORWARD,
cannam@125:             SF_LOOP_BACKWARD,
cannam@125:             SF_LOOP_ALTERNATING
cannam@125:         } ;
cannam@125: 
cannam@125:         typedef struct
cannam@125:         {   int gain ;
cannam@125:             char basenote, detune ;
cannam@125:             char velocity_lo, velocity_hi ;
cannam@125:             char key_lo, key_hi ;
cannam@125:             int loop_count ;
cannam@125: 
cannam@125:             struct
cannam@125:             {   int mode ;
cannam@125:                 unsigned int start ;
cannam@125:                 unsigned int end ;
cannam@125:                 unsigned int count ;
cannam@125:             } loops [16] ; /* make variable in a sensible way */
cannam@125:         } SF_INSTRUMENT ;
cannam@125:
cannam@125: cannam@125:

cannam@125: Example: cannam@125:

cannam@125: 
cannam@125:          SF_INSTRUMENT inst ;
cannam@125:          sf_command (sndfile, SFC_GET_INSTRUMENT, &inst, sizeof (inst)) ;
cannam@125:
cannam@125:
cannam@125:
Return value:
cannam@125:
SF_TRUE if the file header contains instrument information for the cannam@125: file. SF_FALSE otherwise. cannam@125:
cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125:


SFC_SET_INSTRUMENT

cannam@125:

cannam@125: Set the instrument information for the file. cannam@125:

cannam@125:

cannam@125: Parameters: cannam@125:

cannam@125: 
cannam@125:          sndfile  : A valid SNDFILE* pointer
cannam@125:          cmd      : SFC_SET_INSTRUMENT
cannam@125:          data     : a pointer to an SF_INSTRUMENT struct
cannam@125:          datasize : sizeof (SF_INSTRUMENT)
cannam@125:
cannam@125:

cannam@125: Example: cannam@125:

cannam@125: 
cannam@125:          SF_INSTRUMENT inst ;
cannam@125:          sf_command (sndfile, SFC_SET_INSTRUMENT, &inst, sizeof (inst)) ;
cannam@125:
cannam@125:
cannam@125:
Return value:
cannam@125:
SF_TRUE if the file header contains instrument information for the cannam@125: file. SF_FALSE otherwise. cannam@125:
cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125:


SFC_GET_CUE_COUNT

cannam@125:

cannam@125: Retrieve the number of cue markers available for retrieval using the cannam@125: SFC_GET_CUE command. cannam@125:

cannam@125:

cannam@125: Parameters: cannam@125:

cannam@125: 
cannam@125:          sndfile  : A valid SNDFILE* pointer
cannam@125:          cmd      : SFC_GET_CUE
cannam@125:          data     : a pointer to a uint32_t
cannam@125:          datasize : sizeof (uint32_t)
cannam@125:
cannam@125: cannam@125: cannam@125:

cannam@125: Example: cannam@125:

cannam@125: 
cannam@125:          uint32_t cue_count ;
cannam@125:          sf_command (sndfile, SFC_GET_CUE_COUNT, &cue_count, sizeof (cue_count)) ;
cannam@125:
cannam@125:
cannam@125:
Return value:
cannam@125:
SF_TRUE if the file header contains cue marker information for the cannam@125: file. SF_FALSE otherwise. cannam@125:
cannam@125: cannam@125: cannam@125: cannam@125: cannam@125:


SFC_GET_CUE

cannam@125:

cannam@125: Retrieve cue marker information from file. cannam@125:

cannam@125:

cannam@125: Parameters: cannam@125:

cannam@125: 
cannam@125:          sndfile  : A valid SNDFILE* pointer
cannam@125:          cmd      : SFC_GET_CUE
cannam@125:          data     : a pointer to an SF_CUES struct
cannam@125:          datasize : sizeof (SF_CUES)
cannam@125:
cannam@125: cannam@125:

cannam@125: The SF_CUES struct is defined in <sndfile.h> as: cannam@125:

cannam@125: 
cannam@125:     typedef struct
cannam@125:     {	int cue_count ;
cannam@125: 
cannam@125:     	struct
cannam@125:     	{	int32_t   indx ;
cannam@125:     		uint32_t  position ;
cannam@125:     		int32_t   fcc_chunk ;
cannam@125:     		int32_t   chunk_start ;
cannam@125:     		int32_t   block_start ;
cannam@125:     		uint32_t  sample_offset ;
cannam@125:     		char name [256] ;
cannam@125:     	} cue_points [100] ;
cannam@125:     } SF_CUES ;
cannam@125:
cannam@125: cannam@125:

cannam@125: There is also an SF_CUES_VAR #define that allows reading/writing more than 100 cannam@125: cue markers. cannam@125:

cannam@125: cannam@125:

cannam@125: Example: cannam@125:

cannam@125: 
cannam@125:          SF_CUES cues ;
cannam@125:          sf_command (sndfile, SFC_GET_CUE, &cues, sizeof (cues)) ;
cannam@125:
cannam@125:
cannam@125:
Return value:
cannam@125:
SF_TRUE if the file header contains cue marker information for the cannam@125: file. SF_FALSE otherwise. cannam@125:
cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125:


SFC_SET_CUE

cannam@125:

cannam@125: Set the cue marker information for the file. cannam@125:

cannam@125:

cannam@125: Parameters: cannam@125:

cannam@125: 
cannam@125:          sndfile  : A valid SNDFILE* pointer
cannam@125:          cmd      : SFC_SET_CUE
cannam@125:          data     : a pointer to an SF_CUES struct
cannam@125:          datasize : sizeof (SF_CUES)
cannam@125:
cannam@125:

cannam@125: Example: cannam@125:

cannam@125: 
cannam@125:          SF_CUES cues ;
cannam@125:          sf_command (sndfile, SFC_SET_CUE, &cues, sizeof (cues)) ;
cannam@125:
cannam@125:
cannam@125:
Return value:
cannam@125:
SF_TRUE if the file header contains cue marker information for the cannam@125: file. SF_FALSE otherwise. cannam@125:
cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125:


SFC_RF64_AUTO_DOWNGRADE

cannam@125:

cannam@125: Enable auto downgrade from RF64 to WAV. cannam@125:

cannam@125:

cannam@125: The EBU recomendation is that when writing RF64 files and the resulting file is cannam@125: less than 4Gig in size, it should be downgraded to a WAV file (WAV files have a cannam@125: maximum size of 4Gig). cannam@125: libsndfile doesn't follow the EBU recommendations exactly, , mainly because the cannam@125: test suite needs to be able test reading/writing RF64 files without having to cannam@125: generate files larger than 4 gigabytes. cannam@125:

cannam@125:

cannam@125: Note: This command should be issued before the first bit of audio data has been cannam@125: written to the file. cannam@125: Calling this command after audio data has been written will return the current cannam@125: value of this setting, but will not allow it to be changed. cannam@125:

cannam@125:

cannam@125: Parameters: cannam@125:

cannam@125: 
cannam@125:          sndfile  : A valid SNDFILE* pointer
cannam@125:          cmd      : SFC_RF64_AUTO_DOWNGRADE
cannam@125:          data     : NULL
cannam@125:          datasize : SF_TRUE or SF_FALSE
cannam@125:
cannam@125:

cannam@125: Example: cannam@125:

cannam@125: 
cannam@125:          /* Enable auto downgrade on file close. */
cannam@125:          sf_command (sndfile, SFC_RF64_AUTO_DOWNGRADE, NULL, SF_TRUE) ;
cannam@125:
cannam@125:
cannam@125:
Return value:
cannam@125:
Returns SF_TRUE if SFC_RF64_AUTO_DOWNGRADE is set and SF_FALSE cannam@125: otherwise. cannam@125:
cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125: cannam@125:
cannam@125:

cannam@125: The libsndfile home page is here : cannam@125: cannam@125: http://www.mega-nerd.com/libsndfile/. cannam@125:
cannam@125: Version : 1.0.25 cannam@125:

cannam@125: cannam@125: cannam@125: