xwaves.1

speech signal process tools

Those that are important for
.I xwaves
are described in \*(lqThe UNIX environment variables\*(rq in \*(wD.
Only two are mandatory.
ELM_HOST must be set to the host name of the machine on your network
that is running the Entropic license manager daemon.
ESPS_BASE must be set to the top of the
.RI ESPS/ waves +
installation directory tree.
In order to have easy access to the programs
that are likely to be used in conjunction with
.I xwaves,
be sure that
.I $ESPS_BASE/bin
is in your UNIX PATH definition before running
.I xwaves.
.SS File formats
.PP
.I xwaves
supports the use of different data file formats.
The most natural way is to use ESPS
.I FEA
files.
.I xwaves
is tuned to these files and can handle them very easily.
When
.I FEA
files are used,
they can be either in machine native format or EDR format,
which makes it easy to port signals between different systems.
See \*(lqFile formats and \fIxwaves\fP\*(rq
in \*(wD for details.
On the other hand there are various ways to read
.RI non- FEA
files with
.I xwaves.
Like most ESPS programs,
.I xwaves
will directly read
sampled-data files in the NIST
.I Sphere
format
and many files in the new Entropic
.I Esignal
format.
If
.I xwaves
does not recognize a file, it assumes it is headerless.
If the UNIX environment variable DEF_HEADER is defined
and points to a file with a valid
.I FEA
header,
that header is used as a \*(lqvirtual\*(rq header for the headerless file.
Thus, the data description in the file defined by DEF_HEADER
should be valid for the input data.
The ESPS conversion programs
.IR btosps (1\-ESPS),
.IR testsd (1\-ESPS),
and
.IR addfeahd (1\-ESPS)
are useful in creating such headers.
The
.I xwaves
global variable
.I def_header
can be used instead of the environment variable
and can be changed while
.I xwaves
is running.
Files that are headerless from the ESPS and
.I xwaves
viewpoint may in fact contain \*(lqforeign\*(rq headers.
If a
.I FEA
header contains certain \*(lqgeneric header items\*(rq,
a foreign header (i.e. a block of information at the head of the file)
is skipped when reading data.
(A copy is kept inside the
.I FEA
header, however, so that the foreign header
can subsequently be exposed again.)
See
.IR read_header (3\-ESPS)
for more details and for information about setting the relevant
generics in the headers specified by DEF_HEADER or
.I def_header.
.SS UNIX, ESPS, and xwaves
.PP
The discussion of the command
.I add_op
under \*(lqThe command language\*(rq above showed a simple example
of executing a UNIX shell command from within
.I xwaves.
See the discussion of
.I add_op
under \*(lqGlobal
.I xwaves
Commands\*(rq in \*(wD for more information and examples.
In general, the mechanism can start a unix process to run an external
program (while
.I xwaves
goes on its merry way).
If output is to be displayed,
.I xwaves
is signaled
when the forked process terminates.
.PP
In addition to
.I add_op,
there are more special facilities for calling ESPS programs from
.I xwaves.
.PP
When built-in
.I xwaves
support for a DSP board is not used,
external programs are used to generate spectrograms.
In particular the program or command indicated by the global variable
.I sgram_prog
is invoked with appropriate command-line options.
The default value is \*(lqsgram\*(rq,
which calls the program
.IR sgram (1\-ESPS),
but
.IR me_sgram (1\-ESPS)
can be used instead, or any program or script
that supports the right command-line options.
See \*(lqESPS spectrogram computation\*(rq
under \*(lqUNIX, ESPS, and \fIxwaves\fP\*(rq
in \*(wD for details.
.PP
Support for the built-in audio of most workstation on which
.I xwaves
runs is built into
.I xwaves
and is used by default for audio output.
However, you can specify other means of output by setting the
.I xwaves
global variable
.I play_prog
to a program or command
that supports appropriate command-line options.
See \*(lqUsing audio\*(rq in \*(wD for details.
.SS Attachments
.PP
Attachments are programs that run as separate UNIX processes,
but in close cooperation with
.I xwaves.
In fact they will not do anything useful unless
.I xwaves
is running.
In general, attachments are used for tasks
that require a specific user interface that cannot be realized with
.I xwaves
alone.
These tasks require transfer of information between
.I xwaves
and the attachment.
Attachments communicate with
.I xwaves
through the X server,
using a communications protocol that is compatible with Tcl/Tk.
.PP
At the moment there are four standard
.I xwaves
attachments:
.IR xlabel (1\-ESPS),
.IR xspectrum (1\-ESPS),
.IR xmarks (1\-ESPS),
and
.IR xchart (1\-ESPS). 
These are described in corresponding chapters of \*(wD
(\c
.qI xlabel "" ,
.qI xspectrum "" ,
.qI xmarks "" ,
.qI xchart "" )
and \*(wR
(\c
.qI xlabel "reference" ,
.qI xlabel "quick reference" ,
etc.).
.PP
An attachment is normally started with the
.I xwaves
command
.I attach
or by clicking on a button in the
.B Attach:
field in the
.I xwaves
main control panel.
It can also be started from the command line,
but then you may have to worry about the command line options.
The attachments are stopped when
.I xwaves
stops.
.PP
The attachments have their own command languages,
which resemble that of
.I xwaves.
The individual commands are described
in the \*(lq... reference\*(rq chapters of \*(wR.
.PP
The attachments do not have their own command-entry facilities.
Instead, commands are sent to attachments via the
.I xwaves
command
.I send.
This can be issued in any of the usual ways, including
.IR send_xwaves (1\-ESPS).
Thus attachments can be controlled from UNIX shell scripts.
For examples of the use of
.I send,
see \*(lqUsing the program \fIsend_xwaves\fP\*(rq
and \*(lqAttachments and the command language\*(rq
under \*(lqThe
.I waves+
command language\*(rq
and the chapters on the individual attachments in \*(wD.
.PP
The attachment
.IR xlabel (1\-ESPS)
is a general-purpose signal segmentation and labeling program.
It can be used to view multiple label/segmentation files
simultaneously.
Labels can be selected from a user-configurable menu
or typed in directly from the keyboard.
They are displayed in a window containing markers with attached labels
in time alignment with a signal in an
.I xwaves
signal display window.
.I xlabel
is especially useful for comparing and generating
multiple segmentations of the same signal
when the label sequence is not known in advance.
.PP
.IR xspectrum (1\-ESPS)
facilitates interactive
power-spectrum analysis of data that is displayed in
.I xwaves
windows.
Individual spectra displayed by
.I xspectrum
can be compared by overlaying them on a common plot.
The spectrum analysis method and parameters
can be varied by entering values in the
.I xspectrum
control panel.
If a linear-prediction (maximum-entropy) spectrum-analysis method
is used,
.I xspectrum
also supports inverse filtering of the selected data
and formant/bandwidth estimation.
.I xspectrum
will also display \*(lqspectral slices\*(rq (single-frame power spectra)
from data in
.I xwaves
spectrogram windows.
.PP
.IR xmarks (1\-ESPS)
is specialized for assigning times in waveforms
to pre-defined label sequences.
It is specifically designed for labeling speech
in that it supports labeling of sentence-like structures.
Labels are supplied in a specific format
in a file created before the attachment is run.
.I xmarks
lets you quickly place labels
by clicking a mouse button in the signal window.
.I xmarks
automatically selects the next label to be placed.
.PP
.IR xchart (1\-ESPS)
is an extension of
.I xlabel
that offers all the features of
.I xlabel
and provides an additional display mode.
.I xchart
was designed to manipulate displays of \*(lqcharts\*(rq.
A chart is a collection of possibly overlapping
signal-segment labels\*-for example, word hypotheses
from a speech recognizer's \*(lqfront end\*(rq.
Each segment label is associated with a character string
called a
.I symbol.
.I xchart
displays these symbols in a window below an
.I xwaves
signal display, possibly along with label files
of the type described in the chapter on
.I xlabel.
.SH OPTIONS
.PP
The command-line options recognized by
.I xwaves
are the following.
.TP
.BI \-c
Specifies that
.I xwaves
creates its colormap segment as STATIC,
making it sharable with other applications on the same X server. 
Since
.I xwaves
uses a rather large colormap, there may be interference
if another application on the same X server
(such as another copy of
.IR xwaves )
also tries to allocate a large colormap.
If you must run more than
.I xwaves
on the same server, and you have colormap problems
(flashing as you move the mouse or incorrect colors),
start each
.I xwaves
with the
.B \-c
option and have them all load the same colormap via the
.I .wave_pro
file (see
\*(lqChanging the
.I xwaves
environment\*(rq in \*(wD).
They will then share the colormap segment.
.IP
A side effect of this option
is that the colormap cannot be changed after the initial one is loaded.
In addition, interactive alteration of the color threshold
and contour marking via the mouse in spectrogram views
do not work with STATIC colormaps.
.TP
.BI \-n " alternative_name"
.I xwaves
has an interprocess communication capability,
which programs such as
.IR send_xwaves (1\-ESPS)
can use to send commands to
.I xwaves
and get results in reply.
The communication method
is based on communicating through the X server
and is compatible with Tcl/Tk (version 4).
When
.I xwaves
starts, it registers itself with the server
that it is using for display.
By default, it registers under the name \*(lqxwaves\*(rq,
but a different name can be specified by means of this option.
This might be done if, for example, it were necessary to run two
.I xwaves
processes at once on the same X display.
.TP
.BI \-p " socket_port"
Specifies the INET domain socket port number to listen on
when in \*(lqserver mode\*(rq (as a result of the
.B \-s
option or the
.I enable_server
command).
See the comment under
.B \-s
concerning the phaseout of this server mode.
.IP
If this option is not used,
and if the UNIX environment variable WAVES_PORT is defined,
the port is set to the value of WAVES_PORT.
If WAVES_PORT is not defined, a compiled-in default is used.
The port number can be changed at any time through an
.I xwaves
command by setting the
.I xwaves
global variable
.I socket_port
(see the chapter
.qI xwaves "command reference"
in \*(wR);
the change takes effect the next time the
.I enable_server
command is executed.
.TP
.BI \-s 
Specifies that
.I xwaves
starts up in \*(lqserver mode\*(rq.
This is equivalent to executing the
.I xwaves
command
.I enable_server.
When in server mode,
.I xwaves
listens on a socket for commands sent by external scripts or programs
that use the
.IR send_xwaves (3\-ESPS)
library functions.
In pre-5.0 versions of
.I xwaves
it was necessary to be in the server mode for the
.IR send_xwaves (1\-ESPS)
program to function.
This is no longer true, since
.IR send_xwaves (1\-ESPS)
now uses a different communication protocol.
In the current release
this server mode is not needed by any Entropic-supplied programs
and is provided only for compatibility with old user-written programs.
For new programs, use the library functions
.IR SendXwavesNoReply (3\-ESPS)
and
.IR SendXwavesReply (3\-ESPS).
.TP
.BI \-w " wave_pro"
Specifies the startup profile to read.
If this option is not used,
.I xwaves
attempts to read the file
.I .wave_pro
along the search path
.I $HOME:$ESPS_BASE/lib/waves.
That is, it first looks for a file
.I .wave_pro
in the user's home directory and then for
.I $ESPS_BASE/lib/waves/.wave_pro.
The search path used can be overridden by setting the UNIX
environment variable WAVES_PROFILE_PATH before starting
.I xwaves.
The same search path is used for names supplied with the
.B \-w
option.
.TP
.BI \-x " debug_level"
If the argument is positive,
.I xwaves
prints debugging messages on the standard error output.
The number of messages increases with increasing values of
.I debug_level.
No messages are printed for a
.I debug_level
of 0.
The value can be changed at any time through an
.I xwaves
command by setting the
.I xwaves
global variable
.I debug_level
(see the chapter
.qI xwaves "symbols reference"
in \*(wR).
.SH SEE ALSO
\*(wD,
\*(wR,
\*(wT,
.br
.IR addfeahd (1\-ESPS),
.IR btosps (1\-ESPS),
.IR espsenv (1\-ESPS),
.br
.IR me_sgram (1\-ESPS),
.IR send_xwaves (1\-ESPS),
.IR sgram (1\-ESPS),
.br
.IR testsd (1\-ESPS),
.IR xchart (1\-ESPS). 
.IR xlabel (1\-ESPS),
.br
.IR xmarks (1\-ESPS),
.IR xspectrum (1\-ESPS),
.br
.IR SendXwavesNoReply (3\-ESPS),
.IR SendXwavesReply (3\-ESPS),
.br
.IR read_header (3\-ESPS),
.IR send_xwaves (3\-ESPS)
.SH AUTHOR
.PP
Original program by David Talkin at AT&T Bell Laboratories.
Later enhancements by 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,
all derived ultimately from Talkin's original documentation
with many revsions and additions by
David Burton, Joop Jansen, Rod Johnson, Alan Parker, John Shore, David Talkin,
and others at Entropic.