xlabel.1t

speech signal process tools

Another menu, based on the DARPAbet symbols,
is available in the file
.I labelmenu.darpa
in the same directory.
.PP
The format of the label menu file is quite straightforward.
The first
line of the file must contain the keyword
.I "columns"
or
.I "rows"
followed by a space and the decimal number of columns or rows
which you would like your menu of labels to have.
The first line can also additionally specify the font
to be used in the label display by including the keyword
.I font,
a space, and the name of the desired font.
If the font is specified in the menu
and also in an existing label file (see below),
the menu specification overrides.
Any fixed-width font in the list printed by the utility
.I xlsfonts
may be specified.
.PP
The balance of the menu file
contains two blank-separated text items per line.
The left item appears in the menu;
the right item is for insertion in the label file to be created.
(See
.I $ESPS_BASE/lib/waves/menus/labelmenu
for an example.)
.PP
The menu file may optionally include lines
containing some of the special items below as their
right members.
The left members, which appear in the menu,
can be any strings not containing space characters.
The special items have the following functions
when selected from the menu.
.TP
.I "*INSERT*"
selects the insert mode for labeling.
.TP
.I "*MOVE*"
selects the move mode for labeling.
.TP
.I "*REPLACE*"
selects the replace mode for labeling.
.TP
.I "*DEL*"
deletes the closest marker.
.TP
.I "*SHELL*"
takes the left hand entry to be a UNIX command
(e.g. the name of a shell script).
It tries to execute the command with three arguments:
(1) the name of the label file,
(2) the first field of the label closest to the mouse cursor,
and (3) the time location of that label.
A label menu may contain any number of
.I *SHELL*
entries.
.TP
.I "*UNLOAD*"
unloads the label file;
i.e. it saves the current label set in the label file
and removes the labels from the screen.
.TP
.I "*EDIT*"
pops up an edit window containing the label closest to the cursor.
This is useful for editing long labels.
.TP
.I "*PRINT*"
prints the contents of the label window.
.SS "Label files"
.PP
Label files are specified using the control panel or an
.I xlabel
command
.I set
or
.I make
(see
.qI xlabel "commands"
in the chapter
.qI xlabel "reference"
of \*(wR).
Named label files are retrieved
by the same search strategy that applies to
.I xwaves
output files.
See \*(lqLabel files\*(rq in the chapter
.qI xlabel
of \*(wD for details;
also see
.I output_dir
under \*(lqGlobal symbols\*(rq in the chapter
.qI xwaves "symbols reference"
of \*(wR.
If the named
label file exists, it is read and displayed;
otherwise, a new file is created.
.PP
A label file is an ordinary ASCII text file with a short header
followed by a section consisting of one-line records,
one for each label.
The two sections are separated by
a line beginning with a \*(lq#\*(rq sign.
Only the \*(lq#\*(rq line is mandatory;
empty headers are permitted.
.PP
A label
.I header
consists of keyword\-value pairs, which may appear in any order. 
Either spaces or tabs can be used
to separate the keywords and their values.
Here is an example of a label file.
.LP
.RS
.nf
.if t .ft I
signal speech
type 0
color 121
comment created using xlabel Wed Aug 20 16:58:09 1997
font 12x24
separator &
nfields 2
#
   24.520303  121 now&right
   25.674485  121 is&wrong
   26.239576  121 the&right
   24.953758  121 time&right
.if t .ft P
.fi
.RE
.PP
The
.I "separator"
is the character that delimits fields within a label string
(see below).
By default this is a semicolon,
but any non-whitespace character can be used.
.PP
The
.I "color"
is an integer specifying the colormap table entry to use
when adding labels to the file.
It does not override the color specifiers in the records,
but it determines the color of new labels added to the file by
.I xlabel.
.PP
The
.I "font"
is the name of the character font used to create the label file.
If multiple label files are displayed, each can have its own font.
Although you can choose the fonts for label display windows,
there is currently no way to change the fonts displayed in label menus.
.PP
See \*(lqThe label file header\*(rq
under \*(lqLabel file format\*(rq in the chapter
.qI "xlabel"
of \*(wD for the semantics of the keywords
.I type,
.I nfields,
.I signal,
and
.I comment.
Other header entries may also appear in files written by
.I xlabel,
but they are ignored.
In fact the only values that are actually used by
.I xlabel
are the
.I separator,
.I color,
and
.I font.
.PP
After the header lines, if any, and the \*(lq#\*(rq line
come the
.I "label-record lines.
Each label record has three entries, separated by blanks.
The first is a time tag, in units of seconds.
The second is an integer that specifies the colormap entry
to use when plotting the label.
The third, which comprises the remainder of the line, is the label string.
.PP
The label string can have several
.I fields,
separated by the field-separator character specified in the header.
Blank or null fields
are indicated by adjacent or blank-separated delimiters.
The fields are numbered consecutively starting at one.
Which fields
.I xlabel
displays
is determined by the list of numbers in the
.B "Active fields:"
item in the
.I xlabel
panel.
.PP
Label entries need not be in chronological order
to be read and displayed correctly,
but if
.I xlabel
changes the file,
the entries of the modified file are reordered chronologically.
.PP
If a label file contains only time markers (and no colors or label text),
.I xlabel
displays the markers properly but without accompanying text.
This can be useful to merely indicate positions.
See \*(lqThe label file body\*(rq under \*(lqLabel files\*(rq in the chapter
.qI "xlabel"
of \*(wD for an example.
.SS "D/A output"
.PP
If D/A support is available from
.I xwaves,
two D/A playback
features are supported by
.I xlabel.
A left button press while in the label window
causes the marked segment containing the cursor to be played.
A middle button press causes the segment delimited by
the cursor and the label boundary immediately to the left of the cursor
to be played.
In both cases the region played is marked in the 
.I xwaves
waveform window
in case you want to perform additional operations on that segment
(e.g., bracket markers, run an external program on it, etc.).
.SS "Graphics export"
.PP
Like
.I xwaves
and the other attachments,
.I xlabel
can export graphics
in PostScript or PCL (HP LaserJet code).
This can be used to print displays directly on the printer
or to generate graphics to be imported into a document
with a suitable text editing program.
For
.I xlabel
the facility is still somewhat limited in that, for example,
IPA fonts are not yet accommodated.
For that purpose one of the generally available X window-grab utilities
may be more useful.
.PP
There is an
.I xwaves
command,
.I "print_setup,"
that invokes a setup window
with which you can choose output to a file or printer,
select PostScript or PCL, set output resolution and scaling,
and control other aspects of the graphics-export environment.
See the chapter \*(lqPrinting graphics\*(rq in \*(wD for details.
.PP
Graphics output can be invoked by selecting the
.I xlabel
menu item corresponding to
.I *PRINT*
or by a
.I "print"
command sent from
.I xwaves.
See the chapter
.qI xlabel "reference"
of \*(wR.
.PP
.I xlabel
supports the
.I xwaves
command
.I print_ensemble;
it can cooperate with
.I xwaves
to allow the contents of
.I xlabel
windows to be included in
.I xwaves
multi-window graphics output.
See \*(lqPrinting graphics\*(rq in \*(wD for details.
.SS "xlabel symbols"
.PP
By means of the
.B \-w
option and a temporary file written by
.I xwaves,
.I xlabel
reads the current set of
.I xwaves
globals variables on startup.
Included are a few globals that are relevant specifically to
.I xlabel.
See
.qI xlabel "symbols"
in \*(wR
for a list with explanations.
.SS "xlabel commands"
.PP
.I xwaves
can be controlled by a command file,
by commands entered through the control panel,
or by commands from the program
.IR send_xwaves (1\-ESPS)
or programs using the
.IR SendXwaves (3\-ESPS)
functions in the ESPS library.
(See the
program and function manual pages
and the chapter \*(lqThe
.I waves+
command language\*(rq in \*(wD.)
Commands from these sources can be passed through to
.I xlabel
via the
.I xwaves
command
.I "send"
(See \*(lqGlobal
.I xwaves
Commands\*(rq in \*(wD.)
The syntax of the commands as received by
.I xlabel
is:
.LP
.RS
.nf
.if t .ft I
receiver command keyword value keyword value ...
.if t .ft P
.fi
.RE
.LP
(the same as for
.I xwaves
commands).
The first item,
.I receiver,
is either the attachment name \*(lqxlabel\*(rq
or the name of a display ensemble.
The second item,
.I command,
is the actual command name.
There may be any number, including 0, of keyword\-value pairs.
See the chapter
.qI xlabel "reference"
in \*(wR
for discussions of the individual commands.
.PP
There are two illustrations of the control of
.I xlabel
via
.I xwaves
commands under \*(lqExamples with the command language\*(rq in the chapter
.qI "xlabel"
of \*(wD.
One is a C-shell script that attaches
.I xlabel
to
.I xwaves
and then loops through a list of data files, displaying each file,
loading two related label files, pausing to let the user interact with
.I xlabel,
and finally removing the displays before going on to the next data file.
The other example shows how to use the
.I xwaves
commands
.I add_op
and
.I key_map
to allow fast invocation of an
.I xlabel
operation by a single keystroke.
.SH "OPTIONS"
.PP
.I xlabel
is usually started as a subordinate program by
.I xwaves.
In this case, you need not be concerned with the
command-line options presented below, and you may skip this section.
However, it is also possible to run
.I xlabel
(and the other attachments) as sibling UNIX processes,
in which case it may be necessary
to specify one or more of the following options.
.TP
.BI \-c " host_X_registry"
This is the name that the host program is registered under
for X server-based communications.
This option is intended to be supplied by
.I xwaves
when it runs
.I xlabel.
.TP
.BI \-n " host_name"
This is the name of the program object with which
.I xlabel
will be communicating.
When the host program is
.I xwaves,
this name is always the default value, \*(lqwaves\*(rq.
.TP
.BI \-w " wave_pro"
Specifies the startup profile to read.
This option is always used
when
.I xlabel
is invoked by
.I xwaves,
in which case the specified profile
is a temporary file written by
.I xwaves
and containing the current state of the
.I xwaves
globals.
If
.B \-w
is not used (only possible if
.I xlabel
is run from the shell),
.I xlabel
attempts to read the file
.I .wave_pro.
In both cases the search path
.I $HOME:$ESPS_BASE/lib/waves
is used.
The search path used can be overridden
by setting the UNIX environment variable WAVES_PROFILE_PATH before starting
.I xwaves.
.SH "SEE ALSO"
\*(wD,
.br
\*(wR,
.br
\*(wT,
.br
.IR cnvlab (1\-ESPS),
.IR formant (1\-ESPS),
.IR select (1\-ESPS),
.br
.IR xchart (1\-ESPS),
.IR xcmap (1\-ESPS),
.IR xmarks (1\-ESPS),
.br
.IR xspectrum (1\-ESPS),
.IR xwaves (1\-ESPS)
.SH "BUGS"
.PP
Occasionally,
when the vertical size of the label display window is changed manually,
.I xlabel
insists on returning it to its previous size
or some other inappropriate height.
Multiple attempts will usually yield the desired effect.
This will eventually be fixed.
.PP
The label file does
.I not
automatically adjust to time changes
caused by waveform segment deletion or insertion.
It is recommended that no waveform editing be performed
on files being labeled.
.SH "AUTHOR"
Program by David Talkin, AT&T Bell Laboratories.
Later enhancements by
David Burton, Rod Johnson, Alan Parker, John Shore, David Talkin,
and others at Entropic.
This manual page largely extracted by Rod Johnson
from \*(wD and earlier manual pages
derived from Talkin's original documentation
with revisions and additions by
David Burton, Joop Jansen, Rod Johnson, John Shore, David Talkin,
and others at Entropic.