.\" @(#) $Header: /home/barad-dur/b/users/elan/src/rtpgw/ui/RCS/rtpgw_ui.1,v 1.11 1996/11/12 19:05:46 elan Exp $ (UC Berkeley) .\" .\" Copyright (c) 1994-1995 .\" The Regents of the University of California. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that: (1) source code distributions .\" retain the above copyright notice and this paragraph in its entirety, (2) .\" distributions including binary code include the above copyright notice and .\" this paragraph in its entirety in the documentation or other materials .\" provided with the distribution, and (3) all advertising materials mentioning .\" features or use of this software display the following acknowledgment: .\" ``This product includes software developed by the University of California, .\" Lawrence Berkeley Laboratory and its contributors.'' Neither the name of .\" the University nor the names of its contributors may be used to endorse .\" or promote products derived from this software without specific prior .\" written permission. .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. .\" .TH RTPGW_UI 1 "20 Nov 1995" .de HD .sp 1.5 .B .. .SH NAME rtpgw_ui \- RTP gateway user interface .SH SYNOPSIS .na .B rtpgw_ui .B \-T [audio|video] [ .B \-I .I channel ] [ .B \-K .I keyA:keyB ] [ .B \-S ] [ .B \-u .I script ] [ .B \-U .I interval ] [ .B \-v ] [ .B \-x .I engine ] .I Asession .I Bsession .br .ad .SH DESCRIPTION .LP .I Rtpgw_ui is the user interface of an experimental RTP gateway that allows rate controlling of audio and video streams between two RTP sessions through format conversion (transcoding) and frame dropping. The gateway is comprised of two components: the engines, .I vgw(1) (video) and .I agw(1) (audio), and the user interface to the engines, .I rtpgw_ui, which run as separate processes that communicate over a common communication channel. Each session, .I A or .I B, is specified as a colon separated list of addresses of the form .I addr/port[/ttl]. Each session can be either comprised of multicast or a unicast addresses. Note that IP Multicast support is required for multicast sessions. No special hardware is required since all processing is performed in software. .SH 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 .\".I vic .\"any flags in the usual case. The flags only exist to temporarily .\"override some resource.) .TP .B \-I Specify the ``LBL Conference Bus'' channel to interact with other multimedia conferencing tools, in particular the gateway engine. The small integer .I 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. .TP .B \-K Use .I keyA and .I keyB (colon separated) as the encryption keys for this vic session. (This only works if you have a binary with encryption support. Because of U.S. export controls, the standard distribution does not include this support). In the lack of DES support, the encryption will be a simple XOR. .TP .B \-S Standalone mode. Do not start an engine. .TP .B \-T Specify the media type. Must be either 'audio' or 'video'. .TP .B \-u Source .I script, in addition to the compiled-in script. This is only useful during development. .TP .B \-U Update the user interface every .I interval milliseconds. Default is 1000. .TP .B \-v Print out the current version of the engine. .TP .B \-x Use .I engine as the gateway engine. Default is ``vgw'' for video and ``agw'' for audio as determined by the .B \-T flag. .SH OPERATION .HD The Control Menu .LP Clicking on the ``Menu'' button in the lower righthand corner of the main .I rtpgw_ui window will bring up a control panel. The ``Sessions'' panel contains the information on the two sessions (A and B). The first line of a session panel contains the session address, port, and ttl. In addition it contains a ``Rate Control'' button which toggles rate control for the session. The next line in the session panel contains a slider which controls the total output bandwidth for that session. This bandwidth can be specified using the .I RtpgwUI.sessionXtotalOutputBW resource. The maximum value on this slider can be specified using the .I RtpgwUI.sessionXmaxBWScale resource (where X is A or B). Finally, the third line of the panel contains the ``Format...'' menu button which enables selecting the output format for this session if it is rate controlled. .PP If rate control is disabled, the bandwidth allocation slider and the ``Format...'' button will be disabled and all packets destined for that session will simply be forwarded by the gateway without any extra processing. .PP If rate control is enabled, all sources in the session will be reconfigured to be transcoded to the selected output format. The default selection is determined by .I RtpgwUI.sessionXdefaultFormat resource (where X is A or B). During runtime, a different output format can be selected using the ``Format...'' menu. .PP .HD Source Panels .LP The main .I rtpgw_ui window provides an abbreviated summary of all sources on both sessions. If no sources are present, the text ``Waiting for Video...'' or ``Waiting for Audio...'' is displayed in the window depending on the media type. Otherwise, each source has a panel composed of a identification text, input and output bit and frame rate statistics, and a bandwidth allocation slider. .LP The first line of the identification text contains the source session (A or B) in parenthesis, and the RTP NAME attribute of the corresponding source. The second line of text contains the RTP CNAME attribute, the format of transmitted media and the transcoder that is in place for this source. If the NAME and CNAME are identical (or very similar), or if the CNAME does not contain a numeric IP address, the second line will instead list the source's IP address (along with the media format and transcoder). The third line contains input and output filtered frame and bit rate statistics. and a loss indicator. These rates may differ from the actual sender's rate because of network packet drops or loss due to local socket buffer overflows because of CPU saturation. The gain of the low-pass filter used to smooth the statistics is controlled by the .I RtpgwUI.filterGain resource. Note that smoothing can be effectively disabled by setting gain to 1. .HD Source Bandwidth Allocation .LP The second component of a source box is the bandwidth allocation slider. This slider can be used to allocate a fraction of the total output session bandwidth to the source. Note that the slider will not allow allocation that exceeds 100% of the total bandwidth for the output session. .HD Voice Switched Bandwidth Allocation .LP Activating the ``Switching'' button on the session panel of a rate controlled session enables voice activated bandwidth allocation for that session. In this mode, the gateway will accept conference bus commands from the .I vat(1) audio tool and use them to allocate bandwidth to the current speaker in the session. The percentage of bandwidth allocated to the speaker is given by the .I RtpgwUI.sessionXspeakerBWpercent (where X is A or B) X resource, whereas the remaining percentage of bandwidth (if any) is divided up equally among the remaining session members. Note that in order for this feature to work, both the gateway and .I vat must be using the same conference bus channel (the -I flag in both tools sets this channel). .HD Non-Rate Controlled Sources .LP Sources that are members of a non-rate controlled session will simply be forwarded across the gateway and will have their bandwidth allocation slider and frame rate values disabled. The transcoder field in the second line of the source panel will then be designated as ``pass-thru''. .HD Engine Panel .LP Clicking on the ``Engine'' button in the lower right-hand corner of the main interface brings up a panel which gives information about the engine and the conference bus channel being used to communicate with it. The ``Exec'' button starts up an engine on the user interface conference bus. This button is disabled if the interface is already attached to an engine. The ``Kill'' button terminates the engine attached to the interface. This button is disabled if no engine is attached to the engine. By default, the user interface will start an engine on the default conference bus channel (3) unless the \-S flag is specified, in which case the user interface will not start up an engine. .HD Exiting the Gateway .LP Clicking on the ``Quit'' button in the lower right-hand corner of the main interface window will exit the user interface and kill the attached engine as well. ./"Encryption ./".LP ./"\fI(N.B.: Because of U.S. export controls, ./"the standard distribution of vic from LBL does not support encryption. ./"In this case, the ``Key'' type-in box will be disabled.)\fP ./".LP ./"Since vic 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, vic allows the video ./"streams to be DES encrypted. Presumably only sites sharing ./"the same key will be able to decrypt and ./"listen to the encrypted video. ./".LP ./"Encryption is enabled by entering an arbitrary string in the ./".B 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 vic). Encryption ./"can be turned off by entering a null string (just a carriage ./"return or any string starting with a blank) in the ./".B key ./"box. .HD Application Level Forwarding Loops .LP The gateway will attempt to detect application level forwarding loops caused by a circular topology induced by other gateways. In the event that such a loop occurs, the gateway will terminate and the loop that was detected will be printed to stdout. .SH "X RESOURCES" The following are the names and default values of X resources used by the gateway. Any of these resources can be overridden by the -X command switch, which may be used multiple times on the command line. For example, "-XsessionAdefaultTTL=32" overrides .I RtpgwUI.sessionAdefaultTTL with 32. .IP "\fBRtpgwUI.sessionAdefaultTTL\fI (4)\fP" The default IP multicast time-to-live for the A session. .IP "\fBRtpgwUI.sessionBdefaultTTL\fI (4)\fP" The default IP multicast time-to-live for the B session. .IP "\fBRtpgwUI.sessionAdefaultFormat\fI (``h261'')\fP" The default output format to the A session. .IP "\fBRtpgwUI.sessionBdefaultFormat\fI (``h261'')\fP" The default output format to the B session. .IP "\fBRtpgwUI.sessionArateControl\fI (``off'')\fP" The default startup state of rate control for the A session. Options are ``on'' or ``off''. .IP "\fBRtpgwUI.sessionBrateControl\fI (``on'')\fP" The default startup state of rate control for the B session. Options are ``on'' or ``off''. .IP "\fBRtpgwUI.sessionAtotalOutputBandwidth\fI (128000)\fP" The default initial setting of the A session bandwidth slider in bps. .IP "\fBRtpgwUI.sessionBtotalOutputBandwidth\fI (128000)\fP" The default initial setting of the B session bandwidth slider in bps. .IP "\fBRtpgwUI.sessionAscaleStep\fI (``uniform'')\fP" The default step used in the A session bandwidth slider. Options are ``log'' specifying a log scale or ``uniform'' specifying a uniform scale. .IP "\fBRtpgwUI.sessionBscaleStep\fI (``uniform'')\fP" The default step used in the B session bandwidth slider. Options are ``log'' specifying a log scale or ``uniform'' specifying a uniform scale. .IP "\fBRtpgwUI.sessionAmaxBWScale\fI (5000000)\fP" The default upper limit of the A session bandwidth slider in bps. .IP "\fBRtpgwUI.sessionBmaxBWScale\fI (5000000)\fP" The default upper limit of the B session bandwidth slider in bps. .IP "\fBRtpgwUI.sessionAspeakerBWpercent\fI (100)\fP" The percentage of bandwidth to allocate to the speaker when voice switched bandwidth allocation is enabled on the A session (see above section). .IP "\fBRtpgwUI.sessionBspeakerBWpercent\fI (100)\fP" The percentage of bandwidth to allocate to the speaker when voice switched bandwidth allocation is enabled on the B session (see above section). .IP "\fBRtpgwUI.sessionAswitching\fI (``off'')\fP" The default startup state of voice switched bandwidth allocation for the A session. Options are ``on'' or ``off''. This option only takes effect when the A session is rate controlled. .IP "\fBRtpgwUI.sessionBswitching\fI (``off'')\fP" The default startup state of voice switched bandwidth allocation for the B session. Options are ``on'' or ``off''. This option only takes effect when the B session is rate controlled. .IP "\fBRtpgwUI.confBusChannel \fI (3)\fP" The default ``LBL Conference Bus'' channel. .IP "\fBRtpgwUI.iconPrefix\fI (``'')\fP" A string that is prefixed to the .I rtpgw_ui icon names. .IP "\fBRtpgwUI.standalone\fI (``no'')\fP" Setting this resource to ``yes'' suppresses the user interface from starting up an engine upon startup. .IP "\fBRtpgwUI.updateInterval\fI (1000)\fP" The time interval (in milliseconds) between engine updates of the interface. .IP "\fBRtpgwUI.tile\fI (8)\fP" The default number of rows per column used for displaying source panels in the main .I rtpgw_ui window. .IP "\fBRtpgwUI.filterGain\fI (0.25)\fP" The low pass filter constant used for smoothing the frame rate and bit rate statistics. .IP "\fBRtpgwUI.audioEngine\fI (``agw'')\fP" The default engine to use with audio streams. .IP "\fBRtpgwUI.videoEngine\fI (``vgw'')\fP" The default engine to use with video streams. .br .SH "SEE ALSO" vgw(1), agw(1), vat(1), vic(1), ivs(1), nv(1) .LP .I vat is available via anonymous ftp to ftp.ee.lbl.gov in conferencing/vat. .I vic is available via anonymous ftp to ftp.ee.lbl.gov in conferencing/vic. .I nv is available via anonymous ftp to ftp.parc.xerox.com in pub/net-research. .I ivs is available via anonymous ftp to avahi.inria.fr in pub/videoconference. .LP Amir, McCanne, and Zhang ``An Application Level Video Gateway''. In proceedings of ACM Multimedia '95. November, 1995. .LP McCanne, Steven and Jacobson, Van. ``vic: A Flexible Framework for Packet Video''. In proceedings of ACM Multimedia '95. November, 1995. .LP Schulzrinne, Casner, Frederick, Jacobson, ``RTP: A Transport Protocol for Real-Time Applications'', Internet Draft, available via anonymous ftp to ftp.isi.edu in internet-drafts/draft-ietf-avt-rtp-*. .SH ACKNOWLEDGMENTS .LP The RTP gateway implementation was leveraged off the work done by Steven McCanne and Van Jacobson in the .I vic and .I vat conferencing tools. .LP The nv-format decoder was derived from source code from the the Internet video tool .I nv developed by Ron Frederick at Xerox PARC (frederick@parc.xerox.com). .LP Kevin Fall (kfall@ee.lbl.gov) provided help in the implementation of final version of the JPEG decoder and H.261 pixel domain encoder. .LP Jeff Gilbert (gilbertj@eecs.berkeley.edu) assisted in incorporating his implementation of the Infopad VQ encoder into the gateway. .LP This software is based in part on the work of the Independent JPEG Group and the Portable Video Research Group. .LP Tom Parks (parks@ll.mit.edu) assisted in incorporating encryption support into the gateway. .LP This work was supported by: The AT&T Fellowship, ARPA Contract #DAAB07-95-C-D154, ARPA Contract #J-FBI-93-153, California MICRO Program, Hughes Aircraft Corporation, Metricom Corporation .LP .SH AUTHORS Elan Amir (elan@CS.Berkeley.EDU), University of California, Berkeley, CA, and Steven McCanne (mccanne@ee.lbl.gov), University of California, Berkeley and Lawrence Berkeley Laboratory, Berkeley, CA. .SH BUGS MPEG is not yet supported. We plan to implement an ``Intra-MPEG'' encoder using the same principle underlying the ``Intra-H.261'' encoder. A rate controlled "pass-thru" transcoder occurs when a source on a rate controlled session requires a transcoder which is not implemented in the gateway. In order to enforce the bandwidth constraints of the session, these "pass-thru" transcoders are rate controlled as well. However, the effect of this is to arbitrarily drop packets in the gateway, which is pretty bogus. The alternative is just not to allow rate controlled pass-thru transcoders, so we just leave it up to the user to decide what to do. .