xwaves+.help

speech signal process tools

This help file contains a brief introduction to xwaves+ operations and
a list of xwaves+ global parameters and commands.  For more information, 
see the full xwaves+ man page.  To do so, run "eman xwaves+" in a
shelltool window or, if you are using X Windows, click on the "xwaves+ 
manual" button in the control panel.

XWAVES+ STARTUP
==============

Xwaves+ starts up with the following steps: 
(1) It checks to see if any optional DSP board is installed (by trying
to open /dev/dsp32).  If a board is found, xwaves+ will use it for
spectrograms and speech output, and all FEA_SD files will be read in
as SHORTs.  If no board is found, xwaves+ will use external ESPS
programs for spectrogram computation and speech output, and it will
not transform the type of FEA_SD files.  

(2) It reads the \fIxwaves\fP+  profile, initializes 
the \fIxwaves\fP+ globals accordingly, and processes an initialization
command file if one is specified in the profile ("init_file").  The 
profile is (in order of precedence) (a) whatever is specified by the -w
option; (b) the file .wave_pro in your home directory; or (c)
$ESPS_BASE/lib/waves/.wave_pro.  Any file specified by -w or in the
profile is searched for on the path "$HOME:$ESPS_BASE/lib/waves".
The search path used can be overriden by setting the unix environment variable
WAVES_PROFILE_PATH before starting xwaves+.

(3) It processes whatever signal or command files may be listed on the
command line.

XWAVES+ CONTROL PANEL
====================

The values of panel items ending with a colon may be modified by left
mousing (to activate the item) followed by text or numeric input.  Use
<delete> to delete the previous character entered and <CTRL-u> to
remove the entire line.  Any new or changed value must be "entered"
(while activated) by hitting the return key.  The "PAUSE", "CONTINUE,"
"QUIT!," "HELP!", and "xwaves+ manual" items perform the corresponding
functions immediately when moused.  Here are brief explanations of the
panel items.  For details, see the man page.


 INPUTfile:  
      The relative or absolute pathname of a signal to be
      displayed.  A search path ".:$ESPS_BASE/lib/waves/files" 
      is used, but can be overriden with the environment variable 
      WAVES_INPUT_PATH.  Multiple views on a given file may be 
      established by entering the same file name several times.  
      Files with ESPS headers, NIST (Sphere) headers, AT&T SIGnal 
      headers, no headers, and foreign headers are handled.

 OUTPUTfile:
      Base name of files to be created by the "save
      segment in file" function.  NO CHECK IS MADE FOR
      OVERWRITING EXISTING FILES! A list of all files
      generated during a given run of xwaves+ may be browsed
      by right mousing the OUTPUTfile item.  

 OBJECT name:
     The name by which to refer to a display ensemble.  All
     data views in an ensemble have their time cursors and
     markers synchronized and are treated as a unit during
     interaction and in other respects.  If a new object
     name is specified, subsequently generated data views
     become part of a logically distinct ensemble of signals
     and displays.

  COMMAND(or @file):
     A direct command to the xwaves+ program or to an object
     displayed by xwaves+, or the pathname of a text file
     (preceded by the "@" character) containing commands.
     This item may be changed at any time (even in the middle 
     of execution of a command file).  The default search path
     ".:$ESPS_BASE/lib/waves/commands" is used for command files,
     but can be overriden with the environment variable 
     WAVES_COMMAND_PATH.

  PAUSE
     Mousing this item while a command file is running causes the 
     command file to suspend execution, much as though a "pause" 
     command had been encountered in the file.

  CONTINUE
     Mousing this item causes xwaves+ to resume reading from
     a command file after encountering a "pause" in that file (or
     after the PAUSE button has been moused). 

  Attach:
     The name of a function to attach to xwaves+.  The users
     PATH applies. 

  Overlay name:
     The relative or absolute name of a SIGnal formant-bandwidth 
     file or any ESPS FEA file.  Each element of each FEA field is 
     overlayed with a separate track labelled with the field name 
     and element number.  By default, the overlay takes place on 
     the most recently read or computed spectrogram display.  

  HELP
     Mousing this item displays this file. 

  QUIT
     Mousing this item causes xwaves+ to clean up (saving files), 
     return the license, and exit.  

XWAVES+ GLOBALS 
==============

The xwaves+ global parameters can all be initialized at startup from
the .wave_pro file in your home directory.  To change them after 
xwaves+ starts, enter

          set <global name> <global value>

