xspectrum.1

speech signal process tools

item.
The inverse filtered signal is integrated
(e.g., to convert pressure to volume velocity)
using a leaky integrator with the coefficient determined by the
.B "Integration Coeff:"
item; 0.0 implies no integration.
The resultant signal is then stored in a file,
and a message is sent to cause
.I xwaves
to display it in a regular waveform window.
The file name is derived from that of the original signal
by appending a distinguishing number.
If the
.I xwaves
global
.I output_dir
(read by
.I xspectrum
on startup) is defined,
that location is used for the inverse filtered signals.
Otherwise the file is stored
in the same directory as the original signal. 
.TP
.B "xspectrum manual"
Clicking on this button
brings up a formatted version of this manual entry
in a browsable xtext window.
.TP
.B "QUIT"
Clicking on this button detaches
.I xspectrum
from
.I xwaves
and terminates execution.
.TP
.B "Horizontal cursor:"
When
.BR ON ,
display the level (magnitude) cursor that rides on the spectrum
and corresponds to the level at the particular frequency
selected by the X location of the cursor.
.TP
.B "Reticle:"
When
.BR ON ,
display a reticle.
The horizontal axis is frequency; the vertical axis
is determined by the
.B "Plot scale:"
setting.
.TP
.B "Formants:"
When this formant/bandwidth estimate switch is
.BR ON ,
print estimates of the formant frequencies
(i.e. complex poles of the all-pole LPC model)
and their bandwidths to standard output if the current
.B "Analysis type"
is any of the LPC-based (maximum-entropy) types.
The formant frequencies are selected from candidates
proposed by solving for the roots of the linear predictor polynomial.
This frequency and bandwidth output is only available
if the order is less than 30.
.TP
.B "Harmonic cursors:"
When
.BR ON ,
display a harmonic series of cursors.
When the harmonic cursors are turned on,
the mouse pointer, if moved in the spectrum display,
controls the frequency of a harmonic
in the vicinity of the right edge of the display.
As the pointer moves right
it eventually jumps back to the next lower harmonic.
Similarly if the pointer is moved left,
it eventually jumps to the next higher harmonic
(up to the twentieth harmonic).
Thus, fine-grained control of the
first harmonic, and thus the harmonic spacing is always maintained.
If the pointer is moved out of the window vertically,
then back in at about the same place,
control of the same harmonic will be resumed.
If the middle button is pressed,
the pointer can be moved out of the window in any direction
without disturbing the cursor adjustment.
The frequency and amplitude readouts at the top of the plot
continue to refer to the fundamental frequency.
.TP
.B "Plot scale:"
This switches among three different choices
for the scale of the vertical axis:
.B "log pwr (dB)"
(the default),
.BR "magnitude" ,
and
.BR "power (square of magnitude)" .
.TP
.BR "Cep. cut (sec):" "\ \ \ \-\ \ \ " "Cep. trans:" "\ \ \ \-\ \ \ " "Liftering:"
These affect spectrum estimation when cepstral smoothing
.RB ( CEPST )
is specified by
.BR "Analysis type:" .
.B "Liftering:"
selects high-pass liftering, low-pass liftering, or none.
.B "Cep. cut (sec):"
gives the nominal cutoff quefrency.
.B "Cep. trans:"
gives the duration of a quefrency transition region
between zero and full power, which reduces the ripple artifact
that would result from zero transition time (rectangular liftering).
The transition shape is a raised half cycle of a cosine.
The transition region is divided evenly between the stop band
and the passband.
.SS "xspectrum colors"
.PP
The current
.I xwaves
colormap is passed to
.I xspectrum
as part of the temporary
.I .wave_pro
read via the
.B \-w
option.
.PP
The format of
.I xwaves
colormap files is 128 lines with three integers per line,
separated by spaces or tabs.
The integers,
which must be in the range 0\-255,
specify the intensities of red, green, and blue respectively.
The line ordering is from low to high map entries.
The first 115 entries are used by
.I xwaves
for representing spectral power density in spectrograms.
The remaining 13 entries
specify the colors of cursors, reticles, backgrounds, etc.
.I xspectrum
uses some of these last
13 entries for similar purposes, as shown in the following table.
The first column is the entry number, the second is the notation
used to refer to these by
.I xwaves,
and the third column
describes the use within
.I xspectrum.
.nf
.ta .2i .75i 2i 
.sp 0.5
	116	WAVE2
	117	YA1	2nd ref. spectrum and digital readouts
	118	YA2	3rd ref. spectrum and digital readouts
	119	YA3	4th ref. spectrum and digital readouts
	120	YA4
	121	YA5
	122	MARKER	vertical (frequency) cursor(s)
	123	CURSOR	1st ref. spectrum and digital readouts
	124	WAVEFORM
	125	TEXT	current spectrum and digital readouts
	126	RETICLE	current spectrum horizontal cursor
	127	BACKGRND
	128	FOREGROUND
