sphere.doc

speech signal process tools

    Deletes the specified header field from an opened SPHERE file
header.

Syntax:

    int sp_h_delete_field(SP_FILE *sp_file, char *field_name)
	
Arguments:

    sp_h_delete_field deletes the header field named by,
'field_name', in the opened SPHERE file pointed to by 'sp_file'.

Remarks:

    If the specified header field to be deleted, 'field_name', does
not exist in the opened SPHERE file header, sp_h_delete_field() will
not complain, but will return a special value (see below).  Return
Value:

Return Value:

    sp_h_delete_field() returns a 0 on success, a 1 if the header
field does not exist, and a 100 or greater on error.

See Also:
    sp_open(), sp_h_set_field(), sp_h_get_field()


II.B.4  sp_copy_header()

Description:

    Copies the SPHERE header fields and their values from a source
header pointed by an SP_FILE pointer to a destination header pointed
to by another SP_FILE pointer.  Overwrites any existing fields common
to both the source and destination headers.

Syntax:

    int sp_copy_header(SP_FILE *source_sp, SP_FILE *destination_sp)
	
Arguments:

    sp_copy_header copies the fields and their values from the header
pointed to by 'source_sp' to the header pointed to by 'destination_sp'.

Return Value:

    sp_copy_header() returns a zero on success, and 100 or greater
on error.

See Also:
    sp_open(), sp_close()


II.C   Waveform I/O Functions

II.C.1 sp_read_data()

Description:
   
    Reads blocks of waveform data from an opened SPHERE file.

Syntax:

    /* New syntax for SPHERE version 2.2 or later              */
    int sp_read_data(void *ptr, size_t n, SP_FILE *sp_file)

    /* Syntax prior to SPHERE version 2.2, still supported for */
    /* backwards compatibility                                 */
    int sp_read_data(void *ptr, size_t size, size_t n, SP_FILE *sp_file)


Arguments:

    Reads 'n' elements from the waveform data section of the opened
SPHERE file pointed to by 'sp_file'.  An element is defined to be the
sample values of all channels for a particular sample number (common
time point).  The function performs the read (including any
conversions as necessary) to format the data according to the first
encoding specified in the header field, 'sample_coding'.  This
excludes subsequent encodings used on the stored waveform such as
compression, etc.

   The 'ptr' argument can be either a linear array of interleaved
channel samples, or a 2-dimensional array of non-interleaved channel
samples, with each channel contained in a separate array.  Either data
structure can be created by a call to the 'sp_data_alloc' function.
The form of the data structure is determined by the mode string passed
to the 'sp_set_data_mode' function.  By default, the function expects
the data to be structured in a linear array.  To change the format to
a multi-channel 2-dimensional array, use the sp_set_data_mode
function.

Remarks:

    In order to support multi-channel data, the manner of specifying
the waveform parameters has been simplified in SPHERE version 2.2.
Instead of extracting the information from the a variable number of
function arguments, the function now extracts the necessary
information from the SPHERE header.  Therefore, the function argument
list has changed from previous versions of SPHERE.  However, the
SPHERE 2.1 argument list is still supported for backward compatibility.
The 'size' argument although accepted, is now ignored.  Section VI,
"Linking to the SPHERE library" describes how to use either the 3 or 4
argument function call by using the C-define'd preprocessor variable
"SPHERE_PRE_2_2".

    If there is no 'sample_coding' field in the header, the default
operation is to read the data as PCM data.  The default behavior of
'sp_read_data()' can be modified by the function 'sp_set_data_mode()'
before 'sp_read_data()' is called.  If a checksum is present in
the header, the checksum is verified after reading the last 
block of data.

Return Value:

    The value returned by 'sp_read_data' indicates the number of
elements read in from the file.  If no elements are read, a zero is
returned.  Likewise, if an error or checksum verification error
occurs, a zero is returned.  The functions 'sp_eof()' and 'sp_error()'
may be used to determine if an error or an immediate end-of-file
caused the zero to be returned.

See Also:

    sp_eof(), sp_error(), sp_set_data_mode(), sp_data_alloc(),
    sp_data_free()


II.C.2 sp_write_data()

Description:
   
    Writes blocks of waveform data to an opened SPHERE file.

Syntax:

    /* New syntax for SPHERE version 2.2 or later              */
    int sp_write_data(void *ptr, size_t n, SP_FILE *sp_file)

    /* Syntax prior to SPHERE version 2.2, still supported for */
    /* backwards compatibility                                 */
    int sp_write_data(void *ptr, size_t size, size_t n, SP_FILE *sp_file)

Arguments:

    Appends 'n' elements to the end of the waveform data section of
