ref.txt

speech signal process tools

----------------------------------------------------------------------------


                          ----------------------
                          waves+ Reference Guide
                          ----------------------

                        Entropic Research Laboratory

This is a reference guide to the commands and symbols in the waves+ package.
It essentially consists of the material in the ``Reference Guide'' part of
the waves+ Manual.  It covers language to be used to control xwaves and the
attachments; it will not go into detail about how to use the commands to
build your specific application or how to embed them in a standard setup.
For that type of information see the parts ``waves+ in Detail'' and ``The
Attachments'' in the full manual.

 Chapters

   26  xwaves command reference
   27  xwaves symbols reference
   28  xlabel reference
   29  xspectrum reference
   30  xmarks reference
   31  xchart reference

contain a comprehensive reference. Chapters

   32  xwaves quick reference
   33  xlabel quick reference
   34  xspectrum quick reference
   35  xmarks quick reference
   36  xchart quick reference

contain a quick reference to all symbols and commands, which are
alphabetical lists with symbols and commands and their parameters.

In the command references we make frequent use of terms like quoted string,
simple quoted string, boolean, etc. For the definition of these terms refer
to the glossary.

----------------------------------------------------------------------------

   26  xwaves command reference
       26.1  Introduction
       26.2  Global xwaves Commands
       26.3  Obsolete global commands
       26.4  xwaves object commands
   27  xwaves symbols reference
       27.1  Introduction
       27.2  Global symbols
       27.3  View-specific symbols
             27.3.1  Read-only (get only) object symbols
             27.3.2  Write-only (set only) View Symbols
             27.3.3  Read-Write (get or set) View Symbols
             27.3.4  Notes for display window specific symbols
   28  xlabel reference
       28.1  xlabel commands
       28.2  xlabel symbols
   29  xspectrum reference
       29.1  xspectrum commands
       29.2  xspectrum symbols
   30  xmarks reference
   31  xchart reference
   32  xwaves quick reference
       32.1  xwaves commands
             32.1.1  xwaves global commands
             32.1.2  xwaves object commands
             32.1.3  xwaves built-in commands
       32.2  xwaves symbols
             32.2.1  Global symbols
             32.2.2  Objebct symbols
   33  xlabel quick reference
       33.1  xlabel command reference
       33.2  xlabel symbols
   34  xspectrum quick reference
       34.1  xspectrum command reference
       34.2  xspectrum symbols
   35  xmarks quick reference
   36  xchart quick reference
       36.1  xchart command reference
       36.2  xchart symbol reference
   37  Glossary

----------------------------------------------------------------------------

Chapter 26

xwaves command reference

----------------------------------------------------------------------------

   26.1  Introduction
   26.2  Global xwaves Commands
   26.3  Obsolete global commands
   26.4  xwaves object commands

----------------------------------------------------------------------------

26.1  Introduction

There are five routes by which commands may be directed to xwaves:

  1. from xwaves command files.
  2. With the send_xwaves program from the UNIX command-line or from shell
     scripts.
  3. From an attached program (like xspectrum or xlabel).
  4. By way of the send_xwaves ESPS library call.
  5. By typing directly in the COMMAND (or @file): field in the Control
     Panel.

Regardless of the source, the syntax remains the same:

     object command [keyword value] [keyword value] ...

as described in the chapter ``The waves+ Command Language'' of the full
manual.

When commands are read from a xwaves command file, three special xwaves
commands can be used that can not used in other contexts: branch , call  and
return . Refer to their descriptions below.

Note that xwaves command files may be executed by xwaves at startup by
specifying one as the init_file in your profile file, as a file
specification on the xwaves command line, or after xwaves has started by
using the COMMAND or (@file): item (see the section ``The Main Control
Panel'' of the full manual) or via the send_xwaves  (1-ESPS) command. A UNIX
command for starting an xwaves command file with send_xwaves might look like
this:

     send_xwaves @file.WC

where file.WC is the ASCII file containing the command sequence.

The commands for xwaves are divided into two groups: the global commands and
the object commands. The global commands perform general functions in xwaves
not specifically directed at a particular display window or object. The
object commands have an effect on the selected object or display window
only.

----------------------------------------------------------------------------

26.2  Global xwaves Commands

The following commands and keyword/arguments may be directed to xwaves.
These are referred to as waves commands since the explicit or implicit
receiver of them is the xwaves-internal object named waves. If the first
word in a command does not match the name of any existing xwaves object,
waves is assumed, thus shortcutting the expression of commonly used
commands. Thus:

     set verbose 0

is exactly equivalent to

     waves set verbose 0

