SPeech HEader REsources (SPHERE) Version 2.6			     June 6, 1996                   John Garofolo and Jonathan Fiscus                                 NISTTable of Contents:I.      Introduction to SPHEREII.     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 DefinitionIV.     File Pointer StructureVI.     Linking to the SPHERE libraryVII.    Example Interface Library UsageVIII.   System-Level UtilitiesIX.     Revision HistoryX.      Bug ReportsXI.	Supported HardwareXII.    DisclaimerXIII.   AcknowledgementsI.  Introduction to SPHERESPeech HEader REsources (SPHERE) is a software package developed bythe National Institute of Standards and Technology (NIST) AutomatedSpeech Recognition Group to provide an interface to NISTSPHERE-formatted speech waveform files.  (The acronym, SPHERE, has nowcome to represent the format of the files as well as the softwarepackage.)  The SPHERE package contains two primary user-oriented softwarecomponents:	1.  C-language programmer interface library	2.  C-language system-level file manipulation utilitiesThe C-language programmer interface library has been developed toprovide a simple, intuitive interface to access and manipulate SPHEREfiles.  The library has been specifically designed to mimic the syntaxand 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 usingthe SPHERE library and provide command-line-level manipulation ofSPHERE files as well as functional examples of the usage of the SPHERElibraries.Where former versions of SPHERE provided only speech file headeraccess, Version 2.0 provides waveform access as well in both theC-language programmer interface and system-level utilities.  Embeddedu-law, shorten, and wavpack compression/decompression is alsosupported.II.  C-language Programmer Interface Library.    The SPHERE interface library functions provide a high-levelC-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 manipulationof file headers and bodies (waveforms). The functions have beenlogically 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 functions1.  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 andcontrols the opening of files.  Upon opening for read operations, aSPHERE file structure is formed and the header is loaded.  Forwrite operations, a SPHERE file structure is formed and an emptyheader is created.   The 'sp_close' function is analogous to the C-language 'fclose' functionand closes the specified SPHERE file and frees up associated allocatedmemory.2.  Header manipulation functions:   Opened SPHERE header structures are manipulated via a set of headerfield functions to retrieve, write, and delete fields.  The function,'sp_h_get_field', is used to retrieve the contents of the three typesof SPHERE fields.  Likewise, the function, 'sp_h_set_field', is usedto establish the contents of the three types of SPHERE fields.  Thesefunctions are somewhat analogous to the C-language 'gets' and 'puts'functions.  The function, 'sp_h_delete_field', is used to remove afield from a header.    The function, 'sp_copy_header', is used to copy the header of anopened SPHERE header to another opened SPHERE header.3.  Waveform I/O and conversion functions   A set of three functions has been established to handle waveformI/O.  The first, 'sp_read_data', is used to load a block of waveformdata from a SPHERE file into memory.  This function is analogous tothe C-language 'fread' function.  Likewise, the function,'sp_write_data', is used to flush a block of waveform data in memoryto SPHERE file and is analogous to the C-language 'fwrite' function.The function, 'sp_set_data_mode', is used to change the defaultbehavior of 'sp_read_data' and 'sp_write_data' and controls suchvariables as the conversion of waveform encodings and the byte orderduring 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 toprovide 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 addedto allocate and de-allocate memory and create data structures to holdwaveform data.  The functions use the header information to computethe size required for the buffers.	The following sub-sections contain a detailed description template foreach 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 functionsII.A   File Access FunctionsII.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 allocatedfor 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 FunctionsII.B.1 sp_h_get_field()Description:    Gets the specified header field value from an opened SPHERE fileheader.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', oftype, '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.  Thecopied string is a NULL terminated sequence of characters.  It is theprogrammer's responsibility to deallocate this memory using theC-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 fileheader.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 theopened SPHERE file header, then the field is created.Note: If a file is opened for write (using 'sp_open'), then thisfunction may only be called before using 'sp_write_data'.  Also, thefields, 'sample_coding', 'sample_byte_format', 'sample_count','sample_n_bytes', 'sample_checksum', are set automatically by thefunction, '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: