sgram.1

speech signal process tools

.\" Copyright (c) 1990 Entropic Speech, Inc.; All rights reserved
.\" @(#)sgram.1	1.14 3/28/97 ESI
.TH SGRAM 1\-ESPS 3/28/97
.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"
sgram \- compute sequence of FFTs suitable for display as a spectrogram
.SH "SYNOPSIS"
.B sgram 
[
.BI \-d " data_window"
] [
.BI \-m " method"
] [
.BI \-o " fft_order"
] [
.BI \-p " range"
] [
.BI \-s " range"
] [
.BI \-w " window_len"
] [
.BI \-x " debug_level"
] [
.BI \-E " pre_emphasis"
] [
.BI \-P " param_file"
] [
.BI \-S " step_size"
] [
.BI \-T " desired_frames"
] [
.B \-z
] 
.I " input.sd output.fspec"
.SH "DESCRIPTION"
.PP
.I Sgram
reads an ESPS sampled data file, preemphasizes it, and produces an
FFT-based ESPS FEA_SPEC file that is suitable for displaying as a
spectrogram.  (See \fIplotsgram\fP(1\-\s-1ESPS\s+1).)
.PP
By default (specifying no options) or by specifying
\fIwb\fR for the \fB\-m\fR option, \fIsgram\fR produces a FEA_SPEC
file that simulates the analysis done to produce a wide-band speech
spectrogram.  Alternatively, by specifying \fInb\fR for the \fB\-m\fR
option, a FEA_SPEC file that simulates the analysis for a narrow-band
spectrogram is computed.  The \fB\-m\fP option defines different
defaults for the other options.  By specifying any of the other
options, in addition to \fB\-m\fP, the default values are overridden
by the specified option values.  This allows the user to alter the
basic display to highlight facets of the spectrogram that are of
particular interest.
.PP
The output FEA_SPEC file has freq_format SPFMT_SYM_EDGE, spec_type
SPTYP_DB, and frame_meth SPFRM_FIXED.  To compress space, the output 
data type for re_spec_val is BYTE (see FEA_SPEC(5\-\s-1ESPS\s+1)).  
.PP
The number of output frames is the minimum sufficient to cover a
specified range of points (see \fB-p\fP and \fB-s\fP options), given
\fIwindow_len\fP and \fIstep_size\fP.  In the \fB-T\fP option is used,
\fIsgram\fP chooses \fIstep_size\fP so that the number of output
frames is close to \fIdesired_frames\fP, which provides a convenient
means of varying the time-domain resolution in terms that relate to
the physical size of a resulting display via \fIxwaves\fP+ (see the
description under \fB-T\fP below).  Whether or not \fB-T\fP is used,
the last frame analyzed may overrun the range, in which case a warning
is printed if the \fB-x\fP option is used.  If a frame overruns the
end of a file, it is filled out with zeros. Neither complex nor
multichannel sampled data files are supported yet.
.PP
If "\-" is specified for the input file, standard input is used.  If
"\-" is specified for the output file, standard output is used.
.SH OPTIONS
.PP
.TP
.BI \-d " data_window" "\fR [(see \fB\-m\fR)]"
The data window applied to the data before the computation of the
power spectrogram.  If the option is omitted, the parameter file is
consulted, and if no value is found there, the default implied by
.I method
(see
.BR \-m )
is used.  Possible window types include RECT (rectangular), HAMMING,
HANNING, COS4, and TRIANG (triangular).  See
.IR window (3-ESPSsp)
for a complete list of supported data windows.
.TP
.BI \-m " method \fR[wb]\fP"
The basic method for spectrogram computation.
There are two possible values:
.I wb
for wide band and
.I nb
for narrow band.
By specifying
.I wb,
the following default values are set:
preemphasis = .94, fft_order = 8, window_len = 8 ms, step_size = 2 ms,
and data_window = HANNING.
By specifying
.I nb,
the following default values are set: preemphasis = .94, fft_order =
9, window_len = 40 ms, step_size = 2 ms, and data_window = HANNING.
If the option is omitted, the parameter file is consulted, and if no
value is found there, the default
.I wb
is used.  If the parameter file contains a value for \fImethod\fP, 
corresponding default values are determined for the other parameters
\- in this case, these defaults can be overriden by command line
options but not by other parameter file values (there is one exception
\- see the discussion under ESPS PARAMETERS).  
.TP
.BI \-o " fft_order" "\fR [(see \fB\-m\fR)]"
The FFT length used in computing the power spectrum is 2 to the power
.I fft_order.
If the number of data points in each frame
.RI ( window_len )
is less than the transform length, the frame is padded with zeros, and
a warning is given if the \fB-x\fP option is used.  If the number of
data points per frame exceeds the transform length, each frame is
effectively truncated to the transform length, and a warning is given
if the \fB-x\fP is used.  The number of frequencies in the output
spectral records is 1 more than half the transform length.  If this
option is not specified, the parameter file is consulted, and if no
value is found there, the default implied by
.I method
(see
.BR \-m )
is used.
.TP
.BI \-p " first" : last "\fR [1:(last in file)]"
.TP
.BI \-p " first" :+ incr
The range of points in the input file over which the spectrogram
values are to be computed.  In the first form, a pair of unsigned
integers gives the first and last points of the range, counting from 1
for the first point in the file.  If
.I first
is omitted, 1 is used.  If 
.I last 
is omitted, the range extends to the end of the file.  The second form
is equivalent to the first with
.I "last = first + incr".
This option should not be specified if
.B \-s
is specified.  If neither option is specified, the range is determined
by the parameters
.I start
and
.I nan
as read from the parameter file.
If either parameter is missing from the parameter file, it is determined
by default.
.TP
.BI \-s " start_time" : end_time "\fR [0.0:(end of file)]
.TP
.BI \-s " start_time" :+ duration
Determines the range in seconds in the input file over which the
spectrogram values are to be computed.  In the first form, a pair of
real numbers gives the starting and ending times of the range.  The
correspondence between samples and times is determined by two
quantities: the starting time of the file and the interval between
samples.  The former is given by the generic header item
.I start_time
in the input file, or 0.0 if the header item is not present.  The
latter is the reciprocal of the sample frequency
.I sf
in the type-dependent part of the SD header.
If
.I start_time
is omitted, the starting time of the file is used.  If 
.I end_time 
is omitted, the range extends through the end of the file.
The second form of the option is equivalent to the first with 
.I "end = start + duration".
This option should not be specified if
.B \-p
is specified.
If neither option is specified,
the range is determined by the parameters
.I start
and
.I nan,
as discussed above for
.B \-p.
.TP
.BI \-w " window_len" "\fR [(see \fB\-m\fR)]"
The duration of data in milliseconds over which the the power spectrum
is computed for each column of the spectrogram. The analysis bandwidth
is inversely proportional to this value.  If this option is not
specified, the parameter file is consulted, and if no value is found
there, the default implied by
.I method
(see
.BR \-m )
is used.
.TP
.BI \-x " debug_level"
A positive value
causes debugging output to be printed on the standard error output.
Larger values give more output.
The default is 0, for no output.
.TP
.BI \-E " pre_emphasis" "\fR [(see \fB\-m\fR)]"
The coefficient
.I A
in the preemphasis filter
.RI "1 \- " A/z.
This filter is applied to the sampled data before computing the power
spectrum.  A value of 1.0 provides a 6 dB/octave boost to the high
frequencies; a value of 0.0 provides no boost.  If this option is not
specified, the parameter
.I pre_emphasis
is read from the parameter file, and if no value is found there,
the default value implied by
.I method
(see
.BR \-m)
is used.
.TP
.BI \-P " param_file"
Use the parameter file
.I param_file
rather than the default, which is
.I params.
.TP
.BI \-S " step_size" "\fR [(see \fB\-m\fR and \fB-T\fP)]"
The time step in milliseconds between columns in the spectrogram.  The
time resolution and horizontal magnification are affected by this
parameter.  If this option is not specified, the parameter file file
is consulted, and if no value is found there, the default value
implied by
.I method
(see
.BR \-m)
is used.