attachments.help.src

speech signal process tools

@(#)attachments.help.src	1.2 1/17/90 ESI ATT

****************	ATTACHMENTS	   ****************

This file describes the attachment facility in general terms and then
presents instructions for using the attachments marks, label, spectrum
and stub.

Waves are relatively large and complex programs.  Adding features
directly to them entails learning a certain amount about their
ever-changing internal structure and living through long compilation
and debugging sessions.  In addition, there is a serious limitation on
the number of Sun display windows available for a given process
although the total number of windows across several processes can be
quite large.  One way of dealing with this situation is to permit
functional expansion through separate, intercommunicating programs and
processes.  The "attachment" facility is an implementation of this
idea which uses UNIX pipes to loosely link essentially stand-alone
programs with the display facilities of waves.  The file
$WAVES_SRC/c/spectrum.c is a documented example of an
attachment which can serve as a template for those wishing to add
features of their own.

The messages passed between the host (waves) and an attachment
are text strings of the general form

	receiver command [<selector> <argument>]...,

where "receiver" is typically a program name, a display ensemble name,
or a signal name; "command" is one of the operations the receiver is
capable of performing; and the (often optional) "selector argument"
pairs specify parameters for "command."  When one process sends a
message to another, it waits for a response before continuing.  The
responses are of two types: results and command recursion.  Results
responses are either "ok" or "null," indicating the success of the
requested operation, or a message of the form

	returned <selector> <argument> [...],

where the "selector argument" pair(s) specify values requested in a
previous message.  The process can choose to ignore these or not, but
must wait for them before proceeding.  Command recursions occur when a
process which receives a message must get additional information from
the sender or cause the sender to perform some operation before it can
complete its own operation.  These recursions can nest to any depth.

The SIG system library, /usr/local/lib/libsig.a, contains routines
which perform most of the required message manipulations (see
$WAVES_SRC/c/message.c, .../parse.c and the example
program cited above.

Waves and wave expect all attached processes to be able to respond by
name to the following messages:

message		keywords		arguments
----------------------------------------------------------------------
make				>> CREATE A NEW OBJECT <<
		name		character string for the display object name
		file		character string of a file to be manipulated
				"File" is optional and if not present, the
				attached process should assume that "name" is
				to be the object name and file name.

quit				>> DETACH FROM WAVES <<
		<none>
				Cleanup displays, close files as necessary,
				etc. Reply with "ok" and then exit immediately.
------------------------------------------------------------------------------

Named objects created by attached processes must respond to the following
messages:

message		keywords		arguments
------------------------------------------------------------------------------
kill				>> DESTROY THE NAMED OBJECT <<
		file		The name of a particular file view to be
				deleted.  If "file" omitted, the entire named
				object is deleted.
				Kill an object, but remain attached.

redisplay			>> UPDATE DISPLAY TO REFLECT CHANGES IN HOST <<
		<none>
				If attachment has a display to refresh it
				can optionally get the attributes of the
				corresponding display in the host through
				command recursion with "<host-objectname>
				get attributes display [file <filename>]."

mark				>> NOTE A TIME POINT FROM THE HOST <<
		time		floating-point time in sec (optional) [0.0]
		rstart		region-start time (optional) [0.0]
		rend		region-end time (optional) [0.0]
		color		any integer (optional) [1]
		file		a file name (optional) [object name]
				This is the primary message of interest.  It
				is supposed to cause the attachment to perform
				some useful operation like storing a segment
				mark in a file or computing a short-time
				spectrum near the specified time.
				Rstart and rend are sent by waves and indicate
				the location (in sec) of the left and right
				markers respectively.

quit				>> DETACH FROM WAVES <<
				Functions the same as "quit" to attachment.
------------------------------------------------------------------------------

Note that, except for "quit," attachments don't really need to do anything
in response to the above messages, but must at least respond with "ok"
or "null."  In cases of command recursion where data is requested, the
attachment must be able to process the "returned" message.  These messages
are described in $WAVES_DOC/waves.help under the
"get" keyword in the "COMMAND FILES" section.  The attachment has access to
all of the waves commands listed in the "COMMAND FILES" section.

Waves can send arbitrary messages to attached processes directly from
command files using the "send" command (see the examples in mark and
label below).  This provides an individualized level of control beyond
that available through the "standard" command set outlined above.


++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
	       SEGMENTATION AND LABELING: marks
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

The program `marks' is designed to be attached to waves in order to make
it easy to assign times to a set of speech events whose labels are
known in advance (for instance because they have been generated
automatically from text or from a transcription of what was said). If
things are set up right, `marks' should only require one mouse button
press per speech event; a skilled user can achieve average rates of
10-20 events per minute, making it possible to segment fairly large
data bases in moderate time.  Here is an example of an input file:

** This was easy for us.
This    "Dis
  D_release
  s_start
  s_end
was     "w^z
  z_start
  z_end
easy    "EzE
  z_start
  z_end
for     "f>r
  f_start
  f_end
  r_F3_min
us.     "^s
  s_start
  s_end

The speech event labels are arbitrary. There are three levels of
description: (1) the sentence, indicated by the beginning "**"; the
word, indicated by a line beginning with anything other than "**" or
white space; and the event label, corresponding to any line beginning
with white space.  Here is a sample output file:

** This was easy for us.
This    "Dis
   D_release     0.35825
     s_start       0.431
       s_end     0.56925
was     "w^z
     z_start    0.644875
       z_end    0.716125
easy    "EzE
     z_start    0.843375
       z_end    0.931625
for     "f>r
     f_start       0.999
       f_end       1.115
    r_F3_min      1.1965
us.     "^s
     s_start     1.35125
       s_end      1.5945

It is obviously the same as the input, except that times (in seconds)
have been added to the event labels.

The marks attachment creates two windows in addition to those that
waves uses.  The control window shows the current sentence, the
current word, and the names of the marks for that word.  It can be
moved to any convenient location on the screen.  The current mark is
shown in boldface print.  The other window is time-aligned with the
newest waves window.  Marks are displayed there as vertical bars, and
the names are printed just to the left of the bars.  If the waves
window is moved or zoomed, this window will adjust itself accordingly.
Marks are only visible if they have been assigned a time.  The current
mark will have a different color than the others.

Event marks can be set in two ways: by selecting the "marks" menu item
in the waves main menu, or by using the middle button option "blow up;
function" on a waveform type of display.  In either case, the current
mark is assigned the indicated time and the next mark becomes current.
The control window has a number of buttons that give the user control
over the list of markers; most are self-explanatory.  The "next" and
"last" buttons shift the current point through the list.  "Change"
simply changes the name string.  "Unset" removes the time assignment
from the current mark, while "delete" excises that name from the list.
"Add" splices a new name into the list, either before or after the
current mark, as indicated by the "Where?" item.  Setting a time twice
on one name simply replaces any previous time.

The results are written to a file when waves sends the "write file"
message.  In the scripts given below, this will happen when the user
activates the "Continue" button on the waves control panel.  Here is a
waves command file invoking marks to segment a file example1 from an
event description file example1.seg.in, producing an output file
example.seg.out:

waves attach function marks
waves set middle_op blow up; function
waves pause
waves make name example1 file example1.d loc_y 350 height 200 loc_x 0
example1 spectrogram file example1.d loc_y 600 loc_x 0
waves send make name example1
waves send read file example1.seg.in
waves pause
waves send write file example1.seg.out
waves send quit
waves kill

Here is a shell script that generates and executes command files for a
real speech database segmenting task.  The command file created is
similar to the one above.

#!/bin/sh
CMDS=/tmp/pt$$; rm -f $CMDS; touch $CMDS
echo waves attach function marks >>$CMDS
echo waves set middle_op "blow up; function" >>$CMDS
echo waves pause >>$CMDS
for i in $*; do
  NAME=${i}
  FILE=${i}.d
  echo waves make name $NAME file $FILE loc_y 157 height 200 loc_x 41 >>$CMDS
  echo $NAME spectrogram file $FILE loc_y 350 loc_x 0 >>$CMDS
  echo waves send make name $NAME >>$CMDS
  echo waves send read file $NAME.in >>$CMDS
  echo waves pause >>$CMDS
  echo waves send write file $NAME.out >>$CMDS
  echo waves send kill >>$CMDS
  echo waves kill >>$CMDS
done
echo waves quit >>$CMDS
echo "running waves script $CMDS ..."
waves $CMDS

++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
	       SEGMENTATION AND LABELING: label
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

The "Label" attachment is designed as a general-purpose point or
region signal segmentation and labeling program.  Up to 32
label/segmentation files may be viewed and edited simultaneously.
Labels may be selected from a user-configurable menu or typed in
directly from the keyboard.  Label is especially useful for comparing
and generating multiple segmentations of the same signal where the
label sequence can not be easily predicted in advance (see "mark"
above).

This waveform segmentation and labeling utility may be added to waves
by entering "label" for the "Attach:" item in the Control Panel.  This
may be done either before or after a waveform window is created.  If
the labeler is attached after a waveform is displayed, the label
window will not appear until the waveform is redrawn (e.g. by
"paging"), or until the "Label File:" and "Object:" items have been
entered in the "Labeler" control panel.  In the former case the
labeler automatically assigns a label file name by appending ".lab" to
the "Object" name from waves.  In the latter case, any
pathname/filename may be specified as the "Label File."  The label
window will appear below the most recently created waveform or
spectrogram window and will remain time aligned as the object is moved
around, zoomed, etc.  Moving the mouse in the label window causes the
label cursor to appear in all representations of the signal at the
corresponding time location.

When started, the labeler attempts to read a text file named
"labelmenu" from the current directory.  If this is not found, a
default (and generally worthless) menu is created.  The "Labeler"
control panel item "Label Menu File:" may be used to specify the path
name of an alternate menu (also see "labelmenu" command below).  The
first line of the label menu file should contain the keyword "columns"
or "rows" followed by a space and the decimal number of columns or
rows which you would like your menu of labels to have.  The balance of
the file contains two blank-separated text items per line; the left
item will appear in the menu; the right one in the label file to be
created (see $WAVES_MISC/labelmenu for an example).
The menu may optionally include lines containing "*DEL*" and/or
"*UNLOAD*" as their right-hand members (explained below).