sphere.doc

speech signal process tools

	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.  

|	The opchar, "K", can be used to delete, or (K)ill, the field.
	

    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 OUTTYPE ] file_in file_out
    w_decode [-vi] [ -o OUTTYPE ] file1 file2 . . . 
	Where:
		OUTTYPE = short_10 | pcm_10 | 
			  short_01 | pcm_01 |
			  short_natural | pcm |
			  ulaw 
        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.

    w_edit [-vf] -o [-[t|p]F:T]] [-oOUT ] { filein | - } { fileout | - }

        W_edit is a  waveform  editing  command  to  manipulate  and
        extract  samples  the  waveform  data in a sphere file.  The
        following functions can be performed on a file:


        -tF:T   Set the range for output from time  F  (seconds)  to
                time  T.  If F is missing, it defaults to the begin-
                ing of the file, if T is missing, go to the end  of
                the file.

        -sF:T   Set the range for output from F samples  to  T  sam-
                ples.  If F is missing, it defaults to the beginning
                of the file, if T is missing, go to the end  of  the
                file.

        -cEXP   Extract only the samples from channels in EXP.   The
                expression  will  also  add channels together if the
                '+' is used.

        -oOUT   Set the output format to the following formats:

                ulaw
                   output the samples as ulaw encoding.

                pcm_01 | short_01
                   output  the  samples  as   PCM   values   in   01
                   sample_byte_format

                pcm_10 | short_10
                   output  the  samples  as   PCM   values   in   10
                   sample_byte_format
 
                pcm | short_natural
                   output the samples as PCM  values  in  the  cpu's
                   natural byte format

        -v      option gives verbose output.


     w_diff w_diff [-hvdws] [-cCSTR] file1 file2

        W_diff is a waveform comparing program.  It can compare  the
        SPHERE  headers of two files as well as the data portions of
        two SPHERE files.  If the files do not  differ,  a  zero  is
        returned  by  the  program,  otherwise  a  non-zero value is
        returned.


        -cCSTR  Convert the files by the 'CSTR' used in  a  call  to
                sp_set_data_mode()

        -d      Compare the data portions of the files byte by byte.
  
        -h      Print this help message.

        -s      Compare the SPHERE headers of the files.

        -w      Compare the waveforms of the two  files  after  con-
                verting  them using the conversion string in 'CSTR'.
                This is the default

        -v      Set the verbosity level up by one, repeat the v  for
                higher  levels.   A verbosity setting of 1 will pro-
                vide a description of each tests outcome.


IX.  Revision History

Changes 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_read


Changes 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 raw2nist

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


Changes in Release 2.0 Beta 2.1:
	
	1. Corrected an unclosed file pointer problem which was activated
	   when uncompressing files.


Changes in Release 2.1:
 
        1. Corrected an improperly defined variable in sphio.c.
 
	2. Create the following new command line utilities:
		tsphere


Changes in Release 2.2:
	
	1. Added the ability to read and write ulaw data files.  This 
	   includes the following new abilities:
		a. Compute and verify a checksum for the one-byte 
		   sample data using the same algorithm but using
		   one byte data.
		b. Add the capability to read/write ulaw data as ulaw
		   or converted to 2-byte PCM data.  If the sample
		   type changes, a new checksum is computed.

	2. Added support for stereo (multi-channel) data files which
	   includes the following abilities:
		a. Added the ability to selectively read channels from a 
		   multi-channel file.
		b. Added the ability to add channels together for PCM
	 	   and ulaw data.
	   
	3. Changed the syntax for the sp_read_data and sp_write_data
	   functions.

	4. Created the following new library functions:
		sp_copy_header()
		sp_data_free()
		sp_data_alloc()

	5. Create the following new command line utilities:
		w_diff
		w_edit

	6. Added typedef's for the header values:
	  	SP_STRING, SP_INTEGER, SP_REAL
	
	7. Added setjmp to allow compression packages to return error
	   coded rather than aborting execution.	   

	8. All library messages now print to stderr.
	
	9. Update to tsphere to test new capabilties.
		a. Added Document Example 2 to the Tests.

	10. Converted the source code to be ANSI C Compliant.

	11. Added synonyms for the 'short', 'short_10' and 'short_01'
	   options to w_decode. 

	12. Made the default waveform format of a written file to
	   be 2-byte pcm data.  This correct a problem with missing
	   'sample_coding' fields in written files.

	13. Added a new library function, correct_out_of_date_headers(),
	   to handle out-of-date headers.  Currently, the function 
	   correct the incorrect sample count header field of Switchboard
	   files.

	14. Added a new library function, sp_compute_char_checksum()
	    to compute a 2-byte checksum one byte data.

	15. Fixed a bug in h_read's verify option '-V' when used on
	    multi-channel data.

Changes in Release 2.3:

	1. Repaired Non-ANSIism reported by Charles Hemphill.
		a. Removed the use of bcopy in favor of memcpy (everywhere).
		b. Added the include of "string.h" into
		   'src/lib/util/string.c', 'src/bin/tsphere.c',
		   'src/lib/sp/nat_bord.c', 'src/lib/util/hsgetopt.c',
		   'src/lib/sp/dif_wavf.c'
		c. Removed the use of index() in favor of strchr (everywhere).
		   'src/lib/sp/sdatamod.c'
		d. Added code to allow the use of 'ntohl()' and 'htons()'
	 	   in the shortpack library.

	2. Fixed a problem in the Shortpack library.  The function
	   getw() was used instead of fob_getw().

	3. Removed prototypes for function prototype in shorten.h.

	4. Changed the function prototypes for strlen and strcmp in
	   'hs_getops.c'.

	5. Improved SPHERE's ability to be used with pipe-based software.
	   This makes an exception for a missing 'sample_count' field
	   if the SPHERE file was opened for stdin or stdout.

	6. Corrected some errors in 'src/lib/dif_wav.c'.
	   
Changes in Release 2.4:

	1. Corrected a return message for 'sp_set_data_mode()' error
	   code 128.
	
	2. Added a fourth example to the documentation and to 'tsphere'.
	   The example creates a SPHERE headered signal file.

	3. Corrected an error in spoutput.c, proceedure sp_write_header().
	   The temporary files where not being deleted properly. 

	4. Repaired an error in sp_write_header() that was only activated
	   on specific platforms.  The code used sprintf to create a
	   fixed portion of the sphere header and on some machines, sprintf
	   writes extra data after the end of the string.

	5. Fixed problems in sp_write_data() and sp_read_data() where