ref.txt

speech signal process tools

     ALIGN ALL DISPLAY WINDOWS IN A DISPLAY OBJECT

     file
          full name of the signal whose display is to serve as the model for
          other displays. If omitted, the most recently created display
          window is used as a model. Note that display windows will only
          rescale the time base if the attribute h_rescale is enabled. See
          h_rescale and h_spect_rescale in section 27.2.

bracket
     CHANGE DISPLAY WINDOW STARTING TIME AND TIME SCALE

     file
          full path name of signal whose display window is to be changed.
          (default is current INPUT file:)
     start
          time to correspond to left window edge (sec; defaults to left
          marker).
     end
          time to correspond to right window edge (sec; defaults to right
          marker).

     This command corresponds to the bracket markers waveform menu item. It
     has the side effect of placing the marker at the brackets limits.

close
     CLOSE A DATA DISPLAY WINDOW AND TURN INTO AN ICON

     file
          full name of the displayed signal to be closed. If two display
          windows of the same file are opened in the selected object, only
          the last opened display window can be iconized. Performs the same
          operation as the window system's close.
     invisible
          This boolean if set to 1 makes the view completely invisible. So
          there is no icon left on the screen.

colormap
     CHANGE THE COLORMAP USED FOR SPECTROGRAMS

     file
          the name of the display to be modified. This keyword and its
          argument have no effect. It is obsolete.
     threshold
          level (dB) below which spectral densities are white (see
          image_clip) in halftone plotting.
     range
          dB from start to end of current colormap or from saturated black
          to saturated white in dithered, monochrome images (dynamic range;
          see image_range).
     image_clip
          An alternative way to specify the clipping limit. Either threshold
          or image_clip may be specified. They are related by the equation:
          threshold = 105 - image_clip - image_range.
     image_range
          same as range. Note that the colormap command actually affects the
          global colormap of xwaves and is not specifiable on a
          window-by-window basis. This really should be a waves command.

cursor
     MOVE THE TIME/FREQUENCY CURSOR

     time
          the desired time location for the cursor (sec).
     yval
          the desired ordinal location for the cursor. In a spectrogram
          display window, this would correspond to the frequency in Hz.
          frequency is an exact synonym for yval in this context.

     See also the display window set command and the cursor_time  and
     cursor_yval  object symbols.

