rat(1)

NAME
rat - unicast and multicast audio conferencing tool

SYNOPSIS
rat [options] addr/port

rat -F [options] infile outfile

rat -T [options] addr/port/ttl/codec addr/port/ttl/codec

OPTIONS
The following options are supported:

-crypt key
    Enable encryption, with the specified key. Encryption is done using DES, and is believed compatible with encrypting versions of vat.

-drop drop
    Specifies the percentage of packets to be dropped at the transmitter. This is particularly useful when experimenting on files for testing how a given repair/coding technique works.

-f c1/c2/../cn
    Specifies the encodings used when transmitting audio. The order is primary encoding, secondary encoding, etc. A maximum of seven levels of encoding are possible, although only two are available from the user interface. The allowed values are l16, pcm, dvi, gsm, lpc. See CODECS below for description of the codecs and their recommended usage.

-F infile outfile
    Makes RAT to read audio from the file infile , encode it, and transmit it on the local loopback address, and finally write it to outfile. This is useful inconjunction with the -drop option for evaluating repair techniques and codecs. The file format is 16 bit linear PCM audio, currently sampled at 8 kHz, with no header information.

-allow_loopback
    Allows playback of RTP packets looped back during multicast sessions.

-lbl_channel channel
    Specifies the channel identifier for use with the LBL Conference Bus. RAT always listens to the base channel for audio device trading with other tools, like vat(1). When a channel is specified it allows RAT to communicate with other tools, like vic(1), provided they have the same channel number. This is particularly useful for voice switching the video sources.

-lbl_priority priority
    Specifies the processing priority of the code that handles the LBL Conference Bus. The default value is 100 and the permitted range of values is 0 to 200.

-name name
    Sets the RAT window title to name.

-no_ui
    Do not display user interface.

-p priority
    Sets the thread priority on the Windows 32-bit version. The following values are observed:
    1 above normal priority level
    2 time critical thread priority
    3 highest thread priority

-pt type/redundancy
    Specifies the dynamic payload type to be used for redundancy. Later versions will accept configurable configurable payload types for the primary encoding.

-repair method
    Specifies the use of receiver based repair technique based on method. This can currently be none or repeat.

-t ttl
    Specifies the TTL (time to live) value set in the packet headers. This limits the scope of the packets. The following values are generally considered appropriate:
      4 campus/organization
     16 country
     64 continent
    127 planet

-T addr/port/ttl/codec addr/port/ttl/codec
    Causes RAT to operate as an RTP transcoder/mixer. In this mode the user-interface is not displayed, and no audio is played out. Instead, RTP packets received from either group are transcoded into the format specified for the other group, multiple sources are mixed together, and the result transmitted to the other group. In each case, addr may be either unicast or multicast, and the ttl and codec specifiers may be omitted (The default is TTL 16, DVI coding). This option is useful for transcoding between low- and high-bandwidth sessions, for use other a slow link, for example.

-seed number
    Seeds the random number generator that governs dropping of packets at the transmitter. Only valid in conjunction with the -drop option.

-silence on|off
    Turns silence suppression on or off. hysteresis. If the packet average is greater than the threshold for interval packets, the minimum average value is incremented by one, but not beyond max_avg.

-version
    Displays the version number.

DESCRIPTION
RAT is a network audio tool that allows users to particpate in conferences over the internet. These can be between two participants directly (unicast) or between a group of participants on a common multicast address.

To initiate a unicast conference the user specifies the destination host name or IP address and a port number. To participate in a multicast conference a Class D group address should be specified together with a port number. The application uses the greatest even integer less than or equal to the port specified for data (RTP) and the port above for control messages (RTCP). The protocols RTP and RTCP used are specified in RFC 1889.

USER INTERFACE

  Main Window
The main window of RAT is split into three sections. On the left is a list of conference participants, below this are a number of buttons enabling setting of options, and on the right are volume/microphone controls. The list of participants shows local and remote conference members. Active speakers are highlighted. Clicking the left mouse button on the name of a remote participant will display a user information panel, giving various reception statistics for that user. Individuals can be selectively muted by clicking on them with the middle mouse button on three button systems, or moving the mouse to the individual and pressing the m. The right-hand side of the RAT window contains volume and gain controls. The leftmost controls in this section control audio output, and the rightmost control audio input. The sliders control volume/gain, and the icons above them select audio source and destination. Audio output may be toggled between speaker, headset and line out. Audio input may be toggled between microphone and line in. Audio input/output may be independently muted. Pressing the right mouse button anywhere within the RAT window will temporarily toggle the state of the audio input mute: this allows a "push-to-talk" mode of operation.

  Options
Pressing the "options" button brings up a control panel, allowing the operation of RAT to be modified. The options in this panel are as follows:

Duration
    Select amount of audio data, in milliseconds, which is sent in each packet. Larger values result in greater end-to-end delay over the network, but reduce the per-packet header overhead.

Encodings
    Sets the format for data transmitted to the network. If the conference includes vat users, redundancy should be turned off; however if all users are using RAT, and packet loss is being experienced, the use of redundancy will vastly improve sound quality. It is hoped that future versions of vat will eventually be able to decode redundant audio data.

Mode
    Determines whether audio data from the network has priority over outgoing data. Use options other than full duplex with caution, since they can be confusing.

