fea.me

speech signal process tools

.lo
.SJ "Guidelines for Implementing ESPS Feature File Subtypes"
.AU "Alan Parker"
.RB "John Shore"
.TM ETM-S-86-25:rap 1.2 6/5/87
.*R
ESPS User's Manual
.*R
ETM-S-86-14, Entropic Signal Processing System Programming Guidelines
.sh 1 Introduction
.pp
This document describes how to use the ESPS Feature file type
(\fIfea\fR(5\-ESPS)). 
.(f
\(co Copyright 1987 Entropic Speech, Inc.; All rights reserved.  
.)f
ESPS feature files allow the user to create a ESPS data file with named
fields of different data types and sizes.   They can be used to define a
new public ESPS file type (known as a feature file subtype), 
or to implement a private data file for
the user's own work.    When used in conjunction with the generic header
feature (\fIadd_genhd\fR(3\-ESPS)), FEA files provide a very general way for
the user to create ESPS data files.
The general model for using feature files depends on whether the file is
being used for input or output.   
.pp
This document uses as an example a feature file subtype FEA_ANA that 
was created to replace an old ESPS file type called ANA.
.sh 2 "Output Files"
.pp
To create an output feature file
\fInew_header\fR is called to create a new feature file header.   The
fields in the file must be created by calling \fIadd_fea_fld\fR and
providing the required type and size information.    Generic
header items are created using \fIadd_genhd_x\fR(3\-ESPS).
After all the header information is fixed in
place the header is written out, as with any other kind of ESPS file.
The common part of the header contains the same fields as other ESPS
files.  After the header has been written to the file, the program can
start writing the data out.   Methods for dealing with the data are
discussed below.
.sh 2 "Input Files"
.pp
For input feature files, life is simpler since the fields have already
been defined (when the file was created).    In most cases the programmer
will know what the fields are and their types.   
The sizes of the fields might be known by definition, or through some
header item.   But in all cases this information
is available in the FEA header and through access functions (see
\fIget_fea_siz\fR(3\-ESPS).    
If the feature file is a predefined public subtype (public in the sense
that a file type like ANA was public) then documentation of that file
type will show the data structure to use (and usually provide it through
a header file), and will list all the fields and give their type and size
information.   The method of dealing with the data records is much the
same as in the output case and is discussed below.
.sh 1 "Dealing with the Data Records"
.pp
The simple way to use feature files is to create the fields, get
pointers to the data using \fIget_fea_ptr\fR and then move data from
variables in your program to the feature file record.   But with
pointers you can use the memory allocated in the feature file record.    
This is much better than moving all the data around and it's one
reason C has pointers.
For example, consider the data structure that was used to define 
records in ANA files:
.ip
.nf
\fBstruct\fR ana_data {
	\fBlong\fR tag;
	\fBfloat\fR *raw_power;
	\fBfloat\fR *lpc_power;
	\fBfloat\fR *p_pulse_len;
	\fBfloat\fR *ref_coeff;
	\fBshort\fR frame_len;
}
.fi
.pp
Only tag and frame_len here are not pointers, because they are fixed
size (happens to be 1, but could be any fixed size).   The others are
pointers because the amount of memory allocated depends on some values
in the file header.  You can think of these as unallocated arrays of
some size.   The \fIallo_ana_rec\fR function allocates the right amount
of memory for each of these depending on some values in the header and
assigns the pointers (such as raw_power) the \fIaddress\fR of the
allocated memory.   You can write raw_power[i] if you wish and the
compiler will do some pointer arithmetic for you.
.pp
Here's how we replaced the ANA file type with the FEA file subtype
FEA_ANA.  First, field frame_len and tag were changed to
pointers, since the feature file routines have to allocate
memory for it.  So here is our new ANA data structure for feature
files:
.ip
.nf
\fBstruct\fR fea_ana_data {
	\fBlong\fR *tag;
	\fBfloat\fR *raw_power;
	\fBfloat\fR *lpc_power;
	\fBfloat\fR *p_pulse_len;
	\fBfloat\fR *ref_coeff;
	\fBshort\fR *frame_len;
	\fBstruct\fR fea_data *fea_rec;
}
.fi
.pp
Besides changing two items to pointers, we added a pointer to the
feature file record (*fea_rec).   This will be explained later.
.pp
Now to use this we have to create the fields if this is a new file.
.ip
.nf
hd = new_header(\fB\s-1FT_FEA\fR\s+1);
add_fea_fld("raw_power",maxraw,1,\fB\s-1NULL,FLOAT,NULL\fR\s+1,hd);
add_fea_fld("lpc_power",maxlpc,1,\fB\s-1NULL,FLOAT,NULL\fR\s+1,hd);
add_fea_fld("p_pulse_len",maxpulses,1,\fB\s-1NULL,FLOAT,NULL\fR\s+1,hd);
add_fea_fld("ref_coeff",max(order_vcd,order_unvcd),1,\fB\s-1NULL,FLOAT,NULL\fR\s+1,hd);
add_fea_fld("frame_len",1,0,\fB\s-1NULL,SHORT,NULL\fR\s+1,hd);
.fi
.pp
Note that these functions really return an error code, but I'm ignoring
that here.
.pp
Now assuming that all other header items have been fixed we will write
the header.  This is just like any other ESPS file.
.ip
write_header(hd,file);
.pp
Next a \fIfea_ana_data\fR structure must be allocated.    Of course,
depending on the needs in the program, this could have been declared at
compile-time.
.ip
\fBstruct\fR fea_ana_data *ana = (\fBstruct\fR fea_ana_data *)calloc(1,\fBsizeof\fR *ana);
.pp
Before we can get pointers to the data area we must allocate the data
record memory.   That is done with \fIallo_fea_rec\fR.  It uses
information in the file header to allocate the correct amount of memory
of each data type.   After the feature record is allocated,
\fIget_fea_ptr\fR is called to return a pointer to the memory associated
with a particular named field.   Note that the return data type of this
function is (char *), so it must be cast to the correct data type.
(This is like \fImalloc\fR(3)).  If you fail to use the correct cast,
you will get a compile time error complaining about illegal pointer
combinations.
.pp
Note the way the tag field is handled here.  If you do not want to bother
accessing it through a pointer, you can just use it directly from the
feature file record.  It's the one field that is directly built-in and
preallocated in feature file records.
.ip
.nf
rec = allo_fea_rec(hd);
ana->tag = &rec->tag;
ana->raw_power = (\fBfloat *\fR)get_fea_ptr(rec,"raw_power",hd);
ana->lpc_power = (\fBfloat *\fR)get_fea_ptr(rec,"lpc_power",hd);
ana->p_pulse_len =(\fBfloat *\fR) get_fea_ptr(rec,"p_pulse_len",hd);
ana->ref_coeff = (\fBfloat *\fR)get_fea_ptr(rec,"ref_coeff",hd);
ana->frame_len = (\fBshort *\fR)get_fea_ptr(rec,"frame_len",hd);
.fi
.pp
Now, let use the data.   Just use the arrays exactly like you would
with the real ANA data structure.   It works the same and you can easily
hang yourself in all the same ways.   Note that in this case you have
two ways for knowing the size of the arrays, such as lpc_power.    One
way is to know that it is maxlpc from the header (assuming
that you stored it in the header).  If you did not know
that, or the rules were changed, you can get the size of a feature file
field with \fIget_fea_siz\fR. 
But before you can use the data (for an input file) it must be read
from the file.   This is done with \fIget_fea_rec\fR.   This just reads
in the next record into the pool of memory set up by the
\fIallo_fea_rec\fR call.   
.ip
.nf
\fBif\fR (get_fea_rec(rec,hd) == EOF) \fIend of file ...\fR
\fBfor\fR (i=0; i<maxlpc; i+) {
  something = ana->lpc_power[i] + something_else;
}
.fi
.pp
Of course, you could be real C programmer and avoid the use of array
subscripts entirely and just increment the pointer value.   Thats OK,
and you could do that also with the real ANA file.  It's no different.
.pp
As for the scalers (tag and frame_len) in this
case you must remember that they are now pointers.  So to get the
frame_len value do:
.ip
.nf
xx = *ana->frame_len;
.fi
.pp
Of course you can use *ana->frame_len in any expression as often as you
please.    No need to assign it to another variable.   You can access
the tag by *ana->tag.   You can also access the tag by rec->tag; by
just
getting the tag value directly from the record.  Note that 
ana->tag is a pointer containing the address
of rec->tag, so to say *ana->tag is to refer to the same memory as
rec->tag.
.pp
If you forget that frame_len is a pointer and say ana->frame_len in an
expression, you will get a funny number which is the address of the
data.  In some such cases you will get a message about illegal
combination of pointer and integer or some such, but don't count on it.
.pp
Since \fIget_fea_ptr\fR returns a pointer, you can use its return value
directly to access the data.   This probably is not the best way to
use the function in general.  In particular, you probably don't want to
put the function call in a processing loop that gets executed 10,000
times.  But this does work: (if \fIzeta\fR is a feature file field of
type \fB\s-1FLOAT\fR\s+1)
.ip
.nf
something = *(\fBfloat\fR *)get_fea_ptr(rec,"zeta",hd) + something_else;
.fi
.lp
So does this:
.ip
*(\fBfloat\fR *)get_fea_ptr(rec,"zeta",hd) = 77.9;
.sh 1 "Feature File Subtype Support Module"
.pp