--- /dev/null
+<!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 the Variable Bit Rate encoding quality</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_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_SET_VBR_ENCODING_QUALITY">SFC_SET_VBR_ENCODING_QUALITY</A></TD>
+ <TD>Set variable bit rate encoding quality</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 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 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 the Variable Bit Rate encoding quality.
+The encoding quality value should be between 0.0 (lowest quality) and 1.0
+(highest quality).
+</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>Zero on success, non-zero 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_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_GET_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_SET_VBR_ENCODING_QUALITY"></A>
+<H2><BR><B>SFC_SET_VBR_ENCODING_QUALITY</B></H2>
+<P>
+Set the Variable Bite Rate encoding quality.
+Currenly only implemented fro Ogg/Vorbis files.
+</P>
+<p>
+Parameters:
+</p>
+<PRE>
+ sndfile : A valid SNDFILE* pointer
+ cmd : SFC_SET_VBR_ENCODING_QUALITY
+ data : a pointer to double specifing VBR quality
+ datasize : sizeof (double)
+</PRE>
+<P>
+Example:
+</P>
+<PRE>
+ double quality = 0.5 ;
+ sf_command (sndfile, SFC_SET_VBR_ENCODING_QUALITY, &quality, sizeof (double)) ;
+</PRE>
+<DL>
+<DT>Return value:</DT>
+ <dd>SF_TRUE if VBR encoding quality was set.
+ 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>
projects / Faustine.git / blobdiff