add_op
     DEFINE NEW XWAVES MENUS AND OPERATORS

     name
          A simple quoted string specifying the name of the new operator.
          This can be any ASCII string with embedded spaces as required. If
          the operator is being added to a menu, this is the string that
          will appear in the menu.
     op
          A quoted string specifying the operation to be performed. This
          operation can either be a command to be executed in a UNIX shell
          or an xwaves-internal command drawn from either the waves or
          object commands list. If the operation is an xwaves-internal
          command it must be preceded by a # sign. The keyword command is an
          exact synonym for op.
     menu
          The menu list in which the new operator is to be placed. The value
          is usually one of wave, spect, all or none, but can be any name
          you choose. The values wave, spect, and all cause the new operator
          to appear in the corresponding data display window menus. Any
          other name will prevent the operator from appearing in the menus,
          but will make it accessible to the key_map and op commands
          described below.

     The add_op command provides the primary means for specifying new object
     commands to be added to the xwaves command set. The operators may be
     added to the data display window menus or simply placed on lists
     internal to xwaves for access by other means, such as a keyboard
     bindings. Several examples of the use of add_op may be found in
     $ESPS_BASE/bin/test_waves. The syntax for the add_op command is an
     extended version of the standard syntax, with the following two
     extensions:
       1. symbolic access to xwaves state: Any string preceded by a
          non-alpha-numeric character and an underline (e.g. _name) is
          interpreted as an xwaves variable symbol and is evaluated at the
          time the added operator is invoked. Acceptable symbols include any
          of the display window-specific variables, any of the built-in or
          user defined global variables and the distinguished symbol out.
          (note that ``.'' is the last character of the symbol).

          The sequence _out. is interpreted at execution time as an output
          file name generation request. The name of the display window from
          which the operator was invoked is processed to take into account
          the output_dir  specification and then has an extension added to
          make its name unique. The out. symbol can, itself, have extended
          qualifiers, as follows:
             + out.g.[ext]

             + out.t.[ext]

             + out.n.[ext]

          The g. qualifier indicates that the output file should be
          displayed graphically by xwaves after the operation is complete.
          The t. qualifier means that the new file should be displayed as
          ASCII information in a text window. The n. qualifier or absence of
          any qualifier means that xwaves is not to display the new file.
          The optional ext is a filename extension that you would like
          appended to the other name components. If ext is omitted, xwaves
          uses the extension ``.out'' added to the name of the input name of
          the file in the current display window. Subsequent file name
          generation requests results in insertion of sequence numbers
          before the extension .out. The out. symbol may be used any number
          of times in a given add_op command; each instance will result in
          the generation of a unique name. As files are generated by
          execution of the new command, their names are added to the ``new
          files'' list. They may be browsed by right mousing the OUTPUT
          file: main control panel item.

          It is possible to prepend and append some special characters to
          the symbol references. For a description see the section ``Using
          Symbols in the add_op Command'' of the full manual.
       2. Access to xwaves commands or other UNIX processes:

          If the first character in the command specification is the #
          character, the command will be interpreted as an internal waves
          command drawn from either the waves_commands or the
          object_commands list. Commands not preceded by the # will be
          executed by a UNIX shell.

          Except for xwaves symbol-value substitution described above, any
          text strings to be interpreted as UNIX commands are passed through
          unmodified. Thus, several UNIX processes on a pipe or sequences of
          semicolon-separated UNIX commands are permitted. The output file
          specifications described above, may appear anywhere in the op
          value.
     A simple add_op command to create a menu item that will play (D/A
     convert) the data from the left edge of the window to the cursor
     position might look like this:

          add_op name "LEFT PLAY" op # _name play \
              start _view_start_time end _cursor_time


     As a more interesting example, we will demonstrate the use of the
     add_op command to implement a sorting operator using a combination of
     UNIX and ESPS utilities. This operator will sort the samples in a
     one-dimensional signal according to increasing value and then create a
     new ``signal'' consisting of the sorted samples. Put the following in a
     file and execute it as a waves command file by typing @filename into
     the COMMAND (or @file): item of the xwaves main control panel. Put the
     whole add_op command on a single line and DO NOT include the backslash
     (\) line continuation characters.

          add_op name sort menu wave op copysd \
             _range_samp  _file - | pplain - | sort -n | \
             testsd -r `echo _r_marker_samp - \
             _l_marker_samp | bc` -a - _out.g.


     This creates the item sort on a waveform menu. It works like this:
     copysd  extracts the segment delimited by the left and right xwaves
     markers. pplain  converts the signal to an ASCII representation. The
     UNIX sort orders the samples numerically. testsd  is used to convert
     the sorted samples back into an ESPS sampled data file. Note that the
     sample rate argument to testsd (-r) is adjusted to normalize the
     ``duration'' of the sorted samples to unity by setting the rate equal
     to the number of samples sorted. The UNIX ``desk calculator'', bc is
     used to compute the number of samples based on the left and right
     marker positions. To use this new operator, position the left and right
     markers on a waveform display window to delimit a second or so of the
     signal. Then select the sort item from the display window menu.

     It is also possible to define operators as composed xwaves command,
     i.e. multiple xwaves commands in a row. You need to separate them with
     a double colon (::). See also the description of the send_xwaves
     command for precautions when using add_op with send_xwaves.

     Here is a rather complex example, that also shows how symbols can be
     used as commands. It is worthwhile to spend some time on this example
     to get a good understanding of both add_op and the command language in
     general:

          add_op name magnify menu none \
             op # set res_mag "_name set file _file \
             chan _cursor_channel plot_max _plot_max \