fea.me

speech signal process tools

The steps above show what is required to create a feature file and how
to handle the data records.  In most cases there will be several
programs that deal with a particular feature file subtype.   In this
case it is worth the effort to create a library module that contains a
set of standard routines for creating records for the subtype,
initializing the header of the feature file and for doing record I/O.
This module should be named \fIxx\fRsupport.c, where \fIxx\fR is a name
for the subtype.   
.pp
Typical support functions for a new file type include: an initialization
routine that creates the required feature file fields 
and generic header items for a new output
file; an allocate record function that allocates the feature file record,
allocates the subtype record, and calls \fIget_fea_ptr\fR to assign
pointer values of the data fields to the pointers in the subtype record
structure; and get/put record functions that do the record input/output.
.pp
In most cases the get/put functions simply read or write a feature file
record.  Since the subtype record consists of pointers to the data
record memory there is no moving of data required.    In some cases,
however, it might be desirable to move the data into a different type of
data structure.  For example, you might want to represent the data in
the program as a matrix (this could also be done just by setting up an
array of pointers, but in some cases it might be just as well to move
the data).   In such cases, the get/put routines would be where this
movement of the data is done.
.pp
We will use our example from above where we reimplemented the ANA file
type as a feature file and show the required support modules.
So as not to be confused with the existing ana
support routine (named anasupport.c), we will use the name \fIfana\fR
for our new subtype in this example.
.sh 2 "init_fana_hd"
.pp
This routine is used to fill in the header of a feature file to make it
a file of the correct subtype.
The routine creates generic header items as needed and creates the data
record fields.
In general, this routine will take as arguments
those values that affect the size of the data record.  These values
should be stored in the file header (as generic header items).
.pp
This routine is only used when creating a new \fIfana\fR file for
output.  It is not used when reading an \fIfana\fR file.  This function
returns zero on success and non-zero on failure.
.ip
.nf
\fBint\fR
init_fana_hd(hd, maxraw, maxlpc, maxpulses, order_vcd, order_unvcd)
\fBstruct\fR header hd;
\fBint\fR maxraw, maxlpc, maxpulses, order_vcd, order_unvcd;

/* save parameters in the header
*/

*add_genhd_l("maxraw",\fB\s-1NULL\fR\s+1,1,hd) = maxraw;
*add_genhd_l("maxlpc",\fB\s-1NULL\fR\s+1,1,hd) = maxlpc;
*add_genhd_l("maxpulses",\fB\s-1NULL\fR\s+1,1,hd) = maxpulses;
*add_genhd_l("order_vcd",\fB\s-1NULL\fR\s+1,1,hd) = order_vcd;
*add_genhd_l("order_unvcd",\fB\s-1NULL\fR\s+1,1,hd) = order_unvcd;

/* create the record fields
*/

\fBif\fR (add_fea_fld("raw_power",maxraw,1,\fB\s-1NULL,FLOAT,NULL\fR\s+1,hd) == -1 ||
    add_fea_fld("lpc_power",maxlpc,1,\fB\s-1NULL,FLOAT,NULL\fR\s+1,hd) == -1 ||
    add_fea_fld("p_pulse_len",maxpulses,1,\fB\s-1NULL,FLOAT,NULL\fR\s+1,hd) == -1 ||
    add_fea_fld("ref_coeff",max(order_vcd,order_unvcd),1,
		\fB\s-1NULL,FLOAT,NULL\fR\s+1,hd) == -1 ||
    add_fea_fld("frame_len",1,0,\fB\s-1NULL,SHORT,NULL\fR\s+1,hd) == -1))
  \fBreturn\fR (1);

hd->hd.fea->fea_type = \fB\s-1VQ_FANA\fR\s+1;  /* this type code is assigned when the
				    subtype becomes official */
