man.diff

speech signal process tools

.\" Copyright (c) 1988, 1989, 1990 Entropic Speech, Inc. All rights reserved.
.\" @(#)dspsgram.1	1.5  11/30/90  ESI
.TH DSPSGRAM 1\-ESPS 11/30/90
.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"
dspsgram \- uses a DSP32 or DSP32C signal-processing board to produce a FEA_SPEC spectrogram file
.SH "SYNOPSIS"
.B dspsgram 
[
.BI \-d " data_window"
] [
.BI \-m " method"
] [
.BI \-o " fft_order"
] [
.BI \-p " range"
]
.br
[
.BI \-r " range"
]
[
.BI \-s " range"
] [
.BI \-w " window_len"
] [
.BI \-x " debug_level"
] [
.BI \-E " pre_emphasis"
]
.br
 [
.BI \-P " param_file"
] [
.BI \-S " step_size"
] 
.I " input.sd output.fspec"
.SH "DESCRIPTION"
.PP
.I dspsgram
reads an ESPS sampled data file, preemphasizes it, and produces an
FFT-based ESPS FEA_SPEC file that is suitable for displaying as a
speech spectrogram.  (See \fIplotsgram\fP (1\-\s-1ESPS\s+1).)
The command-line options, parameters, and input and output file formats
are the same as for
.IR sgram (ESPS-1),
but
.I dspsgram
uses the DSP32 or DSP32C digital signal-processing board,
rather than the workstation CPU, for computing spectrograms.
On systems that have the board
.I dspsgram
is the faster program,
but on systems without the board
.I sgram
must be used.
Because of differences in arithmetic precision
and details of the computational algorithms and framing methods,
the outputs of the two programs should not be expected to be identical.
\fIdspsgram\fP currently works on FEA_SD (5\-\s-1ESPS\s+1) files (as well as
old style SD (5\-\s-1ESPS\s+1) files,
but it does not work on complex or multichannel data.
.PP
By default (specifying no options) or by specifying
\fIwb\fR for the \fB\-m\fR option, \fIdspsgram\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 approximately
the length of the specified range of points
(see the
.B \-p
and
.B \-s
options)
divided by the step size (see the
.B \-S
option).
The actual number may be slightly smaller than that value, being rounded
down to a multiple of 2 or 4.
The first frame is centered on the first point of the specified range,
with zeros filled in as needed to the left of that point.
The last frame in each file may overrun the range;
in fact more than one may do so
if the step size is smaller than the window length.
If a frame overruns the end of the input file, it is filled out with zeros.
.PP
If "\-" is specified for the input file, standard input is used.  If
"\-" is specified for the output file, standard output is used.
.PP
To avoid mutual interference, all of the programs that make use of the
DSP32 board (\fIwaves\fP+, \fIwplay\fP, \fIwrecord\fP, and
\fIdspsgram\fP) cooperate by means of a lock file on /tmp.  Before
using the board for an operation, these programs attempt to create the
lock file.  If the attempt succeeds, the program proceeds with the
operation and then removes the lock file.  The attempt will fail if
the lock file already exists, indicating that the board is in use.
.PP
When an attempt to create the lock file fails because the file exists,
the program will repeat the attempt at one-second intervals for five
seconds.  If it does not succeed, it gives up and prints a message
giving the name of the lock file and saying that the board is in use.
.PP
File-system problems may keep programs from creating the lock file
even though it does not already exist.  In that case, the programs
quit waiting and print an error message immediately.
.PP
Three messages on \fIstderr\fP are possible in connection with lock files:
.nf

	set_lock: lock file \fIfilename\fP exists

.fi
when the program has tried for 5 seconds and the file still exists;
.nf

	set_lock: can't create lock file \fIfilename\fP

.fi
when the program fails to create the lock file for some other reason;
and
.nf

	rem_lock: can't remove lock file \fIfilename\fP

.fi
when the program has a problem removing a lock file that it has
created.  The name of the lock file has the form
.nf

	/tmp/dspLCK\fIhostname\fP

.fi
where \fIhostname\fP is the hostname of the workstation.  Occasionally
a program may create the lock file and terminate abnormally without
removing it.  Then someone must remove the lock file with the UNIX
\fIrm\fP command before other programs can use the board.  Naturally
one should always check first that some other user is not actually
using the board.
.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 = 7, window_len = 8 ms, step_size = 2 ms,
and data_window = HAMMING.
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 = HAMMING.
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 at least 2 to the power
.I fft_order.
If that quantity is less than the number of data points in each frame
.RI ( window_len
\- see
.BI \-w ),
the transform length is increased to the least power of 2
that is at least equal to
.I window_len.
Then, if
.I window_len
is less than the transform length, the frame is padded with zeros.
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