xwaves.1

speech signal process tools

.I xwaves
command.
The
.B Colormap...
button, mentioned above under \*(lqThe miscellaneous controls panel\*(rq,
works by setting the variable to the name of one of several predefined
colormap files.
See \*(lqColormaps\*(rq in \*(wD to find out
how to create your own colormap files. 
.SS Data window menu items
.PP
Using
.I xwaves
commands, you can customize the contents of the menus that pop up
when you press the right mouse button in the data region of an
.I xwaves
display window.
You can do this separately for the waveform and spectrogram menus.
There are commands for deleting and restoring menu items.
With the
.I add_op
command, you can define new menu items
that invoke arbitrary UNIX shell commands or
.I xwaves
commands.
For full information, see \*(lqData window menu items\*(rq in \*(wD
and the commands
.I delete_item,
.I delete_all_items,
.I add_op,
.I add_waves,
and
.I op
under
.qI xwaves "command reference"
in \*(wR.
In addition there are a number of \*(lqbuilt-in\*(rq menu operations
that are present by default unless explicitly removed.
See \*(lqData window menu items\*(rq in \*(wD for more information
on the individual items.
.PP
.BR "play between marks" ,
.BR "play window contents" ,
.BR "play entire file" ,
and
.B "play to end of file"
let you listen to various portions of a signal
by sending them to a D/A converter.
.BR "page ahead" ,
.BR "page back" ,
.BR "window ahead" ,
and
.B "window back"
move the view in the display window
forward or backward through the file.
.B "align and rescale"
rescales and repositions windows so that all other windows in an
object align vertically with the selected window.
.BR "bracket markers" ,
.BR "zoom in" ,
.BR "zoom out" ,
and
.B "zoom full out"
expand or contract the time scale of the window,
as suggested by the names.
.B "spectrogram (W.B.)"
and
.B "spectrogram (N.B.)"
create spectrograms of the portion of a signal delimited by the markers.
.B "save segment in file"
writes an output file containing the segment of the signal
delimited by the markers.
.B "delete segment"
and
.B "insert file"
let you edit a signal by cutting and pasting.
.B "Button Modes"
lets you determine which functions are invoked
by the left and middle mouse buttons.
.B "kill window"
removes the display window.
(This is needed on systems where a window cannot be removed
by using the window-manager frame menu.)
.B "print graphic"
and
.B "print ensemble"
output one or more display windows for printing.
.SS Printing graphics
.PP
There are two built-in 
.I xwaves
menu operations for producing printable output:
.B print graphic
and
.BR "print ensemble" .
(There are also ordinary
.I xwaves
commands that perform the same functions.)
.B "print graphic"
renders a single display window in either Encapsulated PostScript
or PCL (HP Laserjet code).
.B "print ensemble"
renders all display windows in an object in Encapsulated PostScript
(only).
The relative positions of the windows on the screen are preserved
in the printed output.
Some attachments (see \*(lqAttachments\*(rq below) can cooperate with
.I xwaves
to let
.B "print ensemble"
include windows created by the attachment in the output along with
those created by
.I xwaves
itself.
.PP
There are several
.I xwaves
global variables that control various aspects of the printing,
such as whether the output goes to a file or directly to a printer.
See \*(lqPrinting graphics\*(rq in \*(wD
for a list of the variables with explanations.
The
.B Print setup...
button, mentioned under \*(lqThe miscellaneous controls panel\*(rq above,
lets you set these variables.
.SS The command language
.PP
The
.I xwaves
command language provides control over
essentially the entire domain of actions available to
.I xwaves
and its attachments.
The commands of this language subsume all the functions
available through the mouse-oriented interface,
and they provide a means for extending the command set
and enhancing the interface.
.I xwaves
lets you assign values to symbols (variables) with the
.I set
command.
It also has a large set of built-in symbols
that affect its behavior in various ways (e.g. the colormap filename)
or reflect various aspects of its state (e.g. the cursor position).
These variables can be incorporated in commands you add yourself.
For a full description of the syntax and use of
.I xwaves
commands, see \*(lqThe
.I waves+
command language\*(rq in \*(wD.
For descriptions of the individual symbols and commands,
see
.qI xwaves "symbols reference"
and
.qI xwaves "command reference"
in \*(wR.
.PP
.I xwaves
distinguishes between
.I "object commands,"
which are directed to a particular object (display ensemble), and
.I "global commands,"
which are simply directed to
.I xwaves
itself.
The syntax of simple
.I xwaves
commands is
.LP
.RS
.nf
.if t .ft I
object  command  keyword  value  keyword  value ...
.if t .ft P
.fi
.RE
.LP
where
.I object
is the name of the object to which the command is directed, and
.I command
is the name of the command to be executed.
There may be any number of keyword\-value pairs, including zero.
For a global command,
.I object
is \*(lqwaves\*(rq or is simply omitted.
.PP
For example, the simplest form of the command
that creates a waveform display might look like
.LP
.RS
.nf
.if t .ft I
waves make file speech.sd
.if t .ft P
.fi
.RE
.LP
or simply
.LP
.RS
.nf
.if t .ft I
make file speech.sd
.if t .ft P
.fi
.RE
.LP
since
.I make
is a global command.
The keyword
.I file
indicates that the following argument,
.I speech.sd,
is the name of the data file to be read and displayed.
The command
.I make
has many other optional keywords that permit control of various window
attributes, such as size, etc.
The documentation for each command in \*(wR
lists the keywords recognized by the command
and explains the meaning of each.
.PP
For the command
.I set,
any variable name can be used as a keyword, and the following value
is assigned to the variable.
For example
.LP
.RS
.nf
.if t .ft I
set colormap my_colormap
.if t .ft P
.fi
.RE
.LP
assigns the value
.I my_colormap
to the variable
.I colormap.
.PP
The command
.I add_op
lets you define new operations.
For example
.LP
.RS
.nf
.if t .ft I
add_op name my_op op "doit.sh _l_marker_time _r_marker_time"
.if t .ft P
.fi
.RE
.LP
defines a new operation
.I my_op
that runs a shell script
.I doit.sh.
The keyword
.I name
identifies the following argument, \*(lqmy_op\*(rq,
as the name of the operation;
new items containing the name \*(lqmy_op\*(rq
are added to the display window menus
and will invoke the new operation when selected.
The keyword
.I op
indicates that the following string
\*(lqdoit.sh _l_marker_time _r_marker_time\*(rq
is the definition of the new operation.
In the definition,
.I l_marker_time
and
.I r_marker_time
are examples of variables
whose values are to be substituted in the string.
They are identified as such by the underscores (\*(lq_\*(rq)
that precede them.
.I l_marker_time
and
.I r_marker_time
are built-in
.I xwaves
symbols that contain the times (in seconds)
corresponding to the left and right marker positions
(see
.qI xwaves "symbols reference"
in \*(wR).
Thus, whenever the new operation is invoked,
the values of the variables at that time
are substituted in the definition string.
Suppose the values are 0.25 and 0.35.
Then
.LP
.RS
.nf
.if t .ft I
doit.sh 0.250000 0.350000
.if t .ft P
.fi
.RE
.LP
is executed as a shell command, running the script
.I doit.sh
with arguments that give the marker times.
.PP
There are several ways to convey commands to
.I xwaves.
.TP
(1) The main control panel.
Just type the command in the field
.BR "COMMAND (or @file):" .
.TP
(2) Command files.
You can store a number of commands in a file,
and they can then be executed from
.I xwaves.
You can enter the file preceded by \*(lq@\*(rq in the field
.B "COMMAND (or @file):"
or, if the first line starts with the word \*(lqwaves\*(rq,
enter it on the command line when starting
.I xwaves.
A command file that is always executed when
.I xwaves
is started is the file indicated by the
.I init_file
entry in the
.I .wave_pro
file.
See
.qI xwaves "initialization"
below.
.TP
(3) The program \fIsend_xwaves\fP.
.IR send_xwaves (1\-ESPS)
is a program that takes an
.I xwaves
command string as a parameter and sends the command to
.I xwaves.
The program can easily be used to control
.I xwaves
from a UNIX shell script.
.TP
(4) C library functions.
If you have the ESPS function library,
you can write application programs in C,
using the functions
.IR SendXwavesNoReply (3\-ESPS)
and
.IR SendXwavesReply (3\-ESPS)
to send commands to
.I xwaves.
.TP
(5) Auxiliary panels.
The command
.I make_panel
lets you build X window panels from which you can issue commands
by pushing buttons or selecting from menus.
See the command description under
.qI xwaves "command reference"
in \*(wR.
.TP
(6) Display window menus.
As described above, you can associate
.I xwaves
commands with display-window menu items by using the command
.I add_op.
.TP
(7) Keyboard bindings.
With the command
.I key_map
you can bind an operation to a character on the keyboard
to be executed when the key is pressed.
See the command description under
.qI xwaves "command reference"
in \*(wR.
.PP
There is much more to be said about using
.I add_op
and about
.I xwaves
commands in general.
See \*(lqThe
.I waves+
command language\*(rq in \*(wD.
.SS xwaves initialization
.PP
Initial values for
.I xwaves
global variables and other symbols can be assigned in a profile file
that is read when
.I xwaves
starts.
By default this is a file named
.I .wave_pro
found in the user's home directory or, if not there, in the directory
.I $ESPS_BASE/lib/waves.
(However, see
.B \-w
under OPTIONS below.)
See the
.I .wave_pro
in the latter directory for a fully commented example of a complete
.I xwaves
profile.
The file contains lines of the form
.LP
.RS
.nf
.if t .ft I
name value
.if t .ft P
.fi
.RE
.LP
where
.I value
is a value to be assigned to the symbol
.I name.
For example, you could specify a non-default colormap at startup
by including a line:
.LP
.RS
.nf
.if t .ft I
colormap MyColormap
.if t .ft P
.fi
.RE
.LP
The variables that have special meaning for
.I xwaves
are listed with explanations under
.qI xwaves "symbols reference"
in \*(wR.
Some variables have meaning to
.I xwaves
attachments (see \*(lqAttachments\*(rq below)
which get the values by communicating with
.I xwaves.
You can assign values to other variables
for any convenient purpose\*-e.g. for use in
.I add_op
commands.
.PP
One important global variable is
.I init_file.
This is the name of an
.I xwaves
command file that is executed after the
.I .wave_pro
has been read; it allows more elaborate startup processing
than is possible through simple assignments of values to variables.
See
.I $ESPS_BASE/lib/waves/commands/xw_init.WC
for a default
.I init_file.
It is through the
.I init_file
that the contents of the
.B "Miscellaneous xwaves Controls"
panel is created.
By specifying a different (modified)
.I init_file
in the
.I .wave_pro,
you can customize the panel contents,
change the contents of the display-window menus,
and otherwise modify the initial configuration of
.I xwaves.
See
.qI "xwaves\fR's\fI" "initial state: the .wave_pro file"
and \*(lqChanging the menu files\*(rq
under \*(lqChanging the
.I xwaves
environment\*(rq in \*(wD for details and an example.
.SS UNIX environment variables
.PP
There are numerous UNIX environment variables
that affect the operation of ESPS programs and
.I xwaves.
For a list see
.IR espsenv (1\-ESPS).