vat

NAME
vat - remote audio conferencing tool

SYNOPSIS
vat [ -aAcdEjJklLMnnsSv ] [ -F device ] [ -f audiofmt ]
[ -g geometry ] [ -N sessionname ] [ -n ] [ -C
conferencename ]
[ -I channel ] -K key ] [ -P priority ] [ -R ] [ -t ttl ]
[ -U socket ] [ -u script ] [ -X resource=value ]
dest/port/[/ttl/format]

DESCRIPTION
Vat allows users to conduct host-to-host or multihost audio
teleconferences over an internet (multihost conferences
require that the kernel support IP multicast). On most
systems, no hardware other than a microphone is required -
sound I/O is via the built-in audio hardware. On DEC
systems, an AudioFile server must be running.

The conference is carried out on the address specified by
dest. Point-to-point conferences are initiated by supplying
a standard IP address, while multiparty conferences use a
Class D group address. Port specifies the UDP ports to use,
and ttl specifies the IP time-to-live (see below). Port
specifies two consecutive ports, one for data and one for
control. The data port is set to the greatest even integer
less than or equal to port. The control port is one greater
than the data port.

OPTIONS
(Note that all the parameters set by the following flags can
also be controlled by X resources (which all have
`reasonable' defaults) so one should not need to give vat
any flags in the usual case. The flags only exist to
temporarily override some resource.)

-a Enable automatic gain control on the output (speaker).

-A Enable automatic gain control on the input (mike).

-c Start up in `conference mode' (see description below).
(This flag is the opposite of -l.)

-C Use conference as the title of this vat window. If no
-C flag is given, the destination address and port are
used as the window title.

-d Start up with the VU meters disabled (this can be
changed using the `Disable Meters' checkbox on the
auxiliary controls panel).

-E Include a checkbox in the auxiliary controls panel for
specifying that echo cancellation is being performed
externally (i.e., in hardware). This option can also
be effected by setting the X resource
Vat.externalEchoCancel to ``true''.

-f Sets the output audio packet format to fmt. (Note that
it not necessary to set an input format since vat will
accept any packet format it knows about.) Currently
available audio formats are:
pcm 78Kb/s 8-bit mu-law encoded 8KHz PCM (20ms frames)
pcm2 71Kb/s 8-bit mu-law encoded 8KHz PCM (40ms frames)
pcm4 68Kb/s 8-bit mu-law encoded 8KHz PCM (80ms frames)
dvi 46Kb/s Intel DVI ADPCM (20ms frames)
dvi2 39Kb/s Intel DVI ADPCM (40ms frames)
dvi4 36Kb/s Intel DVI ADPCM (80ms frames)
gsm 17Kb/s GSM (80ms frames)
lpc4 9Kb/s Linear Predictive Coder (80ms frames)
(The dvi encoding was contributed by Jack Jansen of
CWI. The gsm coder was contributed by Carsten Bormann
of the Technische Universitaet Berlin. The lpc coder
was contributed by Ron Frederick of Xerox PARC.)
9 The default audio format can be set with the
audioFormat X resource. It defaults to pcm.

-g Override the default window geometry with geometry,
which should be a standard X geometry string.

-I Use the ``LBL Conference Bus'' to interact with other
multimedia conferencing tools. The small integer
channel, which must be non-zero, is used as the channel
identifier for group interprocess communication on the
local host. This value should be consistent across
each group of applications that belong to a single
conference, and should be unique across conferences.
The session directory tool (sd) will allocate
appropriate values. (Vic and vat currently use this
mechanism to coordinate voice-activated video switching
as well as other conference control abstractions.)

-j Start up with audio output to the external audio jack.
This flag can be defaulted by setting the X resource
Vat.outputPort to Jack.

-J Start up with audio output muted.

-k Keep all sites in the `Conference Hosts' panel.
Normally sites that exit are deleted from the panel.
With -k, sites that exit are grayed-out but not
deleted.

-l Start up in `lecture mode' (see description below).
This flag can be defaulted by setting the X resource
Vat.lectureMode to true.

-M Start up with audio input unmuted.

-N Use session, in lieu of your user name and local host,
to identify you to other sites. If no -N flag is
given, the X resource Vat.sessionName is used.

-n Use a packet format that is compatible with the
obsolete vat protocol, used by version 3 and earlier of
vat.

-P Use priority as this vat window's priority for
obtaining the audio device. All vat windows have a
priority which is typically set by the X resource
Vat.defaultPriority (defaults to 100) but this can be
overridden by a -P flag. If a window requests the
audio (because new network data arrived or the mike has
been unmuted) and the window currently holding the
audio is either lower priority, the audio holder
immediately gives it up. Otherwise the new window's
request is ignored.

-R Disable the mike controls in the user-interface. This
prevents the user from enabling the mike and
transmitting audio to the session.

-s Start up with audio output to the internal speaker.
(This flag is the opposite of -j.)

-S Make new sites come up `suppressed' (the check box next
to the sitename will be checked and you will have to
click on it to hear the site speak). This flag is
intended for something like meeting audiocasts where a
moderator wants to have control over who is able to
speak. This flag can also be set by the
Vat.muteNewSites X resource.

-t Set the multicast ttl (time-to-live) to ttl. (The ttl
is ignored if the destination address is not an IP
multicast address.) If no -t flag is given, the value
of the X resource Vat.defaultTTL is used.

-U Use the unix-domain stream socket specified by socket
for audio I/O. Some process should bind to and listen
on this socket before vat is run. The data is raw 8khz
mulaw samples. If socket is a number, then AudioFile
is used. The number indicates the corresponding

-u Source script, in addition to the compiled-in script,
to build the user interface. You can provide addtional
tcl code that is loaded at startup in $HOME/.vat.tcl.

-X Override the X resource Vat.resource with value.

VAT OPERATION
Note: In addition to invoking the ``quit'' button, typing
`q', `Q', ctrl-C or ctrl-D anywhere in the window will
terminate vat.

The vat window is divided into two parts: the right has
controls for the local audio and the left has a status
display of the remote users participating in the current
conference. The audio controls consist of two sliders that
control the mike and playback gain, a button to toggle
output between the built in speaker and the headphone jack,
buttons to enable/disable either the mike or speaker, and
buttons to control acquistion of the audio hardware. Just
to the left of each slider is a VU meter. A rule of thumb
is to adjust the mike and speaker gain sliders so the peak
readings on the meter are about 80% of full scale.

To change the audio output line (i.e., speaker, headphone,
lineout, etc.) click on the speaker icon (it should change
to a headphone icon). Additional clicks will round-robin
among the available lines. If there is only one option, the
button will be disabled. Similarly, click on the mike icon
to select among the input lines. By default, vat starts
with the mike muted and the speaker enabled. The mike is
active when the ``talk'' button is selected, while output
can be muted by de-selecting the ``listen'' button.

The Conference Hosts window lists all the remote users
participating in the conference. Each user's name is
displayed in a box that is highlighted whenever that user
speaks and grayed-out if a `session' message from that user
hasn't been received for at least 30 seconds (vat sends
`session' message every so often) - this usually indicates
that the site has lost connectivity or that vat has been
aborted or stopped. There is a checkbox to the left of each
participant name. Clicking on the box will cause audio from
that participant to be discarded instead of played (for
example, this might be used to suppress a site that is
generating echoes).

Multiple VAT Windows
One host can be running an arbitrary number of vat sessions
(presumably with different destination addresses). However,

only one of those sessions will be able to access the mike
and speaker. For the most part, the vat sessions will
automatically follow the action. If you select the ``talk''
button or press ``Keep Audio'' button, the audio device will
be acquired by that session and the session that previously
held the audio will relinquish it. Vat displays it's title
bar in an oblique font when the audio is not being held.

A vat session will also acquire the audio if there is input
from the network. But to prevent a background vat session
from stealing the audio from the foreground session, you can
toggle the ``Keep Audio'' button. When the ``Keep Audio''
button is selected, vat will reliquish the audio only if
there is a user demand in another window (i.e., unmuting the
mike or selecting the ``Keep Audio'' button).

Participants in a multi-site conference often want to have
`side conversations' that don't bother the rest of the
conference participants. Vat has some support for
establishing side conversations: If you middle-click on the
name of some site in the conference hosts window, a new vat
window will be created that talks only to that participant
(it sends unicast datagrams rather than multicast). If that
other participant also middle-clicks on your site, you can
have a private conversation between just your two sites
using the newly created vat windows. Note: due to a `bug'
in the way most systems implement multicast, if you create a
new window aimed at a particular participant but they
haven't created a window aimed at you, they will hear you
speaking in the main conference window and may not realize
that your audio is being sent only to them and not
multicast. One can view this either as a feature (it
provides a semi-private channel you can use to ask someone
to set up a side conversation) or a bug (it often leads to
strange, one-sided conversations where one side multicasts
and the other doesn't).

Auxiliary Controls
Clicking on the ``Menu'' label at the bottom of the vat
window will cause a panel of auxiliary controls to open.

The Audio Tests buttons will enable some audio test modes.
These should not be selected during a conference. The
loopback mike button will cause input from the mike to be
sent to the local speaker/jack. This might be useful for
checking levels and debugging cable problems but the 20ms
delay from input to output makes talking in this mode almost
impossible. The three tone buttons will generate one of
three reference tones through the local speaker. Level
setting should generally be done with the -6dBm tone.

feedback/echo from the mike to the speaker. In mike mutes
net mode, vat will mute the speaker whenever it thinks that
you are talking, while in net mutes mike mode, vat will mute
the mike whenever input from the network arrives. In full
duplex mode, vat will assume that feedback can't happen and
do nothing to avoid it. In echo cancel mode, vat will
attempt to eliminate echoes by doing some fancy signal
processing. (EchoCancel requires the BSD sound driver - it
is disabled when running vat under Sun OS because the Sun
driver does not provide any mechanism to time correlate
audio output and input.) The internal speaker should only
be used in `speakerphone' or `echo cancel' mode - selecting
`headphone' mode for it will result in your site injecting a
lot of unpleasant echoes into the conference. The headphone
jack should be set to `FullDuplex' mode if you have
headphones plugged into it and `MikeMutesNet' or
`EchoCancel' mode if you have an external amp and speaker
plugged into it.

There are two type-in boxes (see below) at the bottom of the
Auxiliary Controls panel. The one labeled `Name' can be
used to change the session name announced to other sites.
The one labelled `Key' can be used to specify an encryption
key (see next section).

Encryption
(N.B.: Because of U.S. export controls, the standard
distribution of vat from LBL does not support encryption.
In this case, the ``Key'' type-in box will be disabled.)

Since vat conversations are typically conducted over open IP
networks there is no way to prevent eavesdropping,
particularly for multicast conferences. To add some measure
of privacy, vat allows the audio packet streams to be DES
encrypted. Presumably only sites sharing the same key will
be able to decrypt and listen to the encrypted audio.

Encryption is enabled by entering an arbitrary string in the
key box (this string is the previously agreed upon
encryption key for the conference - note that key
distribution should be done by mechanisms totally separate
from vat). Encryption can be turned off by entering a null
string (just a carriage return or any string starting with a
blank) in the key box.

X Resources
The following are the names and default values of X
resources used by vat. This list is incomplete. Consult the
tcl code in ui-resource.tcl from the vat source distribution
for the complete set.

Vat.audioFormat: pcm
Vat.lectureMode: false
Vat.inputPort: Mike
Vat.outputPort: Speaker
Vat.speakerMode: Speakerphone
Vat.jackMode: Headphone
Vat.mikeGain: 32
Vat.speakerGain: 180
Vat.jackGain: 180
Vat.mikeAGC: false
Vat.mikeAGCLevel: 0
Vat.speakerAGC: false
Vat.speakerAGCLevel: 0
Vat.maxPlayout: 6
Vat.defaultPriority: 100
Vat.idleDropTime: 20
Vat.autoRaise: true
Vat.pushToTalk: false
Vat.keepSites: false
Vat.key:
Vat.muteNewSites: false
Vat.siteDropTime: 30
! fonts
Vat.titleFont: -*-helvetica-bold-r-normal--*-140-75-75-*-*-*-*
Vat.audioFont: -*-helvetica-medium-r-normal--*-100-75-75-*-*-*-*
Vat.helpFont: -*-times-medium-r-normal--*-140-75-75-*-*-*-*
Vat.ctrlFont: -*-helvetica-bold-r-normal--*-100-75-75-*-*-*-*
Vat.ctrlTitleFont: -*-helvetica-bold-r-normal--*-120-75-75-*-*-*-*
Vat.entryFont: -*-helvetica-medium-r-normal--*-100-75-75-*-*-*-*

Vat.maxPlayout is the maximum `play out' delay, in seconds,
that can be tolerated. I.e., vat dynamically adapts to
delays introduced in the network by delaying the play out of
a remote site's audio packets. The range of adaptation is
limited by the size of a buffer in vat and this parameter
essentially sets the size of that buffer. Setting
maxPlayout larger than 10 seconds will probably result poor
vat and system behavior.

Vat has two different modes of adapting the playout delay,
one more suitable for an interactive, multi-party discussion
or conference and the other more suitable for listening to a
speech or lecture. The two modes differ in how quickly they
`forget' the delay vat introduces to adapt to transient
network congestion: In Conference mode vat attempts to
minimize the delay (since large delays make interactive
conversations difficult) but this usually results in more
lost packets when the delay becomes too short handle the
next congestion event. In Lecture mode vat attempts to
minimize lost packets by reducing delays very slowly. This
results in the clearest playback but interactivity may

Conference mode is the default when vat starts up unless the
-l flag is given or the X resource lectureMode is set to
true. There are radio buttons in the network section of the
Auxiliary Controls panel to switch between Conference and
Lecture

Statistics
Clicking on a name with the left mouse button will bring up
a small window of identification information for that user.
The window includes several of the RTP identification
descriptors, the audio format in use, and the times of
reception of the last data and control packets. A packet
statistics window can be brought up from the ``Stats...''
pulldown menu by selecting ``RTP''. There are three columns
of numbers. The last column is the aggregate statistics
since vat started, while the middle column is the difference
between the last update time and the current time. The
first column is an smoother version of the middle column,
using an exponentially weighted average with gain
Vat.statTimeConst.

The statistics are updated every second or so while the
window is mapped. Any of values can be plotted with a
stripchart by clicking on the name of the desired statistic.