.\" @(#) $Header: confcntlr.1,v 0.4 97/26/09 16:33:49 mperry $ (LBL) .\" .\" Copyright (c) 1997 .\" 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 CONFCNTLR 1 "26 September 1997" .de HD .sp 1.5 .B .. .SH NAME confcntlr \- a conference controller .SH SYNOPSIS .na .B confcntlr [ .B \-f .I filename ] [ .B \-p .I port ] .br .br .B confcntlr-crypt [ .B \-f .I filename ] [ .B \-k .I key ] [ .B \-p .I port ] .br .ad .SH DESCRIPTION .LP .I confcntlr is a conference controller intended to allow easier access to, control of, and coordination of a videoconference between remote sites. It is meant to be run on all the machines participating in a videoconference session and used to control the video and audio. .I Confcntlr is a graphical user interface and communication tool. The graphical user interface is for initiating actions and setting the controls for the video and audio portions of a conference. Options and session values are displayed and can be changed in the windows. When .I confcntlr starts, default values are used. These startup values can be changed by the user. The communication tool allows message exchange between remote hosts over a network and between applications on a single host. Messages may be sent to start or stop tools or to change settings of tools that are running. (See OPERATION and SETTING DEFAULTS.) .I Confcntlr is meant to control only one videoconference. However, multiple .I confcntlrs can be executed on one host. ( .Confcntlr version 0.4 is required.) Each .I confcntlr running on the local host must have a unique port on which it listens for connection requests from remote .I confcntlrs. .I Confcntlrs running on different hosts and controlling the same conference must have the same port number. Each conference controller can launch one or two .I vics and one .I vat either locally or from a remote site. .I confcntlr must be started before running .I vic and .I vat. There are security features for access control to .I confcntlr and encryption of messages sent over the network may be supported. (See SECURITY WINDOW.) .SH OPTIONS .br .br .I Confcntlr versions earlier than 0.4 will not support the following options. .TP .B \-f Use .I filename for default values. If .I filename is not found in the home directory at startup, system defaults are used and the current settings are saved to this file upon termination. If not specified, the home directory is searched for ~/.confcntlrrc. .TP .B \-k Use .I key as the encryption key for .I confcntlr-crypt. .TP .B \-p Set the port on which .I confcntlr listens for connection requests from remote .I confcntlrs. Specify .I port as an integer greater than 6000. If not specified, a program-defined port is used. .br .SH OPERATION Starting/stopping tools, changing settings, and communicating with remote hosts are controlled via the windowings. The main window shows the conference status and has buttons for general control (e.g., quitting the program and bringing up the windows for setting options, changing settings, and starting tools). .HD .I MAIN WINDOW .LP .I Remote Host Names The entry field labeled "Contact Host" shows the name of the machine to connect to. Use this field to type or edit the name of the remote site you want to communicate with. Do not use the same name as the local host and do not use a multicast address. To bring up a menu with predefined addresses, click on the button with the arrow. If you press the return key in the entry field or click on a button and .I confcntlr is running on that host, you will get that host's session status, settings, and video/audio devices. You can change the list of host addresses or add new addresses by editing the following line in the defaults file (e.g., $HOME/.confcntlrrc): .br hostlist# ... . .br .br The field labeled "Remote User" indicates the most recent user who started/stopped a tool or changed the settings from a remote host. The format is: user@hostname. .I Status The main window shows the authorization level and which tools are running. The left column of buttons labeled "Status" indicates the tools running on the local host and the right column indicates tools running remotely, in order of video 1, video 2, and audio. A red button indicates that a tool is running. The stop sign image indicates the authorization level. If it is green, control access to .I confcntlr is granted to anyone. If it is yellow, control is allowed by hosts on the authorization list in the home directory. If it is red, no one is allowed control access. .I Subwindows Click on the buttons labeled "Settings", "Conference", and "Security" to bring up the windows described below. At startup, if you specify a Contact Host and .I confcntlr is running on that host, you will automatically get its settings. .I Quitting Confcntlr To quit the program, click on the button labeled "Quit". If changes were made, you will be prompted about saving the changes. .HD .I LOCAL WINDOW .LP This window allows you to change the settings for video and audio tools running on the local host. There is a section for each tool with the titles "vic 1", "vic 2", and "vat" for video 1, video 2, and audio, respectively. For video, a dialog box will appear if the bandwidth or frame rate is set to a value that exceeds the recommended limit. If you still want to use this value, click on the button labeled "USE ANYWAY." If you want to edit the value, type in the entry field and then click "SET." If you want to go back to the default value, click on "SET TO DEFAULT." If you want to use the previous value, click on "UNDO CHANGE." .I Conference Name Extension The entry field labeled "ConfName Ext" is for specifying an optional extension to the conference name for the video or audio. The characters "/", "#", and "@" are .I not allowed since they are used by the program. .I Video Transmission To start or stop video transmission, click on the button labeled "Transmit Video". A red checkbox indicates transmission is "on". .I Video Settings The bandwidth, frame rate, quality, and device may be changed via their pulldown menus or typing in their entry fields and ending with the return key. The format and input (Port...) can be changed only via its pulldown menu. If you want the value you typed for quality to be kept as the quality associated with the current format, press the return key after typing the entry. Since different video formats support different quality ranges, changing the video format will automatically change the range of values for the video quality. Cellb does not support quality, so if cellb is the selected format, the quality menubutton and entry field are disabled. .I Audio Settings The audio format can be changed by either typing in its entry field or clicking on the button labeled with an arrow. Lecture mode, recv-only, and "keep audio" can be turned on and off by clicking in their checkboxes. A red checkbox means "on." Clicking on the "listen" and "talk" checkboxes mutes or unmutes the output and input devices; red means "unmuted". To change a device, click on the button labeled with an arrow below the "talk" or "listen" checkbox. Then click on your selection. The image to the left of the button displays the current device. You may change the devices available by editing the list of values for "audioOutputDevices" and "audioInputDevices" in the defaults file. The sliders below the devices are for changing the gain levels. The selected output mode applies to the current output device. External echo cancellation ("ExtEchoCancel") is available only if the "localvat.echoCancel" value is "true" in the defaults file. (V.4 is required for most of the audio features.) The bitmaps that indicate the current input/output devices were taken from the vat source code. .I Advanced Audio Settings Clicking on the button labeled "AdvAud" will bring up a window with controls for local audio tests. If your $HOME/.vat.tcl file contains a procedure for talk threshold, echo threshold, and echo suppression time, sliders for setting these values will also be displayed. (See SETTING DEFAULTS below and/or the mbone web page at http://www-itg.lbl.gov/mbone for more information.) .I Dynamic Changes You do not need to stop and restart the video to change the following: transmission, bandwidth, frame rate, format, quality, device, and input jack. If you type in an entry field, end with the return key. You do not need to stop and restart the audio to change the following: output/input device, output mode, output/input gain, or threshold levels. Lecture mode, recv-only, "keep audio", and muting/unmuting devices can be turned on and off without stopping and restarting vat. If you click the "quit" button in the vic or vat main window, or if you click vic's transmit button, .I confcntlr will be sent a message and it will update its controls. .I Reverting to Defaults To go back to default values, click the button labeled "Reset to Defaults". To hide the window, click on the "Dismiss" button. .HD .I REMOTE WINDOW .LP This window is used to change the settings for video and audio tools on a remote host. It works in the same way as the "local window." When a remote host sends its settings (as in response to clicking on "Get Remote Settings" or a change in Contact Host), the remote and conference windows display the values. For vat, the external echo cancellation and threshold sliders are disabled and grayed out if .I confcntlr hasn't obtained the contact host's settings or if the contact host doesn't support these features. .HD .I CONFERENCE WINDOW .LP To specify a name for the conference, type in the entry field labeled "Conference Name." The conference name is optional and can be the same or different for each session. The characters "/", "#" and "@" may .I not be used since they have special meaning to the program. .I Conference Address, Port, & Time-to_Live A conference address, port, and time-to-live value must be specified. Each tool has its own conference address and port. The value specified for the video or audio applies to both the local and remote tool. The conference address may be the same or different for each tool, but the ports must be different. (You can run sdr to get the conference address and port if they are unknown.) To change the values, click on the button labeled with an arrow and then click on a selection in the pulldown menu, or type in the entry field and end with the return key. The conference address is the address to which the video and audio tools transmit. If "unicast" is specified and there is no "Contact Host", the local vic/vat will transmit its video/audio to the local host. If there is a "Contact Host" and both local and remote programs are started, they will transmit to each other. Otherwise, transmission will be to the address specified. .I Starting/Stopping Tools To start/stop tools on the local host, click on the selected button in the column on left side of the lower portion of this window. To start/stop tools on a remote host, click on the selected button in the column on the right side of the lower portion of this window. When a local tool is started, the square turns red and the label changes to "stop" to indicate that next action available is to stop the tool. When you start a remote tool, a message is sent to the contact host and a reply is expected. The start button turns pink until the reply is received. This could be delayed if the network is slow or if the remote user is manually setting control permissions (see SECURITY WINDOW). Clicking on a "Start All" button will start all three tools. The "Stop All" button will stop all tools that are running. .I Getting Remote Settings To get a remote site's settings, either type the contact host name and press the return key, or select a host from the menu, or click on the button labeled "Get Remote Settings." The values in the remote window and the status buttons will be updated. The video devices, video input ports (jacks), and the audio threshold and external echo cancellation features will be enabled or disabled, depending on what is supported by the contact host. .HD .I SECURITY WINDOW .LP This window contains controls for setting the authorization level, viewing/editing the authorization list, selecting the prompts and warnings, and editing the encryption key if you are running .I confcntlr-crypt. .I Access Control There are three authorization levels: allow any remote host to make a request, allow only users on the authorization list to make requests, or do not allow anyone to make a request. To change the authorization level, click on the desired radiobutton. The stop sign image in the main window will change color accordingly. The authorization list can be viewed or edited via the scrollbar text field. When you quit .I confcntlr , if this list has been changed, a panel will appear to ask if the changes should be saved to the $HOME/.ccauth file. .I Setting Permissions for Actions If you want to manually approve starting/stopping tools, click "on" the button labeled "Prompt to approve start/stop". If you want to approve changes in conference address, port, time-to-live, or conference name, click "on" the button labeled "Prompt to approve address/ttl/name changes." If you want to approve other changes, click "on" the button labeled "Prompt to approve setting changes." If you want to manually approve every request, click "on" the button labeled "Prompt to approve all actions". If an action is denied, the requesting host will be notified. When you are not prompted to set the permission for a request, a warning panel will appear to notify you that the change has been made. If you do not want to receive these warnings, click "on" the button labeled "Turn off warnings." .I Encryption If you are using encryption, all hosts participating in the conference must use the same key. To turn off encryption, erase the key or use a blank space or tab as the first character. You may change this key, but only after all participants have agreed on the new key. The distribution of .I confcntlr from LBNL via the World Wide Web does not support encryption due to U.S. export controls. In this case, this section is missing in the security window. .SH SETTING DEFAULTS When .I confcntlr starts, settings are read from the $HOME/.confcntlrrc file, or from the defaults file in the home directory that is specified with the -f option. If there is no defaults file, the program supplies the values and displays a notification panel. When you quit the program, if values are different from those at startup, a panel will appear to ask whether you want to save the changes. Click on the button labeled "Save Settings" to update the defaults file if it exists or create one if it does not exist. In order to associate a quality value with a specific format for the video, the numeric value can be edited in the ~/.confcntlrrc file in the following lines: .br *vic.jpeg# xxx .br *vic.h261# xxx .br *vic.nv*# xxx .br .br .I WARNING: .br If the format of the defaults file is not held to strictly, the entry will not be read! The list of users with access control is kept in the $HOME/.ccauth file. If you change this list in the security window, when you quit the program, you will be asked if you want to save the changes to this file. If the file does not exist, it will be created. File entries are in the format: user@host. An asterisk means 'any'; for example, *@host means 'any user at host'. As described in the .I vic and .I vat documentation, both of these tools allow user customization by specifying tcl commands in a $HOME/.vic.tcl (or $HOME/.vat.tcl) file and in a script that can be specified with the "-u" command line option. Although it is not required, a "user_hook" procedure can be included in these files. When .I confcntlr starts a session, it writes a script with a user_hook procedure and starts the video and audio with the "-u" option. Since this script is executed AFTER the $HOME/.vic.tcl (or $HOME/.vat.tcl) scripts, the user_hook procedures in the $HOME/.vic.tcl and $HOME/.vat.tcl files will be overridden. To have them execute, rename "proc user_hook" to "proc confcntlr_hook" in the $HOME/.vic.tcl and $HOME/.vat.tcl files. If there is a user_hook procedure but no confcntlr_hook procedure in a $HOME/.vic.tcl or $HOME/.vat.tcl file, you will get a warning panel one time only, the first time a session is started. .SH SESSION DIRECTORY SERVICES .I sdr will launch .I confcntlr if you have the appropriate plugin (available from http://www-itg.lbl.gov/mbone/confcntlr). .SH BUGS .I confcntlr may "freeze" if an attempt is made to connect to a remote host that is not operational. In this case, end the program by clicking on the small square in the top left corner of the main window, choose "quit", and then restart the program. Versions 0.3 and 0.4 are not fully compatible. .I Confcntlr v0.3 may not start a remote tool with the values specified by v0.4 and v0.3 may not be able to obtain the settings on v0.4. To avoid this problem, it is necessary to "Get Remote Settings" for a contact host (to get the remote ] version number.) .SH ALSO SEE vic, vat, sdr .SH AUTHORS Marcia Perry (mperry@george.lbl.gov), San Francisco State University, and Lawrence Berkeley Laboratory, Berkeley, CA Deb Agarwal (deba@george.lbl.gov), University of California, Berkeley and Lawrence Berkeley Laboratory, Berkeley, CA .