Loss repair
    If set to packet repetition the receiver attempts to patch over missing packets with the replay of the previous packet. This is a receiver based solution to the problem of network packet loss. We recommend that redundancy is used in these cases, but if that is not possible, use of this option may help. This does not affect the data sent to the network.

Suppress Silence
    If on periods of silence within a conversation are not transmitted, reducing the network traffic. We recommend that this option is on.

Powermeters
    If on, audio powermeters will be displayed in the main RAT window.

Lecture Mode
    If on, the playout delay at the receiver is artificially increased. This results in better performance in the presence of variable network delay, at the expense of reduced interactivity. It is most useful when listening to broadcast lectures, hence the name. This is automatically turned off if you transmit audio.

Video Synchronisation
    If using a modified version of vic, this enables lip synchronisation between audio and video streams. This is not generally useful at present.

Automatic Gain Control
    If on, the microphone gain will be controlled automatically.

Acoustic Feedback
    If on, acoustic feedback of input gain will be provided.

Play file/Rec file
    Allow the playback/recording of audio data in the conference. Format of the files is raw 8kHz 16bit linear PCM data, with no headers.

RTP info
    Allows setting of the name by which you appear in the conference.

Session key
    Entering a key, and enabling this will encrypt the audio data using DES. This encryption is believed compatible with encrypting versions of vat.

CODECS
Five types of audio encoding are currently possible with RAT, although more are in development. The encodings are:
    Name | Bit rate | Description
    l16 | 128 kb/s | Linear PCM at 16 bits per sample.
    pcm | 64 kb/s | Mulaw companded PCM at 8 bits per sample (G711).
    dvi | 32 kb/s | Intel's DVI ADPCM at 4 bits per sample.
    gsm | 13.2 kb/s | EDSI Group Systeme Mobile codec.
    lpc | 5.8 kb/s | Ron Zuckerman's 10 pole LPC codec.
Internally, RAT uses 16 bit linear sampling at 8 kHz (except on hardware where it is unavailable, then 8 bit mulaw is used). Multiple sampling rates will be available in a future release. NB The DVI codec has 4 bytes of state associated with each packet irrespective of it's length.

PACKET OVERHEADS
There is an overhead associated with each audio packet sent. When RAT is operating as an audio tool the RTP header is 96 bits per packet (it is longer when RAT is acting as mixer and there are multiple contributing sources in each packet. The UDP/IP overhead is 224 bits per packet. Thus transmitting with 20 ms packets has an overhead of 11.2 kb/s, whereas 80 ms only incurr 2.8 kb/s. By default RAT starts with 40 ms packets of DVI coded data. This represents a trade off between bandwidth, quality, and the ability of receiver based repair techniques to work successfully.

EXAMPLES
To start a unicast session between the current host and the host shrew.cs.ucl.ac.uk using port 12000 type:
        rat shrew.cs.ucl.ac.uk/12000 To join a multicast session on group address 224.5.6.7 and port 8110 type, using primary encoding of dvi and a secondary encoding of lpc:
        rat -f dvi/lpc 224.5.6.7/8110 To simulate packet loss between 2 hosts of 10% using trek.in as the input file and trek.out as output file:
        rat -F -drop 10 trek.in trek.out

AUTHORS
The original RAT code was developed by Vicky Hardman <V.Hardman@cs.ucl.ac.uk> and Isidor Kouvelas <I.Kouvelas@cs.ucl.ac.uk> at University College London. The DES encryption was written by Saleem Bhatti <S.Bhatti@cs.ucl.ac.uk> and integrated by Darren Harris. This release of RAT has been substantially enhanced by Isidor Kouvelas, Colin Perkins <C.Perkins@cs.ucl.ac.uk>, and Orion Hodson <O.Hodson@cs.ucl.ac.uk>. The RAT project is managed by Vicky Hardman and Angela Sasse, and supported by the following projects:
    MICE | Multimedia Conferencing in Europe (ESPRIT)
    MERCI | Multimedia European Research Conferencing
     | Integration
    ReLaTe | Remote Language Teaching for Super Janet (BT/JISC)
    RAT | Robust Audio Tool (EPSRC/BT)

ACKNOWLEDGEMENTS
We thank Anna Watson, Mark Handley, Steve Casner, Jon Crowcroft, Atanu Ghosh, Roy Bennett, Jane Hughes, Marcus Iken, and our collegues at UCL who have provided countless suggestions and extended good humour through the buggy pre-releases. Modifications for HP-UX by Terje Vernly <terjeve@usit.uio.no> and Geir Harald Hansen <g.h.hansen@usit.uio.no>. This software is derived, in part, from publically available source code with the following copyright: Copyright (c) 1991-1993,1996 Regents of the University of California. Copyright (c) 1992 Stichting Mathematisch Centrum, Amsterdam. Copyright (c) 1991,1992 RSA Data Security, Inc. Copyright (c) 1992 Jutta Degener and Carsten Bormann, Technische Universitaet Berlin. Copyright (c) 1994 Henning Schulzrinne. Copyright (c) 1994 Paul Stewart. This product includes software developed by the Computer Systems Engineering Group and by the Network Research Group at Lawrence Berkeley Laboratory.

Encryption features of this software use the RSA Data Security, Inc. MD5 Message-Digest Algorithm.

FEEDBACK
Please send comments and suggestions to rat-trap@cs.ucl.ac.uk. Please check ftp://www.cs.ucl.ac.uk/mice/rat for latest release information.