the opened SPHERE file pointed to by 'sp_file'.  An element is defined
to be the sample values of all channels for a particular sample number
(common time point).  The function outputs the data in the form
specified by the mode string passed to 'sp_set_data_mode'.  By
default, the data is written with interleaved channels (if the data is
multi-channel data) and without further conversions.

   The 'ptr' argument can be either a linear array of interleaved
channel samples, or a 2-dimensional array of non-interleaved channel
samples, with each channel contained in a separate array.  The data is
written from an existing waveform data structure. 

   [ A waveform data structure is created by a call to the
'sp_data_alloc' function.  The form of the data structure is
determined by the mode string passed to the 'sp_set_data_mode'
function.  By default, the function expects the data to be structured
in a linear array.  To change the format to a multi-channel
2-dimensional array, use the sp_set_data_mode function. ]

Remarks:

    In order to support multi-channel data, the manner of specifying
the waveform parameters has been simplified in SPHERE version 2.2.
Instead of writing the data according to a variable number of function
arguments, the function now extracts the necessary information from a
SPHERE header constructed prior to the write.  Therefore, the function
argument list has changed from previous versions of SPHERE.  However,
the SPHERE 2.1 argument list is still supported for backward
compatibility.  The 'size' argument although accepted, is now ignored.
Section VI, "Linking to the SPHERE library" describes how to use
either the 3 or 4 argument function call by using the C-define'd
preprocessor variable "SPHERE_PRE_2_2".

    sp_write_data() uses the 'sample_coding', 'channel_count'
'sample_byte_format' and 'sample_n_bytes' fields of the header in the
'sp_file' structure to identify the format of the data in memory to
be written.  The default behavior is for the data to be written as
it is represented in memory (as specified by the above header fields).

    The default behavior of 'sp_write_data()' can be modified by the
function 'sp_set_data_mode()' before 'sp_write_data()' is called.
'sp_set_data_mode()' allows the programmer to specify waveform data
transformations as the data is written.

Return Value:

    The value returned by 'sp_write_data' indicates the number of
elements written to the file pointed to by the 'sp_file' structure.
Incomplete writes are not flagged by the function.  It is the
programmer's responsibility to make sure that the return value equals
'n'.

See Also:

    sp_eof(), sp_error(), sp_set_data_mode(), sp_data_alloc(),
    sp_data_free()


II.C.3 sp_set_data_mode()

Description:
   
    Changes the default behavior of the SPHERE File I/O functions, 
'sp_read_data()' and 'sp_write_data()'.

Syntax:

    int sp_set_data_mode(SP_FILE *sp_file, char *mode)

Arguments:

    Specifies the waveform transformations for data read from, or
written to, the file pointed to by 'sp_file'.  The transformations are
specified in the string, 'mode'.  See the "Remarks" section for the
format and permissible values of this string.

Remarks:

    The 'mode' string argument specifies sample encoding and byte
order transformations to be performed by the SPHERE File I/O
functions, 'sp_read_data()' and 'sp_write_data()'.  (Future versions
may support sample rate transformations as well.) 

    When reading from a file via sp_read_data(), sp_set_data_mode()
sets the format of the data which is output from the sp_read function.

    When writing to a file via sp_write_data(), sp_set_data_mode()
sets the format of the data which is ultimately written to the file.
While the format of the data passed to sp_write_data() is controlled
by header field values for the fields: "sample_coding",
"channel_count", "sample_byte_format", and "sample_n_bytes", which
have been set by sp_h_set_field().

    The 'mode' string has the following format:


        MODE        :==  <MODE_FLAG> | <MODE_FLAG>:<MODE>
        MODE_FLAG   :==  SE-<SE_OPTIONS> | SBF-<SBF_OPTIONS> |
			 DF-<DF_OPTIONS> | CH-<CHANNEL_OPTIONS>
        SE_OPTIONS  :==  PCM | PCM-1 | PCM-2 | ULAW | RAW | ORIG |
                         SHORTEN | WAVPACK
	SBF_OPTIONS :==  01 | 10 | 1 | N | ORIG

Mode Flag and Option Descriptions:


    DF -> specifies the data structure of the buffer passed
	  into the functions 'sp_read_data()' and 'sp_write_data()'.  The
	  default format, "DF-RAW", specifies interleaved channels in a
	  1-dimensional array.

	DF_OPTIONS:
	    "RAW"     -> Data buffers are 1-dimensional arrays of contiguous
		 	 memory.  If multiple channels are present, they
			 are assumed to be interleaved.
	    "ARRAY"   -> Data buffers are 2-dimensional arrays (double 
			 pointers) where the data for each channel is in a
			 1-dimensional array of contiguous data.  The channel
			 number, starting at zero for the first channel, is
			 the first index in 2-dimensional array and the
			 sample number the second index.  See
			 'sp_data_alloc()' for a  description of the memory
			 layout.

	  The functions 'sp_data_alloc()' and 'sp_data_free()' allocate and 
	  deallocate data buffers in either format.

    CH -> specifies the channels to be read from a file, or written
	  to a file via the <CHANNEL_OPTIONS>.  If the file is being
	  read, the function 'sp_read_data()' returns the requested
	  channels from the input file.  If the files is being written
	  or updated, the library extracts the channels from the input
	  buffer before writing the samples to the file.  The default
	  operation (without channel selection), is to not perform any
	  modifications.

	  The <CHANNEL_OPTIONS> can select and re-order channels.  If the
	  sample type is pcm, pculaw or ulaw, the <CHANNEL_OPTIONS> can 
	  sum two or more channels together.

	  The <CHANNEL_OPTIONS> format is a comma separated list of 
	  channel identifiers.  The channel identifiers start at 1 
	  for the first channel.  The <CHANNEL_OPTIONS> are of the
	  following format:

	CHANNEL_OPTIONS :== <CHANNEL_ID> | <CHANNEL_ID>,<CHANNEL_OPTIONS>
	CHANNEL_ID      :== <CHANNEL_NUMBER> | <CHANNEL_NUMBER>+<CHANNEL_ID>
	CHANNEL_NUMBER  :== the channel number, starting with 1 for
	 		    the first channel.
	  
		   	 
    SE -> specifies a transformation to the encoding of the sampled
	  waveform data.

        SE_OPTIONS:

            "PCM-2"   -> Read or write data as 2-byte PCM samples.
            "PCM-1"   -> Read or write data as 1-byte PCM samples.
            "PCM"     -> Synonym for "PCM-2"
            "ULAW"    -> Read or write data as 1-byte ULAW samples.
  	    "RAW"     -> Read or write data as 1-byte character
	                 stream (for unsupported data types).
            "ORIG"    -> Read or write data as-is.
	    "SHORTEN" -> Write data as Shorten-compressed byte stream.
	    "WAVPACK" -> Write data as Wavpack-compressed byte stream.
    
    SBF -> specifies a transformation to the byte format (byte order)
	   of the sampled waveform data.  This is only appropriate for
           multi-byte sampled data.

        SBF_OPTIONS:
            "01"      -> Read or write data as LSB/MSB.
            "10"      -> Read or write data as MSB/LSB.
            "1"       -> Read or write data as 1-byte samples.
            "N"       -> Read or write data as natural to the host.
            "ORIG"    -> Read or write data as-is.

Currently Supported Sample Encoding (SE) Read Transformations: ***

    PCM-2   -->  ULAW | RAW | ORIG
    ULAW    -->  PCM-2 | RAW | ORIG
    RAW     -->  ORIG
    SHORTEN -->  PCM-2 | ULAW | RAW | ORIG
    WAVPACK -->  PCM-2 | ULAW | RAW | ORIG
    
Currently Supported Sample Encoding (SE) Write Transformations: ***

    PCM-2   -->  ULAW | ORIG | SHORTEN | WAVPACK 
    ULAW    -->  PCM-2 | ORIG | SHORTEN | WAVPACK 
    RAW     -->  ORIG

Return Value:

    The value returned by 'sp_set_data_mode()' are:

	0     - if the transformation specified by 'mode' is supported
  	        and successfully performed.
	1     - if the mode of a compressed file has been set to
	        'SE-ORIG'.  In this case, the waveform is not readable or
		writable until the sample encoding has been changed, but
		the header is.
	100   - if the transformation is not supported.
	> 100 - if an error occurs,

See Also:

    sp_read_data(), sp_write_data(), sp_open(), sp_close(),
    sp_data_alloc(), sp_data_free()


II.C.4 sp_rewind()

Description:
   
    Rewind to the beginning of a SPHERE waveform if the file was
opened for reading.

Syntax:

    int sp_rewind(SP_FILE *sp_file)

Arguments:

    Rewind to the beginning of a waveform if the SPHERE file,
'sp_file', was opened for reading.  

Remarks:

    If the data mode was changed via 'sp_set_data_mode()', the changes
are in effect until subsequent calls to 'sp_set_data_mode()' are made.

    Using the rewind function is more efficient than closing the file
using 'sp_close()' and then re-opening the file using 'sp_open()'.
Overhead is saved by not re-parsing the SPHERE header and not
re-decompressing a compressed waveform.

    This function is unable to rewind SPHERE files which are read from
stdin.

    Although this function could be written solely with sp_seek(),
using this function resets the SPHERE file so that sp_set_data_mode()
can be called again on the file.

Return Value:

    The value returned by 'sp_rewind()' is 0 if the operation was
successful and greater than 100 on error.