Mercurial > hg > sv-dependency-builds
diff src/libsndfile-1.0.27/doc/command.html @ 40:1df64224f5ac
Current libsndfile source
| author | Chris Cannam |
|---|---|
| date | Tue, 18 Oct 2016 13:22:47 +0100 |
| parents | |
| children |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/src/libsndfile-1.0.27/doc/command.html Tue Oct 18 13:22:47 2016 +0100 @@ -0,0 +1,1872 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<HTML> + +<HEAD> + <TITLE> + libsndfile : the sf_command function. + </TITLE> + <META NAME="Author" CONTENT="Erik de Castro Lopo (erikd AT mega-nerd DOT com)"> + <!-- Another version at the bottom of the page. --> + <META NAME="Description" CONTENT="The libsndfile API."> + <META NAME="Keywords" CONTENT="WAV AIFF AU libsndfile sound audio dsp Linux"> + <LINK REL="stylesheet" HREF="libsndfile.css" TYPE="text/css" MEDIA="all"> + <LINK REL="stylesheet" HREF="print.css" TYPE="text/css" MEDIA="print"> +</HEAD> + +<BODY> + +<H1><B>sf_command</B></H1> +<PRE> + + int sf_command (SNDFILE *sndfile, int cmd, void *data, int datasize) ; +</PRE> +<P> + This function allows the caller to retrieve information from or change aspects of the + library behaviour. + Examples include retrieving a string containing the library version or changing the + scaling applied to floating point sample data during read and write. + Most of these operations are performed on a per-file basis. +</P> +<P> + The cmd parameter is an integer identifier which is defined in <sndfile.h>. + All of the valid command identifiers have names beginning with "SFC_". + Data is passed to and returned from the library by use of a void pointer. + The library will not read or write more than datasize bytes from the void pointer. + For some calls no data is required in which case data should be NULL and datasize + may be used for some other purpose. +</P> +<P> + The available commands are as follows: +</P> + +<CENTER> +<TABLE BORDER="0" WIDTH="90%" CELLPADDING="4"> +<TR> + <TD><A HREF="#SFC_GET_LIB_VERSION">SFC_GET_LIB_VERSION</A></TD> + <TD>Retrieve the version of the library.</TD> +</TR> +<TR> + <TD><A HREF="#SFC_GET_LOG_INFO">SFC_GET_LOG_INFO</A></TD> + <TD>Retrieve the internal per-file operation log.</TD> +</TR> +<TR> + <TD><A HREF="#SFC_CALC_SIGNAL_MAX">SFC_CALC_SIGNAL_MAX</A></TD> + <TD>Calculate the measured maximum signal value.</TD> +</TR> +<TR> + <TD><A HREF="#SFC_CALC_NORM_SIGNAL_MAX">SFC_CALC_NORM_SIGNAL_MAX</A></TD> + <TD>Calculate the measured normalised maximum signal value.</TD> +</TR> +<TR> + <TD><A HREF="#SFC_CALC_MAX_ALL_CHANNELS">SFC_CALC_MAX_ALL_CHANNELS</A></TD> + <TD>Calculate the peak value for each channel.</TD> +</TR> +<TR> + <TD><A HREF="#SFC_CALC_NORM_MAX_ALL_CHANNELS">SFC_CALC_NORM_MAX_ALL_CHANNELS</A></TD> + <TD>Calculate the normalised peak for each channel.</TD> +</TR> + +<TR> + <TD><A HREF="#SFC_GET_SIGNAL_MAX">SFC_GET_SIGNAL_MAX</A></TD> + <TD>Retrieve the peak value for the file (as stored in the file header).</TD> +</TR> +<TR> + <TD><A HREF="#SFC_GET_MAX_ALL_CHANNELS">SFC_GET_MAX_ALL_CHANNELS</A></TD> + <TD>Retrieve the peak value for each channel (as stored in the file header).</TD> +</TR> + +<TR> + <TD><A HREF="#SFC_SET_NORM_FLOAT">SFC_SET_NORM_FLOAT</A></TD> + <TD>Modify the normalisation behaviour of the floating point reading and writing functions.</TD> +</TR> +<TR> + <TD><A HREF="#SFC_SET_NORM_DOUBLE">SFC_SET_NORM_DOUBLE</A></TD> + <TD>Modify the normalisation behaviour of the double precision floating point reading and writing functions.</TD> +</TR> +<TR> + <TD><A HREF="#SFC_GET_NORM_FLOAT">SFC_GET_NORM_FLOAT</A></TD> + <TD>Retrieve the current normalisation behaviour of the floating point reading and writing functions.</TD> +</TR> +<TR> + <TD><A HREF="#SFC_GET_NORM_DOUBLE">SFC_GET_NORM_DOUBLE</A></TD> + <TD>Retrieve the current normalisation behaviour of the double precision floating point reading and writing functions.</TD> +</TR> +<TR> + <TD><A HREF="#SFC_SET_SCALE_FLOAT_INT_READ">SFC_SET_SCALE_FLOAT_INT_READ</A></TD> + <TD>Set/clear the scale factor when integer (short/int) data is read from a file + containing floating point data.</TD> +</TR> + +<TR> + <TD><A HREF="#SFC_SET_SCALE_INT_FLOAT_WRITE">SFC_SET_SCALE_INT_FLOAT_WRITE</A></TD> + <TD>Set/clear the scale factor when integer (short/int) data is written to a file + as floating point data.</TD> +</TR> + +<TR> + <TD><A HREF="#SFC_GET_SIMPLE_FORMAT_COUNT">SFC_GET_SIMPLE_FORMAT_COUNT</A></TD> + <TD>Retrieve the number of simple formats supported by libsndfile.</TD> +</TR> +<TR> + <TD><A HREF="#SFC_GET_SIMPLE_FORMAT">SFC_GET_SIMPLE_FORMAT</A></TD> + <TD>Retrieve information about a simple format.</TD> +</TR> + +<TR> + <TD><A HREF="#SFC_GET_FORMAT_INFO">SFC_GET_FORMAT_INFO</A></TD> + <TD>Retrieve information about a major or subtype format.</TD> +</TR> + +<TR> + <TD><A HREF="#SFC_GET_FORMAT_MAJOR_COUNT">SFC_GET_FORMAT_MAJOR_COUNT</A></TD> + <TD>Retrieve the number of major formats.</TD> +</TR> +<TR> + <TD><A HREF="#SFC_GET_FORMAT_MAJOR">SFC_GET_FORMAT_MAJOR</A></TD> + <TD>Retrieve information about a major format type.</TD> +</TR> +<TR> + <TD><A HREF="#SFC_GET_FORMAT_SUBTYPE_COUNT">SFC_GET_FORMAT_SUBTYPE_COUNT</A></TD> + <TD>Retrieve the number of subformats.</TD> +</TR> +<TR> + <TD><A HREF="#SFC_GET_FORMAT_SUBTYPE">SFC_GET_FORMAT_SUBTYPE</A></TD> + <TD>Retrieve information about a subformat.</TD> +</TR> + +<TR> + <TD><A HREF="#SFC_SET_ADD_PEAK_CHUNK">SFC_SET_ADD_PEAK_CHUNK</A></TD> + <TD>Switch the code for adding the PEAK chunk to WAV and AIFF files on or off.</TD> +</TR> + +<TR> + <TD><A HREF="#SFC_UPDATE_HEADER_NOW">SFC_UPDATE_HEADER_NOW</A></TD> + <TD>Used when a file is open for write, this command will update the file + header to reflect the data written so far.</TD> +</TR> +<TR> + <TD><A HREF="#SFC_SET_UPDATE_HEADER_AUTO">SFC_SET_UPDATE_HEADER_AUTO</A></TD> + <TD>Used when a file is open for write, this command will cause the file header + to be updated after each write to the file.</TD> +</TR> + +<TR> + <TD><A HREF="#SFC_FILE_TRUNCATE">SFC_FILE_TRUNCATE</A></TD> + <TD>Truncate a file open for write or for read/write.</TD> +</TR> + +<TR> + <TD><A HREF="#SFC_SET_RAW_START_OFFSET">SFC_SET_RAW_START_OFFSET</A></TD> + <TD>Change the data start offset for files opened up as SF_FORMAT_RAW.</TD> +</TR> + +<TR> + <TD><A HREF="#SFC_SET_CLIPPING">SFC_SET_CLIPPING</A></TD> + <TD>Turn on/off automatic clipping when doing floating point to integer + conversion.</TD> +</TR> + +<TR> + <TD><A HREF="#SFC_GET_CLIPPING">SFC_GET_CLIPPING</A></TD> + <TD>Retrieve current clipping setting.</TD> +</TR> + +<TR> + <TD><A HREF="#SFC_GET_EMBED_FILE_INFO">SFC_GET_EMBED_FILE_INFO</A></TD> + <TD>Retrieve information about audio files embedded inside other files.</TD> +</TR> + +<TR> + <TD><A HREF="#SFC_WAVEX_GET_AMBISONIC">SFC_GET_AMBISONIC</A></TD> + <TD>Test a WAVEX file for Ambisonic format</TD> +</TR> + +<TR> + <TD><A HREF="#SFC_WAVEX_SET_AMBISONIC">SFC_SET_AMBISONIC</A></TD> + <TD>Modify a WAVEX header for Ambisonic format</TD> +</TR> + +<TR> + <TD><A HREF="#SFC_SET_VBR_ENCODING_QUALITY">SFC_SET_VBR_ENCODING_QUALITY</A></TD> + <TD>Set the Variable Bit Rate encoding quality</TD> +</TR> + +<TR> + <TD><A HREF="#SFC_SET_COMPRESSION_LEVEL">SFC_SET_COMPRESSION_LEVEL</A></TD> + <TD>Set the compression level.</TD> +</TR> + +<TR> + <TD><A HREF="#SFC_RAW_NEEDS_ENDSWAP">SFC_RAW_NEEDS_ENDSWAP</a></td> + <TD>Determine if raw data needs endswapping</TD> +</TR> + +<TR> + <TD><A HREF="#SFC_GET_BROADCAST_INFO">SFC_GET_BROADCAST_INFO</A></TD> + <TD>Retrieve the Broadcast Chunk info</TD> +</TR> + +<TR> + <TD><A HREF="#SFC_SET_BROADCAST_INFO">SFC_SET_BROADCAST_INFO</A></TD> + <TD>Set the Broadcast Chunk info</TD> +</TR> + +<TR> + <TD><A HREF="#SFC_SET_CART_INFO">SFC_SET_CART_INFO</A></TD> + <TD>Set the Cart Chunk info</TD> +</TR> + +<TR> + <TD><A HREF="#SFC_GET_CART_INFO">SFC_GET_CART_INFO</A></TD> + <TD>Retrieve the Cart Chunk info</TD> +</TR> + +<TR> + <TD><A HREF="#SFC_GET_LOOP_INFO">SFC_GET_LOOP_INFO</A></TD> + <TD>Get loop info</TD> +</TR> + +<TR> + <TD><A HREF="#SFC_GET_INSTRUMENT">SFC_GET_INSTRUMENT</A></TD> + <TD>Get instrument info</TD> +</TR> + +<TR> + <TD><A HREF="#SFC_SET_INSTRUMENT">SFC_SET_INSTRUMENT</A></TD> + <TD>Set instrument info</TD> +</TR> + +<TR> + <TD><A HREF="#SFC_GET_CUE_COUNT">SFC_GET_CUE_COUNT</A></TD> + <TD>Get the cue marker count</TD> +</TR> + +<TR> + <TD><A HREF="#SFC_GET_CUE">SFC_GET_CUE</A></TD> + <TD>Get cue marker info</TD> +</TR> + +<TR> + <TD><A HREF="#SFC_SET_CUE">SFC_SET_CUE</A></TD> + <TD>Set cue marker info</TD> +</TR> + +<TR> + <TD><A HREF="#SFC_RF64_AUTO_DOWNGRADE">SFC_RF64_AUTO_DOWNGRADE</A></TD> + <TD>Enable auto downgrade from RF64 to WAV</TD> +</TR> + +<!-- +<TR> + <TD><A HREF="#add-dither">add dither</A></TD> + <TD>Add dither to output on write.</TD> +</TR> +--> +</TABLE> +</CENTER> + +<BR><BR> + +<HR> + +<!-- ========================================================================= --> +<A NAME="SFC_GET_LIB_VERSION"></A> +<H2><BR><B>SFC_GET_LIB_VERSION</B></H2> +<P> +Retrieve the version of the library as a string. +</P> +<P> +Parameters: +<PRE> + sndfile : Not used + cmd : SFC_GET_LIB_VERSION + data : A pointer to a char buffer + datasize : The size of the buffer +</PRE> +<P> +Example: +</P> +<PRE> + char buffer [128] ; + sf_command (NULL, SFC_GET_LIB_VERSION, buffer, sizeof (buffer)) ; +</PRE> + +<DL> +<DT>Return value:</DT> + <DD><DD>This call will return the length of the retrieved version string. +</DL> +<DL> +<DT>Notes:</DT> +<DD> +The string returned in the buffer passed to this function will not overflow +the buffer and will always be null terminated . +</DL> + +<!-- ========================================================================= --> +<A NAME="SFC_GET_LOG_INFO"></A> +<H2><BR><B>SFC_GET_LOG_INFO</B></H2> +<P> +Retrieve the log buffer generated when opening a file as a string. This log +buffer can often contain a good reason for why libsndfile failed to open a +particular file. +</P> +<P> +Parameters: +<PRE> + sndfile : A valid SNDFILE* pointer + cmd : SFC_GET_LOG_INFO + data : A pointer to a char buffer + datasize : The size of the buffer +</PRE> +<P> +Example: +</P> +<PRE> + char buffer [2048] ; + sf_command (sndfile, SFC_GET_LOG_INFO, buffer, sizeof (buffer)) ; +</PRE> + +<DL> +<DT>Return value:</DT> + <DD><DD>This call will return the length of the retrieved version string. +</DL> +<DL> +<DT>Notes:</DT> +<DD> +The string returned in the buffer passed to this function will not overflow +the buffer and will always be null terminated . +</DL> + +<!-- ========================================================================= --> +<A NAME="SFC_CALC_SIGNAL_MAX"></A> +<H2><BR><B>SFC_CALC_SIGNAL_MAX</B></H2> +<P> +Retrieve the measured maximum signal value. This involves reading through +the whole file which can be slow on large files. +</P> +<P> +Parameters: +<PRE> + sndfile : A valid SNDFILE* pointer + cmd : SFC_CALC_SIGNAL_MAX + data : A pointer to a double + datasize : sizeof (double) +</PRE> +<P> +Example: +</P> +<PRE> + double max_val ; + sf_command (sndfile, SFC_CALC_SIGNAL_MAX, &max_val, sizeof (max_val)) ; +</PRE> + +<DL> +<DT>Return value:</DT> + <DD><DD>Zero on success, non-zero otherwise. +</DL> + +<!-- ========================================================================= --> +<A NAME="SFC_CALC_NORM_SIGNAL_MAX"></A> +<H2><BR><B>SFC_CALC_NORM_SIGNAL_MAX</B></H2> +<P> +Retrieve the measured normalised maximum signal value. This involves reading +through the whole file which can be slow on large files. +</P> +<P> +Parameters: +<PRE> + sndfile : A valid SNDFILE* pointer + cmd : SFC_CALC_NORM_SIGNAL_MAX + data : A pointer to a double + datasize : sizeof (double) +</PRE> +<P> +Example: +</P> +<PRE> + double max_val ; + sf_command (sndfile, SFC_CALC_NORM_SIGNAL_MAX, &max_val, sizeof (max_val)) ; +</PRE> + +<DL> +<DT>Return value:</DT> + <DD><DD>Zero on success, non-zero otherwise. +</DL> + +<!-- ========================================================================= --> +<A NAME="SFC_CALC_MAX_ALL_CHANNELS"></A> +<H2><BR><B>SFC_CALC_MAX_ALL_CHANNELS</B></H2> +<P> +Calculate the peak value (ie a single number) for each channel. +This involves reading through the whole file which can be slow on large files. +</P> +<P> +Parameters: +<PRE> + sndfile : A valid SNDFILE* pointer + cmd : SFC_CALC_MAX_ALL_CHANNELS + data : A pointer to a double + datasize : sizeof (double) * number_of_channels +</PRE> +<P> +Example: +</P> +<PRE> + double peaks [number_of_channels] ; + sf_command (sndfile, SFC_CALC_MAX_ALL_CHANNELS, peaks, sizeof (peaks)) ; +</PRE> +<DL> +<DT>Return value:</DT> + <DD>Zero if peaks have been calculated successfully and non-zero otherwise. +</DL> + + +<!-- ========================================================================= --> +<A NAME="SFC_CALC_NORM_MAX_ALL_CHANNELS"></A> +<H2><BR><B>SFC_CALC_NORM_MAX_ALL_CHANNELS</B></H2> +<P> +Calculate the normalised peak for each channel. +This involves reading through the whole file which can be slow on large files. +</P> +<P> +Parameters: +<PRE> + sndfile : A valid SNDFILE* pointer + cmd : SFC_CALC_NORM_MAX_ALL_CHANNELS + data : A pointer to a double + datasize : sizeof (double) * number_of_channels +</PRE> +<P> +Example: +</P> +<PRE> + double peaks [number_of_channels] ; + sf_command (sndfile, SFC_CALC_NORM_MAX_ALL_CHANNELS, peaks, sizeof (peaks)) ; +</PRE> +<DL> +<DT>Return value:</DT> + <DD>Zero if peaks have been calculated successfully and non-zero otherwise. +</DL> + + + + +<!-- ========================================================================= --> +<A NAME="SFC_GET_SIGNAL_MAX"></A> +<H2><BR><B>SFC_GET_SIGNAL_MAX</B></H2> +<P> +Retrieve the peak value for the file as stored in the file header. +</P> +<P> +Parameters: +<PRE> + sndfile : A valid SNDFILE* pointer + cmd : SFC_GET_SIGNAL_MAX + data : A pointer to a double + datasize : sizeof (double) +</PRE> +<P> +Example: +</P> +<PRE> + double max_peak ; + sf_command (sndfile, SFC_GET_SIGNAL_MAX, &max_peak, sizeof (max_peak)) ; +</PRE> +<DL> +<DT>Return value:</DT> + <DD>SF_TRUE if the file header contained the peak value. SF_FALSE otherwise. +</DL> + +<!-- ========================================================================= --> +<A NAME="SFC_GET_MAX_ALL_CHANNELS"></A> +<H2><BR><B>SFC_GET_MAX_ALL_CHANNELS</B></H2> +<P> +Retrieve the peak value for the file as stored in the file header. +</P> +<P> +Parameters: +<PRE> + sndfile : A valid SNDFILE* pointer + cmd : SFC_GET_SIGNAL_MAX + data : A pointer to an array of doubles + datasize : sizeof (double) * number_of_channels +</PRE> +<P> +Example: +</P> +<PRE> + double peaks [number_of_channels] ; + sf_command (sndfile, SFC_GET_MAX_ALL_CHANNELS, peaks, sizeof (peaks)) ; +</PRE> +<DL> +<DT>Return value:</DT> + <DD>SF_TRUE if the file header contains per channel peak values for the file. + SF_FALSE otherwise. +</DL> + + +<!-- ========================================================================= --> +<A NAME="SFC_SET_NORM_FLOAT"></A> +<H2><BR><B>SFC_SET_NORM_FLOAT</B></H2> +<P> +This command only affects data read from or written to using the floating point functions: +</P> +<PRE> + size_t <A HREF="api.html#read">sf_read_float</A> (SNDFILE *sndfile, float *ptr, size_t items) ; + size_t <A HREF="api.html#readf">sf_readf_float</A> (SNDFILE *sndfile, float *ptr, size_t frames) ; + + size_t <A HREF="api.html#write">sf_write_float</A> (SNDFILE *sndfile, float *ptr, size_t items) ; + size_t <A HREF="api.html#writef">sf_writef_float</A> (SNDFILE *sndfile, float *ptr, size_t frames) ; +</PRE> +<P> +Parameters: +</P> +<PRE> + sndfile : A valid SNDFILE* pointer + cmd : SFC_SET_NORM_FLOAT + data : NULL + datasize : SF_TRUE or SF_FALSE +</PRE> +<P> +For read operations setting normalisation to SF_TRUE means that the data from all +subsequent reads will be be normalised to the range [-1.0, 1.0]. +</P> +<P> +For write operations, setting normalisation to SF_TRUE means than all data supplied +to the float write functions should be in the range [-1.0, 1.0] and will be scaled +for the file format as necessary. +</P> +<P> +For both cases, setting normalisation to SF_FALSE means that no scaling will take place. +</P> +<P> +Example: +</P> +<PRE> + sf_command (sndfile, SFC_SET_NORM_FLOAT, NULL, SF_TRUE) ; + + sf_command (sndfile, SFC_SET_NORM_FLOAT, NULL, SF_FALSE) ; +</PRE> +<DL> +<DT>Return value: </DT> + <DD>Returns the previous float normalisation mode. +</DL> + +<!-- ========================================================================= --> +<A NAME="SFC_SET_NORM_DOUBLE"></A> +<H2><BR><B>SFC_SET_NORM_DOUBLE</B></H2> +<P> +This command only affects data read from or written to using the double precision +floating point functions: +</P> +<PRE> + size_t <A HREF="api.html#read">sf_read_double</A> (SNDFILE *sndfile, double *ptr, size_t items) ; + size_t <A HREF="api.html#readf">sf_readf_double</A> (SNDFILE *sndfile, double *ptr, size_t frames) ; + + size_t <A HREF="api.html#write">sf_write_double</A> (SNDFILE *sndfile, double *ptr, size_t items) ; + size_t <A HREF="api.html#writef">sf_writef_double</A> (SNDFILE *sndfile, double *ptr, size_t frames) ; +</PRE> +<P> +Parameters: +</P> +<PRE> + sndfile : A valid SNDFILE* pointer + cmd : SFC_SET_NORM_DOUBLE + data : NULL + datasize : SF_TRUE or SF_FALSE +</PRE> +<P> +For read operations setting normalisation to SF_TRUE means that the data +from all subsequent reads will be be normalised to the range [-1.0, 1.0]. +</P> +<P> +For write operations, setting normalisation to SF_TRUE means than all data supplied +to the double write functions should be in the range [-1.0, 1.0] and will be scaled +for the file format as necessary. +</P> +<P> +For both cases, setting normalisation to SF_FALSE means that no scaling will take place. +</P> +<P> +Example: +</P> +<PRE> + sf_command (sndfile, SFC_SET_NORM_DOUBLE, NULL, SF_TRUE) ; + + sf_command (sndfile, SFC_SET_NORM_DOUBLE, NULL, SF_FALSE) ; +</PRE> +<DL> +<DT>Return value: </DT> + <DD>Returns the previous double normalisation mode. +</DL> + +<!-- ========================================================================= --> +<A NAME="SFC_GET_NORM_FLOAT"></A> +<H2><BR><B>SFC_GET_NORM_FLOAT</B></H2> +<P> +Retrieve the current float normalisation mode. +</P> +<P> +Parameters: +</P> +<PRE> + sndfile : A valid SNDFILE* pointer + cmd : SFC_GET_NORM_FLOAT + data : NULL + datasize : anything +</PRE> +<P> +Example: +</P> +<PRE> + normalisation = sf_command (sndfile, SFC_GET_NORM_FLOAT, NULL, 0) ; +</PRE> +<DL> +<DT>Return value: </DT> + <DD>Returns TRUE if normalisation is on and FALSE otherwise. +</DL> + +<!-- ========================================================================= --> +<A NAME="SFC_GET_NORM_DOUBLE"></A> +<H2><BR><B>SFC_GET_NORM_DOUBLE</B></H2> +<P> +Retrieve the current float normalisation mode. +</P> +<P> +Parameters: +</P> +<PRE> + sndfile : A valid SNDFILE* pointer + cmd : SFC_GET_NORM_DOUBLE + data : NULL + datasize : anything +</PRE> +<P> +Example: +</P> +<PRE> + normalisation = sf_command (sndfile, SFC_GET_NORM_DOUBLE, NULL, 0) ; +</PRE> +<DL> +<DT>Return value: </DT> + <DD>Returns TRUE if normalisation is on and FALSE otherwise. +</DL> + + +<!-- ========================================================================= --> +<A NAME="SFC_SET_SCALE_FLOAT_INT_READ"></A> +<H2><BR><B>SFC_SET_SCALE_FLOAT_INT_READ</B></H2> +<P> +Set/clear the scale factor when integer (short/int) data is read from a file +containing floating point data. +</P> +<P> +Parameters: +</P> +<PRE> + sndfile : A valid SNDFILE* pointer + cmd : SFC_SET_SCALE_FLOAT_INT_READ + data : NULL + datasize : TRUE or FALSE +</PRE> +<P> +Example: +</P> +<PRE> + sf_command (sndfile, SFC_SET_SCALE_FLOAT_INT_READ, NULL, SF_TRUE) ; +</PRE> +<DL> +<DT>Return value: </DT> + <DD>Returns the previous SFC_SET_SCALE_FLOAT_INT_READ setting for this file. +</DL> + + +<!-- ========================================================================= --> +<A NAME="SFC_SET_SCALE_INT_FLOAT_WRITE"></A> +<H2><BR><B>SFC_SET_SCALE_INT_FLOAT_WRITE</B></H2> +<P> +Set/clear the scale factor when integer (short/int) data is written to a file +as floating point data. +</P> +<P> +Parameters: +</P> +<PRE> + sndfile : A valid SNDFILE* pointer + cmd : SFC_SET_SCALE_FLOAT_INT_READ + data : NULL + datasize : TRUE or FALSE +</PRE> +<P> +Example: +</P> +<PRE> + sf_command (sndfile, SFC_SET_SCALE_INT_FLOAT_WRITE, NULL, SF_TRUE) ; +</PRE> +<DL> +<DT>Return value: </DT> + <DD>Returns the previous SFC_SET_SCALE_INT_FLOAT_WRITE setting for this file. +</DL> + +<!-- ========================================================================= --> +<A NAME="SFC_GET_SIMPLE_FORMAT_COUNT"></A> +<H2><BR><B>SFC_GET_SIMPLE_FORMAT_COUNT</B></H2> +<P> +Retrieve the number of simple formats supported by libsndfile. +</P> +<P> +Parameters: +</P> +<PRE> + sndfile : Not used. + cmd : SFC_GET_SIMPLE_FORMAT_COUNT + data : a pointer to an int + datasize : sizeof (int) +</PRE> +<P> +Example: +</P> +<PRE> + int count ; + sf_command (sndfile, SFC_GET_SIMPLE_FORMAT_COUNT, &count, sizeof (int)) ; +</PRE> +<DL> +<DT>Return value: </DT> + <DD>0 +</DL> + +<!-- ========================================================================= --> +<A NAME="SFC_GET_SIMPLE_FORMAT"></A> +<H2><BR><B>SFC_GET_SIMPLE_FORMAT</B></H2> +<P> +Retrieve information about a simple format. +</P> +<P> +Parameters: +</P> +<PRE> + sndfile : Not used. + cmd : SFC_GET_SIMPLE_FORMAT + data : a pointer to an SF_FORMAT_INFO struct + datasize : sizeof (SF_FORMAT_INFO) +</PRE> +<P> +The SF_FORMAT_INFO struct is defined in <sndfile.h> as: +</P> +<PRE> + typedef struct + { int format ; + const char *name ; + const char *extension ; + } SF_FORMAT_INFO ; +</PRE> +<P> +When sf_command() is called with SF_GET_SIMPLE_FORMAT, the value of the format +field should be the format number (ie 0 <= format <= count value obtained using +SF_GET_SIMPLE_FORMAT_COUNT). +</P> +<P> +Example: +</P> +<PRE> + SF_FORMAT_INFO format_info ; + int k, count ; + + sf_command (sndfile, SFC_GET_SIMPLE_FORMAT_COUNT, &count, sizeof (int)) ; + + for (k = 0 ; k < count ; k++) + { format_info.format = k ; + sf_command (sndfile, SFC_GET_SIMPLE_FORMAT, &format_info, sizeof (format_info)) ; + printf ("%08x %s %s\n", format_info.format, format_info.name, format_info.extension) ; + } ; +</PRE> +<DL> +<DT>Return value: </DT> + <DD>0 on success and non-zero otherwise. + <DD>The value of the format field of the SF_FORMAT_INFO struct will be a value which + can be placed in the format field of an SF_INFO struct when a file is to be opened + for write. + <DD>The name field will contain a char* pointer to the name of the string, eg. "WAV (Microsoft 16 bit PCM)". + <DD>The extension field will contain the most commonly used file extension for that file type. +</DL> + +<!-- ========================================================================= --> +<A NAME="SFC_GET_FORMAT_INFO"></A> +<H2><BR><B>SFC_GET_FORMAT_INFO</B></H2> +<P> +Retrieve information about a major or subtype format. +</P> +<P> +Parameters: +</P> +<PRE> + sndfile : Not used. + cmd : SFC_GET_FORMAT_INFO + data : a pointer to an SF_FORMAT_INFO struct + datasize : sizeof (SF_FORMAT_INFO) +</PRE> +<P> +The SF_FORMAT_INFO struct is defined in <sndfile.h> as: +</P> +<PRE> + typedef struct + { int format ; + const char *name ; + const char *extension ; + } SF_FORMAT_INFO ; +</PRE> +<P> +When sf_command() is called with SF_GET_FORMAT_INFO, the format field is +examined and if (format & SF_FORMAT_TYPEMASK) is a valid format then the struct +is filled in with information about the given major type. +If (format & SF_FORMAT_TYPEMASK) is FALSE and (format & SF_FORMAT_SUBMASK) is a +valid subtype format then the struct is filled in with information about the given +subtype. +</P> +<P> +Example: +</P> +<PRE> + SF_FORMAT_INFO format_info ; + + format_info.format = SF_FORMAT_WAV ; + sf_command (sndfile, SFC_GET_FORMAT_INFO, &format_info, sizeof (format_info)) ; + printf ("%08x %s %s\n", format_info.format, format_info.name, format_info.extension) ; + + format_info.format = SF_FORMAT_ULAW ; + sf_command (sndfile, SFC_GET_FORMAT_INFO, &format_info, sizeof (format_info)) ; + printf ("%08x %s\n", format_info.format, format_info.name) ; +</PRE> +<DL> +<DT>Return value: </DT> + <DD>0 on success and non-zero otherwise. +</DL> +<!-- ========================================================================= --> +<A NAME="SFC_GET_FORMAT_MAJOR_COUNT"></A> +<H2><BR><B>SFC_GET_FORMAT_MAJOR_COUNT</B></H2> +<P> +Retrieve the number of major formats. +</P> +<P> +Parameters: +</P> +<PRE> + sndfile : Not used. + cmd : SFC_GET_FORMAT_MAJOR_COUNT + data : a pointer to an int + datasize : sizeof (int) +</PRE> +<P> +Example: +</P> +<PRE> + int count ; + sf_command (sndfile, SFC_GET_FORMAT_MAJOR_COUNT, &count, sizeof (int)) ; +</PRE> +<DL> +<DT>Return value: </DT> + <DD>0 +</DL> + +<!-- ========================================================================= --> +<A NAME="SFC_GET_FORMAT_MAJOR"></A> +<H2><BR><B>SFC_GET_FORMAT_MAJOR</B></H2> +<P> +Retrieve information about a major format type. +</P> +<P> +Parameters: +</P> +<PRE> + sndfile : Not used. + cmd : SFC_GET_FORMAT_MAJOR + data : a pointer to an SF_FORMAT_INFO struct + datasize : sizeof (SF_FORMAT_INFO) +</PRE> +<P> +Example: +</P> +<PRE> + SF_FORMAT_INFO format_info ; + int k, count ; + + sf_command (sndfile, SFC_GET_FORMAT_MAJOR_COUNT, &count, sizeof (int)) ; + + for (k = 0 ; k < count ; k++) + { format_info.format = k ; + sf_command (sndfile, SFC_GET_FORMAT_MAJOR, &format_info, sizeof (format_info)) ; + printf ("%08x %s %s\n", format_info.format, format_info.name, format_info.extension) ; + } ; +</PRE> +<P> +For a more comprehensive example, see the program list_formats.c in the examples/ +directory of the libsndfile source code distribution. +</P> +<DL> +<DT>Return value: </DT> + <DD>0 on success and non-zero otherwise. + <DD>The value of the format field will be one of the major format identifiers such as + SF_FORMAT_WAV or SF_FORMAT_AIFF. + <DD>The name field will contain a char* pointer to the name of the string, eg. "WAV (Microsoft)". + <DD>The extension field will contain the most commonly used file extension for that file type. +</DL> + +<!-- ========================================================================= --> +<A NAME="SFC_GET_FORMAT_SUBTYPE_COUNT"></A> +<H2><BR><B>SFC_GET_FORMAT_SUBTYPE_COUNT</B></H2> +<P> +Retrieve the number of subformats. +</P> +<P> +Parameters: +</P> +<PRE> + sndfile : Not used. + cmd : SFC_GET_FORMAT_SUBTYPE_COUNT + data : a pointer to an int + datasize : sizeof (int) +</PRE> +<P> +Example: +</P> +<PRE> + int count ; + sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE_COUNT, &count, sizeof (int)) ; +</PRE> +<DL> +<DT>Return value: </DT> + <DD>0 +</DL> + +<!-- ========================================================================= --> +<A NAME="SFC_GET_FORMAT_SUBTYPE"></A> +<H2><BR><B>SFC_GET_FORMAT_SUBTYPE</B></H2> +<P> +Enumerate the subtypes (this function does not translate a subtype into +a string describing that subtype). +A typical use case might be retrieving a string description of all subtypes +so that a dialog box can be filled in. +</P> +<P> + +</P> +<P> +Parameters: +</P> +<PRE> + sndfile : Not used. + cmd : SFC_GET_FORMAT_SUBTYPE + data : a pointer to an SF_FORMAT_INFO struct + datasize : sizeof (SF_FORMAT_INFO) +</PRE> +<P> +Example 1: Retrieve all sybtypes supported by the WAV format. +</P> +<PRE> + SF_FORMAT_INFO format_info ; + int k, count ; + + sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE_COUNT, &count, sizeof (int)) ; + + for (k = 0 ; k < count ; k++) + { format_info.format = k ; + sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE, &format_info, sizeof (format_info)) ; + if (! sf_format_check (format_info.format | SF_FORMAT_WAV)) + continue ; + printf ("%08x %s\n", format_info.format, format_info.name) ; + } ; +</PRE> +<P> +Example 2: Print a string describing the SF_FORMAT_PCM_16 subtype. +</P> +<PRE> + SF_FORMAT_INFO format_info ; + int k, count ; + + sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE_COUNT, &count, sizeof (int)) ; + + for (k = 0 ; k < count ; k++) + { format_info.format = k ; + sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE, &format_info, sizeof (format_info)) ; + if (format_info.format == SF_FORMAT_PCM_16) + { printf ("%08x %s\n", format_info.format, format_info.name) ; + break ; + } ; + } ; +</PRE> +<P> +For a more comprehensive example, see the program list_formats.c in the examples/ +directory of the libsndfile source code distribution. +</P> +<DL> +<DT>Return value: </DT> + <DD>0 on success and non-zero otherwise. + <DD>The value of the format field will be one of the major format identifiers such as + SF_FORMAT_WAV or SF_FORMAT_AIFF. + <DD>The name field will contain a char* pointer to the name of the string; for instance + "WAV (Microsoft)" or "AIFF (Apple/SGI)". + <DD>The extension field will be a NULL pointer. +</DL> + +<!-- ========================================================================= --> +<A NAME="SFC_SET_ADD_PEAK_CHUNK"></A> +<H2><BR><B>SFC_SET_ADD_PEAK_CHUNK</B></H2> +<P> +By default, WAV and AIFF files which contain floating point data (subtype SF_FORMAT_FLOAT +or SF_FORMAT_DOUBLE) have a PEAK chunk. +By using this command, the addition of a PEAK chunk can be turned on or off. +</P> +<P> +Note : This call must be made before any data is written to the file. +</P> +<P> +Parameters: +<PRE> + sndfile : A valid SNDFILE* pointer + cmd : SFC_SET_ADD_PEAK_CHUNK + data : Not used (should be NULL) + datasize : TRUE or FALSE. +</PRE> +<P> +Example: +</P> +<PRE> + /* Turn on the PEAK chunk. */ + sf_command (sndfile, SFC_SET_ADD_PEAK_CHUNK, NULL, SF_TRUE) ; + + /* Turn off the PEAK chunk. */ + sf_command (sndfile, SFC_SET_ADD_PEAK_CHUNK, NULL, SF_FALSE) ; +</PRE> +<DL> +<DT>Return value:</DT> +<DD>Returns SF_TRUE if the peak chunk will be written after this call. +<DD>Returns SF_FALSE if the peak chunk will not be written after this call. +</DL> + +<!-- ========================================================================= --> +<A NAME="SFC_UPDATE_HEADER_NOW"></A> +<H2><BR><B>SFC_UPDATE_HEADER_NOW</B></H2> +<P> +The header of an audio file is normally written by libsndfile when the file is +closed using <B>sf_close()</B>. +</P> +<P> +There are however situations where large files are being generated and it would +be nice to have valid data in the header before the file is complete. +Using this command will update the file header to reflect the amount of data written +to the file so far. +Other programs opening the file for read (before any more data is written) will +then read a valid sound file header. +</P> +<P> +Parameters: +<PRE> + sndfile : A valid SNDFILE* pointer + cmd : SFC_UPDATE_HEADER_NOW + data : Not used (should be NULL) + datasize : Not used. +</PRE> +<P> +Example: +</P> +<PRE> + /* Update the header now. */ + sf_command (sndfile, SFC_UPDATE_HEADER_NOW, NULL, 0) ; +</PRE> +<DL> +<DT>Return value:</DT> +<DD>0 +</DL> + +<!-- ========================================================================= --> +<A NAME="SFC_SET_UPDATE_HEADER_AUTO"></A> +<H2><BR><B>SFC_SET_UPDATE_HEADER_AUTO</B></H2> +<P> +Similar to SFC_UPDATE_HEADER_NOW but updates the header at the end of every call +to the <B>sf_write*</B> functions. +</P> +<P> +Parameters: +<PRE> + sndfile : A valid SNDFILE* pointer + cmd : SFC_UPDATE_HEADER_NOW + data : Not used (should be NULL) + datasize : SF_TRUE or SF_FALSE +</PRE> +<P> +Example: +</P> +<PRE> + /* Turn on auto header update. */ + sf_command (sndfile, SFC_SET_UPDATE_HEADER_AUTO, NULL, SF_TRUE) ; + + /* Turn off auto header update. */ + sf_command (sndfile, SFC_SET_UPDATE_HEADER_AUTO, NULL, SF_FALSE) ; +</PRE> +<DL> +<DT>Return value:</DT> +<DD>TRUE if auto update header is now on; FALSE otherwise. +</DL> + +<!-- ========================================================================= --> +<A NAME="SFC_FILE_TRUNCATE"></A> +<H2><BR><B>SFC_FILE_TRUNCATE</B></H2> +<P> +Truncate a file that was opened for write or read/write. +</P> +<P> +Parameters: +<PRE> + sndfile : A valid SNDFILE* pointer + cmd : SFC_FILE_TRUNCATE + data : A pointer to an sf_count_t. + datasize : sizeof (sf_count_t) +</PRE> + +<P> +Truncate the file to the number of frames specified by the sf_count_t pointed +to by data. +After this command, both the read and the write pointer will be +at the new end of the file. +This command will fail (returning non-zero) if the requested truncate position +is beyond the end of the file. +</P> +<P> +Example: +</P> +<PRE> + /* Truncate the file to a length of 20 frames. */ + sf_count_t frames = 20 ; + sf_command (sndfile, SFC_FILE_TRUNCATE, &frames, sizeof (frames)) ; +</PRE> +<DL> +<DT>Return value:</DT> + <DD>Zero on sucess, non-zero otherwise. +</DL> + +<!-- ========================================================================= --> +<A NAME="SFC_SET_RAW_START_OFFSET"></A> +<H2><BR><B>SFC_SET_RAW_START_OFFSET</B></H2> +<P> +Change the data start offset for files opened up as SF_FORMAT_RAW. +</P> +<P> +Parameters: +<PRE> + sndfile : A valid SNDFILE* pointer + cmd : SFC_SET_RAW_START_OFFSET + data : A pointer to an sf_count_t. + datasize : sizeof (sf_count_t) +</PRE> + +<P> +For a file opened as format SF_FORMAT_RAW, set the data offset to the value +given by data. +</P> +<P> +Example: +</P> +<PRE> + /* Reset the data offset to 5 bytes from the start of the file. */ + sf_count_t offset = 5 ; + sf_command (sndfile, SFC_SET_RAW_START_OFFSET, &offset, sizeof (offset)) ; +</PRE> +<DL> +<DT>Return value:</DT> + <DD>Zero on success, non-zero otherwise. +</DL> + +<!-- ========================================================================= --> +<A NAME="SFC_SET_CLIPPING"></A> +<H2><BR><B>SFC_SET_CLIPPING</B></H2> +<P> +Turn on/off automatic clipping when doing floating point to integer conversion. +</P> +<P> +Parameters: +<PRE> + sndfile : A valid SNDFILE* pointer + cmd : SFC_SET_CLIPPING + data : NULL + datasize : SF_TRUE or SF_FALSE. +</PRE> + +<P> +Turn on (datasize == SF_TRUE) or off (datasize == SF_FALSE) clipping. +</P> +<P> +Example: +</P> +<PRE> + sf_command (sndfile, SFC_SET_CLIPPING, NULL, SF_TRUE) ; +</PRE> +<DL> +<DT>Return value:</DT> + <DD>Clipping mode (SF_TRUE or SF_FALSE). +</DL> + + +<!-- ========================================================================= --> +<A NAME="SFC_GET_CLIPPING"></A> +<H2><BR><B>SFC_GET_CLIPPING</B></H2> +<P> +Turn on/off automatic clipping when doing floating point to integer conversion. +</P> +<P> +Parameters: +<PRE> + sndfile : A valid SNDFILE* pointer + cmd : SFC_GET_CLIPPING + data : NULL + datasize : 0 +</PRE> + +<P> +Retrieve the current cliiping setting. +</P> +<P> +Example: +</P> +<PRE> + sf_command (sndfile, SFC_GET_CLIPPING, NULL, 0) ; +</PRE> +<DL> +<DT>Return value:</DT> + <DD>Clipping mode (SF_TRUE or SF_FALSE). +</DL> + +<!-- ========================================================================= --> +<A NAME="SFC_GET_EMBED_FILE_INFO"></A> +<H2><BR><B>SFC_GET_EMBED_FILE_INFO</B></H2> +<P> +Get the file offset and file length of a file enbedded within another +larger file. +</P> +<P> +Parameters: +<PRE> + sndfile : A valid SNDFILE* pointer + cmd : SFC_GET_CLIPPING + data : a pointer to an SF_EMBED_FILE_INFO struct + datasize : sizeof (SF_EMBED_FILE_INFO) +</PRE> +<P> +The SF_EMBED_FILE_INFO struct is defined in <sndfile.h> as: +</P> +<PRE> + typedef struct + { sf_count_t offset ; + sf_count_t length ; + } SF_EMBED_FILE_INFO ; +</PRE> +<DL> +<DT>Return value: </DT> + <DD>0 on success and non-zero otherwise. + <DD>The value of the offset field of the SF_EMBED_FILE_INFO struct will be + the offsets in bytes from the start of the outer file to the start of + the audio file. + <DD>The value of the offset field of the SF_EMBED_FILE_INFO struct will be + the length in bytes of the embedded file. +</DL> + + + +<!-- ========================================================================= --> +<A NAME="SFC_WAVEX_GET_AMBISONIC"></A> +<H2><BR><B>SFC_WAVEX_GET_AMBISONIC</B></H2> +<P> +Test if the current file has the GUID of a WAVEX file for any of the Ambisonic +formats. +</P> +<P> +Parameters: +<PRE> + sndfile : A valid SNDFILE* pointer + cmd : SFC_WAVEX_GET_AMBISONIC + data : NULL + datasize : 0 +</PRE> +<P> + The Ambisonic WAVEX formats are defined here : + <A HREF="http://dream.cs.bath.ac.uk/researchdev/wave-ex/bformat.html"> + http://dream.cs.bath.ac.uk/researchdev/wave-ex/bformat.html</A>. +</P> +<DL> +<DT>Return value: </DT> + <DD>SF_AMBISONIC_NONE or SF_AMBISONIC_B_FORMAT or zero if the file format + does not support ambisonic formats. +</DL> + +<!-- ========================================================================= --> +<A NAME="SFC_WAVEX_SET_AMBISONIC"></A> +<H2><BR><B>SFC_WAVEX_SET_AMBISONIC</B></H2> +<P> +Set the GUID of a new WAVEX file to indicate an Ambisonics format. +</P> +<P> +Parameters: +<PRE> + sndfile : A valid SNDFILE* pointer + cmd : SFC_WAVEX_SET_AMBISONIC + data : NULL + datasize : SF_AMBISONIC_NONE or SF_AMBISONIC_B_FORMAT +</PRE> +<P> +Turn on (SF_AMBISONIC_B_FORMAT) or off (SF_AMBISONIC_NONE) encoding. +This command is currently only supported for files with SF_FORMAT_WAVEX format. +</P> +<P> + The Ambisonic WAVEX formats are defined here : + <A HREF="http://dream.cs.bath.ac.uk/researchdev/wave-ex/bformat.html"> + http://dream.cs.bath.ac.uk/researchdev/wave-ex/bformat.html</A>. +</P> +<DL> +<DT>Return value: </DT> + <DD>Return the ambisonic value that has just been set or zero if the file + format does not support ambisonic encoding. +</DL> + +<!-- ========================================================================= --> +<A NAME="SFC_SET_VBR_ENCODING_QUALITY"></A> +<H2><BR><B>SFC_SET_VBR_ENCODING_QUALITY</B></H2> +<P> +Set the Variable Bit Rate encoding quality. +The encoding quality value should be between 0.0 (lowest quality) and 1.0 +(highest quality). +Currenly this command is only implemented for FLAC and Ogg/Vorbis files. +It has no effect on un-compressed file formats. +</P> +<P> +Parameters: +<PRE> + sndfile : A valid SNDFILE* pointer + cmd : SFC_SET_VBR_ENCODING_QUALITY + data : A pointer to a double value + datasize : sizeof (double) +</PRE> +<P> +The command must be sent before any audio data is written to the file. +</P> +<P> +</P> +<DL> +<DT>Return value:</DT> + <dd>SF_TRUE if VBR encoding quality was set. + SF_FALSE otherwise. +</DL> + +<!-- ========================================================================= --> +<A NAME="SFC_SET_COMPRESSION_LEVEL"></A> +<H2><BR><B>SFC_SET_COMPRESSION_LEVEL</B></H2> +<P> +Set the compression level. +The compression level should be between 0.0 (minimum compression level) and 1.0 +(highest compression level). +Currenly this command is only implemented for FLAC and Ogg/Vorbis files. +It has no effect on un-compressed file formats. +</P> +<P> +Parameters: +<PRE> + sndfile : A valid SNDFILE* pointer + cmd : SFC_SET_COMPRESSION_LEVEL + data : A pointer to a double value + datasize : sizeof (double) +</PRE> +<P> +The command must be sent before any audio data is written to the file. +</P> +<P> +</P> +<DL> +<DT>Return value:</DT> + <dd>SF_TRUE if compression level was set. + SF_FALSE otherwise. +</DL> + +<!-- ========================================================================= --> +<A NAME="SFC_RAW_NEEDS_ENDSWAP"></A> +<H2><BR><B>SFC_RAW_NEEDS_ENDSWAP</B></H2> +<P> +Determine if raw data read using + <a href="api.html#raw"> + sf_read_raw</a> +needs to be end swapped on the host CPU. +</P> +<P> +For instance, will return SF_TRUE on when reading WAV containing +SF_FORMAT_PCM_16 data on a big endian machine and SF_FALSE on a little endian +machine. +</P> +<P> +Parameters: +<PRE> + sndfile : A valid SNDFILE* pointer + cmd : SFC_RAW_NEEDS_ENDSWAP + data : NULL + datasize : 0 +</PRE> + +<DL> +<DT>Return value: </DT> + <DD>SF_TRUE or SF_FALSE +</DL> + + +<!-- ========================================================================= --> +<A NAME="SFC_GET_BROADCAST_INFO"></A> +<H2><BR><B>SFC_GET_BROADCAST_INFO</B></H2> +<P> +Retrieve the Broadcast Extension Chunk from WAV (and related) files. +</P> +<p> +Parameters: +</p> +<PRE> + sndfile : A valid SNDFILE* pointer + cmd : SFC_GET_BROADCAST_INFO + data : a pointer to an SF_BROADCAST_INFO struct + datasize : sizeof (SF_BROADCAST_INFO) +</PRE> +<P> +The SF_BROADCAST_INFO struct is defined in <sndfile.h> as: +</P> +<PRE> + typedef struct + { char description [256] ; + char originator [32] ; + char originator_reference [32] ; + char origination_date [10] ; + char origination_time [8] ; + unsigned int time_reference_low ; + unsigned int time_reference_high ; + short version ; + char umid [64] ; + char reserved [190] ; + unsigned int coding_history_size ; + char coding_history [256] ; + } SF_BROADCAST_INFO ; +</PRE> + +<DL> +<DT>Return value: </DT> + <DD>SF_TRUE if the file contained a Broadcast Extension chunk or SF_FALSE + otherwise. +</DL> + +<!-- ========================================================================= --> +<A NAME="SFC_SET_BROADCAST_INFO"></A> +<H2><BR><B>SFC_SET_BROADCAST_INFO</B></H2> +<P> +Set the Broadcast Extension Chunk for WAV (and related) files. +</P> +<p> +Parameters: +</p> +<PRE> + sndfile : A valid SNDFILE* pointer + cmd : SFC_SET_BROADCAST_INFO + data : a pointer to an SF_BROADCAST_INFO struct + datasize : sizeof (SF_BROADCAST_INFO) +</PRE> + +<DL> +<DT>Return value: </DT> + <DD>SF_TRUE if setting the Broadcast Extension chunk was successful and SF_FALSE + otherwise. + +</DL> + +<!-- ========================================================================= --> +<A NAME="SFC_GET_CART_INFO"></A> +<H2><BR><B>SFC_GET_CART_INFO</B></H2> +<P>Retrieve the Cart Chunk from WAV (and related) files. Based on AES46 standard for CartChunk (see <a href="http://www.cartchunk.org/">CartChunk.org</a> for more information. +</P> +<p> +Parameters: +</p> +<PRE> + sndfile : A valid SNDFILE* pointer + cmd : SFC_GET_CART_INFO + data : a pointer to an SF_CART_INFO struct + datasize : sizeof (SF_CART_INFO) +</PRE> +<P> +The SF_CART_INFO struct is defined in <sndfile.h> as: +</P> +<PRE> +#define SF_CART_INFO_VAR(p_tag_text_size) \ + struct + { char version [4] ; + char title [64] ; + char artist [64] ; + char cut_id [64] ; + char client_id [64] ; + char category [64] ; + char classification [64] ; + char out_cue [64] ; + char start_date [10] ; + char start_time [8] ; + char end_date [10] ; + char end_time [8] ; + char producer_app_id [64] ; + char producer_app_version [64] ; + char user_def [64] ; + long level_reference ; + SF_CART_TIMER post_timers [8] ; + char reserved [276] ; + char url [1024] ; + unsigned int tag_text_size ; + char tag_text[p_tag_text_size] ; + } +</PRE> + +<DL> +<DT>Return value: </DT> + <DD>SF_TRUE if the file contained a Cart chunk or SF_FALSE + otherwise. +</DL> + +<!-- ========================================================================= --> +<A NAME="SFC_SET_CART_INFO"></A> +<H2><BR><B>SFC_SET_CART_INFO</B></H2> +<P> +Set the Cart Chunk for WAV (and related) files. +</P> +<p> +Parameters: +</p> +<PRE> + sndfile : A valid SNDFILE* pointer + cmd : SFC_SET_CART_INFO + data : a pointer to an SF_CART_INFO struct + datasize : sizeof (SF_CART_INFO) +</PRE> + +<DL> +<DT>Return value: </DT> + <DD>SF_TRUE if setting the Cart chunk was successful and SF_FALSE + otherwise. +</DL> +<!-- ========================================================================= --> + +<A NAME="SFC_GET_LOOP_INFO"></A> +<H2><BR><B>SFC_GET_LOOP_INFO</B></H2> +<P> +Retrieve loop information for file including time signature, length in +beats and original MIDI base note +</P> +<p> +Parameters: +</p> +<PRE> + sndfile : A valid SNDFILE* pointer + cmd : SFC_GET_LOOP_INFO + data : a pointer to an SF_LOOP_INFO struct + datasize : sizeof (SF_LOOP_INFO) +</PRE> +<P> +The SF_BROADCAST_INFO struct is defined in <sndfile.h> as: +</P> +<PRE> + typedef struct + { short time_sig_num ; /* any positive integer > 0 */ + short time_sig_den ; /* any positive power of 2 > 0 */ + int loop_mode ; /* see SF_LOOP enum */ + + int num_beats ; /* this is NOT the amount of quarter notes !!!*/ + /* a full bar of 4/4 is 4 beats */ + /* a full bar of 7/8 is 7 beats */ + + float bpm ; /* suggestion, as it can be calculated using other fields:*/ + /* file's lenght, file's sampleRate and our time_sig_den*/ + /* -> bpms are always the amount of _quarter notes_ per minute */ + + int root_key ; /* MIDI note, or -1 for None */ + int future [6] ; + } SF_LOOP_INFO ; +</PRE> +<P> +Example: +</P> +<PRE> + SF_LOOP_INFO loop; + sf_command (sndfile, SFC_GET_LOOP_INFO, &loop, sizeof (loop)) ; +</PRE> +<DL> +<DT>Return value:</DT> + <DD>SF_TRUE if the file header contains loop information for the file. + SF_FALSE otherwise. +</DL> + +<!-- ========================================================================= --> + + +<A NAME="SFC_GET_INSTRUMENT"></A> +<H2><BR><B>SFC_GET_INSTRUMENT</B></H2> +<P> +Retrieve instrument information from file including MIDI base note, +keyboard mapping and looping informations(start/stop and mode). +</P> +<p> +Parameters: +</p> +<PRE> + sndfile : A valid SNDFILE* pointer + cmd : SFC_GET_INSTRUMENT + data : a pointer to an SF_INSTRUMENT struct + datasize : sizeof (SF_INSTRUMENT) +</PRE> + +<P> +The SF_INSTRUMENT struct is defined in <sndfile.h> as: +</P> +<PRE> + enum + { /* + ** The loop mode field in SF_INSTRUMENT will be one of the following. + */ + SF_LOOP_NONE = 800, + SF_LOOP_FORWARD, + SF_LOOP_BACKWARD, + SF_LOOP_ALTERNATING + } ; + + typedef struct + { int gain ; + char basenote, detune ; + char velocity_lo, velocity_hi ; + char key_lo, key_hi ; + int loop_count ; + + struct + { int mode ; + unsigned int start ; + unsigned int end ; + unsigned int count ; + } loops [16] ; /* make variable in a sensible way */ + } SF_INSTRUMENT ; +</PRE> + +<P> +Example: +</P> +<PRE> + SF_INSTRUMENT inst ; + sf_command (sndfile, SFC_GET_INSTRUMENT, &inst, sizeof (inst)) ; +</PRE> +<DL> +<DT>Return value:</DT> + <dd>SF_TRUE if the file header contains instrument information for the + file. SF_FALSE otherwise. +</DL> + +<!-- ========================================================================= --> + + +<A NAME="SFC_SET_INSTRUMENT"></A> +<H2><BR><B>SFC_SET_INSTRUMENT</B></H2> +<P> +Set the instrument information for the file. +</P> +<p> +Parameters: +</p> +<PRE> + sndfile : A valid SNDFILE* pointer + cmd : SFC_SET_INSTRUMENT + data : a pointer to an SF_INSTRUMENT struct + datasize : sizeof (SF_INSTRUMENT) +</PRE> +<P> +Example: +</P> +<PRE> + SF_INSTRUMENT inst ; + sf_command (sndfile, SFC_SET_INSTRUMENT, &inst, sizeof (inst)) ; +</PRE> +<DL> +<DT>Return value:</DT> + <dd>SF_TRUE if the file header contains instrument information for the + file. SF_FALSE otherwise. +</DL> + + +<!-- ========================================================================= --> + +<A NAME="SFC_GET_CUE"></A> +<H2><BR><B>SFC_GET_CUE_COUNT</B></H2> +<P> +Retrieve the number of cue markers available for retrieval using the +SFC_GET_CUE command. +</P> +<P> +Parameters: +</P> +<PRE> + sndfile : A valid SNDFILE* pointer + cmd : SFC_GET_CUE + data : a pointer to a uint32_t + datasize : sizeof (uint32_t) +</PRE> + + +<P> +Example: +</P> +<PRE> + uint32_t cue_count ; + sf_command (sndfile, SFC_GET_CUE_COUNT, &cue_count, sizeof (cue_count)) ; +</PRE> +<DL> +<DT>Return value:</DT> + <dd>SF_TRUE if the file header contains cue marker information for the + file. SF_FALSE otherwise. +</DL> + +<!-- ========================================================================= --> + +<A NAME="SFC_GET_CUE"></A> +<H2><BR><B>SFC_GET_CUE</B></H2> +<P> +Retrieve cue marker information from file. +</P> +<P> +Parameters: +</P> +<PRE> + sndfile : A valid SNDFILE* pointer + cmd : SFC_GET_CUE + data : a pointer to an SF_CUES struct + datasize : sizeof (SF_CUES) +</PRE> + +<P> +The SF_CUES struct is defined in <sndfile.h> as: +</P> +<PRE> + typedef struct + { int cue_count ; + + struct + { int32_t indx ; + uint32_t position ; + int32_t fcc_chunk ; + int32_t chunk_start ; + int32_t block_start ; + uint32_t sample_offset ; + char name [256] ; + } cue_points [100] ; + } SF_CUES ; +</PRE> + +<P> +There is also an SF_CUES_VAR #define that allows reading/writing more than 100 +cue markers. +</P> + +<P> +Example: +</P> +<PRE> + SF_CUES cues ; + sf_command (sndfile, SFC_GET_CUE, &cues, sizeof (cues)) ; +</PRE> +<DL> +<DT>Return value:</DT> + <dd>SF_TRUE if the file header contains cue marker information for the + file. SF_FALSE otherwise. +</DL> + + +<!-- ========================================================================= --> + + +<A NAME="SFC_SET_CUE"></A> +<H2><BR><B>SFC_SET_CUE</B></H2> +<P> +Set the cue marker information for the file. +</P> +<P> +Parameters: +</P> +<PRE> + sndfile : A valid SNDFILE* pointer + cmd : SFC_SET_CUE + data : a pointer to an SF_CUES struct + datasize : sizeof (SF_CUES) +</PRE> +<P> +Example: +</P> +<PRE> + SF_CUES cues ; + sf_command (sndfile, SFC_SET_CUE, &cues, sizeof (cues)) ; +</PRE> +<DL> +<DT>Return value:</DT> + <dd>SF_TRUE if the file header contains cue marker information for the + file. SF_FALSE otherwise. +</DL> + + +<!-- ========================================================================= --> + + +<A NAME="SFC_RF64_AUTO_DOWNGRADE"></A> +<H2><BR><B>SFC_RF64_AUTO_DOWNGRADE</B></H2> +<P> +Enable auto downgrade from RF64 to WAV. +</P> +<P> +The EBU recomendation is that when writing RF64 files and the resulting file is +less than 4Gig in size, it should be downgraded to a WAV file (WAV files have a +maximum size of 4Gig). +libsndfile doesn't follow the EBU recommendations exactly, , mainly because the +test suite needs to be able test reading/writing RF64 files without having to +generate files larger than 4 gigabytes. +</P> +<p> +Note: This command should be issued before the first bit of audio data has been +written to the file. +Calling this command after audio data has been written will return the current +value of this setting, but will not allow it to be changed. +</p> +<p> +Parameters: +</p> +<PRE> + sndfile : A valid SNDFILE* pointer + cmd : SFC_RF64_AUTO_DOWNGRADE + data : NULL + datasize : SF_TRUE or SF_FALSE +</PRE> +<P> +Example: +</P> +<PRE> + /* Enable auto downgrade on file close. */ + sf_command (sndfile, SFC_RF64_AUTO_DOWNGRADE, NULL, SF_TRUE) ; +</PRE> +<DL> +<DT>Return value:</DT> + <dd>Returns SF_TRUE if SFC_RF64_AUTO_DOWNGRADE is set and SF_FALSE + otherwise. +</DL> + + + +<!-- ========================================================================= --> + + +<HR> +<P> + The libsndfile home page is here : + <A HREF="http://www.mega-nerd.com/libsndfile/"> + http://www.mega-nerd.com/libsndfile/</A>. +<BR> +Version : 1.0.25 +</P> + +</BODY> +</HTML>