files.vtme

speech signal process tools

\s-1FT_SCBK\s+1	\fIhd.scbk\fR
\s-1FT_FEA\s+1	\fIhd.fea\fR
.TE

.fi
.lp
For example, the sampling frequency from the header of an SD file 
is head\->hd.sd\->sf.
.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, or the file does not begin with a valid header,
\fIread_header\fR returns \s-1NULL\s+1.  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. \fIAdd_source_file\fR also appends the variable.comment field 
of the source file header to the variable.comment field of the
current header.  Thus, provided that all programs use 
.i add_source_file
properly, the variable.comment field of an ESPS file will contain the
catenated comments of all the source files plus any additional
comments added at the end.  Since all ESPS programs are supposed to
at least add the command line as a comment (see below), this means
that the variable.comment field should always contain a complete 
history of the command lines.  This will be retained even if 
.i hdshrink
(1\-\s-1ESPS\s+1) is used to delete the embedded headers (an action
sometimes taken to conserve space).  
.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.  Note that
the comment-copying behavior of 
.i add_source_file
makes it important to invoke 
.i add_source_file 
before 
.i add_comment.
.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 SD header */
    samp_freq = ih->hd.sd->sf;		/*example from type-specific portion*/
    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*/
    (void) 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", 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