sphere.doc

speech signal process tools

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_alloc_data.  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>

The first line specifies the header type and the second line specifies the
header length.  Each of these lines are 8 bytes long (including new-line) and
are structured to identify the header as well as allow those who do not wish
to read the subsequent header information to programmatically skip over it. 

The remaining object-oriented variable portion is composed of
object-type-value "triple" lines which have the following format:


<LINE> --> <TRIPLE><new-line> |
           <COMMENT><new-line> | 
           <TRIPLE><COMMENT><new-line> | 

  <TRIPLE> --> <OBJECT><space><TYPE><space><VALUE><OPT-SPACES>

    <OBJECT> --> <PRIMARY-SUBOBJECT> | 
                 <PRIMARY-SUBOBJECT><SECONDARY-SUBOBJECT>

    <PRIMARY-SUBOBJECT> --> <ALPHA> | <ALPHA><ALPHA-NUM-STRING>
    <SECONDARY-SUBOBJECT> --> _<ALPHA-NUM-STRING> | 
                              _<ALPHA-NUM-STRING><SECONDARY-SUBOBJECT>

    <TYPE> --> -<INTEGER-FLAG> | -<REAL-FLAG> | -<STRING-FLAG>

      <INTEGER-FLAG> --> i
      <REAL-FLAG> --> r
      <STRING-FLAG> --> s<DIGIT-STRING>
      
    <VALUE> --> <INTEGER> | <REAL> | <STRING>  (depending on object type)

      <INTEGER> --> <SIGN><DIGIT-STRING>
      <REAL> --> <SIGN><DIGIT-STRING>.<DIGIT-STRING> 

    <OPT-SPACES> --> <SPACES> | NULL

  <COMMENT> --> ;<STRING>  (excluding embedded new-lines)

<ALPHA-NUM-STRING> --> <ALPHA-NUM> | <ALPHA-NUM><ALPHA-NUM-STRING>
<ALPHA-NUM> --> <DIGIT> | <ALPHA>
<ALPHA> --> a | ... | z | A | ... | Z
<DIGIT-STRING> --> <DIGIT> | <DIGIT><DIGIT-STRING>
<DIGIT> --> 0 | ... | 9
<SIGN> --> + | - | NULL
<SPACES> --> <space> | <SPACES><space>
<STRING> -->  <CHARACTER> | <CHARACTER><STRING>
<CHARACTER> --> char(0) | char(1) | ... | char(255)

The following fields are required for proper SPHERE I/O handling.
These fields completely describe the geometry of the data contained in
the SPHERE file.

        Field_name         Field_type
	----------         ----------
	sample_count           -i      (Defined to be the number of samples
					per channel)
	sample_n_bytes         -i
	channel_count          -i

The following fields are optional:

        Field_name         Field_type
	----------         ----------
	sample_checksum        -i       
        sample_coding          -s       (If missing, defaults to 'pcm')
        sample_byte_format     -s       (If missing, defaults to the Host's
                                         natural byte format.)

The following fields are conditionally required:

        Field_name         Field_type   Required if:
	----------         ----------   ------------
	sample_rate            -i       (the 'sample_coding' field is
					 missing, or contains 'pcm' or 'ulaw')

Possible values for these fields are:

	sample_count -> 1 .. MAXINT
	sample_n_bytes -> 1 | 2
	channel_count -> 1 .. 32
	sample_byte_format -> 01 | 10 | 1 (* See below for exception)
	sample_checksum -> 0 .. 32767
	sample_rate -> 1 .. MAXINT
	sample_coding -> pcm | ulaw | pcm,embedded-shorten-vX.X | 
			 ulaw,embedded-shorten-vX.X |
			 pcm,embedded-wavpack-X.X | 
			 ulaw,embedded-wavpack-X.X |
			 pcm,embedded-shortpack-X.X (Read Only)

	* Note: The original recordable CD-ROM release of WSJ0 incorporated
	        "shortpack" waveform compression.  The compression was 
		indicated by the now outmoded presence of the string,
		'shortpack-v0',	in the 'sample_byte_format' field.
		Since this software attempts to support all previous
		NIST releases of speech corpora, this "non-standard"
		field value is permitted.  Please note that this
		software will not generate files with this field value
		and that the LDC is producing a CD-ROM release of WSJ0
		which conforms to the specifications defined in SPHERE 2.0.

The single object "end_head" marks the end of the active header and the
remaining unused header space is undefined. A sample header is included
below.

Example SPHERE header from the TIMIT corpus (NIST Speech Disc 1-1.1):

NIST_1A
   1024
database_id -s5 TIMIT
database_version -s3 1.0
utterance_id -s8 aks0_sa1
channel_count -i 1
sample_count -i 63488
sample_rate -i 16000
sample_min -i -6967
sample_max -i 7710
sample_n_bytes -i 2
sample_byte_format -s2 01
sample_sig_bits -i 16
end_head


Example SPHERE header from the CSR Phase II corpus:

NIST_1A
   1024
microphone -s21     Sennheiser HMD414
recording_site -s4  SRI
database_id -s8     wsj1
database_version -s3 1.0
recording_environment -s38 quiet office, door closed (room EJ186)
speaker_session_number -s2 01
session_utterance_number -s2 01
prompt_id -s8 adapt.01
utterance_id -s8 460a0101
speaking_mode -s15 read-adaptation
speaker_id -s3 460
sample_count -i 82561
sample_min -i -560
sample_max -i 655
sample_checksum -i 27320
recording_date -s11 11-Nov-1992
recording_time -s11 12:14:16.00
channel_count -i 1
sample_rate -i 16000
sample_n_bytes -i 2
sample_byte_format -s2 01
sample_sig_bits -i 16
sample_coding -s25 pcm,embedded-shorten-v1.1
end_head



IV.  File Pointer Structure

The following is a description of the file pointer structure used by
SPHERE to address opened files.

The structure includes pointers to the parsed header, the waveform,
and a structure used by SPHERE to track the status of various
operations on the opened file.

NOTE:   The SPHERE file pointer structure has been designed to be used
	exclusively by the SPHERE library functions.  The programmer
	should only include the structure in argument lists passed to
	SPHERE function calls.  The programmer should NOT attempt to
	manipulate this structure directly.


    SPHERE Structure 'SP_FILE' 

	typedef struct sphere_t SP_FILE;

	struct sphere_t {
       		struct header_t *header;
                struct waveform_t *waveform;
		struct spfile_status_t *status;
	};

        struct waveform_t {
	        /* This structure is intended for use only by */