\fBreturn\fR 0;
}
.fi
.sh 2 "allo_fana_rec"
.pp
This function allocates a record for the FEA file subtype FEA_ANA.   It
allocates a structure and assigns the pointer values in it to the values
returned by \fIget_fea_ptr\fR, which is the address of the data in the
feature file record.  Note that the address of the feature file record
itself is saved in the record.  This is so that other subtype specific
routines can simply be passed a pointer to the subtype record and still
have access to the underlying feature file record.
The feature file header must be set up before this function is called.
.ip
.nf
\fBstruct\fR fea_ana_data *
allo_fana_rec(hd)
\fBstruct\fR header hd;
{

\fBstruct\fR fea_ana_data *fana = (\fBstruct\fR fea_ana_data *)calloc(1,\fBsizeof\fR *ana);
\fBstruct\fR fea_data *fea_rec = allo_fea_rec(hd);

/* check to be sure this is the right kind of file
*/

\fBif\fR(hd->common.type != \fB\s-1FT_FEA\fR\s+1) error("Not a feature file");
\fBif\fR(hd->hd.fea->fea_type != \fB\s-1FEA_FANA\fR\s+1) error("Not a fana feature file");

/* hook the pointers in the ana record up to the data area in the
   feature file record
*/

fana->tag = &fea_rec->tag;
fana->raw_power = (float *)get_fea_ptr(fea_rec, "raw_power", hd);
fana->lpc_power = (float *)get_fea_ptr(fea_rec, "lpc_power", hd);
fana->p_pulse_len = (float *)get_fea_ptr(fea_rec, "p_pulse_len", hd);
fana->ref_coeff = (float *)get_fea_ptr(fea_rec, "ref_coeff", hd);
fana->frame_len = (short *)get_fea_ptr(fea_rec, "frame_len", hd);

/* save the pointer to the feature file record in the ana record
*/

fana->fea_rec = fea_rec;

\fBreturn\fR fana;
}
.fi
.sh 2 "put_fana_rec"
.pp
This routine writes a record of the FEA file subtype FEA_ANA.   In this
example, it does nothing more than write the feature file record.  In
some other cases, it might have to do some transformation of the data
(for example to support a matrix data structure).
.ip
.nf
\fBvoid\fR
put_fana_rec(rec, hd, strm)
\fBstruct\fR fea_ana_data *rec;
\fBstruct\fR header *hd;
\fBFILE\fR *strm;
{
\fBif\fR (hd->common.type != \fB\s-1FT_FEA\fR\s+1) error("Not a feature file");
\fBif\fR (hd->hd.fea->fea_type != \fB\s-1FEA_FANA\fR\s+1) error("Not a fana feature file");

put_fea_rec(rec->fea_rec, hd, strm);
}
.fi
.sh 2 "get_fana_rec"
.pp
This routine reads a record of the FEA file subtype FEA_ANA.   Like the put
function above, it does nothing more than get the feature file record.
It returns 1 because all other ESPS \fIget_record\fR functions return EOF
on end of file or a positive non-zero integer if the record is read
correctly.
.ip
.nf
\fBint\fR
get_fana_rec(rec, hd, strm)
\fBstruct\fR fea_ana_data *rec;
\fBstruct\fR header *hd;
\fBFILE\fR *strm;
{
\fBif\fR (hd->common.type != \fB\s-1FT_FEA\fR\s+1) error("Not a feature file");
\fBif\fR (hd->hd.fea->fea_type != \fB\s-1FEA_FANA\fR\s+1) error("Not a fana feature file");

\fBif\fR (get_fea_rec(rec->fea_rec, hd, strm) == \fB\s-1EOF\fR\s+1) return \fB\s-1EOF\fR\s+1;
\fBreturn\fR (1);
}
.fi
.sh 2 "Other Parts of the Support Module"
.pp
In addition to these routines the support module should contain
definitions for any global variables needed by the feature file subtype.
The most common example of required global variables are string arrays
used to define possible values for coded or enumerated data fields in
the record.  See \fIlin_search\fR(3\-ESPS).
.pp
For a more complete (and more complex) example of a feature file subtype
support routine see \fI/usr/esps/general/src/lib/vqsupport.c\fR.   The most
significant difference between vqsupport.c and the example here that one
of the items in the data structure is a two-dimensional array, so the
data is moved between the feature file record and the vq record.   This
could have been done by setting up an array of pointers with the correct
values, but since vq files do not have many records it did not seem
necessary at this time.   Of course, it could be changed without
affecting existing programs.  The other difference between vqsupport.c
and this example, is that it is complete and does compile and execute.
.sh 1 "Documentation for Official Feature File Subtypes"
.pp
This section describes
the standard documentation format for an official feature file subtype.
The feature file header has a field for a type code to allow for the
definition of new file types implemented with feature files.   When this
is done, the new file type must be documented so that other programmers
can properly design programs that must use these files.
.pp
The format of the documentation for these files is nearly the same as
the existing section 5 manual pages for files types such as ANA.  The
information that a programmer must have to use a feature file
includes:
.(l
file type code,
generic header items and their meaning,
listing of the fields in the feature file and their size information,
the data structure of the record if one is appropriate, and
manual pages for supporting functions as appropriate.
.)l
.pp
In most cases when a new file type is implemented using feature files,
the designer should provide a data structure like our ANA example above
for other programmers to use.  This will go into an include file that will be
installed into /usr/esps/include/esps.   This header file should also include
declarations for any support functions for the new file type.   See
\fI<esps/vq.h>\fR for an example of this.
.pp
When a feature file subtype is to be made official, the designer will
submit the following to the ESPS maintainer:
.(l
section 5 manual page,
section 3 manual pages for support functions,
support functions C module as described above, and
include file with structure declarations.
.)l
.pp
The ESPS maintainer will assign the file type a type code (FEA_\fIxx\fR)
and add this to the others in \fI<esps/fea.h>\fR.