get
     GET ANY ATTRIBUTES FROM xwaves

     attributes
          Currently recognized arguments are global  and view . These
          determine the mode in which get, as an object command, functions.
          If global is specified, the get command operates exactly as
          described under get in section 26.2. (Note that in this mode, the
          results are represented as keyword-value pairs and are ONLY output
          to a specified output file or to xwaves' standard output.)

          If view is specified (the default case), the attribute names
          specified (see aname below) are first interpreted as display
          window-specific attributes. If a name match is not found in the
          display window-specific list, the global symbol list is then
          searched. If any match is found, the value is returned as a quoted
          string (quotes are only used if the value has embedded spaces or
          quotes). In this view mode, the value is ONLY sent to a specified
          output file or returned to the calling program (such as
          send_xwaves). In this mode, output is NOT sent to xwaves' standard
          output.
     file
          the file name of a specific display window for which attribute
          values are to be obtained. If file is omitted, the most recently
          created display window is assumed.
     output
          the name of an output file to receive keyword-value pairs (in a
          format suitable for a .wave_pro file), in the case where global is
          specified for attributes, or an unadorned list of space-separated
          values if attributes is view or is not specified. If an output
          file is not specified, and attributes is view, then only the
          requesting client (e.g. the send_xwaves program or a program using
          SendXwavesReply() (3-ESPS)) will receive the value(s). The output
          name can include UNIX environment variables (for example $HOME).
     aname
          a quoted string list of the name(s) of the symbols whose values
          are to be retrieved. If aname is omitted in the attributes view
          mode, nothing is returned. If omitted in the attributes global
          mode, all currently defined global symbols are returned as
          keyword-value pairs. The value(s) of the aname item may be any of
          the symbol names listed in chapter 27 and any new symbols you may
          have defined.

     The primary utility of get as an object command is to permit other
     programs to retrieve display window-specific information from xwaves
     via the send_xwaves  program. For example, suppose a program called
     from a UNIX script wanted to know the exact segment of a signal on
     display in xwaves. Assuming the program name was foobar, a command like
     the following might be used:

          foobar `send_xwaves dat get file dat.sd aname \
             view_start_time view_end_time`


     where dat is the display object name and dat.sd

     is the display window of interest. foobar would then get two
     command-line arguments, namely the time, in seconds, corresponding to
     the left and right edges of the display window on dat.sd.

     Another example (use with caution!) could be used to eliminate any
     files that have been created by xwaves operations:

          rm -f `send_xwaves get aname new_files`


insert
     INSERT FILE INTO SIGNAL IN WINDOW

     file
          The name of the signal in which something is to be inserted. This
          attribute is mandatory.
     source
          The name of any existing (but not necessarily displayed) file that
          is to be inserted. This attribute is mandatory.
     time
          The time in file at which source is to be inserted. This attribute
          is mandatory.
     output
          The name of the resulting output file. This attribute is optional.
          If output is omitted, the current outputname will be used (as
          entered in the OUTPUT file: control panel item) or or a filename
          will be constructed (see the section ``The Main Control Panel'' of
          the full manual at the description of OUTPUT file:). Output may be
          the same as file.

mark
     APPLY TIME MARKS TO ALL DISPLAY WINDOWS IN THE OBJECT

     time
          time point (sec) at which to apply the mark.
     color
          colormap entry number (0-127); sets marker color. If omitted, the
          default color that is assigned to markers is assumed (see the
          table ``Meaning of the high-numbered color values'' in the full
          manual).

     Historically, these marks were only used in conjunction with the
     attachments. As of waves+ version 5.0, you may access these mark
     locations directly with xwaves. For example, suppose you wanted to
     cause the keyboard space-bar to play the segment between the two marks
     on either side of the current cursor position. These marks might have
     been applied by any means, including by the programs xlabel or xmarks.
     The following two commands would set up the mapping:

          add_op name play_m op # _name play start \
             _l_mark_time  end _r_mark_time
          key_map key _ op play_m


     Note that this is something different than play between marks! In this
     example it is assumed that mark_reference is cursor_time. See the entry
     for mark_reference in chapter 27.3

marker
     MOVE THE RIGHT OR LEFT TIME MARKER

     time
          the desired time location of the marker (sec).
     do_left
          logical (0 or 1) determines if right or left mark.

     See also the display window set command and the l_marker_time  and
     r_marker_time  object symbols.

op
     CALL ANY OPERATOR AS AN OBJECT COMMAND

     file
          the name of the file whose display window is to be manipulated.
          This is the name used in the make command or other specification
          that created the display window. If omitted, the most recently
          created display window is assumed.
     c_chan
          the channel over which you wish to simulate the cursor location.
          This optional specification is only relevant if the operation to
          be performed needs the channel information (e.g. to select a
          particular vector element from a vector signal). If omitted, the
          channel last accessed (e.g. via mouse pointer movement) will be
          used.
     c_yval
          the simulated value of the cursor in ordinal data coordinates.
          Thus, if the vertical limits of a data display window were -10000
          to 10000, a c_yval of 5000 would simulate a cursor position 1/4 of
          the display window height from the top. If omitted, the last
          actual cursor position is assumed.
     c_time
          the simulated time (in seconds) at which the cursor is located. If
          omitted, the current cursor location will be used.
     op
          a quoted string containing the exact name of the operator to be
          invoked. This is the name specified when the operator was created
          with the add_op or add_waves command, or the exact name appearing
          in one of the xwaves data display window menus. In this context
          command is an exact synonym for op if you find the latter
          confusing. NOTE: the op command does not discriminate among the
          menu-operator lists. It uses the first operator it finds while
          scanning ALL operator lists. It starts with the wave list, then
          the spect list, then other lists in the order in which you created
          them.

     The op command is designed as a convenience for instances when it is
     desirable to simulate some display window-oriented operation. The
     operators that are accessed via op are usually designed to be invoked
     from display window menus or keyboard bindings (see the add_op and
     key_map commands in section 26.2). As such, these operators are called
     as methods of the display window in question. op permits simulation of
     this behavior.

     For example, suppose you designed an operator that echoed the value of
     the spectral amplitude under the cursor in a spectrogram display window
     with an add_op command like this:

          add_op name S-value menu spect op \
             echo _cursor_value


     This operator will appear in the spectrogram display window menu and,
     when selected, will cause the data value under the cursor to be printed
     out. Now, an external program can access this operator to get the data
     value corresponding to 1000Hz and .5 seconds in the data object named
     dt and file named dt.hp.fspec

     with the command:

          send_xwaves dt op file dt.hp.fspec c_yval 1000 \
             c_time .5 op S-value


     N.B.: All calls to the built-in menu items can be made in this way.

open
     OPEN A DATA DISPLAY WINDOW THAT IS CLOSED (ICONIZED)

     file
          full name of the ``iconized'' signal to be opened. Performs the
          same operation as the window system's open or restore.

overlay
     OVERLAY A SIGNAL ON AN EXISTING DISPLAY WINDOW

     file
          the filename of the overlay data. This can be any ESPS FEA file
          except a FEA_SPEC file. NIST  Sphere-format files or AT&T SIGnal
          files are also acceptable. The overlay does not need to be the
          same data type or sample rate as the file to be overlaid. It's
          always handy if there is some meaningful relation between the
          overlay and its host display window, but this is not enforced. The
          time interval that is common to both the host and its overlays
          will be the region overlaid. (i.e. the start times and durations
          of the signals are observed correctly).
     on_file
          the name of the display to be overlaid. This is the name of any
          existing xwaves data display window of any type. If omitted the
          overlay will be put on the most recently created spectrogram, if
          one exists, else the most recently created display window of any
          kind.

     On color systems, overlays are plotted in colors dis