xwaves.1

speech signal process tools

.\" Copyright (c) 1987-1990 AT&T, Inc.
.\" Copyright (c) 1986-1990 Entropic Speech, Inc.
.\" Copyright (c) 1990-1997 Entropic Research Laboratory, Inc. All rights reserved.
.\" @(#)xwaves.1	1.14 9/24/98 ATT/ESI/ERL
.ds ]W (c) 1997 Entropic Research Laboratory, Inc.
.TH XWAVES 1\-ESPS 9/24/98
.if t .ds - \(em\h'-0.5m'\(em
.if n .ds - ---
.if n .ds lq \&"\"
.if t .ds lq \&``
.if n .ds rq \&"\"
.if t .ds rq \&''
.\" Macro for chapter titles like "xlabel" or "xchart reference"
.\" or "xmarks quick reference"<punctuation>.
.de qI
.ie '\\$2'' \&\\*(lq\fI\\$1\fP\\*(rq\\$3
.el \&\\*(lq\fI\\$1\fP \\$2\\*(rq\\$3
..
.ds wD \fIwaves+ Manual\fP
.ds wR \fIwaves+ Reference\fP
.ds wT \fIIntroducing waves+\fP
.ad l
.SH "NAME"
xwaves \- an interactive display program for X
.SH SYNOPSIS
.B xwaves
[
.B \-c
] [
.BI \-n " alternative_name"
] [
.BI \-p " socket_port"
] [
.B \-s
] [
.BI \-w " wave_pro"
] [
.BI \-x " debug_level"
] [
.I infile1 infile2 ...
]
.SH DESCRIPTION
.PP
This manual entry briefly describes
.I xwaves,
the central component of the speech analysis package
.I waves+,
but does not pretend to be a complete
.I xwaves
manual.
For full details you will need to follow the references to the
complete documentation in \*(wD and \*(wR.
See \*(wT for a hands-on tutorial introduction.
.SS Introduction
.PP
.I xwaves
is an interactive program for display and manipulation of time-series data.
It lets you, among other things,
browse through lengthy signals,
zoom in on selected portions to examine features in detail,
cut and paste segments of the signal,
do interactive spectral analysis and signal annotation,
play back signals,
compute and display speech formant frequencies and pitch contours,
and perform other editing and display operations.
Operations can be selected from menus with the mouse,
activated by single keystrokes at the keyboard,
or invoked through commands in an interpreted language.
Commands can be entered manually via the control panel,
supplied in command files,
or sent to
.I xwaves
from other programs.
Besides its many built-in capabilities,
.I xwaves
provides several modes for customization and functional extension.
It implements most of its signal-processing functions
by calling ESPS or other programs running somewhere on the local network.
The graphical interface is based on the X Window System.
.I xwaves
displays can be generated and controlled
by another UNIX process, and
.I xwaves
can be used as an interface to control another UNIX process.
.PP
.I xwaves
is executed like any other UNIX process,
and input files can be specified on the command line.
However, there are many other ways of specifying input files,
and output file names are never specified on the command line.
The files, if any, specified on the command line are interpreted
either as data to be displayed or as commands to be executed,
depending on the file contents.
If the first non-comment line (not starting with #) in the file
is a line beginning with \*(lqwaves\*(rq,
the file is interpreted as a command file.
Up to 50 files can be specified on the command line.
.SS The main control panel
.PP
The basic interface to
.I xwaves
is its
.I main control panel.
This contains text input items 
that specify data file names, commands, and command-file names,
and it contains buttons that access on-line help and control program flow
in various ways.
By default, the control panel appears
in the upper left corner of the screen
when startup is complete.
The value of a text item can be modified
by activating it with the left mouse button
and then typing in or editing text.
The new value does not take effect until
.I entered
by hitting the RETURN key (while the item is active).
The panel buttons perform their functions immediately
when selected with the left mouse button.
The names of the panel items and brief explanations follow.
For more complete explanations, see \*(lqThe
.I xwaves
main control panel\*(rq in \*(wD.
.TP
.B INPUT file:
The relative or absolute pathname of a signal to be displayed.
To read in and display a new signal, enter the file name here.
.TP
.B OUTPUT file:
Specifies the names of output files to be created by the
.B save segment in file
and
.B insert file
functions (see \*(lqData window menu items\*(rq in \*(wD).
An extension appropriate to the data type is automatically appended.
A purely alphabetic name is used without modification
(except for the appended extension).
A name whose basename ends in a number increments the number
after the output waveform segment is stored.
A name preceded with \*(lq@\*(rq specifies a text file
containing a list of output filenames.
If
.B OUTPUT file:
is blank, the filename of the source signal is modified by insertion
of a \*(lq.\*(rq followed by a number chosen to maintain uniqueness.
A list of files generated during the current run
can be browsed by clicking on the
.B OUTPUT file:
item with the right mouse button.
.TP
.B OBJECT name:
The name by which to refer to an
.I object
or
.IR "display ensemble" :
a set of data display windows
that are treated as a unit for certain purposes.
The time cursors and markers of all display windows in an object
are synchronized.
If a new object name is specified, subsequently generated data display
windows become part of a logically distinct and independent object.
.TP
.B COMMAND (or @file):
A direct command in the
.I xwaves
command language or the pathname of a text file
(preceded by the character \*(lq@\*(rq)
containing commands to be executed.
.TP
.B PAUSE
Clicking on this button with the mouse
while commands are being executed from a command file
causes the command file to suspend execution.
The
.B PAUSE
button has no effect on commands coming from processes via the
.IR send_xwaves (1\-ESPS)
program or the
.IR SendXwaves (3\-ESPS)
library functions.
.TP
.B CONTINUE
Clicking on this button causes
.I xwaves
to resume processing of a command file that was suspended by a
.I pause
or
.I sleep
command or by clicking on the
.B PAUSE
button.
If the global variable
.I command_step
is non-zero,
.B CONTINUE
causes
.I xwaves
to execute only the next pending command and then pause again,
allowing the user to single-step through a sequence of commands.
.TP
.B Attach:
This collection of buttons provides a selection of auxiliary programs
.RI ( attachments \*-see
\*(lqThe attachments\*(rq in \*(wD)
that can each be activated by pressing the corresponding button
or deactivated by pressing the button again.
.TP
.B Overlay name:
The relative or absolute name of any ESPS
.I FEA
file.
Each element of each field in the file is overlaid as a separate track
labeled with the field name and (if non-scalar) indices.
By default the overlay is placed on the most recently created
spectrogram display window, if any,
and otherwise simply on the most recently created display window.
You can override the default by following the overlaying file's name
with the filename (separated by whitespace)
of the window on which to place the overlay.
.TP
.B QUIT!
Clicking on this item causes all modified or newly created signals to
be saved and
.I xwaves
to exit.
.TP
.B waves MANUAL
This pops up a copy of \*(wR
in a searchable text window.
.PP
When a wildcard construct (e.g. \*(lq*\*(rq) is entered in
.B INPUT file:
or
.BR Overlay: ,
a window appears to the right of the main control panel
containing a scrollable list of files matching the construct.
A directory path generates a list of all files in the directory.
If signals have been generated and saved in files,
they are entered in a list that can be viewed by clicking on
.B OUTPUT file:
with the right mouse button.
A file can be selected as input to the panel item
with the left mouse button.
The right button displays a menu of operations on the files.
See \*(lqThe file browsers\*(rq in \*(wD for a list of the operations
with explanations.
.SS The miscellaneous controls panel
.PP
When you start
.I xwaves,
another panel normally appears to the right of the main control panel:
.BR "Miscellaneous xwaves Controls" .
This normally contains the 12 buttons listed below.
However, the panel is fully customizable;
it is just another panel created with the
.I xwaves
command
.I make_panel
(see
.qI xwaves "command reference"
in \*(wR),
and you can change its functionality by editing the relevant files
(see \*(lqThe init_file\*(rq under \*(lqChanging the
.I xwaves
environment\*(rq in \*(wD,
\*(lqThe
.I waves+
directory structure\*(rq in \*(wD,
and the discussions of the individual buttons
under \*(lqThe miscellaneous controls panel\*(rq in \*(wD).
.TP
.B Add_op...
Clicking on this button with the left mouse button pops up a new panel
that lets you interactively specify new functions to be added to your
menu lists.
For a full description of the functionality of the window
see the description of the
.I xwaves
command
.I add_op_panel
in the chapter
.qI xwaves "command reference"
of \*(wR.
.TP
.B Image Painting
This button allows control of the appearance of spectrogram
displays and their behavior when their windows are resized.
.TP
.B Audio extensions...
Clicking with the left mouse button pops up a panel with a help file 
and menus that you will need only if you purchased ETSM (an
optional waves+ add-on product for time scale modified playback) or if
you are using a third party DSP board (Ariel DSP 32C, LSI C30, or
Townshend DATLink) for playback and/or recording.  The play and record
program menus are using for controlling playback and recording sound
with the 3rd party DSP boards as listed above.  The play menus lets you 
select the play program
.RI ( play_prog \*-see
\*(lqUsing audio\*(rq in \*(wD) used by
.I xwaves
to play audio files.  If you are using
native hardware for playback and recording, you will not need to use
these menus.  
.TP
.B waves+ profile...
Clicking with the left mouse button pops up a panel
that lets you examine and change command configurations
and the profile file
.I .wave_pro.
.TP
.B Print setup...
Clicking with the left mouse button pops up a panel that let you
set the
.I xwaves
global variables that control printing.
See \*(lqPrinting graphics\*(rq in \*(wD
and
.qI xwaves "symbols reference"
in \*(wR
for more information on printing and the individual variables.
.TP
.B Annotation...
Clicking with the left mouse button pops up a panel
that gives you detailed control over
whether the following annotations on the data windows are displayed:
ESPS field names, field values at the cursor position,
and axis tick marks or grids.
.TP
.B Ganging...
Clicking with the left mouse button pops up a panel
that lets you control which of the following operations
are performed simultaneously on all windows of an object
and which affect only one window at a time:
scrolling, zooming, and deletion of segments.
.TP
.B Colormap...
Clicking with the left mouse button pops up a panel
that lets you change the colors
in which waveforms and spectrograms are displayed.
.TP
.B Toolbars...
Clicking with the left mouse button pops up a panel
that lets you add
.I toolbar creators
to the waveform and spectrogram menus.
This means that an entry in the display menu lets you create a toolbar
with functions that apply to a specific display.
Several ready-to-use toolbars are available,
and it is easy to create more yourself.
See the help file available through the
.B Toolbars...
panel, and see the
.B Toolbars...
entry under \*(lqThe miscellaneous controls panel\*(rq in \*(wD.
.TP
.B Menu Changes...
Clicking with the left mouse button pops up a panel
that lets you change the waveform and spectrogram display menus
by adding items or selecting predefined alternative menus.
A help function is also provided.
.TP
.B Mouse bindings...
Clicking with the left mouse button pops up a panel
that lets you select the functions
performed by the left and middle mouse buttons
in waveform and spectrogram windows.
See also \*(lqMouse button modes\*(rq in \*(wD.
.TP
.B Debug...
Clicking with the left mouse button pops up a panel
that lets you set
.I xwaves
global variables
that control the verbosity of information and debugging messages
and turn on single-stepping mode for command-file interpretation.
See
.qI xwaves "symbols reference"
in \*(wR.
.SS Data display windows
.PP
There are two major types of signal data display windows:
.I waveform
windows and
.I spectrogram
windows.
Waveform windows display plots of single or multiple
sampled-data and parameter tracks.
Spectrogram windows display data as intensities or colors
in the time-frequency plane.
Each window has a frame that includes a title bar.
If the right mouse button is pressed
while the cursor is in the frame,
the window system frame menu appears.
The contents of this frame menu depend on the window manager,
but common items allow the window to be iconized removed, resized, etc.
.PP
Inside the frame are three regions:
a data display that fills most of the window,
a scrollbar region just above it,
and an information region just above the scrollbar.
As the cursor moves in the data region,
the corresponding time values
are continually updated in the information region,
and data values are updated either there or in the data region.
Cursors in other windows of the same object (see
.B OBJECT name:
under \*(lqThe main control panel\*(rq above)
move in synchrony.
.PP
Pressing the right mouse button while the cursor is in the
data display region calls up a menu listing
data- and display-manipulation options.
The left and middle mouse buttons have several programmable
functions, such as moving markers, playing segments, modifying 
data, or any of the right-button menu items.
Menu operations and
.I xwaves
commands permit changing the button semantics.
The functions currently in effect are displayed in the frame title bar.
There are four distinguished markers, two horizontal and two vertical,
that can be positioned with the mouse pointer
if an appropriate mouse-button function is enabled.
To move the horizontal markers,
hold down the shift key on the keyboard while operating the mouse;
otherwise the vertical markers are moved.
See \*(lqMouse button modes\*(rq in \*(wD for more information.
.PP
Mouse buttons pressed while in the scrollbar region
cause the following operations:
.I left
moves the displayed point marked by the mouse pointer
to the left window edge;
.I right
moves the displayed point at the left window edge
to the position of the mouse pointer;
.I middle
centers the display window over the point in the data file
proportional to the distance along the scrollbar
at which the button was pressed.
When the mouse pointer is in the scrollbar, the time readout changes
to reflect not the time in the displayed portion of the file,
but the time in the whole file,
with the beginning corresponding to the left end of the scrollbar
and the end of the file corresponding to the right end.
The shaded portion of the scrollbar
corresponds to the portion of the data file
that is currently visible in the window.
.PP
In spectrogram windows
the operations that can be bound to the left or middle mouse button
include three that are inapplicable to waveform windows:
.BR "mark formants" ,
.BR "move contour" ,
and
.BR "modify intensity" .
The latter is the default action of the middle button;
it lets you modify the threshold and dynamic-range values
that control the mapping
from spectral density to display intensity or color;
think of it as analogous to manipulating
the brightness and contrast controls of a television set.
For the other mouse button functions, see \*(lqMouse button modes\*(rq
in \*(wD.
.PP
In a spectrogram window,
data can be displayed at the \*(lqnatural scale\*(rq of one point per pixel,
or it can be rescaled vertically or horizontally
to accommodate changes in the height and width of the window.
Scaling behavior is controlled by four global variables
that can be set by an
.I xwaves
command or with the help of the
.B Image Painting
item of the miscellaneous controls panel.
See the description of the panel item above, and see
\*(lqScaling, interpolation, and zooming\*(rq under \*(lqData display windows\*(rq
in \*(wD.
.PP
To determine the colors used for plotting waveforms and spectrograms
and for drawing cursors, markers, axes, etc.,
.I xwaves
reads a colormap file, whose name is given by the global variable
.I colormap.
This can be initialized in the
.I .wave_pro
file and changed at any time by an