sphere.doc

speech signal process tools

	     SPeech HEader REsources (SPHERE) Version 2.6
			     June 6, 1996

                   John Garofolo and Jonathan Fiscus
                                 NIST


Table of Contents:

I.      Introduction to SPHERE

II.     C-language Programmer Interface Library

	II.A   File Access Functions

		II.A.1	sp_open()
		II.A.1	sp_close()

	II.B   Header Manipulation Functions

		II.B.1	sp_h_get_field()
		II.B.2	sp_h_set_field()
		II.B.3	sp_h_delete_field()
		II.B.4  sp_copy_header()
	
	II.C   Waveform I/O and Conversion Functions

		II.C.1	sp_read_data()
		II.C.2	sp_write_data()
                II.C.3  sp_set_data_mode()
		II.C.4  sp_rewind()
		II.C.5  sp_seek()
		II.C.6  sp_tell()
		II.C.7  sp_compute_checksum();

	II.D   Status Functions

                II.D.1  sp_eof()
                II.D.2  sp_error()
                II.D.3  sp_print_return_status()
                II.D.4  sp_get_return_status()
		II.D.5  sp_get_version()

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

		II.E.1  sp_data_alloc()
		II.E.2  sp_data_free()

III.    File Format Definition

IV.     File Pointer Structure

VI.     Linking to the SPHERE library

VII.    Example Interface Library Usage

VIII.   System-Level Utilities

IX.     Revision History

X.      Bug Reports

XI.	Supported Hardware

XII.    Disclaimer

XIII.   Acknowledgements



I.  Introduction to SPHERE

SPeech HEader REsources (SPHERE) is a software package developed by
the National Institute of Standards and Technology (NIST) Automated
Speech Recognition Group to provide an interface to NIST
SPHERE-formatted speech waveform files.  (The acronym, SPHERE, has now
come to represent the format of the files as well as the software
package.)  

The SPHERE package contains two primary user-oriented software
components:

	1.  C-language programmer interface library

	2.  C-language system-level file manipulation utilities

The C-language programmer interface library has been developed to
provide a simple, intuitive interface to access and manipulate SPHERE
files.  The library has been specifically designed to mimic the syntax
and functionality of standard C-language file I/O functions.
Functions are provided to open, close, read, and write SPHERE files.
C-like header field manipulation functions have been included as well.

The system-level file manipulation utilities have been written using
the SPHERE library and provide command-line-level manipulation of
SPHERE files as well as functional examples of the usage of the SPHERE
libraries.

Where former versions of SPHERE provided only speech file header
access, Version 2.0 provides waveform access as well in both the
C-language programmer interface and system-level utilities.  Embedded
u-law, shorten, and wavpack compression/decompression is also
supported.



II.  C-language Programmer Interface Library.

    The SPHERE interface library functions provide a high-level
C-program interface to access and manipulate SPHERE-formatted files.
Many of the interface functions have been designed specifically 
to mimic standard C-language I/O functions.  Functions are 
included to provide SPHERE file access and separate manipulation
of file headers and bodies (waveforms). The functions have been
logically divided into five broad types:

	1.  File access functions (open and close SPHERE FILES)
	2.  Header manipulation functions
	3.  Waveform I/O and conversion functions
	4.  File I/O error status functions
	5.  Data (waveform) buffer allocation/deallocation functions


1.  File access functions:

   SPHERE file access is achieved via the 'sp_open' function.  The
'sp_open' function is analogous to the C-language 'fopen' function and
controls the opening of files.  Upon opening for read operations, a
SPHERE file structure is formed and the header is loaded.  For
write operations, a SPHERE file structure is formed and an empty
header is created.

   The 'sp_close' function is analogous to the C-language 'fclose' function
and closes the specified SPHERE file and frees up associated allocated
memory.


2.  Header manipulation functions:

   Opened SPHERE header structures are manipulated via a set of header
field functions to retrieve, write, and delete fields.  The function,
'sp_h_get_field', is used to retrieve the contents of the three types
of SPHERE fields.  Likewise, the function, 'sp_h_set_field', is used
to establish the contents of the three types of SPHERE fields.  These
functions are somewhat analogous to the C-language 'gets' and 'puts'
functions.  The function, 'sp_h_delete_field', is used to remove a
field from a header. 

   The function, 'sp_copy_header', is used to copy the header of an
opened SPHERE header to another opened SPHERE header.


3.  Waveform I/O and conversion functions

   A set of three functions has been established to handle waveform
I/O.  The first, 'sp_read_data', is used to load a block of waveform
data from a SPHERE file into memory.  This function is analogous to
the C-language 'fread' function.  Likewise, the function,
'sp_write_data', is used to flush a block of waveform data in memory
to SPHERE file and is analogous to the C-language 'fwrite' function.
The function, 'sp_set_data_mode', is used to change the default
behavior of 'sp_read_data' and 'sp_write_data' and controls such
variables as the conversion of waveform encodings and the byte order
during I/O.

Currently, only block-style sequential file access is supported.


4.  File I/O error status functions

   The functions, 'sp_eof' and 'sp_error', have been added to
provide file I/O status information analogous to the C-language
'feof' and 'ferror' functions.

5.  Data (waveform) buffer allocation/deallocation functions

    The functions, 'sp_data_alloc' and 'sp_data_free' have been added
to allocate and de-allocate memory and create data structures to hold
waveform data.  The functions use the header information to compute
the size required for the buffers.
	


