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

sf_command

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

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

cannam@85:

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

cannam@85:

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

cannam@85: cannam@85:
cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85: cannam@85:
SFC_GET_LIB_VERSIONRetrieve the version of the library.
SFC_GET_LOG_INFORetrieve the internal per-file operation log.
SFC_CALC_SIGNAL_MAXRetrieve the measured maximum signal value.
SFC_CALC_NORM_SIGNAL_MAXRetrieve the measured normalised maximum signal value.
SFC_CALC_MAX_ALL_CHANNELSCalculate peaks for all channels.
SFC_CALC_NORM_MAX_ALL_CHANNELSCalculate normalised peaks for all channels.
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_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@85: 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@85: 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.
cannam@85:
cannam@85: cannam@85:

cannam@85: cannam@85:
cannam@85: cannam@85: cannam@85: cannam@85:


SFC_GET_LIB_VERSION

cannam@85:

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

cannam@85:

cannam@85: Parameters: cannam@85: 

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

cannam@85: Example: cannam@85:

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


SFC_GET_LOG_INFO

cannam@85:

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

cannam@85:

cannam@85: Parameters: cannam@85: 

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

cannam@85: Example: cannam@85:

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


SFC_CALC_SIGNAL_MAX

cannam@85:

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

cannam@85:

cannam@85: Parameters: cannam@85: 

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

cannam@85: Example: cannam@85:

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


SFC_CALC_NORM_SIGNAL_MAX

cannam@85:

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

cannam@85:

cannam@85: Parameters: cannam@85: 

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

cannam@85: Example: cannam@85:

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


SFC_CALC_MAX_ALL_CHANNELS

cannam@85:

cannam@85: Calculate peaks for all channels. This involves reading through cannam@85: the whole file which can be slow on large files. cannam@85:

cannam@85:

cannam@85: Parameters: cannam@85: 

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

cannam@85: Example: cannam@85:

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


SFC_CALC_NORM_MAX_ALL_CHANNELS

cannam@85:

cannam@85: Calculate normalised peaks for all channels. This involves reading through cannam@85: the whole file which can be slow on large files. cannam@85:

cannam@85:

cannam@85: Parameters: cannam@85: 

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

cannam@85: Example: cannam@85:

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


SFC_SET_NORM_FLOAT

cannam@85:

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

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

cannam@85: Parameters: cannam@85:

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

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

cannam@85:

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

cannam@85:

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

cannam@85:

cannam@85: Example: cannam@85:

cannam@85: 
cannam@85:         sf_command (sndfile, SFC_SET_NORM_FLOAT, NULL, SF_TRUE) ;
cannam@85: 
cannam@85:         sf_command (sndfile, SFC_SET_NORM_FLOAT, NULL, SF_FALSE) ;
cannam@85:
cannam@85:
cannam@85:
Return value:
cannam@85:
Returns 1 on success or 0 for failure. cannam@85:
cannam@85: cannam@85: cannam@85: cannam@85:


SFC_SET_NORM_DOUBLE

cannam@85:

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

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

cannam@85: Parameters: cannam@85:

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

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

cannam@85:

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

cannam@85:

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

cannam@85:

cannam@85: Example: cannam@85:

cannam@85: 
cannam@85:         sf_command (sndfile, SFC_SET_NORM_DOUBLE, NULL, SF_TRUE) ;
cannam@85: 
cannam@85:         sf_command (sndfile, SFC_SET_NORM_DOUBLE, NULL, SF_FALSE) ;
cannam@85:
cannam@85:
cannam@85:
Return value:
cannam@85:
Returns 1 on success or 0 for failure. cannam@85:
cannam@85: cannam@85: cannam@85: cannam@85:


SFC_GET_NORM_FLOAT

cannam@85:

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

cannam@85:

cannam@85: Parameters: cannam@85:

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

cannam@85: Example: cannam@85:

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


SFC_GET_NORM_DOUBLE

cannam@85:

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

cannam@85:

cannam@85: Parameters: cannam@85:

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

cannam@85: Example: cannam@85:

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


SFC_GET_SIMPLE_FORMAT_COUNT

cannam@85:

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

cannam@85:

cannam@85: Parameters: cannam@85:

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

cannam@85: Example: cannam@85:

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


SFC_GET_SIMPLE_FORMAT

cannam@85:

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

cannam@85:

cannam@85: Parameters: cannam@85:

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

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

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

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

cannam@85:

cannam@85: Example: cannam@85:

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


SFC_GET_FORMAT_INFO

cannam@85:

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

cannam@85:

cannam@85: Parameters: cannam@85:

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

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

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

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

cannam@85:

cannam@85: Example: cannam@85:

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


SFC_GET_FORMAT_MAJOR_COUNT

cannam@85:

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

cannam@85:

cannam@85: Parameters: cannam@85:

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

cannam@85: Example: cannam@85:

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


SFC_GET_FORMAT_MAJOR

cannam@85:

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

cannam@85:

cannam@85: Parameters: cannam@85:

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

cannam@85: Example: cannam@85:

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

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

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


SFC_GET_FORMAT_SUBTYPE_COUNT

cannam@85:

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

cannam@85:

cannam@85: Parameters: cannam@85:

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

cannam@85: Example: cannam@85:

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


SFC_GET_FORMAT_SUBTYPE

cannam@85:

cannam@85: Retrieve information about a subformat. cannam@85:

cannam@85:

cannam@85: Parameters: cannam@85:

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

cannam@85: Example: cannam@85:

cannam@85: 
cannam@85:         SF_FORMAT_INFO	format_info ;
cannam@85:         int             k, count ;
cannam@85: 
cannam@85:         sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE_COUNT, &count, sizeof (int)) ;
cannam@85: 
cannam@85:         /* Retrieve all the subtypes supported by the WAV format. */
cannam@85:         for (k = 0 ; k < count ; k++)
cannam@85:         {   format_info.format = k ;
cannam@85:             sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE, &format_info, sizeof (format_info)) ;
cannam@85:             if (! sf_format_check (format.info | SF_FORMAT_WAV))
cannam@85:                continue ;
cannam@85:             printf ("%08x  %s\n", format_info.format, format_info.name) ;
cannam@85:             } ;
cannam@85:
cannam@85:

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

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


SFC_SET_ADD_PEAK_CHUNK

cannam@85:

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

cannam@85:

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

cannam@85:

cannam@85: Parameters: cannam@85: 

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

cannam@85: Example: cannam@85:

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


SFC_UPDATE_HEADER_NOW

cannam@85:

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

cannam@85:

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

cannam@85:

cannam@85: Parameters: cannam@85: 

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

cannam@85: Example: cannam@85:

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


SFC_SET_UPDATE_HEADER_AUTO

cannam@85:

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

cannam@85:

cannam@85: Parameters: cannam@85: 

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

cannam@85: Example: cannam@85:

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


SFC_FILE_TRUNCATE

cannam@85:

cannam@85: Truncate a file open for write or for read/write. cannam@85:

cannam@85:

cannam@85: Parameters: cannam@85: 

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

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

cannam@85:

cannam@85: Example: cannam@85:

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


SFC_SET_RAW_START_OFFSET

cannam@85:

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

cannam@85:

cannam@85: Parameters: cannam@85: 

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

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

cannam@85:

cannam@85: Example: cannam@85:

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

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

cannam@85: cannam@85: cannam@85: