sphere.doc

speech signal process tools

See Also:

    sp_set_data_mode(), sp_read_data(), sp_open(), sp_close()


II.C.5 sp_seek()

Description:
   
    Perform a 'seek' operation to a specific sample of opened SPHERE
waveform which has been opened for read.

Syntax:

    int sp_seek(SP_FILE *sp_file, int offset, int origin)

Arguments:

    Move the SPHERE file pointer 'sp_file' to the sample defined by
'offset' and 'origin'.  The SPHERE waveform file must be opened for
read.

Remarks:

    Sp_seek() takes the opened-for-read SPHERE file and moves the file
pointer to the sample defined by the 'offset' and 'origin' arguments.

    The 'offset' and 'origin' arguments specify the sample position at
which the next read will occur.  Offset must be an integer (which may
be negative) and origin must be one of the following:
 
     0    The new access position will be offset samples from  the
          start of the file.
 
     1    The new access position will be offset samples from  the
          current  access  position;  a negative offset moves the
          access position backwards in the file.
 
     2    The new access position will be offset samples from  the
          end  of  the file.  A negative offset places the access
          position before the end-of-file, and a positive  offset
          is illegal.

    For multi-channel interleaved data, the file pointer is moved to
the nth sample of all channels.

    If the opened SPHERE file is a pipe, then the seek can only go
forward in the file.  In this case, the seek is performed via
sequential reads to the appropriate location.

    When sp_seek() is called, checksum computation and verification
are disabled unless the file is seek'd to sample 0 in which case
the sample checksum computations are reset.

Return Value:

    If an error occurs, 1 is return.  Otherwise 0 is returned.

See Also:

    sp_set_data_mode(), sp_read_data(), sp_open(), sp_close()


II.C.6 sp_tell()

Description:
   
    Return the waveform sample position at which the next read or
write to a SPHERE file will occur.

Syntax:

    int sp_tell(SP_FILE *sp_file)

Arguments:

    Return the sample position in 'sp_file' at which the next read or
write will occur.

Remarks:

    Sp_tell() works for SPHERE files opened for read or write access
only.

    For multi-channel interleaved data, the value returned is
the nth sample of all channels.

Return Value:

    If an error occurs, -1 is return.  Otherwise the sample number is
returned.

See Also:

    sp_read_data(), sp_write_data(), sp_open(), sp_close()

II.C.6 sp_compute_checksum()

Description:
   
    Compute and return the checksum for a SPHERE file opened for read.

Syntax:

    int sp_compute_checksum(SP_FILE *sp_file, SP_CHECKSUM *checksum)

Arguments:

    Compute a checksum for the SPHERE file 'sp_file' which has been
opened for read and return the checksum in the pointer '*checksum'.

Remarks:

    Sp_compute_checksum() first calls sp_tell() to save the current
sample pointed to by the SP_FILE pointer.  Then an sp_seek() to the
0th sample of the SPHERE file is performed and the entire waveform is
read in to compute the checksum.  After the checksum is calculated,
another sp_seek() is performed to return the SP_FILE to it's original
sample position.

Return Value:

    Successful execution returns a 0, otherwise a number greater than 
100 is returned.

See Also:

    sp_tell(), sp_seek(), sp_open(), sp_close()


II.D   Status Functions

II.D.1 sp_eof()

Description:

    Returns the End-of-File (EOF) status of an opened SPHERE file.

Syntax:

    int sp_eof(SP_FILE *sp_file)
	
Arguments:

    sp_eof takes as it's argument a SPHERE file pointer, 'sp_file',
and returns the EOF status of that file.

Return Value:

    sp_eof returns a non-zero value if the end-of-file has been
reached during the last file read.  Otherwise, it returns a zero.

See Also:
    sp_read_data(), sp_error()


II.D.2 sp_error()

Description:

    Returns the error status of an opened SPHERE file.

Syntax:

    int sp_error(SP_FILE *sp_file)
	
Arguments:

    sp_error takes as it's argument a SPHERE file pointer, 'sp_file',
and returns the error status of that file.

Return Value:

    sp_error returns a zero if no errors occurred during the last file
I/O operation, a 100 if a checksum verification error occurred, or greater
than 100 if a fatal file I/O error occurred.

See Also:
    sp_read_data(), sp_write_data(), sp_eof()


II.D.3 sp_print_return_status()

Description:

    Prints the return status of the last SPHERE function call.

Syntax:

    int sp_print_return_status(FILE *fp)

Arguments:
    
    sp_return_status takes as it's argument an opened file pointer,
'fp', and prints a message indicating the success or failure and
library version number of the last SPHERE function called to 'fp'.

Remarks:

    sp_return_status prints the following report for the last
function called:

    Procedure: <function-name> V2.4
        Status code: <integer-value>
        Status type: <Success|Warning|Error>
        Message: <message-string>

Failures of child functions are recorded in the Message string.

Note: This is currently only defined for the SPHERE 2.0 C-language
Programmer Interface Library functions.

