fea_ana.5t

speech signal process tools

.\" Copyright (c) 1987 Entropic Speech, Inc.; All rights reserved
.\" @(#)fea_ana.5t	1.11 08 May 1997 ESI
.TH FEA_ANA 5\-ESPS 08 May 1997
.ds ]W "\fI\s+4\ze\h'0.05'e\s-4\v'-0.4m'\fP\(*p\v'0.4m'\ Entropic Speech, Inc.
.de us
\\$1\l'|0\(ul'
..
.SH NAME
ESPS ANA Feature File Subtype \- (.fana)
.SH SYNOPSIS
.nf
.ft B
#include <esps/esps.h>
#include <esps/fea.h>
#include <esps/anafea.h>
.fi
.SH DESCRIPTION
.PP
The FEA_ANA file is a subtype of the FEA file.  If \fIhd\fR is a 
pointer to the header of such a file, then \fIhd\->hd.fea\->fea_type\fR
== FEA_ANA.  Such files are created by calling 
.I init_anafea_hd
(3\-ESPSu) after 
.I new_header
(3\-ESPSu).  
.PP
FEA_ANA files store spectral parameters, power, and voicing information.
The file type is intended for speech processing applications.
.PP
The header for a FEA_ANA file consists of the following generic header
items (note that \fIfilt_nsiz\fP and \fIfilt_dsiz\fP are only defined
if \fIfilters\fP == YES):
.PP
.TS
center, box, tab(;);
c | c | c | c
l | l | l | l.
Name;Size;Type;Enums
=
maxraw;1;long;
maxlpc;1;long;
maxpulses;1;long;
order_vcd;1;long;
order_unvcd;1;long;
src_sf;1;float;
filters;1;coded;NO,YES
spec_rep;1;coded;\fIspec_reps\fP
filt_nsiz;1;short;
filt_dsiz;1;short;
start;1;long;
nan;1;long;
frmlen;1;long;
.TE
.PP
The generic header items have the following meanings:
.IP maxraw
Maximum number of raw powers per record.
.IP maxlpc
Maximum number of lpc error powers per record.
.IP maxpulses
Maximum number of pitch pulses per record.
.IP order_vcd
Model order (number of autoregressive coefficients) for voiced frames
and transition frames.
.IP order_unvcd
Model order (number of autoregressive coefficients) for unvoiced, silence,
none, and unknown frame types.
.IP src_sf
Sampling frequency of the header reference file \fIvariable.refer\fP.  
.IP spec_rep
Specifies the type of spectral parameters stored in the
\fIspec_param\fP field of each record.  Values are defined in 
\fIanafea.h\fP with corresponding strings defined in the table
\fIfspec_reps\fR in the FEA_ANA support module \fIanafeasupp.c\fP.  
Currently supported values are RC, LAR, LSF, and AUTO.  
.IP filters
If this coded type is YES, then a filter is stored within every record;
if it is NO, then filters are not stored.
.IP "filt_nsiz, filt_dsiz"
if \fIfilters\fP == YES, these are defined (otherwise they aren't).
If defined, they are the respective lengths of the numerator and
denominator polynomials for the filters stored within each record;
.IP "start, nan"
Starting point and intended number of points analyzed.
Values are set to zero if they are not meaningful.
If the file is tagged (see description of \fIcommon.tag\fR in ESPS(5\-ESPS)),
\fIstart\fR and \fInan\fR refer to the file named by \fIvariable.refer\fR.
Otherwise, they refer to a relevant source file (\fIvariable.refer\fR is also
likely to be a source file).
If the file has many source files, then \fIstart\fR and \fInan\fR usually refer
to all the source files.
Often, \fIstart\fR and \fInan\fR will be determined by a command-line range
option or by values in the ESPS Parameter or Common file.
In cases where an entire file is to be analyzed and the file is processed by
means of standard input, \fInan\fR will be set to LONG_MAX (2147483648 on
68000 class machines);
if a disk file is used, then \fInan\fR can be set to the actual number of
points in the file since \fIcommon.ndrec\fR is filled in by
\fIread_header\fR(3\-ESPSu) \- see ESPS(5\-ESPS).
.sp .5
Note that \fInan\fR is the
\fBintended\fR
number of points analyzed.
Whether or not standard input is used, \fInan\fR will not reflect the actual
number of points analyzed if an input file is exhausted before the intended
range is covered.
This is because the header is written before the data.
To require \fInan\fR always to be the actual number of points analyzed
would require that programs use a temporary file and therefore that they
write the data twice.
If it is crucial to record in \fInan\fR the actual number of points
processed, this can be accomplished by using such a temporary file.
.IP frmlen
For programs that use a fixed frame size, the size is stored in \fIfrmlen\fR.
.PP
The header of a FEA_ANA file also contains definitions for the record fields
as given by the following table:
.PP
.TS
center, box, tab(;);
c | c | c | c | c | c 
l | l | l | l | l | l.
Name;Size;Rank;Dimen;Type;Enums
=
frame_len;1;0;NULL;long;NULL
num_pulses;1;0;NULL;long;NULL
frame_type;1;0;NULL;coded;\fIframe_types\fP
voiced_fraction;1;0;NULL;float;NULL
raw_power;\fImaxraw\fP;1;NULL;float;NULL
lpc_power;\fImaxlpc\fP;1;NULL;float;NULL
p_pulse_len;\fImaxpulses\fP;1;NULL;float;NULL
spec_param;MAX(\fIorder_vcd, order_unvcd\fP);1;NULL;float;NULL
filt_zeros;\fIfilt_nsiz\fP;1;NULL;float;NULL
filt_poles;\fIfilt_dsiz\fP;1;NULL;float;NULL
.TE
.PP
In the above table, \fIframe_types\fR is an array of of the possible
values the field \fIframe_type\fP can take.  These are defined in the
FEA_ANA library support module \fIanafeasupp.c\fP.  See FEA(5\-ESPS)
for additional information on the meaning of the table columns.
.PP
In most cases, programs that deal with FEA_ANA files will use the support
routines provided in the ESPS library and will not have to make direct
use of the information in the above tables.   The library routine
.I init_anafea_hd
(3\-ESPSu) creates the record fields and the generic header items.
.PP
Programs that deal with FEA_ANA files do so in terms of structures of
type (struct anafea) \- pointers to structures of this type are returned by 
.I allo_anafea_rec
(3\-ESPSu), and the FEA_ANA read and write routines (\fIget_anafea_rec\fR(3-ESPSu)
and \fIput_anafea_rec\fP(3-ESPSu) have parameters of type (struct anafea).
Here is 
the definition of the anafea struct (given in \fI<esps/anafea.h>\fR):
.nf
.ta .5i 1i 1.75i

    struct anafea  {
        long		*tag;	
        long		*frame_len;
        long		*num_pulses;
        short		*frame_type;
        float		*voiced_fraction;
        float		*raw_power;	
        float		*lpc_power;	
        float		*p_pulse_len;	
        float		*spec_param;
        float		*filt_zeros;
        float		*filt_poles;	
        struct	    fea_data    *fea_rec;
    };
.fi
.PP
The record fields have the following meanings:
.IP tag
position tag in reference file \fIvariable.refer\fP, valid only
if \fIcommon.tag\fP == YES.  This field is not 
represented in the table above, since it arises from general support
of ESPS files (see ESPS(5\-ESPS)).  
.IP frame_len
number of samples represented by the frame
.IP num_pulses
number of pitch pulses in frame \- only this number of \fIp_pulse_len[]\fP 
values are meaningful.
.IP frame_type
classification of frame; numerical values are defined in
\fIanafea.h\fP with corresponding strings defined in
\fIanafeasupp.c\fP.  Common supported values are VOICED, UNVOICED,
SILENCE, TRANSITION.  
.IP voiced_fraction
Fraction of excitation energy that is voiced \- not all programs
support this field.  
.IP "raw_power, lpc_power"
These are respectively the raw and lpc error powers.  
Starting with
\fIraw_power[0]\fR, \fIraw_power\fR values are valid 
only until the first negative
value, and starting with \fIlpc_power[0]\fR, \fIlpc_power\fR 
values are valid only
until the first negative value, unless all are valid in which case
none of them are negative.  Typically, for a voiced frame there
should be either one \fIraw_power\fR value (for the whole frame) or one for
each pulse.  For an unvoiced frame, typically there should be one 
\fIraw_power\fR value for the frame.  The situation for \fIlpc_power\fR 
is similar, 
except that one might have only one \fIlpc_power\fR for the frame even if 
there are \fIraw_power\fR values for every pitch pulse, and one might not 
have any \fIlpc_power\fR values at all.  
.IP p_pulse_len
These are the pitch pulse lengths; only the first \fInum_pulses\fP 
are significant, starting with \fIp_pulse_len[0]\fP.  
.IP spec_param
The spectral parameters, whose representation 
is determined by the generic header item \fIspec_rep\fP.  
For VOICED or TRANSITION frames, \fIorder_vcd\fP values are
meaningful.  Otherwise, \fIorder_unvcd\fP values are meaningful.  
If \fIspec_rep\fP == AUTO, the values stored in \fIspec_param\fP are 
the normalized autocorrelations R(i)/R(0), where R(i) is the 
autocorrelation function with sample delay i.  
.IP "filt_zeros, filt_poles"
Respectively the numerator and denominator polynomials of a record-specific
filter; the respective lengths are \fIfilt_nsiz\fP and \fIfilt_dsiz\fP.  
Space for these polynomials is allocated only if the generic header
item \fIfilters\fP is YES; otherwise these pointers are set to NULL.
.IP fea_rec
This is a pointer to the FEA file record in which all the FEA_ANA 
information is stored.  Programs should not use this value directly.
.PP
The sign convention for spectral parameters is such that the first
reflection coefficient is R(1)/R(0) where R(1) and R(0) are autocorrelation
functions with sample delays of 1 and 0 respectively.
.SH SEE ALSO
.PP
init_anafea_hd(3\-ESPSu), allo_anafea_rec(3\-ESPSu), get_anafea_rec(3\-ESPSu),
put_anafea_rec(3\-ESPSu), get_genhd(3\-ESPSu), spectrans(1\-ESPS), transpec(1\-ESPS),
refcof(1\-ESPS), FEA(5\-ESPS), ESPS(5\-ESPS)
.SH RECORD ELEMENT FILE STRUCTURE
.PP
In order to use this (or any other) FEA file type with a generic ESPS
program (one that operates on any file type) it is necessary to know the
way that record elements are positioned in the file.   For a FEA file
that information is obtained by running the program
\fIfea_element\fR(1\-ESPS) on the file in question.
.SH FILES
.PP
.nf
/usr/include/esps/fea.h
/usr/include/esps/anafea.h
.SH AUTHOR
Manual page by John Shore