files.vtme

speech signal process tools

header (such as found on the TIMIT CD-ROM database).  This is
implemented by having the ESPS file header access routines, detect an
input file containing a NIST header and build an ESPS FEA_SD header from
it.   All header information in the NIST header is saved as generic
header items in the ESPS header.   
.sh 3 "Foreign Headers"
.lp
It is often desirable to maintain an existing file header even if a file
is converted to ESPS.   The non-ESPS header is called a foreign header
and it can be stored in the file between the ESPS header and the first
data record.
.lp
Foreign headers are kept in the ESPS header in the following manner:
The generic header item \fIforeign_hd_length\fP contains the size (in
bytes) of the foreign header.  If this item is present (and non-zero),
\fIread_header\fP() will read this many additional bytes of data, put
it into the header, and set an additional generic header item
\fIforeign_hd_ptr\fP to point to it.  From that point on, the foreign
header is just part of the ESPS header.  
.lp
With this mechanism, it is possible to write programs that 
use the ESPS header and record I/O functions while still having
access to the foreign header.  The procedure is simple: use 
\fIread_header\fP() to read the ESPS header, and \fIget_genhd\fP() 
to get the pointer to the foreign header.  
.lp
The conversion programs \fIbtosps\fR and \fIaddfeahd\fR would usually be
used to create such files.   See reference [7].
.sh 2 "Header Access Routines"
.lp
There are several \s-1ESPS\s+1 library routines that support access to the
\s-1ESPS\s+1 data file headers.    
These are described in detail in Section 3 of [1].
Declarations
for all these functions are found in \fI<esps/header.h>\fR; 
the programmer need not declare them if this file is included.
.lp
The \fIread_header\fR routine attempts to read a file header from a
stream (the fd parameter is typically one from a "fopen" call).  If an
I/O error occurs
\fIread_header\fR returns \s-1NULL\s+1.  
If the file does not begin with a valid ESPS header, then
\fIread_header\fR will determine if the file begins with a NIST header.
If a NIST header is present, then a FEA_SD header is generated and
filled in with the appropriate values from the NIST header (sample rate,
minimum and maximum sample values, data type, etc).   \fIRead_header\fR
then returns a pointer to this FEA_SD header in the usual way.
Programs which called \fIread_header\fR on a NIST file will operate
normally and not know that the file wasn't initially a normal ESPS
file.  If neither a valid ESPS header, or a NIST header in present, then
\fIread_header\fR will check for the \fIunix\fR environment variable
\fBDEF_HEADER\fR.  If it is defined and points to a file containg a
valid ESPS header, then that header is used instead.
If all of the above attempts to find a header fail, then NULL is
returned.
Memory for the file header is
allocated from dynamic memory.  After \fIread_header\fR returns, the
program should consult \fIcommon.type\fR to determine the type of the
header that has been returned.
.lp
The \fIwrite_header\fR routine attempts to write a file header onto a
stream.  It computes and fills in values for hsize, fixsiz, check,
date, and hdvers and ensures that must-be-zero fields contain zero, by
clearing them.  If an I/O error occurs, \fIwrite_header\fR writes an
error message and the program bombs.
.lp
The \fInew_header\fR routine allocates a new header from dynamic memory and
returns a pointer to it.   Which type-specific header is allocated
depends on the value of the argument \fItype\fR.    If \fItype\fR is
zero, then no type-specific header is allocated, only the common part
is.   This case is intended for use by the header access programs.  
.lp
The \fIcopy_header\fR routine accepts a pointer to a file header and
returns a copy of the same type in which all items except
common.comment, common.prog, common.vers, common.date,
common.progdate, and common.hdvers are copied from the source header.
This routine partially generates a header for an output file, given a
header for an input file (any changed parameters must be filled in,
along with the program name and version).  It is important to realize
that this function can only be used when the output file is of the
same type as the input file.
.lp
The \fIadd_source_file\fR routine inserts a source file name and header
into the next available positions in a header. The nnames and nheads
fields are incremented. Strictly speaking, only pointers are copied, so
the source parameters must not be altered before \fIwrite_header\fR is
called. 
.lp
The \fIadd_comment\fR routine appends a character string onto the
comment field of a header.  For example, with the help of
.i get_cmd_line
(3\-\s-1ESPS\s+1), the command line is added as a comment.  
All ESPS programs by convention add the command line as a comment in 
the output header.  
.lp
For creating \fIzfunc\fR structures, the function 
.i new_zfunc
is supplied.  It allocates dynamic memory, builds a new zfunc structure,
and returns a pointer to it. The zeros and poles are also copied to
dynamic memory.  To assist in storing \fIzfunc\fRs as generic 
header items 
the functions 
.i add_genzfunc
and
.i get_genzfunc
are provided.  
.lp
Generic header items are added to an existing header by the 
.i add_genhd_\fRX\fP
(3\-\s-1ESPS\s+1) routines ("X" stands for one of six possible data types).
Other generic-related header access routines are 
.i genhd_list,
which returns a list of the defined generic header items, 
.i genhd_type,
which returns the type of a specific generic header item, and 
.i get_genhd,
which returns a pointer to a specific generic header item.  These
routines make it possible for programs to process the generic 
header items in ESPS files without having to know what they are in 
advance.  
.sh 3 "Using the Header Access Routines"
.lp
The header access routines are easy to use.   The important
thing to remember is that, before
\fIwrite_header\fR is called, 
.i "all values must be set in the header."
The easiest error is to confuse pointers that might be in use pointing
to several different headers, most often the input and the output file.
The basic model of use is to open the input file and call
\fIread_header\fR on this file.  This allocates memory for the input
file header, checks the header on the input file, and reads to its end.
The next read on this file will return data, rather than header, values.
.lp
If \fIread_header\fR returns without error, then it has found a
valid \s-1ESPS\s+1 header.    The program should now check \fIcommon.type\fR
to be sure that the file is of the type expected by the program.
If it is not, then an error message should be printed and the
program should exit with a non-zero exit code (standard convention
is to use exit(1)).    Some programs may accept several (or any) of
the valid \s-1ESPS\s+1 file types.    These programs should still consult
\fIcommon.type\fR to determine which pointer in the union \fIhd\fR
to use.    The use of the wrong pointer will cause unpredictable
results (most often a harmless bus error, but worse could happen).
.lp
Since \fIread_header\fR returns a pointer to the main header structure,
a pointer must be declared 
before
.i read_header 
is called:
.vS
.nf

    struct header *h;
    .
    .
    .
    h = read_header(file);