in the space after the "COMMAND(or @file):" prompt in the control
panel, or enter the name of a command file containing a sequence of 
"set" commands.  Here is a list of the current globals, with brief 
descriptions.  For details, see the man page. 

       bg_color
            background color for window frames (6 digits; 2
            each for red, green, blue) (see also fg_color)

       colormap
            file name of an RGB color map (see "COLORMAPS"
            below).  The default search path for colormap
            file names is
            ".:$ESPS_BASE/lib/waves/colormaps".  To use a
            different path, set the unix environment vari-
            able WAVES_COLORMAP_PATH before starting
            xwaves+.

       command_step
            Allows the user to single-step through command
            files.  When command_step is non-zero, xwaves+
            prints each command before executing it and
            pauses after its execution (except for "sleep"
            commands).  The next command can then be read
            and executed by mousing CONTINUE in the xwaves+
            control panel.  "Sleep" commands are not
            affected by command_step.  If command_step is
            non-zero and CONTINUE is moused when the next
            command is "sleep", xwaves+ executes the "sleep"
            and then goes on directly to execute the subse-
            quent command; if that command is not a "sleep",
            xwaves+ will pause after its execution.

       ctlwin_iconized
            If this is non-zero, the xwaves+ control window
            is iconized on startup; otherwise the control
            window is displayed on startup.  The default for
            ctlwin_iconized is 0.  Note the standard xview
            command line options -Wi (iconic) and +Wi (open)
            can also be used to determined the initial icon-
            ization state.  Also, the position of the icon
            can be determined by the standard xview command
            line option "-WP <x> <y>".

       ctlwin_x
            x coordinate of upper left of control window

       ctlwin_y
            y coordinate of upper left of control window

       debug_level
            > 0 causes debug messages to be printed.  The
            default value is 0.

       def_header
            filename of a header for use with headerless
            data; the default startup profile
            ($ESPS_BASE/lib/waves/.wave_pro) sets this to
            $ESPS_BASE/lib/waves/files/def_head.feasd, which
            is an ESPS FEA_SD header for single-channel,
            SHORT, sampled-data, with sampling rate 8000 Hz.
            A default SIGnal header is in
            $ESPS_BASE/lib/waves/files/def_head.sig.  The
            default search path used for default header file
            names is ".:$ESPS_BASE/lib/waves/files"; this
            can be overriden by setting the unix environment
            variable WAVES_INPUT_PATH before starting
            xwaves+.  If the environment variable DEF_HEADER
            is defined when xwaves+ starts up, its value
            takes precedence over def_header.  Thus, if you
            want def_header to change for different input
            files while xwaves+ is running, then DEF_HEADER
            should not be defined.

       do_color
            0 or 1 to enable B&W or color operation; This
            global is set automatically on startup prior to
            reading the startup profile, so you should set
            it in the profile only if you don't want the
            automatic setting.

       dsp32_wait
            Specifies the number of attempts (at one second
            intervals) that xwaves+ will make to use an
            installed DSP board before giving up.  The
            default is 5.  The purpose of this global is to
            make the temporary use of the board by other
            programs (wplay, wrecord, dspsgram) less
            intrusive to the xwaves+ user.

       edit_ganged
            1 to edit all signals in object, 0 for just one

       fea_sd_special
            1 to treat ESPS FEA_SD files as a special case,
            0 to treat in standard FEA manner.  If
            fea_sd_special == 1, the sampled data from ESPS
            FEA_SD files are read in as SHORTs (regardless
            of their external representation) so that the
            DSP board can be used for spectrograms and D/A.
            In this case, values outside of the range (-
            32768,+32768) are clipped to the extremes of the
            range.  If fea_sd_special == 0, no such conver-
            sions are performed, and the external programs
            sgram_prog and play_prog will be used for spec-
            trograms and D/A.  Fea_sd_special is set on
            startup to 1 or 0 depending respectively on
            whether or not the DSP board is present.

       fg_color
            foreground color for window frames (6 digits; 2
            each for red, green, blue) (see also bg_color)

       first_x
            x coordinate of upper left of first window
            created

       first_y
            y coordinate of upper left of first window
            created

       funcname
            an attached function (like "xlabel" or "xspec-
            trum")

       f0_min
            minimum frequency to display for F0 files

       f0_plot_specs
            plotting method and optional ASCII symbol to
            use.  Argument syntax is: N s xd yd, where N is
            0 or 1, s is the plotting character to use (if N
            is 1), xd and yd are the x and y displacements
            (in pixels) required to center the character.
            If N is 0, F0 is plotted using the usual
            connect-the-dots paradigm.  F0_plot_specs must
            be the last variable set on a command line.

       f0_range
            range in Hz to display for F0 files

       f0_size
            fraction of canvas for plotting F0 for F0 files

       image_clip
            This is used by the digital halftone algorithm
            when spectrograms are displayed on a monochrome
            monitor.  The display algorithm assumes that the
            maximum displayed value MAX is 127.  Values
            between MAX and (MAX -image_clip) are displayed
            in black. The default value is 7 (i.e., in spec-
            trogram terms, everything 7db down from the max-
            imum possible value is shown in black).

       image_range
            This is also used by the digital halftone algo-
            rithm when spectrograms are displayed on a mono-
            chrome monitor.  Everything below (MAX -
            image_clip - image_range) is shown in white.
            The default is 40 (i.e., in spectrogram terms,
            assuming 7 as the value of image_clip, every-
            thing more than 47db down from the maximum pos-
            sible value is shown in white.

       init_file
            The name of a command file to be executed on
            startup.  Execution takes place after all the
            other variable initializations in the profile
            are done, regardless of where in that file the
            definition of init_file occurs.  After the pro-
            file has been processed, redefining the value of
            init_file has no effect other than changing the
            output value for the command "get attributes
            global".  By default, xwaves+ looks for
            init_file along the path
            ".:$ESPS_BASE/lib/waves/commands".  The search
            path used can be overriden by setting the unix
            environment variable WAVES_COMMAND_PATH before
            starting xwaves+.

       inputname
            default pathname to appear at "INPUT file"
            prompt

       invert_dither
            If set to non-zero, this causes the display of
            digital-halftone images to appear with black and
            white pixels reversed ("inverse video"). Spec-
            trograms are displayed in digital halftone form
            on monochrome monitors or when do_color is set
            to 0.

       line_type
            plotting algorithm to use for plotting generic
            vector signals.  Default is 1 (line segments
            connect sample points); 2 causes additional
            lines to be drawn from the sample point to the
            minimum value, resulting in a histogram-like
            display).

       left_op
            text corresponding to desired left button opera-
            tion for waveform menus; must be one of:
                               up/down move
                               move closest
                               modify signal
                               repeat previous

       max_buff_size
            determines a limit on the number of bytes of
            storage that xwaves+ will attempt to allocate
            for in-memory data storage for any one signal.
            The value is 2000000 by default, but of course
            can be changed via the startup profile or a set
            command.  If this limit is set high enough for a
            signal to be contained entirely in memory,