| <!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> |