Return Value:
    
    sp_return_status a zero on success and a 100 or greater on error.


II.D.4 sp_return_status()

Description:

    Returns the return status of the last SPHERE function call.

Syntax:

    int sp_return_status()

Return Value:
    
    sp_return_status returns the status of the last SPHERE function
call.  The SPHERE 2.0 C-Language Programmers Interface Library functions
follow the conventions below for indicating Success, Warnings, or
Errors:

     	Return Condition	Possible Range of Values
	---------------- 	------------------------
	   Success		           0
	   Warning                        1-99
	   Fatal Error	             100 or greater

Note: This is currently only defined for the SPHERE 2.0 C-language
Programmer Interface Library functions.

II.D.5  sp_get_version()

Description:

    Returns a pointer to a character string that identifies the SPHERE
library version.

Syntax:

    char *sp_get_version(void)

Return Value:
    
    sp_get_version returns a pointer to a character string that
defines the SPHERE Library version.  An example of the string would
be: "SPHERE Lib V2.4".


Note: The character string should NOT by "free()'d" by the programmer.


II.E   Data (Waveform) Buffer Allocation/Deallocation Functions

II.E.1 sp_data_alloc()

Description:

    Return a pointer to memory allocated for N samples of all data
channels for an opened SP_FILE.

Syntax:

    void *sp_data_alloc(SP_FILE *sp, int nsamp)
	
Arguments:

sp_data_alloc takes as it's argument a SP_FILE pointer, 'sp', and the
number of samples 'nsamp' and returns an allocated buffer large enough
to hold 'nsamp' samples times the number of channels.  If the SP_FILE
pointer is opened for read and 'nsamp' is -1, the returned buffer will
be size of the entire file.  If the SP_FILE is opened for write, and
'nsamp' is -1, an error will occur.

Remarks:

   The returned buffer 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 form of
the data structure is determined by the mode string passed to the
'sp_set_data_mode' function.

If 'nsamp' is greater than 0, and if a linear array
(interleaved channels) is specified in the mode string, the buffer
byte size is computed as follows:

	sample_n_bytes * channel_count * nsamp

	The sample_n_bytes and channel_count values are obtained from
	the SP_FILE's header.    

If 'nsamp' is greater than zero and a 2-dimensional array is specified
in the mode string, then the memory structure below is created and
returned.  The SP_FILE's sample_n_bytes and channel_count fields are
used to create a structure large enough to hold the data.

The structure consists of an array of double pointers for each
channel, and each double pointer points to an array of 'nsamp'
samples.

                	 <--- 'nsamp' samples --->    
		___      _________________________
     	^	| |  ->  |  |  |  |  |  |  |  |  |
        |	| |	 -------------------------
     	|	|-|      _________________________
     channel	| |  ->  |  |  |  |  |  |  |  |  |
      count	| |	 -------------------------
	|	|-|      _________________________
	|	| |  ->  |  |  |  |  |  |  |  |  |
	|	| |	 -------------------------
	v	---

The programmer must 'cast' the returned pointer to a double pointer of
the expected type.  The programmer has a choice to access the data in
two ways: 

	1. as a 2-dimensional array where the first subscript is the
	   channel (zero for the first channel), and the second
	   subscript is the sample number, e.g. arr[0][40].

	2. as a pointer to each channel's data, e.g. arr[0], arr[1] ...

If the defaults are not to be used, sp_set_data_mode must be called
before sp_data_alloc.  Further calls to sp_set_data_mode after the
structure is created can result in unknown spurious errors.

Return Value:

    sp_data_alloc() returns a pointer to memory allocated for waveform
data.  The returned value must be 'cast' to the programmer's expected
data type.  If an error occurs, a NULL is returned.

See Also:
    sp_read_data(), sp_write_data(), sp_set_data_mode(), sp_data_free()

I.E.2 sp_data_free()

Description:

    Frees a memory structure created by a call to sp_data_alloc().

Syntax:

    int sp_data_free(SP_FILE *sp, void *buffer)
	
Arguments:

    sp_data_free takes as it's argument a SPHERE file pointer, 'sp',
and a pointer to a memory buffer created by a call to sp_data_alloc()
and "frees" the memory associated with the buffer.

Remarks:

   The buffer 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 form of the data
structure is determined by the mode string passed to the
'sp_set_data_mode' function.

Return Value:

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

See Also:
    sp_read_data(), sp_write_data(), sp_set_data_mode(), sp_data_alloc()


III.  File Format Definition

SPHERE files contain a strictly defined header portion followed by
the file body (waveform).  Any waveform encoding may be used, but the
encoding must be sufficiently described in the header.

The header is an object-oriented, 1024-byte blocked, ASCII structure
which is prepended to the waveform data.  The header is composed of a
fixed-format portion followed by an object-oriented variable portion.
The fixed portion is as follows:

NIST_1A<new-line>
   1024<new-line>