.sp 0.5
.fi
.DT
.SS "Graphics export"
.PP
Like
.I xwaves
and the other attachments,
.I xspectrum
has the capability to export graphics
in either PostScript or PCL (HP LaserJet code).
This can be used to print displays directly on the printer
or to generate graphics to be imported into a document
with a suitable text editing program.
Graphics output is invoked by selecting the
.B print graphic
item on the
.I xspectrum
menu or by a
.I print
command sent to the display object in
.I xspectrum
from
.I xwaves.
.PP
There is an
.I xwaves
command,
.I "print_setup",
that invokes a setup window
with which you can choose output to a file or printer,
select PostScript or PCL, set output resolution and scaling,
and control other aspects of the graphics-export environment.
See the chapter \*(lqPrinting graphics\*(rq in \*(wD for details.
.PP
.I xspectrum
supports the
.I xwaves
command
.I print_ensemble;
it can cooperate with
.I xwaves
to allow the contents of
.I xspectrum
windows to be included in
.I xwaves
multi-window graphics output.
See \*(lqPrinting graphics\*(rq in \*(wD for details.
.SS "xspectrum symbols"
.PP
.I xspectrum
has its own set of symbols.
A full list of these symbols and their uses
can be found in the chapter
.qI xspectrum "reference"
in \*(wR.
.PP
You can specify these variables in your profile file.
When
.I xspectrum
is started from
.I xwaves,
it is automatically passed a temporary file written by
.I xwaves
that contains the values of all the
.I xwaves
globals in standard
.I xwaves
profile format.
The file  is passed with the option
.BR \-w .
.PP
Most of these
.I xspectrum
variables can also be set after starting by a
.I set
command sent to
.I xspectrum
by the
.I xwaves
command
.I send.
E.g.:
.LP
.RS
.nf
.if t .ft I
send function xspectrum op xspectrum set <var> <val>
.if t .ft P
.fi
.RE
.PP
.SS "xspectrum commands"
.PP
.I xspectrum
recognizes a limited set of commands
that are listed and described in the chapter
.qI xspectrum "reference"
in \*(wR.
.PP
.I xspectrum
can be controlled by an
.I xwaves
command file or by commands from the program
.IR send_xwaves (1\-ESPS)
or the
.IR SendXwaves (3\-ESPS)
functions.
Commands from these sources can be passed through to
.I xspectrum
via the
.I xwaves
command
.I send.
The syntax of the
.I received
commands is:
.LP
.RS
.nf
.if t .ft I
object command keyword value keyword value ...
.if t .ft P
.fi
.RE
.LP
(the same as for
.I xwaves
commands).
The first item,
.I object,
is either the attachment name \*(lqxspectrum\*(rq
or the name of a display object.
The second item,
.I command,
is the actual command name.
There may be any number, including 0, of keyword\-value pairs.
.SH OPTIONS
.PP
.I xspectrum
is usually started as a subordinate program by
.I xwaves.
In this case, you need not be concerned with the
command-line options presented below, and you may skip this section.
However, it is also possible to run
.I xspectrum
(and the other attachments) as sibling UNIX processes,
in which case it may be necessary
to specify one or more of the following options.
.TP
.BI \-c " host_X_registry"
This is the name that the host program is registered under
for X server-based communications.
This option is intended to be supplied by
.I xwaves
when it runs
.I xspectrum.
.TP
.BI \-n " host_name"
This is the name of the program object with which
.I xspectrum
will be communicating.
When the host program is
.I xwaves,
this name is always the default value, \*(lqwaves\*(rq.
.TP
.BI \-w " wave_pro"
Specifies the startup profile to read.
This option is always used
when
.I xspectrum
is invoked by
.I xwaves,
in which case the specified profile
is a temporary file written by
.I xwaves
and containing the current state of the
.I xwaves
globals.
If
.B \-w
is not used (only possible if
.I xspectrum
is run from the shell),
.I xspectrum
attempts to read the file
.I .wave_pro.
In both cases the search path
.I $HOME:$ESPS_BASE/lib/waves
is used.
The search path used can be overriden
by setting the UNIX environment variable WAVES_PROFILE_PATH before starting
.I xwaves.
.SH SEE ALSO
\*(wD,
.br
\*(wR,
.br
\*(wT,
.br
.IR fft (1\-ESPS),
.IR formant (1\-ESPS),
.IR me_spec (1\-ESPS),
.br
.IR refcof (1\-ESPS),
.IR send_xwaves (1\-ESPS),
.IR transpec (1\-ESPS),
.br
.IR xchart (1\-ESPS),
.IR xfft (1\-ESPS),
.IR xlabel (1\-ESPS),
.br
.IR xrefcof (1\-ESPS),
.IR xwaves (1\-ESPS),
.IR compute_rc (3\-ESPSsp)
.SH BUGS
.PP
Depending on the analysis method and the waveform being analyzed, the
maximum-entropy methods can get into computational trouble at large
orders, in some cases leading to abrupt terminations.
Pure (noise-free) sinusoids can cause trouble with several of the
maximum-entropy methods at any analysis order.
This is because the estimated correlation
matrix is singular for line spectrum.
See
.I Digital Signal Processing,
Roberts and Mullis, Addison Wesley, 1987, page 533.
.PP
.I xspectrum
requires that the data to be analyzed
(or displayed) exist in a UNIX file.
Thus,
.IR xwaves -internal
signals (such as spectrograms generated by some
of the DSP boards, or hand-edited signals not written to disk)
must be explicitly saved to disk if they are to be analyzed
by issuing a
.I "send make ..."
command.
If the spectrum analysis is initiated from the
.I xwaves
.B xspectrum
menu item, such signals are saved automatically.
.SH AUTHOR
Program by David Talkin, AT&T Bell Laboratories.
Later enhancements by
David Burton, Rod Johnson, Alan Parker, John Shore, David Talkin,
and others at Entropic.
This manual page largely extracted by Rod Johnson
from \*(wD and earlier manual pages
derived from Talkin's original documentation
with revisions and additions by
David Burton, Joop Jansen, Rod Johnson, John Shore, David Talkin,
and others at Entropic.