forked from Mirrors/freeswitch
1018 lines
29 KiB
HTML
1018 lines
29 KiB
HTML
<!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 a integer identifier which is defined in <sndfile.h>.
|
|
All of the valid command identifiers have names begining 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>Retrieve the measured maximum signal value.</TD>
|
|
</TR>
|
|
<TR>
|
|
<TD><A HREF="#SFC_CALC_NORM_SIGNAL_MAX">SFC_CALC_NORM_SIGNAL_MAX</A></TD>
|
|
<TD>Retrieve 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 peaks for all channels.</TD>
|
|
</TR>
|
|
<TR>
|
|
<TD><A HREF="#SFC_CALC_NORM_MAX_ALL_CHANNELS">SFC_CALC_NORM_MAX_ALL_CHANNELS</A></TD>
|
|
<TD>Calculate normalised peaks for all channels.</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_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="#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 normailised 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 peaks for all channels. 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 normalised peaks for all channels. 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="read-text"></A>
|
|
<H2><BR><B>Read text</B></H2>
|
|
<P>
|
|
Many sound file formats contain allow the inclusion of a text string describing the nature
|
|
of the file. If a file contains such a string, this functions will return it to the caller.
|
|
</P>
|
|
<P>
|
|
It should be noted that the way the string is added to the file is file format dependant
|
|
but that any string added with <A HREF="#write-text">write text</A> will be returned by
|
|
<A HREF="#read-text">read text</A>.
|
|
</P>
|
|
<P>
|
|
<P>
|
|
Parameters:
|
|
</P>
|
|
<PRE>
|
|
sndfile : A valid SNDFILE* pointer
|
|
cmd : The text string "read text".
|
|
data : A pointer to a char buffer.
|
|
datasize : The size of the the buffer.
|
|
</PRE>
|
|
<P>
|
|
Example:
|
|
</P>
|
|
<PRE>
|
|
char buffer [128] ;
|
|
sf_command (sndfile, "read text", buffer, sizeof (buffer)) ;
|
|
</PRE>
|
|
<DL>
|
|
<DT>Return value:</DT>
|
|
<DD>If a text string is found, this call will return the length of the retrieved text
|
|
string.
|
|
<DD>If no text string is found, zero will be returned and the first element in the
|
|
buffer will be set to the null character.
|
|
<DT>Notes:</DT>
|
|
<DD>The string returned in the buffer passed to this function will not overflow
|
|
the buffer and will be correctly null terminated .
|
|
</DL>
|
|
|
|
<A NAME="write-text"></A>
|
|
<H2><BR><B>Write text</B></H2>
|
|
<P>
|
|
Add a text string to a file. The text string added can be retrieved when the file is
|
|
read using <A HREF="#read-text">read text</A>.
|
|
</P>
|
|
<P>
|
|
Parameters:
|
|
</P>
|
|
<PRE>
|
|
sndfile : A valid SNDFILE* pointer
|
|
cmd : The text string "write text".
|
|
data : A pointer to the string to be added.
|
|
datasize : Not used.
|
|
</PRE>
|
|
<P>
|
|
Example:
|
|
</P>
|
|
<PRE>
|
|
char text = "The sound of one hand clapping." ;
|
|
sf_command (sndfile, "write text", text, strlen (text)) ;
|
|
</PRE>
|
|
<DL>
|
|
<DT>Return value: </DT>
|
|
<DD>If the current file format allows the addition of text strings, the string will
|
|
be added and the length of the string will be returned.
|
|
<DD>If the file format does not allow the addition of text strings zero will be returned.
|
|
<DD>If this function is called after the file is openned but before
|
|
</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 1 on success or 0 for failure.
|
|
</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 1 on success or 0 for failure.
|
|
</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 normaisation 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_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 an 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 ie "WAV (Microsoft 16 bit PCM)".
|
|
<DD>The extention 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 one of the major format identifiers suc as SF_FORMAT_WAV
|
|
SF_FORMAT_AIFF.
|
|
<DD>The name field will contain a char* pointer to the name of the string ie "WAV (Microsoft)".
|
|
<DD>The extention 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>
|
|
Retrieve information about a subformat.
|
|
</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:
|
|
</P>
|
|
<PRE>
|
|
SF_FORMAT_INFO format_info ;
|
|
int k, count ;
|
|
|
|
sf_command (sndfile, SFC_GET_FORMAT_SUBTYPE_COUNT, &count, sizeof (int)) ;
|
|
|
|
/* Retrieve all the subtypes supported by the WAV format. */
|
|
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 | SF_FORMAT_WAV))
|
|
continue ;
|
|
printf ("%08x %s\n", format_info.format, format_info.name) ;
|
|
} ;
|
|
</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 one of the major format identifiers such as SF_FORMAT_WAV
|
|
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 extention 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 open for write or for 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 sucess, non-zero 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>
|