SPeech HEader REsources (SPHERE) Version 2.0 Beta2			   August 27, 1993                   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.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.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()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.   AcknowlegementsI.  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 four 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 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.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.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 functions	II.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.    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 field_type values:       T_STRING    (string field type [char*])       T_INTEGER   (integer field type [long*])       T_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.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 field_type values:       T_STRING    (string field type [char*])       T_INTEGER   (integer field type [long*])       T_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,the fields, 'sample_coding', 'sample_byte_format', 'sample_count','sample_n_bytes', 'sample_checksum', are set automatically bythe function, 'sp_set_data_mode', and should not be set manuallyif 'sp_set_data_mode' has been called.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:    Deletes the specified header field from an opened SPHERE fileheader.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', doesnot exist in the opened SPHERE file header, sp_h_delete_field() willnot complain, but will return a special value (see below).  ReturnValue:Return Value:    sp_h_delete_field() returns a 0 on sucess, a 1 if the headerfield does not exist, and a 100 or greater on error.See Also:    sp_open(), sp_h_set_field(), sp_h_get_field()II.C   Waveform I/O FunctionsII.C.1 sp_read_data()Description:       Reads blocks of waveform data from an opened SPHERE file.Syntax:    int sp_read_data(void *ptr, size_t size, size_t n, SP_FILE *sp_file)Arguments:    Reads 'n' elements of size 'size' (in bytes) from the waveformdata section of the opened SPHERE file pointed to by 'sp_file'.Performs the read (including any conversions as necessary) to formatthe data according to the primary (base) encoding specified in theheader field, 'sample_coding'. Remarks:    If there is no 'sample_coding' field in the header, the defaultoperation 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 inthe header, the checksum is verified after reading the last block of data.Return Value:    The value returned by 'sp_read_data' indicates the number ofelements read in from the file.  If no elements are read, a zero isreturned.  Likewise, if an error or checksum verification erroroccurs, a zero is returned.  The functions 'sp_eof()' and 'sp_error()'may be used to determine if an error or an immediate end-of-filecaused the zero to be returned.See Also:    sp_eof(), sp_error(), sp_set_data_mode()II.C.2 sp_write_data()Description:       Writes blocks of waveform data to an opened SPHERE file.Syntax:    int sp_write_data(void *ptr, size_t size, size_t n, SP_FILE *sp_file)Arguments:    Appends 'n' elements of size 'size' (in bytes) to the end of thewaveform data section of the opened SPHERE file pointed to by'sp_file'.Remarks:    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 tobe written.  The default behavior is for the data to be written asit is represented in memory (as specified by the above header fields).    The default behavior of 'sp_write_data()' can be modified by thefunction 'sp_set_data_mode()' before 'sp_write_data()' is called.'sp_set_data_mode()' allows the programmer to specify waveform datatransformations as the data is written.Return Value:    The value returned by 'sp_write_data' indicates the number of