fea_ana.5t

speech signal process tools

.\" Copyright (c) 1987 Entropic Speech, Inc.; All rights reserved
.\" @(#)fea_ana.5t	1.2 7/15/87 ESI
.TH FEA_ANA 5\-ESPS 7/15/87
.ds ]W "\fI\s+4\ze\h'0.05'e\s-4\v'-0.4m'\fP\(*p\v'0.4m'\ Entropic Speech, Inc.
.SH NAME
ESPS ANA Feature File Subtype \- (.fana)
.SH SYNOPSIS
.nf
.ft B
#include <sps/sps.h>
#include <sps/fea.h>
#include <sps/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
The header for a FEA_ANA
file consists of the following generic header items:
.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;
.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
frames.
.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 "filt_nsiz, filt_dsiz"
The respective lengths of the numerator and denominator polynomials 
for the filters stored within each record; if \fIfilters\fP == YES, 
these are both zero and no space for filters is allocated in the 
records.
.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 \fIfea\fR(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
and \fIput_anafea_rec\fP) have parameters of type (struct anafea).  Here is 
the definition of the anafea struct (given in \fI<sps/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), ana2fea(1\-ESPS), fea2ana(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/sps/fea.h
/usr/include/sps/anafea.h
.SH AUTHOR
Manual page by John Shore