sphere.doc

speech signal process tools

Example 3: To load the SPHERE file, "file.wav", update the contents
of the header, and then change the header on disk.

    SP_FILE *sp;
    char *db_version, new_db_version[10];
    SP_REAL stnr=55.4;

    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", &stnr) > 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(sp);  /* deallocates the header & buffers */


Example 4: Create a single-channel PCM file, "example4.wav", using
the SPHERE libraries.  Note: This example has been implemented in the
SPHERE library testing program 'tsphere.c'.

    SP_FILE *spp;
    short *wavbuf;
    SP_INTEGER lint;
    SP_INTEGER buf_nsamp = 16000;
    SP_INTEGER nbyte = 2;
    SP_INTEGER srate = 16000;
    int stow, i;
    int samps_written=0, size=64000, status;
    char *name="example4.wav";
    double factor;	

    fprintf(spfp,"-- Documentation Example 4: File Creation example\n");
    fprintf(spfp,"---- filename: %s\n",name);

    if ((spp = sp_open(name, "w")) == SPNULL) {
	fprintf(spfp,"Couldn't open NIST waveform file: %s\n", name);
	sp_print_return_status(spfp); 	exit(-1);
    }

    fprintf(spfp,"---- Setting header fields\n");
    lint = size;
    if (sp_h_set_field(spp, "sample_count", T_INTEGER,(void *) &lint) != 0){
	fprintf(spfp,"Error: unable to set sample_count field\n");
	sp_print_return_status(spfp); 	exit(-1);
    }
    if (sp_h_set_field(spp, "sample_rate", T_INTEGER,(void *) &srate)){
	fprintf(spfp,"Error: unable to set sample_rate field\n");
	sp_print_return_status(spfp); 	exit(-1);
    }
    if (sp_h_set_field(spp, "sample_n_bytes", T_INTEGER, (void *) &nbyte)){
	fprintf(spfp,"Error: unable to set sample_n_bytes field\n");
	sp_print_return_status(spfp); 	exit(-1);
    }
    if (sp_h_set_field(spp, "sample_byte_format", T_STRING, (void *)"10")){
	fprintf(spfp,"Error: unable to set sample_byte_format field\n");
	sp_print_return_status(spfp); 	exit(-1);
    }
    if (sp_h_set_field(spp, "sample_coding", T_STRING, (void *)"pcm")){
	fprintf(spfp,"Error: unable to set sample_coding field\n");
	sp_print_return_status(spfp); 	exit(-1);
    }
    lint = 1;
    if (sp_h_set_field(spp, "channel_count", T_INTEGER, (void *)&lint)){
	fprintf(spfp,"Error: unable to set channel_count field\n");
	sp_print_return_status(spfp); 	exit(-1);
    }

    if (sp_set_data_mode(spp,"SE-PCM-2") != 0){
	fprintf(spfp,"Error: sp_set_data_mode failed\n");
	sp_print_return_status(spfp);
	exit(-1);
    }

    fprintf(spfp,"---- Allocating a waveform buffer\n");
    if ((wavbuf=(short *)sp_data_alloc(spp,buf_nsamp)) == (short *)0){
	fprintf(spfp,"Unable to malloc memory for wav buffer\n");
	exit(-1);
    }

    factor = 1.0 / 100.0 ;
    for (i=0; i<buf_nsamp; i++)
	wavbuf[i] = (short)(1000 * cos( M_PI * 2.0 * i * factor));


    fprintf(spfp,"---- Writing the waveform\n");
    while (samps_written < size){
	stow = (samps_written + buf_nsamp) < size ? buf_nsamp :
	    size - samps_written;
	status = sp_write_data((void *)wavbuf, sizeof(short), stow, spp);
	if (status != stow){
	    fprintf(spfp,"Couldn't write NIST waveform file: %s\n", name);
	    sp_print_return_status(spfp);
	    status = sp_error(spp);
	    sp_print_return_status(spfp);
	    sp_close(spp);
	    (void) mtrf_free((char *)wavbuf);
	    exit(-1);
	}	
	samps_written += stow;
    }
    fprintf(spfp,"---- Closing the file\n");
    sp_data_free(spp,wavbuf);
    if (sp_close(spp) != 0) {
	fprintf(spfp,"SP_close failed\n");
	sp_print_return_status(spfp);
	exit(-1);
    }
    fprintf(spfp,"\n");


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 [-vh] 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 -K fieldname ... file ...
    h_edit [-uf] [-o outfile] -opchar fieldname=value -K fieldname ... 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.  

|	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.  The 
	qualifiers "_10" and "_01" on the output types "short" and "pcm" 
	stand for byte orders MSB/LSB and LSB/MSB respectively.  The output
	types "pcm" and "short_natural" forces the byte order to be
	converted if necessary to the local machine's natural byte order.

        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.

	If the file size has been changed by either the '-t' or '-s' option,
	the program adds (or modifies) three header fields to describe 
	the origins of the data.  Two "REAL" type header fields, 'start_time'
	and 'end_time', are added to store the begin and end times of the
	new file in relation to the original file.  The third field, 
	'data_origins', is added to identify original file.  The field
	contains a comma separated list of fields from the original file
	including, "database_id", "database_version" (if present), and
	either "conversation_id", "utterance_id", or by default 'file1' from
	the command line.

     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