The following sub-sections contain a detailed description template for
each function.  The templates are comprised of the following fields:

	Description - Brief general description of the purpose of the function
	Syntax - Function type and syntax including argument list
	Arguments - Description of arguments passed to the function
	Remarks - General comments and advisories regarding the function
	Return Value - Interpretation of the return values of the function
	See Also - List of related functions


II.A   File Access Functions


II.A.1 sp_open()

Description:

    Opens a SPHERE-formatted file and returns a SPHERE file pointer to
    the opened file.

Syntax:

    struct SP_FILE *sp_open(char *filename, char *mode)
	
Arguments:

    sp_open opens the file named by the string, 'filename', as
    instructed by the string, 'mode'.  

    The 'mode' string has the following values:

	"r[v]" -> Open a SPHERE file specified by the string, 'filename',
                  for reading.

	"w[v]" -> Open a SPHERE file specified by the string, 'filename',
                  for writing.

Remarks:

    Although a checksum is always generated upon completion of
    reading or writing any SPHERE file, an extra checksum verification
    may be performed using the optional 'v' modifier to
    'r' and 'w'.

    'rv' Checksum Verification:

    If a file is opened for read operations with the checksum
    verification flag, the checksum is verified before the
    file is made available for read operations.  Normally, the
    checksum is verified upon completion of reading a file.

    'wv' Checksum Verification:
   
    If a file is opened for write operations with the checksum
    verification flag, after a file is written, it is re-read and
    the checksum is verified.  Normally, if a checksum is present in the 
    file header before initiating write operations, then the existing
    checksum is verified against a checksum generated upon closing
    the file (with sp_close).  If a checksum is not present in the
    file header before initiating write operations, then a initial
    checksum is computed and no checksum verification takes placed.
    
    The 'filename' option may be '-' to signify stdin or stdout for
    files opened for read or write operations respectively.  As a special case,
    files opened in this manner do need to have a 'sample_count' field present
    in the header.  If the file is opened for read operations, the
    'sp_read_data()' function will read data until End-of-File is detected.
    If the file is opened for write operations, a flag value is placed
    in the output header so as to allow pipe-lined SPHERE operations to 
    work together.

Return Value:

    Returns a pointer to an opened SP_FILE structure.  If an error
    occurs during the open, returns a null pointer to a SP_FILE
    structure, "(SP_FILE *)0".

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


II.A.2 sp_close()

Description:

    Closes an opened SPHERE-formatted file.

Syntax:

    int sp_close(SP_FILE *sp)
	
Arguments:

    sp_close closes the file pointed to by 'sp'.  

Remarks:

    Upon closing the file, '*sp' sp_close frees the memory allocated
for the file buffer.

Return Value:

    Returns 100 or greater on failure, otherwise returns a zero.

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



II.B   Header Manipulation Functions

II.B.1 sp_h_get_field()

Description:

    Gets the specified header field value from an opened SPHERE file
header.

Syntax:

    int sp_h_get_field(SP_FILE *sp_file, char *field_name,
                       int field_type, void **field_value)

Arguments:

    sp_h_get_field copies the header field named by, 'field_name', of
type, 'field_type', from the opened SPHERE file pointed to by
'sp_file', to address pointed to by 'field_value'.

Remarks:

        Permitted        Library Defined            Field
    field_type values:        C-Types:           Definitions
    ------------------   ---------------         -----------	
       T_STRING           SP_STRING        string field type [char *]
       T_INTEGER   	  SP_INTEGER       integer field type [long]
       T_REAL             SP_REAL          real field type [double]


Note: in the case of a string field type (T_STRING), sp_h_get_field()
allocates sufficient dynamic memory for the string to be copied.  The
copied string is a NULL terminated sequence of characters.  It is the
programmer's responsibility to deallocate this memory using the
C-Language 'free()' function when the string is no longer needed.

In order to avoid mis-typing of header values, the SPHERE library has a
'typedef' for each of the header field types.

Return Value:

    sp_h_get_field() returns a 0 upon success, 1 to 99 for a warning,
and 100 or greater for an error.

See Also:

    sp_open()


II.B.2 sp_h_set_field()

Description:

    Sets the specified header field value in an opened SPHERE file
header.

Syntax:

    int sp_h_set_field(SP_FILE *sp_file, char *field_name, 
                       char* field_type, void *field_value)
	
Arguments:

    sp_h_set_field sets the header field value named by, 'field_name',
of type, 'field_type', in the opened SPHERE file pointed to by
'sp_file' with the value, 'field_value'.

Remarks:

        Permitted        Library Defined            Field
    field_type values:        C-Types:           Definitions
    ------------------   ---------------         -----------	
       T_STRING           SP_STRING        string field type [char *]
       T_INTEGER   	  SP_INTEGER       integer field type [long]
       T_REAL             SP_REAL          real field type [double]

    If the specified header field, 'field_name', does not exist in the
opened SPHERE file header, then the field is created.

Note: If a file is opened for write (using 'sp_open'), then this
function may only be called before using 'sp_write_data'.  Also, the
fields, 'sample_coding', 'sample_byte_format', 'sample_count',
'sample_n_bytes', 'sample_checksum', are set automatically by the
function, 'sp_set_data_mode', and should not be set manually if
'sp_set_data_mode' has been called.

In order to avoid mis-typing of header values, the SPHERE library has a
'typedef' for each of the header field types.

Return Value:
    sp_h_get_field() returns a 0 upon success, 1 to 99 for a warning,
and 100 or greater for an error.

See Also:
    sp_open()


II.B.3 sp_h_delete_field()

Description: