spec.5t

speech signal process tools

.\" Copyright (c) 1987 Entropic Speech, Inc.; All rights reserved
.\" @(#)spec.5t	1.8 25 Sep 1997 ESI
.TH SPEC 5\-ESPS 25 Sep 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 SPEC Spectral Record File \- (.spec)
.SH SYNOPSIS
.B #include <esps/esps.h>
.br
.B #include <esps/spec.h>
.SH DESCRIPTION
A Spectral Record file consists of a header followed by a series 
of tagged records or a series of untagged records (tagging is determined
by the \fIcommon.tag\fR field in the universal section of the header.
Each record consists of
a vector of spectral values (powers or power densities in the case of
power spectra),
together with certain optional fields \-
an imaginary-part vector, frame length, voicing indicator,
number of frequencies, and a vector of frequencies \-
that are present or absent according to the values of certain header fields.
.PP
The header has the following layout as defined by
.I <esps/header.h>
The data items common to all ESPS data files are described in
.IR ESPS (5\-ESPS).
The type specific header structure for SPEC files
is shown below.
.PP
.nf
.br
/* SPEC Spectral Record File specific header */
.br
.sp
struct spec_header {
.TS
l1 l1 l1 l.

    long	start;	/\(** starting point analyzed \(**/
    long	nan;	/\(** number of points analyzed \(**/
    short	frmlen;	/\(** analysis window width \(**/
    short	order_vcd;	/\(** model order voiced \(**/
    short	order_unvcd;	/\(** model order unvoiced \(**/
    short	win_type;	/\(** data window type \(**/
    float	sf;	/\(** sampling frequency \(**/
    short	spec_an_meth;	/\(** analysis method \(**/
    float	dcrem;	/\(** DC term removed \(**/
    short	post_proc;	/\(** post-processing method \(**/
    short	frame_meth;	/\(** how speech was divided into frames \(**/
    short	voicing;	/\(** voicing indicator appears in each record \(**/
    short	freq_format;	/\(** how to determine the set of frequencies \(**/
    short	spec_type;	/\(** are data power, log power, complex, etc.? \(**/
    short	contin;	/\(** discrete distribution or continuous density? \(**/
    long	num_freqs;	/\(** number of frequencies \(**/
    short	spares[SPEC_SPARES];	/\(** spares \(**/
    float	*freqs;	/\(** frequencies (if listed in header) \(**/
.TE
.TS
l1 l1 l1 l.
    struct zfunc	*pre_emp;	/\(** preemphasis filter \(**/
.TE
};
.fi
.sp
.PP
The following items are all in the SPEC file specific header structure.
.IP "start, nan"
.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\-ESPS) \- see ESPS(5\-ESPS).
.sp .5
Note that \fInan\fR is the
.I "intended"
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.
.I refer.
.IP frmlen
Analysis window width, the number of data points used for analysis,
if the same for all records.
.IP order_vcd
Model order (number of autoregressive coefficients) for voiced speech.
.IP order_unvcd
Model order (number of autoregressive coefficients) for unvoiced speech.
.IP win_type
Window type.  Indicates the type of window function applied to the data, 
NONE if no window function was applied.
Type codes are defined in
.I <esps/header.h>.
.IP sf
Sampling frequency of the reference file named in \fIcommon.refer\fR,
if any; for certain values of
.I freq_format,
used in determining band limits.
If zero, there is no reference file.
.IP spec_an_meth
Spectrum analysis method.  Values are defined in
.I <esps/header.h>.
.IP dcrem
If the DC term in the original source data was removed before
analysis its value is stored here.
.IP post_proc;
Post-processing operation (such as smoothing).  Values are defined in
.I <esps/header.h>.
.IP frame_meth
Method used for selecting analysis frames.
If FM_NONE, frame length is not defined.
If FM_FIXED, the frame length is given by
.I frmlen
in the header.
If FM_VARIABLE, the
.I frame_len
field is present in each record and gives the frame length.
(Usually, the file will be tagged if \fIframe_meth\fR == FM_VARIABLE.)
.IP voicing
If YES, the
.I voiced
field is present in each record, and the model order is
.I order_vcd
or
.I order_unvcd
according to its value.
If NO,
.I order_vcd
and
.I order_unvcd
must be equal or undefined.
.IP freq_format
If SYM_CTR, the spectrum is symmetric,
and only the positive-frequency part is given.
The frequencies are the centers of
.I num_freqs
equal bins that span the band from 0 to
.I "sf/2."
Thus the frequencies run from
.I "sf/(4*num_freqs)"
to
.I "sf/2 \- sf/(4*num_freqs)"
in steps of
.I "sf/(2*num_freqs)."
.IP
If SYM_EDGE, the spectrum is symmetric,
and only the positive-frequency part is given.
The frequencies are the edges of
.I "num_freqs \- 1"
equal bins that span the band from 0 to
.I "sf/2."
Thus the frequencies run from
.I 0
to
.I "sf/2"
in steps of
.I "sf/(2*(num_freqs\-1))."
.IP
If ASYM_CEN, the spectrum is not (necessarily) symmetric,
and both positive-frequency and negative-frequency parts are given.
The frequencies are the centers of
.I num_freqs
equal bins that span the band from
.I "\-sf/2"
to
.I "sf/2."
Thus the frequencies run from
.I "\- sf/2 + sf/(2*num_freqs)"
to
.I "sf/2 \- sf/(2*num_freqs)"
in steps of
.I "sf/num_freqs."
.IP
If ASYM_EDGE, the spectrum is not (necessarily) symmetric,
and both positive-frequency and negative-frequency parts are given.
The frequencies are the edges of
.I "num_freqs \- 1"
equal bins that span the band from
.I "\-sf/2"
to
.I "sf/2."
Thus the frequencies run from
.I "\-sf/2"
to
.I "sf/2"
in steps of
.I "sf/(num_freqs\-1)."
.IP
If ARB_VAR, both positive-frequency and negative-frequency parts must be given.
The frequencies need not be equispaced and are listed explicitly in
.I frqs
in each record.
.IP
If ARB_FIXED, both positive-frequency and negative-frequency parts must be given.
The frequencies need not be equispaced and are listed explicitly in
.I freqs
in the header.
The ARB_FIXED frequency format is not yet implemented.
.IP spec_type
If ST_PWR, actual values of spectral powers or power densities
(necessarily positive) are stored in the records.
If ST_DB, logarithmically scaled powers or power densities (in decibels)
are stored in the records.
If ST_REAL, the records contain real values other than the above \-
.I e.g.
values of a weighting function.
If ST_CPLX, complex spectral values are stored in the records.
.IP contin
If YES, the data represent samples of a continuous density function.
For example, if
.IR spec_type ==ST_PWR,
the data give the amount of power per unit frequency
in the neighborhood of each given frequency.
If NO, the data represent a discrete distribution.
For example, if
.IR spec_type ==ST_PWR,
the data give the amount of power concentrated at each given frequency.
.IP num_freqs
The number of frequencies for which spectral values are given.
If
.IR freq_format ==ARB_VAR,
this is a maximum number, the number for which space is allocated,
and the actual number is in
.I n_frqs
in each record.
.IP spares
There are SPEC_SPARES spare shorts.
.IP freqs
Frequencies to which the spectral values in each record correspond.
This field is NULL unless
.IR freq_format ==ARB_FIXED.
.IP pre_emp 
A pointer to a preemphasis filter.
.PP
The data follows the header.
The data structure in the file is shown below in C syntax.
Of course, the variable
.I num_freqs
cannot be used in the declaration, but is used to allocate the correct
amount of memory.
.PP
This data structure is defined in
.I <esps/spec.h>.
A function is available to allocate memory for
this data structure, based on a particular header, and to fill in the
type fields in the common part of the header.
See
.IR allo_spec_rec " and " write_header (3\-ESPSu).

.nf
.sp
.if n .ta 37
.if t .ta 3i
struct spec_data {
       long   tag; 	/\(** position tag \(**/ 
       float  tot_power;	/\(** total power \(**/
       float  re_spec_val[num_freqs];	/\(** real part of spectral value \(**/
       float  im_spec_val[num_freqs];	/\(** imaginary part of spectral value \(**/
       float  frqs[num_freqs];	/\(** frequencies \(**/
       long   n_frqs;	/\(** number of frequencies \(**/
       short  frame_len;	/\(** number of samples in analysis window \(**/ 
       short  voiced;	/\(** YES for voiced frame \(**/
};
.fi
.PP
SPEC files optionally have a position tag in each record.
In addition there is space for
.I num_freqs
real or complex values, where
.I num_freqs
is given in the header.
If the header item
.I spec_type
has any value but ST_CPLX, then
.I im_spec_val
is required to be all zeros in memory and is not stored in the file.
(See
.IR allo_spec_rec " and " put_spec_rec (3\-ESPSu)
on this point, and on the treatment of
.I frame_len, voiced, n_frqs,
and
.I frqs
when not defined.)
If
.I frame_meth
in the header is neither FM_NONE nor FM_FIXED,
.I frame_len
is defined and is the length of the analysis frame.
If
.I voicing
in the header is YES,
.I voiced
is defined and is a voicing indicator:  YES for voiced, NO for unvoiced.
If
.I freq_format
in the header is ARB_VAR, then
.I n_frqs
and
.I frqs
are defined, and
.I n_frqs
frequencies in
.I frqs
and the first
.I n_frqs
spectral values are valid (though space for
.I num_freqs
frequencies and
.I num_freqs
spectral values is allocated).
.SH FILES
/usr/include/esps/header.h,
/usr/include/esps/spec.h
.SH SEE ALSO
.IR allo_spec_rec (3\-ESPSu),
.IR get_spec_rec (3\-ESPSu),
.br
.IR put_spec_rec (3\-ESPSu),
.IR read_header (3\-ESPSu),
.br
.IR write_header (3\-ESPSu)
.IR ESPS (5\-ESPS),
.IR SD (5\-ESPS)
.SH FUTURE CHANGES
Implement case ARB_FIXED for
.I freq_format.
.SH AUTHOR
Rodney Johnson, Entropic Speech, Inc.