sphere.doc

speech signal process tools

		/* the SPHERE-library functions               */
        };

        struct spfile_status_t {
	        /* This structure is intended for use only by */
		/* the SPHERE-library functions               */
	};

	struct header_t {
	        /* This structure is intended for use only by */
		/* the SPHERE-library functions               */
	};



V.  Installation

To install SPHERE on a Unix system, cd into the 'nist' directory of
the SPHERE distribution hierarchy and type the command:

	sh src/scripts/install

The SPHERE libraries will be created and placed in the 'lib'
directory, and the sample programs, described in the 'System-Level
Utilities' section, will be compiled and placed in the 'bin'
directory.  Installation on non-Unix systems without "make" and "sh"
will probably require manual compilation.  The next release of SPHERE
will support compilation of SPHERE on PC's.

Included with this release is a functional interface test program
which exercises various header manipulation and waveform
compression/decompression functions.  To run the test, execute the
command from the 'nist' directory in the distribution hierarchy:

	tsphere -d lib/data

The program requires the files in the 'lib/data' directory of the
SPHERE distribution hierarchy.  If all is well, the program will run
without errors.  If an error occurs, send a bug report as specified in
the 'Bug Reports' section.



VI.  Linking to the SPHERE library

User programs are linked with two object code libraries:

	libsp.a       - user level SPHERE functions
			include compression code
	libutil.a     - SPHERE-internal functions

Both libraries must be 'linked' for successful use of SPHERE.
During the installation process, the source code for these
libraries is placed in the 'lib' directory of the distribution
hierarchy.   

User programs must include the following line in order to link
with the SPHERE libraries:

	#include <sp/sphere.h>

This include file references all of the required library files.

If the user's programs were written using a SPHERE version 2.0 beta 1
to SPHERE version 2.1, the new syntax for sp_read_data and
sp_write_data needs to be taken into consideration, (see Section II
for function descriptions).  There are two ways to use the old code,
either change the code to conform to the new syntax, or do not
re-write the code, but set a pre-processor variable, "SPHERE_PRE_2_2".
The pre-processor variable can be set in two locations, the choice
of location depends on the choice of the programmer. 

	1. The first location is in each source file which includes
	   the "sp/sphere.h" file.  Before the include statement for
	   "sp/sphere.h", put in the define statement
	   "#define SPHERE_PRE_2_2".  This allows flexibility for each
	   source code file.

	2. The second location is in the "sp/sphere.h" file itself.
	   Simply uncomment the define for "SPHERE_PRE_2_2" on line 36.
	   Now every program which includes "sp/sphere.h" must use
	   the old syntax of sp_read_data and sp_write_data.

In either case, the include file will then properly handle all
references to sp_read_data and sp_write_data.

To compile a program, such as the command-line SPHERE utility,
'w_decode', which is found in the 'src/prog' directory, execute
the 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 the
SPHERE library, you may send a bug report as specified in the 'Bug
Reports' section and someone will assist you.



VII.  Example Interface Library Usage

Example 1: To load the embedded shorten-compressed 2-byte-per-sample
PCM file, "file.wav", into memory in its uncompressed form.  This version
uses the SPHERE 2.2 and later function call to sp_read_data.

    SP_FILE *sp;
    short *waveform;
    SP_INTEGER 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,"sample_count",T_INTEGER,&sample_count) > 0)
	return(-1);

    if ((waveform=(short *)sp_data_alloc(-1)) == (short *)0){
        fprintf(stderr,"Error: Unable to allocate waveform memory\n");
        exit(-1);
    }
    
    if (sp_read_data(waveform,total_samples,sp) != samples_count){
        fprintf(stderr,"Error: reading speech waveform\n");
	sp_return_status(stderr);
        exit(-1);
    }
                     .
                     .
                     .

    sp_data_free(sp,(void *)waveform);
    sp_close(sp);  /* deallocates the header & buffers */


Example 2: To load a single-channel ulaw file, "ulaw.wav", and convert
it to a 2-byte-per-sample PCM format.  This 

    #define SPHERE_PRE_2_2
    #include <sp/sphere.h>
    SP_FILE *sp=SPNULL;
    short *waveform;
    SP_INTEGER channel_count, sample_n_bytes, sample_count;
    int wave_byte_size, total_samples, samp_read;

    printf("-- Documentation Example 2\n");
    if ((sp = sp_open(EX4_ULAW,"r")) == SPNULL) {
        fprintf(stderr,"Error: Unable to open SPHERE file %s\n",EXAMPLE4_ULAW);
	sp_print_return_status(stdout);
	exit(-1);
    }

    if (sp_set_data_mode(sp, "SE-PCM-2") > 0){
	sp_print_return_status(stdout);
	sp_close(sp);
	exit(-1);
    }
    if (sp_h_get_field(sp,"channel_count",T_INTEGER,&channel_count) > 0){
	fprintf(stderr,"Error: Unable to get the '%s' field\n",
		"channel_count");
	sp_close(sp);
	exit(-1);
    }
    /*  When the sd_set_data_mode() function is called to convert the file */
    /*  from ulaw to pcm, the sample_n_bytes in the header is automatically*/
    /*  changed to 2                                                       */
    if (sp_h_get_field(sp,"sample_n_bytes",T_INTEGER,&sample_n_bytes) > 0){
	fprintf(stderr,"Error: Unable to get the '%s' field\n",
		"sample_n_bytes");
	sp_close(sp);
	exit(-1);
    }
    if (sp_h_get_field(sp,"sample_count",T_INTEGER,&sample_count) > 0){
	fprintf(stderr,"Error: Unable to get the '%s' field\n","sample_count");
	sp_close(sp);
	exit(-1);
    }

    total_samples=sample_count * channel_count;
    wave_byte_size=sample_n_bytes * total_samples;

    printf("---- Example 2: Expected channel_count=1,      Actually=%d\n",
		channel_count);
    printf("---- Example 2: Expected sample_n_bytes=2,     Actually=%d\n",
		sample_n_bytes);
    printf("---- Example 2: Expected sample_count=16000,   Actually=%d\n",
		sample_count);
    printf("---- Example 2: Expected total_samples=16000,  Actually=%d\n",
		total_samples);
    printf("---- Example 2: Expected wave_byte_size=32000, Actually=%d\n",
	wave_byte_size);

    if ((waveform=(short *)malloc(wave_byte_size)) == (short *)0){
        fprintf(stderr,"Error: Unable to allocate %d bytes for the waveform\n",
                       wave_byte_size);
	sp_close(sp);
	exit(-1);
    }
    
    if ((samp_read=sp_read_data(waveform,sample_n_bytes,total_samples,sp)) !=
                     total_samples){
        fprintf(stderr,"Error: Unable to read speech waveform, ");
	fprintf(stderr,"%d samples read\n",samp_read);
	sp_print_return_status(stderr);
	sp_close(sp);
	exit(-1);
    }
    sp_close(sp); /* deallocates the header & buffers */



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