.fi
.vE
After the call to 
.i read_header, 
items in the header may be accessed.  Here are some examples:
.vS
.nf

    char *ref_file;
    float frequency, avg_zero;
    .
    .
    .
    if (h->common.type == FT_SD) {	/*verify file type*/
        fprintf(stderr, "Input file is not an SD file.\n");
        exit(1)
    }
    ref_file = h->variable.refer;	/*get name of reference file for tags*/
    frequency = h->hd.sd.sf;		/*sampling frequency of data*/
    avg_zero = *(float *) get_genhd("zero_crossing", h);
        
.fi
.vE
.lp
In some ESPS programs (especially newer programs), the call to 
.i read_header
and the file type checking is done within a library function 
.i eopen,
which also opens the file.  An example of this is given later.  
.lp
If the output file of the program is the same type as the input file
then \fIcopy_header\fR is useful for creating the header of the new
output file and filling in most values from the input file.  Some of
these values might have to be changed before \fIwrite_header\fR is
called, but in many cases, the header of an output file is much like
that of its input file.  If the output file is of a different type than
the input file, or the programmer decides that none or very few values
will be in common, then \fInew_header\fR should be used to create the
header for the new output file.  A type code must be specified when
\fInew_header\fR is called.  In either case, when creating an output
\s-1ESPS\s+1 file from source \s-1ESPS\s+1 files, the source headers
should be saved in the new output header.  This is done by calling
\fIadd_source_file\fR.  Here is an example of reading values 
from the header of an input file, and creating and writing
an output file header.   
.vS
.nf

    char *speaker_name;
    float samp_freq, zero_crossing, *coh_thresh;
    long num_samples;
    .
    .
    .
    ih = read_header(in_file);    	/* get input header */
    speaker_name = (char *) get_genhd("speaker", ih);  /*generic example*/
    .
    .
    .
    oh = new_header(FT_FEA)		/* create new output header */
    (void) add_source_file(oh,in_file,ih);       /* save input header */
    oh->variable.refer = ih->variable.refer;   /*same refer file*/
    /*add the command line as a comment*/
    add_comment(oh, get_cmd_line(argc, argv));
    (void) strcpy (oh->common.prog, progname);
    (void) strcpy (oh->common.vers, Version);
    /*add generic header items*/
    (void)add_genhd_f("avg. zero crossing", &zero_crossing, 1, ih)
    coh_thresh = add_genhd_d("voicing threshold", (double *)NULL, 1, ih);
    .
    .
    .
    zero_crossing = . . .;
    *coh_thresh = . . .;
    (void) write_header(oh, ostrm);	/*ostrm is output file stream*/

