libsp.a       - user level SPHERE functions			include compression code	libutil.a     - SPHERE-internal functionsBoth libraries must be 'linked' for successful use of SPHERE.During the installation process, the source code for theselibraries is placed in the 'lib' directory of the distributionhierarchy.   User programs must include the following line in order to linkwith the SPHERE libraries:	#include <sp/sphere.h>This include file references all of the required library files.To compile a program, such as the command-line SPHERE utility,'w_decode', which is found in the 'src/prog' directory, executethe following command:	cc -L<INSTALL_DIR>/nist/lib -I<INSTALL_DIR>/nist/include \		-o w_decode w_decode.c -lsp -lutil -lm        where "INSTALL_DIR" is the directory where the SPHERE library        source code is located.If an unresolvable error occurs in compiling a program which uses theSPHERE library, you may send a bug report as specified in the 'BugReports' section and someone will assist you.VII.  Example Interface Library UsageExample 1: To load the embedded shorten-compressed 2-byte-per-samplePCM file, "file.wav", into memory in its uncompressed form.    SP_FILE *sp;    short *waveform;    long channel_count, sample_n_bytes, sample_count;    int wave_byte_size, total_samples;    if ((sp = sp_open("file.wav","r")) != (SP_FILE *)0) {        fprintf(stderr,"Error: Unable to open SPHERE file %s\n","file.wav");        return(-1);    }    if (sp_h_get_field(sp,"channel_count",T_INTEGER,&channel_count) > 0)	return(-1);    if (sp_h_get_field(sp,"sample_n_bytes",T_INTEGER,&sample_n_bytes) > 0)	return(-1);    if (sp_h_get_field(sp,"sample_count",T_INTEGER,&sample_count) > 0)	return(-1);    total_samples=sample_count * channel_count;    wave_byte_size=sample_n_bytes * total_samples;    if ((waveform=(short *)malloc(wave_byte_size)) == (short *)0){        fprintf(stderr,"Error: Unable to allocate %d bytes for the waveform\n",                       wave_byte_size);        exit(-1);    }        if (sp_read_data(waveform,sample_n_bytes,total_samples,sp) !=                     total_samples){        fprintf(stderr,"Error: reading speech waveform\n");	sp_return_status(stderr);        exit(-1);    }                     .                     .                     .    sp_close(sp);  /* deallocates the header & buffers */Example 2: To load a single-channel ulaw file, "ulaw.wav", and convertit to a 2-byte-per-sample PCM format.    SP_FILE *sp;    short *waveform;    long channel_count, sample_n_bytes, sample_count;    int wave_byte_size, total_samples;    if ((sp = sp_open("ulaw.wav","r")) != (SP_FILE *)0) {        fprintf(stderr,"Error: Unable to open SPHERE file %s\n","file.wav");        return(-1);    }    sp_data_mode(sp, "SE-PCM-2");    if (sp_h_get_field(sp,"channel_count",T_INTEGER,&channel_count) > 0)	return(-1);    if (sp_h_get_field(sp,"sample_n_bytes",T_INTEGER,&sample_n_bytes) > 0)	return(-1);    if (sp_h_get_field(sp,"sample_count",T_INTEGER,&sample_count) > 0)	return(-1);    total_samples=sample_count * channel_count;    wave_byte_size=sample_n_bytes * total_samples;    if ((waveform=(short *)malloc(wave_byte_size)) == (short *)0){        fprintf(stderr,"Error: Unable to allocate %d bytes for the waveform\n",                       wave_byte_size);        exit(-1);    }        if (sp_read_data(waveform,sp->sample_n_bytes,total_sample,sp) !=                     total_samples){        fprintf(stderr,"Error: reading speech waveform\n");	sp_return_status(stderr);        exit(-1);    }                     .                     .                     .    sp_close(fp);  /* deallocates the header & buffers */Example 3: To load the SPHERE file, "file.wav", update the contentsof the header, and then change the header on disk.    SP_FILE *sp;    char *db_version, new_db_version[10];    if ((sp = sp_open("file.wav","u")) != (SP_FILE *)0) {        fprintf(stderr,"Error: Unable to open SPHERE file %s\n","file.wav");        return(-1);    }    /******  Delete a header field  ******/    if (sp_h_delete_field(sp,"prompt_id") == 0){        fprintf(stderr,"Error: Unable to delete header field");	fprintf(stderr," 'prompt_id' from %s\n", "file.wav");        fprintf(stderr,"       Field does not exist\n");        break;    } else {        fprintf(stderr,"Error: Unable to delete header field");	fprintf(stderr," 'prompt_id' from %s\n", "file.wav");	sp_return_status(stderr);        return(-1);    }    /******  Add a header field  ******/    if (sp_h_set_real(sp, "signal-to-noise", 55.4) > 0){	fprintf(stderr,"Error: Unable to add the 'signal-to-noise' field ");        fprintf(stderr," %s\n","file.wav");	sp_return_status(stderr);        return(-1);    }    /******  Change a header field  ******/    if (sp_h_get_string(sp, "database_version", &db_version) > 0){	fprintf(stderr,"Error: Unable to get the 'database_version' field from %s\n",	               "file.wav");	sp_return_status(stderr);        return(-1);    }    sprintf(new_db_version,"%3.2f",atof(db_version)+1.0);    if (sp_h_set_string(sp, "database_version", new_db_version) > 0){	fprintf(stderr,"Error: Unable to set the 'database_version' field from %s\n",	               "file.wav");	sp_return_status(stderr);        return(-1);    }    free(db_version);             .             .             .    sp_close(fp);  /* deallocates the header & buffers */VIII.  System-Level Utilities    The following are command-line utilities which have been created using    the SPHERE libraries.  These programs provide the ability to read,    write, and modify SPHERE headers and to compress/decompress    SPHERE-headered waveforms.    h_read [options] [file ...]        reads headers from the files listed on the command line; by default,	output is lines of tuples consisting of all fieldnames and values;	many options modify the program's behavior; see the manual page	"h_read.1";    h_add inputfile outputfile        adds an empty header to the "raw" unheadered speech samples in	inputfile and stores the result in outputfile;    h_strip inputfile outputfile        strips the SPHERE header from inputfile, stores the remaining data in	outputfile; if outputfile is "-", writes the sample data to "stdout";    h_edit [-uf] [-D dir] -opchar fieldname=value ... file ...    h_edit [-uf] [-o outfile] -opchar fieldname=value ... file        edit specified header fields in the specified file(s).  In the first	form, it either modifies the file(s) in place or copies them to the	specified directory "dir".  In the second form, it either modifies	the file in place or copies it to the specified file "outfile".        The "-u" option causes the original files to be unlinked (deleted)	after modification.  The "-f" option forces the program to continue	after reporting any errors.        The "opchar" must be either "S","I", or "R" to denote string,	integer, or real field types respectively.    h_delete [-uf] [-D dir] -F fieldname ... file ...    h_delete [-uf] [-o outfile] -F fieldname ... file        delete specified header fields in the specified file(s). In the first	form, it either modifies the file(s) in place or copies them to the	specified directory "dir".        In the second form, it either modifies the file in place or copies it	to the specified file "outfile".        The "-u" option causes the original files to be unlinked (deleted)	after modification.  The "-f" option forces the program to continue after	reporting any errors.    w_encode [-mvf] -t [ wavpack | shorten | ulaw ]  file_in file_out    w_encode [-mvi] -t [ wavpack | shorten | ulaw ]  file1 file2 . . .         Encode the file as the type defined by the "-t" option.  The program	will use the header information to optimize the compression scheme.	The default operation is to encode the file specified in	"file_in" and place the contents into the file specified in	"file_out".  If the filenames specified in "file_in" or "file_out"	are "-", then stdin and stdout are used respectively.  In addition,	an error will be generated if "file_out" already exists. The "-f"	option causes an existing "file_out" to be overwritten.        The waveform I/O routines automatically convert the byte order of a	file to the host machine's natural format.  The "-m" option forces	the encoding to maintain the original byte order of "file_in".        The "-i" option forces w_encode to replace the input file with it's	encoded version.  When this "in place" option is used, the header is	modified to indicate the new encoding as well.  This option also	allows more than one input file to be specified on the command line.        The "-v" option gives verbose output.    w_decode [-vf] -o [ short_10 | short_01 | short_natural | ulaw ]  file_in file_out    w_decode [-vi] -o [ short_10 | short_01 | short_natural | ulaw ]  file1 file2 . . .         Decode the input file into the output format specified by "-o".  If	the file is already encoded as specified, no action is taken.        w_decode reads the header and sample data and performs conversions on	the output as necessary.  The default operation is to decode the file	specified in "file_in" and place the contents into the file specified	in "file_out".  If the filenames specified in "file_in" or "file_out"	are "-", then stdin and stdout are used respectively.  In addition,	an error will be generated if "file_out" already exists.  The "-f"	option causes an existing "file_out" to be overwritten.        The "-i" option forces w_encode to replace the input file with it's	encoded version.  When this "in place" option is used, the header is	modified to indicate the new encoding as well.  This option also	allows more than one input file to be specified on the command line.        The "-v" option gives verbose output.IX.  Revision HistoryChanges in Release 1.5:	1. New functions were added to the Sphere library:		sp_get_fieldnames()		sp_get_type()		sp_get_size()		sp_is_std()		(see the sphere library man page for descriptions)	2. h_read: command line options were changed	3. h_strip: writes to stdout if destination is "-"	4. man page for h_readChanges in Release 1.6:	1. Utilities that use h_modify.c are now much faster in		most cases when editing in-place -- if the size		of the header does not change, the new header is		copied over the old one.	2. Modified sp_write_header() to work when writing to		objects other than files. The function ftell()		was previously used directly on the output		stream to ascertain the number of bytes		in the header; now the header is written		to a temp file to ascertain the header size,		then to the output stream.	3. Modified to sp_open_header() and spx_read_header()		to no longer test if the input file is at		position 0. This will allow reading from		pipes, etc.	4. h_add: can read from stdin and/or write to stdout;		no longer puts any dummy fields in the header.	5. h_strip: can now read from stdin in addition to		writing to stdout.	6. Added h_header and raw2nist to the Sphere package.		They are Bourne shell scripts (/bin/sh) to,		respectively, print file headers and convert raw		data (no header) to Sphere format.	7. Manual pages for commands h_edit, h_delete, h_add,		h_strip and raw2nistChanges in Release 1.7:	1. h_read: added "-C field" option to check that the		specified field(s) is in the headers of all files		on the command line.Changes in Release 2.0 Beta:	1. SPHERE now has a new functional interface to waveform data		and headers.  The unified approach is detailed in the                "C-Language Programmer Interface Library" section.	2. Library libsp.a won't be removed if "make" is interrupted.	3. Using ANSI functions instead of BSD equivalents:		index() -> strchr()		rindex() -> strrchr()		bcopy() -> memcpy()		bzero() -> memset()	4. Include file changes:		<stdlib.h>: rand(), malloc(), realloc(), etc.		<string.h>: replaces <strings.h>		<errno.h>: errno		"getopt.h": getopt(), optind, optarg	5. The function getopt() is now expected to return -1		when there are no more command line arguments		to be parsed. Previously, it was expected  to		return EOF.  resetopt() clears the history state		of getopt() to enable re-using getopt().	6. New programs "w_encode" and "w_decode" allow sampled                waveform data to be compressed (w_encode) or                decompressed (w_decode) using either the "wavpack" or                "shorten" algorithms.	7. Waveform encoding functions added including a set                to allow data to be compressed using the "wavpack" or		"shorten" algorithms with input and/or output		data coming from memory or a file pointer, and		a set of analogous functions for decompression.	Changes in Release 2.0 Beta 2:	1. Corrected Known Software Bugs:		a. The function 'set_data_mode' should have been named 		   'sp_set_data_mode'.		b. Waveforms without checksums are now readable.		c. the installation process was updated.	2. Function Changes:		a. The function 'sp_return_status' was renamed to 		   'sp_print_return_status'.		b. A new function was written 'sp_get_return_status'		   which allows the programmer to retrieve the return		   status of the last function call.		   	3. Merged the libraries to simplify the linking procedures.		- see the Linking to the SPHERE library Section of the		  SPHERE Manual	4. Re-designation of required header fields.		- see the File Format Definition Section of the		  SPHERE Manual	5. Decompression will use a temporary file if the waveform size	   is larger the a specified byte size.  (Details of modifying the	   variable will be added to the installation script in a future	   release.)	6. Addition of 'shortpack' decompression to facilitate reading	   of the WSJ0 Write-Once CD-ROMS.X.  Bug ReportsPlease send bug reports to 'sphere-bugs@jaguar.ncsl.nist.gov'.  Or viapostal-mail to:	Jon Fiscus	National Institute of Standards and Technology	Bldg. 225, Room A-216	Gaithersburg, MD 20899XI.  Supported HardwareThe SPHERE functions and programs have been developed in Sun-C on aSun Microsystems workstation running SunOS 4.1.1 and 4.1.2.  To date,SPHERE 2.0 has been tested on SPARC-based UNIX systems, NeXT workstations, and DEC Alpha Workstations.  It is currently beingtested on a SGI Indigo workstation.Once SPHERE 2.0 has completed Beta testing, NIST plans to convertingit to ANSI C for maximum portability.  NIST then plans to port SPHEREto the PC platform.XII.  DisclaimerThese software tools have been developed for use within the ARPAspeech research community.  Although care has been taken to ensurethat this software is complete and error-free, it may not meet allusers' requirements.  As such, it is made available to the speechresearch community at large, without endorsement, or express orimplied warranties by the National Institute of Standards andTechnology, the Department of Defense, or the United StatesGovernment.XIII.  AcknowledgementsThe SPHERE file format was designed by John Garofolo at NIST.The SPHERE-internal low-level functions were designed by John Garofoloand Stanley Janet and coded by Stanley Janet at NIST.The SPHERE 2.0 Programmer Interface Library was designed by JohnGarofolo and Jon Fiscus and coded by Jon Fiscus at NIST.The Shorten compression algorithm was developed and implemented byTony Robinson at Cambridge University.The Wavpack compression algorithm was developed and implemented byDoug Paul at MIT Lincoln Laboratories.NIST would like to thank those people who provided constructivesuggestions during the design of SPHERE 2.0. and NIST would like toparticularly thank Tony Robinson for his help in integrating 'shorten'into the SPHERE interface.