Controlling WAVE from an external program

Although the facilities discussed in the previous sections provide highly flexible control of external analysis programs, in some cases it is desirable for another program to control WAVE rather than for that program to run under WAVE 's control.

The program wave-remote, provided with the WAVE distribution, can drive WAVE 's display. Using wave-remote, you can cause WAVE to go to any specified location in the current record, to load another set of annotations for the current record, or to open another record. By providing a command-line interface for driving WAVE , wave-remote simplifies the task of driving WAVE from other programs or shell scripts; in general, it is sufficient merely to fork a new process and invoke wave-remote with the appropriate arguments (for example, using the system() function provided in the standard C library). If it is not acceptable to start a new process for this purpose, wave-remote is also provided in C source form, and the functions it uses to drive WAVE can be invoked directly from your program.

Options for wave-remote are:

-pid processid

Control the WAVE process with the specified processid. (If this option is omitted, and more than one instance of WAVE is running, wave-remote controls the one with the highest processid.)

-r record

(Re)open the specified record.

-a annotator

(Re)open the specified annotator for the current record.

-f time

Go to the specified time in the current record.

-s signal ...

Display the specified signal(s) only. (Use signal numbers as in the Signal list in the Analyze window.)

For example, the command

    wave-remote -r 100s -a atr -f 0:22

causes WAVE to open record 100s, with annotator atr, and to show data starting at 22 seconds after the beginning of the record.

If WAVE is not running when wave-remote is invoked, wave-remote launches WAVE provided that the record to be opened has been specified. wave-remote exits immediately once it has delivered its instructions to WAVE .

As an alternative to the command-line interface offered by wave-remote, the wavescript application provides the same services, but is controlled by a script file (named on the wavescript command line). Scripts for wavescript should contain on each non-comment line a single option/argument pair as described above for wave-remote. In addition to wave-remote's options, wavescript also accepts a -p path option; the path argument is appended to the WFDB path. Any line in the script that does not begin with a `-' is treated as a comment line. For example, if the file example.xws contains

    # Here is a comment
    -r 100s
    -a atr
    -f 0:22

then `wavescript example.xws' has the same effect as the wave-remote example above.

Using these interfaces, an analysis program (or any program, such as a web browser) can drive WAVE 's display automatically. In a typical application, a semi-automated analysis program might require the user to make or correct annotations for portions of a record that are selected as part of the program's analysis (and that cannot be known a priori).

An analysis program that runs wave-remote or wavescript may itself be running within WAVE 's own Analysis Commands window. This might be useful to permit the user to set the region of interest interactively, before the analysis begins and takes over control of WAVE to show its progress or to obtain additional input.