.fi
.vE
.lp
The call to 
.i add_source_file
results in the input header being stored on the new output
file.   This is done (within 
.i add_source_file
) by setting a pointer (\fIvariable.srchead\fR)
to point to the old header.   There is a limit to the number of
headers that can be embedded in this way.  It is defined as
\s-1MAX_SOURCES\s+1 and its current value can be found in
\fI<esps/header.h>\fR.    The header item \fIvariable.nheads\fR
should be checked before calling \fIadd_source_file\fR if the
programmer wants to avoid the chance of a run-time error because of
exceeding this limit.   Of course, if the header is being stored in
a new header and only once in the program, then it is safe to store a
header without checking.  This is the case in the above example.  
.lp
The example above includes both "styles" of adding generic header items
\- the \fIadd_genhd_\fRX routines can either allocate space for the item
and return a pointer to it, or accept a pointer to existing space.  Note
that the actual values written out to the header are the values that
exist when 
.i write_header
is called, \fInot\fP the values that exist when the \fIadd_genhd_\fRX 
routines are called.  Thus, in the above example, the two lines 
prior to the 
.i write_header 
call determine the values written to the corresponding generic 
header items.  There is, however, a "Hi-C" way to guarantee that
the value written to the header is fixed at the time of the call to 
\fIadd_genhd_\fRX routine, as follows:
.nf

    *add_genhd_f("avg. zero crossing", NULL, 1, ih) = zero_crossing;

.fi
When writing programs that exploit the generic header items in the input
ESPS files, it may be the case that the presence of those items is useful
but not essential.  In such cases, care should be taken allow the
program to run on ESPS files that do not have the required gereric header
items.  This can be accomplished by using 
.i genhd_list, 
or by checking for a NULL return value from 
.i get_genhd.  
.sh 1 "Data Structures"
.lp
The data structures for data records in the different types of
\s-1ESPS\s+1 files are specified in the Section 5 manual pages that
describe the file formats.  The general approach is to define a C
structure that represents one data record in the file.  Access functions
are available to support reading and writing such records, so that
programmers can deal with the C structure and ignore the issue of how
that structure is stored in the file.  
.sh 2 "Data Access Routines"
.lp
In general a function named \fIget_\fRxx\fI_rec\fR and one named 
\fIput_\fRxx\fI_rec\fR are provided to get and put records from/onto
an \s-1ESPS\s+1 file type xx.   There is also  n\fIallo_\fRxx\fI_rec\fR 
function that allocates memory for one record.  
In most cases, the size of
certain elements of the record, depend on values in the file header.
.lp
For example, here is an example of reading a \s-1SPEC\s+1 record:
.vS
.nf

    FILE *ifile;
    struct ana_data *p;