fft.1

speech signal process tools

.\" Copyright (c) 1986-1990 Entropic Speech, Inc.
.\" Copyright (c) 1991 Entropic Research Laboratory, Inc. All rights reserved.
.\" @(#)fft.1	3.31 01 Apr 1997 ESI/ERL
.ds ]W (c) 1991 Entropic Research Laboratory, Inc.
.TH FFT 1\-ESPS 01 Apr 1997
.SH "NAME"

fft \- Fast Fourier Transform of ESPS sampled data file to an ESPS FEA_SPEC file

xfft \- run \fIfft\fP with X Windows interactions and displays
.SH "SYNOPSIS"
.B fft
[
.BI \-c
] [
.BI \-l " frame_len"
] [
.BI \-o " order"
] [
.BI \-{pr} " range"
] [
.BI \-w " window_type"
] [
.BI \-x " debug_level"
] [
.BI \-z
] [
.BI \-P " param"
] [
.BI \-O " frequency_offset"
] [
.BI \-S " step"
]
.I sd_file
.I fea_spec_file
.br

.B xfft
[
.BI \-c
] [
.BI \-{rp} " range"
]
.I sd_file

.SH "DESCRIPTION"
.PP
.I Fft
takes an input ESPS Sampled Data (SD or FEA_SD) file, 
.I sd_file,
and takes the Fast Fourier Transform of one or more fixed-length
segments to produce an ESPS Spectral Feature (FEA_SPEC) file
.I fea_spec_file
containing one or more spectral records.  If the input file name
.I sd_file
is replaced by "\-", then stdin is read; similarily, if
.I fea_spec_file
is replaced by "\-", then the output is written to stdout.
.PP
For details about the FEA_SPEC file format, see FEA_SPEC(5\-ESPS).
The power spectra in such FEA_SPEC files are suitable for plotting with
\fIplotspec\fP(1\-\s-1ESPS\s+1).  
.PP
Note that FEA_SD(5\-\s-1ESPS\s+1) files support complex sampled data,
and \fIfft\fP(1\-\s-1ESPS\s+1) supports complex sampled data
inputs.
.PP
By default, the output FEA_SPEC file has spectral type SPTYP_DB;
i.e. it contains logarithmically scaled powers (in decibels)
stored in the real part of the records.
If the complex spectrum is desired, use the \fB\-c\fP option.
This results in spectral type SPTYP_CPLX; see FEA_SPEC(5\-\s-1ESPS\s+1).
Note that \fIfftinv\fP(1\-\s-1ESPS\s+1)
assumes spectral records of the type produced with the \fB\-c\fP option.
.PP
If the input data type is real and
.B \-c
is not used, the frequency format in the FEA_SPEC file is SPFMT_SYM_EDGE;
the spectrum is symmetetric
with only the positive-frequency part being stored.
If the input data type is complex or
.B \-c
is used, the frequency format is SPFMT_ASYM_EDGE;
the negative-frequency and positive-frequency parts are both stored.
.PP
All input frames have the same length
.I frame_len
(see the
.B \-l
option).  The initial point of the first frame is determined by the
\fB\-r\fP option or by \fIstart\fP in the parameter file.  Initial
points of any subsequent frames follow at equal intervals
.I step
(see
.B \-S
option).
Thus the 3 cases
.IR step " < " frame_len,
.IR step " = " frame_len,
and
.IR step " > " frame_len,
correspond to overlapping frames, exactly abutted frames,
and frames separated by gaps.
.PP
The power values stored in the records of \fIfea_spec_file\fP are
based on the windowed data and are averaged over the actual number of 
points contributing to the transform (this is the transform 
length unless it exceeds \fIframe_len\fP, in which case it is 
\fIframe_len\fP).  
.PP
The number of frames
is the minimum sufficient to cover a specified range of
.I nan
points (see
.B \-r
option), given \fIframe_len\fP and \fIstep\fP.  The last frame in each file
may overrun the range, in which case a warning is printed.  If a frame
overruns the end of a file, it is filled out with zeros.
.PP
\fIxfft\fP is a script that runs \fIfft\fP on a single frame of data
that is specified by the range option (\fB-r\fP or \fB-p\fP) or by
means of ESPS Common.  A pop-up window is used to prompt the user for
the \fIwindow_type\fP and \fIorder\fP.  The results of the \fIfft\fP are
displayed in a pop-up window containing a spectral plot.  \fIxfft\fP 
is well suited for addition to the \fIxwaves\fP+ menu via the 
\fIxwaves\fP+ command "add_espsn name FFT command xfft".  
The (only) advantage of \fIxfft\fP over \fIxspectrum\fP is that 
\fIxfft\fP will do arbitrarily long FFTs (well, how much memory
do you have?).  \fIxfft\fP makes used of
\fIexprompt\fP(1\-\s-1ESPS\s+1) 
and \fIplotspec\fP(1\-\s-1ESPS\s+1).  
.PP
The parameter prompting for \fIxfft\fP is performed by means of the
parameter file named PWfft, which is normally obtained from
$ESPS_BASE/lib/params.  However, if you have a file by this name in
the current directory (or if you define the environment variable
ESPS_PARAMS_PATH and put one on that path), it will be used instead.
.SH "OPTIONS"
.PP
The following options are supported (only \fB-r\fP or \fB-p\fP can 
be given for \fIxfft\fP). 
.TP
.BI \-P " param"
uses the parameter file 
.I param
rather than the default, which is
.I params.
.TP
.BI \-p " range"
\fB\-p\fP is a synonym for \fB\-r\fP, and the allowed forms for
.I range
are the same.
.TP
.BI \-r " first" : "last"
.TP
.BI \-r " first" \- "last"
.TP
.BI \-r " first" :+ "incr"
In the first two forms, a pair of unsigned integers specifies the range of
sampled data to analyze.  If 
.IR last " = " first " + " incr,
the third form (with the plus sign) specifies the same range as the
first two forms.  If 
.I first
is omitted, the default value of 1 is used.  If
.I last
is omitted (in the first two forms),
the range extends to the end of the file.
If the specified range extends beyond the end of the file,
it is reduced to end at the end of the file.
If the range doesn't end on a frame boundary,
it is extend to make up a full last frame.
If the range, so extended, goes past the end of the file,
the last frame is filled out with zeros.
All forms of the option override the values of 
.I start
and
.I nan
in the parameter file or ESPS Common file.
The first two forms are equivalent to supplying values of
.I first
for the parameter
.I start
and
.RI ( last " + 1 \- " first )
for the parameter
.I nan.
The third form is equivalent to values of
.I first
for
.I start
and
.RI ( incr " + 1)"
for
.I nan.
If the \fB\-r\fP option is not
used, the range is determined from the ESPS Parameter or Common file if the
appropriate parameters are present.
.TP
.BI \-O " frequency_offset" "\fR [0]"
Specifies a frequency offset, in Hz, to be subtracted from the
frequency tags attached to the spectrum values when the signal input
to \fIfft\fP is complex.  This is relevant in cases where the
frequency axis was rotated by complex modulation prior to calling
\fIfft\fP. This option permits implementation of "frequency zooming"
functions like that in the example below.
.TP
.BI \-l " frame_len" "\fR [0]"
Specifies the length of each frame.
If the option is omitted, the parameter file is consulted.
A value of 0 (from either the option or the parameter file)
indicates that a default value is to be used:
the transform length determined by the fft order.  (See the
.B \-o
option and the
.I order
parameter.)
This is also the default value in case
.I frame_len
is not specified either with the
.B \-l
option or in the parameter file.
.TP
.BI \-S " step" "\fR [" frame_len "\fR]"
Initial points of consecutive frames differ by this number of samples.
If the option is omitted, the parameter file is consulted,
and if no value is found there, a default equal to
.I frame_len
is used (resulting in exactly abutted frames).
The same default applies if the argument \fIstep\fP is specified as 0.
.TP
.BI \-w " window_type" "\fR [RECT]"
The name of the data window to apply to the data in each frame before
computing the transform.  If the option is omitted, the parameter
file is consulted, and if no value is found there, the default used is a
rectangular window with amplitude one.  Possible window types include
rectangular ("RECT"), Hamming ("HAMMING"), Hanning ("HANNING"),
cos**4 ("COS4"), and triangular ("TRIANG"); see
the window(3-ESPSsp) manual page for the complete list.
.TP
.BI \-o " order" "\fR [10]\fP"
The order of the fft; the transform length is 2^order (2 to the order-th
power).  If the number of data points in each frame (frame length) is less
than the transform length, the frame is padded with zeros (a warning is
given).  If the number of data points in each frame exceeds the transform
length, only the first 2^order points from each frame are transformed \-
i.e., points are effectively skipped between each transform (a warning is
given).  The default order is 10 (transform length 1024).
If the \fB\-c\fP option is not used and the input data type is real,