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 an integer identifier which is defined in <sndfile.h>. cannam@85: All of the valid command identifiers have names beginning 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:| SFC_GET_LIB_VERSION | cannam@85:Retrieve the version of the library. | cannam@85:
| SFC_GET_LOG_INFO | cannam@85:Retrieve the internal per-file operation log. | cannam@85:
| SFC_CALC_SIGNAL_MAX | cannam@85:Calculate the measured maximum signal value. | cannam@85:
| SFC_CALC_NORM_SIGNAL_MAX | cannam@85:Calculate the measured normalised maximum signal value. | cannam@85:
| SFC_CALC_MAX_ALL_CHANNELS | cannam@85:Calculate the peak value for each channel. | cannam@85:
| SFC_CALC_NORM_MAX_ALL_CHANNELS | cannam@85:Calculate the normalised peak for each channel. | cannam@85:
| SFC_GET_SIGNAL_MAX | cannam@85:Retrieve the peak value for the file (as stored in the file header). | cannam@85:
| SFC_GET_MAX_ALL_CHANNELS | cannam@85:Retrieve the peak value for each channel (as stored in the file header). | cannam@85:
| SFC_SET_NORM_FLOAT | cannam@85:Modify the normalisation behaviour of the floating point reading and writing functions. | cannam@85:
| SFC_SET_NORM_DOUBLE | cannam@85:Modify the normalisation behaviour of the double precision floating point reading and writing functions. | cannam@85:
| SFC_GET_NORM_FLOAT | cannam@85:Retrieve the current normalisation behaviour of the floating point reading and writing functions. | cannam@85:
| SFC_GET_NORM_DOUBLE | cannam@85:Retrieve the current normalisation behaviour of the double precision floating point reading and writing functions. | cannam@85:
| SFC_SET_SCALE_FLOAT_INT_READ | cannam@85:Set/clear the scale factor when integer (short/int) data is read from a file cannam@85: containing floating point data. | cannam@85:
| SFC_SET_SCALE_INT_FLOAT_WRITE | cannam@85:Set/clear the scale factor when integer (short/int) data is written to a file cannam@85: as floating point data. | cannam@85:
| SFC_GET_SIMPLE_FORMAT_COUNT | cannam@85:Retrieve the number of simple formats supported by libsndfile. | cannam@85:
| SFC_GET_SIMPLE_FORMAT | cannam@85:Retrieve information about a simple format. | cannam@85:
| SFC_GET_FORMAT_INFO | cannam@85:Retrieve information about a major or subtype format. | cannam@85:
| SFC_GET_FORMAT_MAJOR_COUNT | cannam@85:Retrieve the number of major formats. | cannam@85:
| SFC_GET_FORMAT_MAJOR | cannam@85:Retrieve information about a major format type. | cannam@85:
| SFC_GET_FORMAT_SUBTYPE_COUNT | cannam@85:Retrieve the number of subformats. | cannam@85:
| SFC_GET_FORMAT_SUBTYPE | cannam@85:Retrieve information about a subformat. | cannam@85:
| SFC_SET_ADD_PEAK_CHUNK | cannam@85:Switch the code for adding the PEAK chunk to WAV and AIFF files on or off. | cannam@85:
| SFC_UPDATE_HEADER_NOW | cannam@85:Used when a file is open for write, this command will update the file cannam@85: header to reflect the data written so far. | cannam@85:
| SFC_SET_UPDATE_HEADER_AUTO | cannam@85:Used 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. | cannam@85:
| SFC_FILE_TRUNCATE | cannam@85:Truncate a file open for write or for read/write. | cannam@85:
| SFC_SET_RAW_START_OFFSET | cannam@85:Change the data start offset for files opened up as SF_FORMAT_RAW. | cannam@85:
| SFC_SET_CLIPPING | cannam@85:Turn on/off automatic clipping when doing floating point to integer cannam@85: conversion. | cannam@85:
| SFC_GET_CLIPPING | cannam@85:Retrieve current clipping setting. | cannam@85:
| SFC_GET_EMBED_FILE_INFO | cannam@85:Retrieve information about audio files embedded inside other files. | cannam@85:
| SFC_GET_AMBISONIC | cannam@85:Test a WAVEX file for Ambisonic format | cannam@85:
| SFC_SET_AMBISONIC | cannam@85:Modify a WAVEX header for Ambisonic format | cannam@85:
| SFC_SET_VBR_ENCODING_QUALITY | cannam@85:Set the the Variable Bit Rate encoding quality | cannam@85:
| SFC_RAW_NEEDS_ENDSWAP | cannam@85:Determine if raw data needs endswapping | cannam@85:
| SFC_GET_BROADCAST_INFO | cannam@85:Retrieve the Broadcast Chunk info | cannam@85:
| SFC_SET_BROADCAST_INFO | cannam@85:Set the Broadcast Chunk info | cannam@85:
| SFC_GET_LOOP_INFO | cannam@85:Get loop info | cannam@85:
| SFC_GET_INSTRUMENT | cannam@85:Get instrument info | cannam@85:
| SFC_SET_INSTRUMENT | cannam@85:Set instrument info | cannam@85:
| SFC_SET_VBR_ENCODING_QUALITY | cannam@85:Set variable bit rate encoding quality | 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: 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: 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: Retrieve the measured normalised 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: Calculate the peak value (ie a single number) for each channel. cannam@85: This involves reading 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_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: Calculate the normalised peak for each channel. cannam@85: This involves reading 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_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: Retrieve the peak value for the file as stored in the file header. cannam@85:
cannam@85:cannam@85: Parameters: cannam@85:
cannam@85: sndfile : A valid SNDFILE* pointer cannam@85: cmd : SFC_GET_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_peak ; cannam@85: sf_command (sndfile, SFC_GET_SIGNAL_MAX, &max_peak, sizeof (max_peak)) ; cannam@85:cannam@85:
cannam@85: Retrieve the peak value for the file as stored in the file header. cannam@85:
cannam@85:cannam@85: Parameters: cannam@85:
cannam@85: sndfile : A valid SNDFILE* pointer cannam@85: cmd : SFC_GET_SIGNAL_MAX cannam@85: data : A pointer to an array of doubles 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_GET_MAX_ALL_CHANNELS, peaks, sizeof (peaks)) ; cannam@85: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: 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: 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: 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: Set/clear the scale factor when integer (short/int) data is read from a file cannam@85: containing floating point data. cannam@85:
cannam@85:cannam@85: Parameters: cannam@85:
cannam@85:cannam@85: sndfile : A valid SNDFILE* pointer cannam@85: cmd : SFC_SET_SCALE_FLOAT_INT_READ cannam@85: data : NULL cannam@85: datasize : TRUE or FALSE cannam@85:cannam@85:
cannam@85: Example: cannam@85:
cannam@85:cannam@85: sf_command (sndfile, SFC_SET_SCALE_FLOAT_INT_READ, NULL, SF_TRUE) ; cannam@85:cannam@85:
cannam@85: Set/clear the scale factor when integer (short/int) data is written to a file cannam@85: as floating point data. cannam@85:
cannam@85:cannam@85: Parameters: cannam@85:
cannam@85:cannam@85: sndfile : A valid SNDFILE* pointer cannam@85: cmd : SFC_SET_SCALE_FLOAT_INT_READ cannam@85: data : NULL cannam@85: datasize : TRUE or FALSE cannam@85:cannam@85:
cannam@85: Example: cannam@85:
cannam@85:cannam@85: sf_command (sndfile, SFC_SET_SCALE_INT_FLOAT_WRITE, NULL, SF_TRUE) ; cannam@85: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: 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: 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: 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: 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: 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: Enumerate the subtypes (this function does not translate a subtype into cannam@85: a string describing that subtype). cannam@85: A typical use case might be retrieving a string description of all subtypes cannam@85: so that a dialog box can be filled in. cannam@85:
cannam@85:cannam@85: 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 1: Retrieve all sybtypes supported by the WAV format. 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: 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.format | 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: Example 2: Print a string describing the SF_FORMAT_PCM_16 subtype. 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: 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 (format_info.format == SF_FORMAT_PCM_16)
cannam@85: { printf ("%08x %s\n", format_info.format, format_info.name) ;
cannam@85: break ;
cannam@85: } ;
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: 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: 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: 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: Truncate a file that was opened for write or 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: 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: Turn on/off automatic clipping when doing floating point to integer conversion. cannam@85:
cannam@85:cannam@85: Parameters: cannam@85:
cannam@85: sndfile : A valid SNDFILE* pointer cannam@85: cmd : SFC_SET_CLIPPING cannam@85: data : NULL cannam@85: datasize : SF_TRUE or SF_FALSE. cannam@85:cannam@85: cannam@85:
cannam@85: Turn on (datasize == SF_TRUE) or off (datasize == SF_FALSE) clipping. cannam@85:
cannam@85:cannam@85: Example: cannam@85:
cannam@85:cannam@85: sf_command (sndfile, SFC_SET_CLIPPING, NULL, SF_TRUE) ; cannam@85:cannam@85:
cannam@85: Turn on/off automatic clipping when doing floating point to integer conversion. cannam@85:
cannam@85:cannam@85: Parameters: cannam@85:
cannam@85: sndfile : A valid SNDFILE* pointer cannam@85: cmd : SFC_GET_CLIPPING cannam@85: data : NULL cannam@85: datasize : 0 cannam@85:cannam@85: cannam@85:
cannam@85: Retrieve the current cliiping setting. cannam@85:
cannam@85:cannam@85: Example: cannam@85:
cannam@85:cannam@85: sf_command (sndfile, SFC_GET_CLIPPING, NULL, 0) ; cannam@85:cannam@85:
cannam@85: Get the file offset and file length of a file enbedded within another cannam@85: larger file. cannam@85:
cannam@85:cannam@85: Parameters: cannam@85:
cannam@85: sndfile : A valid SNDFILE* pointer cannam@85: cmd : SFC_GET_CLIPPING cannam@85: data : a pointer to an SF_EMBED_FILE_INFO struct cannam@85: datasize : sizeof (SF_EMBED_FILE_INFO) cannam@85:cannam@85:
cannam@85: The SF_EMBED_FILE_INFO struct is defined in <sndfile.h> as: cannam@85:
cannam@85:
cannam@85: typedef struct
cannam@85: { sf_count_t offset ;
cannam@85: sf_count_t length ;
cannam@85: } SF_EMBED_FILE_INFO ;
cannam@85:
cannam@85: cannam@85: Test if the current file has the GUID of a WAVEX file for any of the Ambisonic cannam@85: formats. cannam@85:
cannam@85:cannam@85: Parameters: cannam@85:
cannam@85: sndfile : A valid SNDFILE* pointer cannam@85: cmd : SFC_WAVEX_GET_AMBISONIC cannam@85: data : NULL cannam@85: datasize : 0 cannam@85:cannam@85:
cannam@85: The Ambisonic WAVEX formats are defined here : cannam@85: cannam@85: http://dream.cs.bath.ac.uk/researchdev/wave-ex/bformat.html. cannam@85:
cannam@85:cannam@85: Set the GUID of a new WAVEX file to indicate an Ambisonics format. cannam@85:
cannam@85:cannam@85: Parameters: cannam@85:
cannam@85: sndfile : A valid SNDFILE* pointer cannam@85: cmd : SFC_WAVEX_SET_AMBISONIC cannam@85: data : NULL cannam@85: datasize : SF_AMBISONIC_NONE or SF_AMBISONIC_B_FORMAT cannam@85:cannam@85:
cannam@85: Turn on (SF_AMBISONIC_B_FORMAT) or off (SF_AMBISONIC_NONE) encoding. cannam@85: This command is currently only supported for files with SF_FORMAT_WAVEX format. cannam@85:
cannam@85:cannam@85: The Ambisonic WAVEX formats are defined here : cannam@85: cannam@85: http://dream.cs.bath.ac.uk/researchdev/wave-ex/bformat.html. cannam@85:
cannam@85:cannam@85: Set the the Variable Bit Rate encoding quality. cannam@85: The encoding quality value should be between 0.0 (lowest quality) and 1.0 cannam@85: (highest quality). cannam@85:
cannam@85:cannam@85: Parameters: cannam@85:
cannam@85: sndfile : A valid SNDFILE* pointer cannam@85: cmd : SFC_SET_VBR_ENCODING_QUALITY cannam@85: data : A pointer to a double value cannam@85: datasize : sizeof (double) cannam@85:cannam@85:
cannam@85: The command must be sent before any audio data is written to the file. cannam@85:
cannam@85:cannam@85:
cannam@85:cannam@85: Determine if raw data read using cannam@85: cannam@85: sf_read_raw cannam@85: needs to be end swapped on the host CPU. cannam@85:
cannam@85:cannam@85: For instance, will return SF_TRUE on when reading WAV containing cannam@85: SF_FORMAT_PCM_16 data on a big endian machine and SF_FALSE on a little endian cannam@85: machine. cannam@85:
cannam@85:cannam@85: Parameters: cannam@85:
cannam@85: sndfile : A valid SNDFILE* pointer cannam@85: cmd : SFC_RAW_NEEDS_ENDSWAP cannam@85: data : NULL cannam@85: datasize : 0 cannam@85:cannam@85: cannam@85:
cannam@85: Retrieve the Broadcast Extension Chunk from WAV (and related) files. cannam@85:
cannam@85:cannam@85: Parameters: cannam@85:
cannam@85:cannam@85: sndfile : A valid SNDFILE* pointer cannam@85: cmd : SFC_GET_BROADCAST_INFO cannam@85: data : a pointer to an SF_BROADCAST_INFO struct cannam@85: datasize : sizeof (SF_BROADCAST_INFO) cannam@85:cannam@85:
cannam@85: The SF_BROADCAST_INFO struct is defined in <sndfile.h> as: cannam@85:
cannam@85:
cannam@85: typedef struct
cannam@85: { char description [256] ;
cannam@85: char originator [32] ;
cannam@85: char originator_reference [32] ;
cannam@85: char origination_date [10] ;
cannam@85: char origination_time [8] ;
cannam@85: unsigned int time_reference_low ;
cannam@85: unsigned int time_reference_high ;
cannam@85: short version ;
cannam@85: char umid [64] ;
cannam@85: char reserved [190] ;
cannam@85: unsigned int coding_history_size ;
cannam@85: char coding_history [256] ;
cannam@85: } SF_BROADCAST_INFO ;
cannam@85:
cannam@85:
cannam@85: cannam@85: Set the Broadcast Extension Chunk for WAV (and related) files. cannam@85:
cannam@85:cannam@85: Parameters: cannam@85:
cannam@85:cannam@85: sndfile : A valid SNDFILE* pointer cannam@85: cmd : SFC_SET_BROADCAST_INFO cannam@85: data : a pointer to an SF_BROADCAST_INFO struct cannam@85: datasize : sizeof (SF_BROADCAST_INFO) cannam@85:cannam@85: cannam@85:
cannam@85: Retrieve loop information for file including time signature, length in cannam@85: beats and original MIDI base note cannam@85:
cannam@85:cannam@85: Parameters: cannam@85:
cannam@85:cannam@85: sndfile : A valid SNDFILE* pointer cannam@85: cmd : SFC_GET_LOOP_INFO cannam@85: data : a pointer to an SF_LOOP_INFO struct cannam@85: datasize : sizeof (SF_LOOP_INFO) cannam@85:cannam@85:
cannam@85: The SF_BROADCAST_INFO struct is defined in <sndfile.h> as: cannam@85:
cannam@85:
cannam@85: typedef struct
cannam@85: { short time_sig_num ; /* any positive integer > 0 */
cannam@85: short time_sig_den ; /* any positive power of 2 > 0 */
cannam@85: int loop_mode ; /* see SF_LOOP enum */
cannam@85:
cannam@85: int num_beats ; /* this is NOT the amount of quarter notes !!!*/
cannam@85: /* a full bar of 4/4 is 4 beats */
cannam@85: /* a full bar of 7/8 is 7 beats */
cannam@85:
cannam@85: float bpm ; /* suggestion, as it can be calculated using other fields:*/
cannam@85: /* file's lenght, file's sampleRate and our time_sig_den*/
cannam@85: /* -> bpms are always the amount of _quarter notes_ per minute */
cannam@85:
cannam@85: int root_key ; /* MIDI note, or -1 for None */
cannam@85: int future [6] ;
cannam@85: } SF_LOOP_INFO ;
cannam@85:
cannam@85: cannam@85: Example: cannam@85:
cannam@85:cannam@85: SF_LOOP_INFO loop; cannam@85: sf_command (sndfile, SFC_GET_LOOP_INFO, &loop, sizeof (loop)) ; cannam@85:cannam@85:
cannam@85: Retrieve instrument information from file including MIDI base note, cannam@85: keyboard mapping and looping informations(start/stop and mode). cannam@85:
cannam@85:cannam@85: Parameters: cannam@85:
cannam@85:cannam@85: sndfile : A valid SNDFILE* pointer cannam@85: cmd : SFC_GET_INSTRUMENT cannam@85: data : a pointer to an SF_INSTRUMENT struct cannam@85: datasize : sizeof (SF_INSTRUMENT) cannam@85:cannam@85: cannam@85:
cannam@85: The SF_INSTRUMENT struct is defined in <sndfile.h> as: cannam@85:
cannam@85:
cannam@85: enum
cannam@85: { /*
cannam@85: ** The loop mode field in SF_INSTRUMENT will be one of the following.
cannam@85: */
cannam@85: SF_LOOP_NONE = 800,
cannam@85: SF_LOOP_FORWARD,
cannam@85: SF_LOOP_BACKWARD,
cannam@85: SF_LOOP_ALTERNATING
cannam@85: } ;
cannam@85:
cannam@85: typedef struct
cannam@85: { int gain ;
cannam@85: char basenote, detune ;
cannam@85: char velocity_lo, velocity_hi ;
cannam@85: char key_lo, key_hi ;
cannam@85: int loop_count ;
cannam@85:
cannam@85: struct
cannam@85: { int mode ;
cannam@85: unsigned int start ;
cannam@85: unsigned int end ;
cannam@85: unsigned int count ;
cannam@85: } loops [16] ; /* make variable in a sensible way */
cannam@85: } SF_INSTRUMENT ;
cannam@85:
cannam@85:
cannam@85: cannam@85: Example: cannam@85:
cannam@85:cannam@85: SF_INSTRUMENT inst ; cannam@85: sf_command (sndfile, SFC_GET_INSTRUMENT, &inst, sizeof (inst)) ; cannam@85:cannam@85:
cannam@85: Set the instrument information for the file. cannam@85:
cannam@85:cannam@85: Parameters: cannam@85:
cannam@85:cannam@85: sndfile : A valid SNDFILE* pointer cannam@85: cmd : SFC_GET_INSTRUMENT cannam@85: data : a pointer to an SF_INSTRUMENT struct cannam@85: datasize : sizeof (SF_INSTRUMENT) cannam@85:cannam@85:
cannam@85: Example: cannam@85:
cannam@85:cannam@85: SF_INSTRUMENT inst ; cannam@85: sf_command (sndfile, SFC_SET_INSTRUMENT, &inst, sizeof (inst)) ; cannam@85:cannam@85:
cannam@85: Set the Variable Bite Rate encoding quality. cannam@85: Currenly only implemented fro Ogg/Vorbis files. cannam@85:
cannam@85:cannam@85: Parameters: cannam@85:
cannam@85:cannam@85: sndfile : A valid SNDFILE* pointer cannam@85: cmd : SFC_SET_VBR_ENCODING_QUALITY cannam@85: data : a pointer to double specifing VBR quality cannam@85: datasize : sizeof (double) cannam@85:cannam@85:
cannam@85: Example: cannam@85:
cannam@85:cannam@85: double quality = 0.5 ; cannam@85: sf_command (sndfile, SFC_SET_VBR_ENCODING_QUALITY, &quality, sizeof (double)) ; 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: