man.diff

speech signal process tools

.\" Copyright (c) 1997 Entropic Research Laboratory, Inc. All rights reserved.
.\" @(#)cepanal.1	1.1 29 Apr 1997 ERL
.ds ]W (c) 1993 Entropic Research Laboratory, Inc.
.if t .ds pi \(*p
.if n .ds pi pi
.TH  CEPANAL 1\-ESPS 29 Apr 1997
.SH NAME

cepanal \- cepstrum and phase of sampled data
.SH SYNOPSIS
.B
cepanal
[
.BI \-l " frame_len"
] [
.BI \-o " order"
] [
.BI \-r " range"
] [
.BI \-w " window_type"
] [
.BI \-x " debug_level"
] [
.BI \-S " step"
]
.I input.sd
.I phase_out.fea
.I cepst_out.fea
.SH DESCRIPTION
.PP
This is one of a pair of programs that lets one
analyze a file of sampled data to obtain cepstrum and phase information,
modify the cepstrum,
and recombine the modified cepstrum with the original phase
to obtain a new sampled-data file.
This program analyzes the sampled data into cepstrum and phase.
The program
.IR cepsyn (1\-ESPS)
performs the inverse transformation, combining cepstrum and phase to
produce sampled data.
The input file,
.I input.sd,
must be a single-channel, real sampled-data file (FEA_SD or equivalent).
.PP
.I cepanal
forms the input into equally spaced frames of fixed length (see
.BR "\-l" ", " "\-S"
in the O\s-2PTIONS\s+2 section below),
optionally windows the data (see option
.BR "\-w" ),
performs a Fast Fourier Transform on each frame,
and computes the complex logarithm of the Fourier transform.
It saves the phase (the imaginary part of the logarithm)
in the output file
.I phase_out.fea.
It takes the inverse Fourier transform of the log magnitude
(the real part of the complex logarithm) to obtain the cepstrum
and outputs the result in
.I cepst_out.fea.
The output cepstrum is essentially the same as the output of
.sp
.nf
.RS
fftcep \-R \-F input.sd output.fea
.RE
.fi
.sp
(see
.IR fftcep (1\-ESPS))
with redundant values (nearly half the total number)
dropped from the end of each record.
.PP
The input frames have length
.I frame_len
(see option
.BR "\-l" ).
The initial point of the first frame is determined by the
\fB\-r\fP option.
Initial points of any subsequent frames follow at equal intervals
.I step
(see option
.BR \-S ).
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 number of frames is the minimum sufficient to cover the specified
range (see option
.BR "\-r" ).
The last frame in the file may overrun the range,
in which case a warning is printed.
If a frame overruns the end of the file, it is filled out with zeros.
.PP
The output phase is not unwrapped, is between \-\*(pi and \*(pi,
and may have jumps with sizes of nearly 2\*(pi.
These discontinuities don't matter when the phase is used as input to
.IR cepsyn (1\-ESPS).
.PP
The output files are ordinary ESPS FEA files, not of any special FEA
subtype, and each contains a single field with data type FLOAT.
The field in
.I phase_out.fea
is named
.I phase;
its length is
.IR "n" "/2 + 1",
where
.I "n"
is the transform length (see option
.BR \-o ).
The phase values correspond to frequencies
that run in equal steps from 0 to
.IR "sf" "/2",
where
.I "sf"
is the sampling frequency.
The field in
.I cepst_out.fea
is named
.I cepstrum;
its length is also one greater than half the transform length
.I n
(see
.BR "\-o" ).
The cepstrum values correspond to quefrencies
that run in equal steps from 0 to
.RI "(" "n" "/2)(1/" "sf" ")."
.PP
If
.I input.sd
is "\-", standard input is read.
Either
.I phase_out.fea
or
.I cepst_out.fea,
but not both, may be "\-", for standard output.
.SH OPTIONS
.PP
The following options are supported.  Default values are shown in brackets.
.TP
.BI \-l " frame_len" "\fR [(transform length)]"
The length of each frame.
This is also the length of the data window applied to each frame (see option
.BI "\-w" ).
If the option is omitted or 0, a default value is used:
the transform length determined by the FFT order (see option
.BR "\-o" ).
.TP
.BI \-o " order" "\fR [10]\fP"
The order of the FFT used in the computations;
the transform length is
.RI 2^ order
(2 to the
.IR order -th
power).
This is also the default length of the frames
into which the input sampled-data stream is divided (see option
.BR "\-l" ).
If the frame length is less than the transform length,
each frame is padded with zeros.
(This is done after windowing\*-see option
.BI "\-w" ).
If the frame length is greater than the transform length,
each frame is truncated after windowing.
The default order, 10, corresponds to a transform length of 1024
and output fields of length 513.
.TP
.BI \-r " first" : "last" "\fR [1:(last in file)]"
.TP
.BI \-r " first" :+ "incr"
.TP
.BI \-r " first"
In the first form, a pair of unsigned integers specifies the range of
sampled data to analyze.
If
.I first
is omitted, the default value of 1 is used.  If
.I last
is omitted, the range extends to the end of the file.
If 
.IR last " = " first " + " incr,
the second form (with the plus sign) specifies the same range as the
first form.
The third form (omitting the colon) specifies a single sample.
If the range doesn't end on a frame boundary, it is extended to make
up a full last frame.
If a frame overruns the end of the file, it is filled out with zeros.
.TP
.BI \-w " window_type" "\fR [RECT]"
The name of the data window to apply to the data in each frame.
If the option is omitted, no windowing is done
(equivalent to a rectangular window with amplitude one).
Possible window types include
rectangular ("RECT"), Hamming ("HAMMING"), Hanning ("HANNING"),
cos^4 ("COS4"), and triangular ("TRIANG");
see the
.IR window (3-ESPSsp)
manual page for the complete list.
.TP
.BI \-x " debug_level \fR[0]\fP"
A positive value specifies that debugging output is to be printed on
the standard error output.
Larger values result in more output.
For the default value, 0, there is no output.
.TP
.BI \-S " step" "\fR [(frame length)]"
Initial points of consecutive frames differ by this number of samples.
If the option is omitted or 0, a default equal to
.I frame_len
is used (resulting in exactly abutted frames).
.SH ESPS PARAMETERS
.PP
This program does not access a parameter file.
.SH ESPS COMMON
.PP
The ESPS common file is not read.
.PP
If Common processing is enabled,
and the output file is not standard output,
the program writes the Common parameters
.I prog,
.I filename,
.I start,
and
.I nan
to record the program's name, the name of the input file,
the starting sample in the input file,
and the number of samples in the specified range.
(A value of 0 for
.I nan
implies that no explicit end of range was specified,
so that the program continued processing
to the end of the input file.)
.PP
ESPS Common processing may be disabled
by setting the environment variable USE_ESPS_COMMON to
.I off.
The default ESPS Common file is
.I espscom
in the user's home directory.
This may be overridden
by setting the environment variable ESPSCOM to the desired path.
User feedback of Common processing is determined
by the environment variable ESPS_VERBOSE, with 0 causing no feedback
and increasing levels causing increasingly detailed feedback.
If ESPS_VERBOSE is not defined, a default value of 3 is assumed.
.SH ESPS HEADERS
.PP
The program reads the header item
.I record_freq
from the input header, and it uses
.IR update_waves_gen (3\-ESPS)
to process the items
.I start_time
and
.I record_freq
in the standard way.
.PP
In addition to
.I start_time
and
.I record_freq,
the program add header items
.I start,
.I nan,
.I sf,
.I fft_length,
.I frmlen,
.I step,
and
.I window_type
to both output file headers.
The values of
.I start
and
.I nan
give the starting sample in the input file
and the number of samples in the specified range.
(A value of 0 for
.I nan
implies that no explicit end of range was specified,
so that the program continued processing
to the end of the input file.)
The value of
.I sf
(``sampling frequency'') records the value of
.I record_freq
from the input file.
The value of
.I fft_length
is the transform length, computed from the order.
The values of
.I frmlen
and
.I step
are the frame length and step (see the options
.B \-l
and
.BR \-S ).
The item
.I window_type
is a coded item that records the window type (see
.BR \-w ).
.PP
The programs defines fields
.I phase
in the header of
.I phase_out.fea
and
.I cepstrum
in the header of
.I cepst_out.fea.
Like most ESPS programs, it includes copies of the input file header
in the ouput headers,
and it saves a copy of the command line as a comment in each output
header.
.SH FUTURE CHANGES
.PP
.SH EXAMPLES
.PP
.SH ERRORS AND DIAGNOSTICS
.PP
If an unknown option is specified,
or if the number of file names is wrong,
.I cepanal
prints a synopsis of command-line usage and exits.
.PP
The program exits with an error message if any of the following are true:
the input file name is the same as one of the output file names
(but not "\-");
the output file names are the same;
the input file contains multichannel or complex sampled data;
a negative FFT order is specified;
a starting sample less than 1 is specified;
an empty range of records is specified;
no samples can be read from the input file.
.PP
The program prints a message and continues
if any of the following conditions are encountered:
the indicated input range does not end on a frame boundary;
the end of the input file is reached when an incomplete frame
has been read;
the end of the input file is reached prematurely
according to an explicitly indicated end of range.
.SH BUGS
.PP
None known.
.SH REFERENCES
.PP
.SH "SEE ALSO"
.PP
.na
.IR cepsyn (1\-ESPS),
.IR fft (1\-ESPS),
.IR fftcep (1\-ESPS),
.br
.IR fftinv (1\-ESPS)
.IR update_waves_gen (3\-ESPS)
.ad
.SH AUTHOR
.PP
Rod Johnson