.\" .\" Copyright (c) 1995 International Computer Science Institute .\" All Rights Reserved. .\" .\" Permission to use, copy, modify, and distribute this software and its .\" documentation for educational, research and non-profit purposes, .\" without fee, and without a written agreement is hereby granted, .\" provided that the above copyright notice, this paragraph and the .\" following five paragraphs appear in all copies. .\" .\" Permission to incorporate this software into commercial products may .\" be obtained from the International Computer Science Institute, .\" 1947 Center Street, Suite 600, Berkeley, CA 94704. .\" .\" IN NO EVENT SHALL THE INTERNATIONAL COMPUTER SCIENCE INSTITUTE BE .\" LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR .\" CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS, ARISING OUT OF THE .\" USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE INTERNATIONAL .\" COMPUTER SCIENCE INSTITUTE HAS BEEN ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" THE INTERNATIONAL COMPUTER SCIENCE INSTITUTE SPECIFICALLY DISCLAIMS .\" ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE .\" PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE INTERNATIONAL .\" COMPUTER SCIENCE INSTITUTE HAS NO OBLIGATIONS TO PROVIDE MAINTENANCE, .\" SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS. .\" .\" The International Computer Science Institute will appreciate .\" receiving any enhancements and modifications of this software .\" made by others, and reserves the right to include them in future .\" releases. The Institute also recommends that this software not .\" be redistributed by third parties, but be obtained by all directly .\" from the ICSI server, so that all users of the software may .\" receive bug notifications and other relevant announcements. .\" .\" The German Academic Exchange Service has supported the development .\" of this software. Their support is gratefully acknowledged. .\" .TH vcr 1 "5 Nov 1995" .de HD .sp 1.5 .B .. .SH NAME MBone vcr \- MBone Video Conference Recorder .SH SYNOPSIS .na .B vcr [ .B \-c[md] .I command_file ] [ .B \-d[isplay] .I display ] [ .B \-h[elp] ] [ .B \-i .I init_file ] [ .B \-v ] [ .B [\-s] .I session_file[.vcr] ] .br .SH DESCRIPTION .LP .I MBone VCR is an X-based video conference recorder for the MBone tools. MBone VCR provides functions to record and play back MBone sessions with multiple multicast multimedia data streams from different applications at various locations. Recording is done by receiving data from other MBone applications over the network, playback is done by sending the, possibly transformed, previously recorded data back over the network to the applications. A session recorded by VCR can virtually consist of as many multicast channels as a user desires to record. During recording, the MBone VCR will synchronize these time-critical data streams based on information provided by protocols such as RTP (the Real Time Transport Protocol). The MBone VCR does not need to know which particular application originates a data stream or what the exact content of the data stream is; it suffices that the data stream conforms to one of the supported protocols. To play back a recorded session, MBone VCR sends the data, possibly transformed (e.g. for double speed), out to the network, recovering the original timing and synchronization of all the media streams included in this session and using the same network protocols used by the applications from which the data was recorded. Therefore users run these application in order to watch and/or listen to the data played back by the MBone VCR. With this approach, we achieve three important things: (1) independence from application specific details, (2) use of already invented and implemented technology for playback and (3) off-line teleconferencing support since sessions can be recorded and sent out at a later time reaching audiences in various time zones. During playbacks, the users of the MBone VCR can, among other things, change the MBone scope, thus making it possible to reach either a larger or smaller audience depending on the actual intention of the "re-multicast". .SH OPTIONS .TP .B \-c[md] read the command file .I command_file which contains vcr macro commands and execute them sequentially (see below for details about vcr macro commands) .TP .B \-h[elp] get a help screen .TP .B \-i use .I init_file instead of ~/.vcr.tcl as vcr's initialization file .TP .B \-v show version number .TP .B [\-s] load the session specified by the session file .I session_file .SH OPERATION The main vcr window tries to imitate the look of a home vcr. The left area of the main window gives some status information about the loaded session whereas the right area provides a session clock and buttons to control the session. .HD Load a session .LP If no session is loaded, "No session" is displayed in the status area of the vcr window and the media list (below) is empty. To open an existing session one can either use the "Open Session..." entry in the "Session" menu or double click on the "No Session" label. .HD Import a session from the Session Directory .LP This is probably the easiest way to get started. If you have sd running, it creates a file .sd_cache in your home directory (you might need to quit and restart sd in order to get an updated version of .sd_cache). The MBone VCR can read and interpret this file and create a vcr-session out of it. Just click on "Import SD Session" in the "Session" menu and Choose from one of the sessions. VCR will ask you for a filename after you have choosen a session (it creates a default filename out of the session name so you might just want to select an apropriate directory). Click Ok and you are ready to record this session. Since the sessions in sd often only include one media, you might need to edit the session to add more media from sd-sessions to your vcr-session (see below for more information). .HD Create a session .LP To create a new (empty) session a user can either use the "New Session..." entry in the "Session" menu or double click in the empty media list below the "No session" label. .LP If you create a session "by hand" a session name and an optional session description have to be specified in the "New Session" window. The "Max Scope" defines the maximum scope for all media included in this session. To add a new media to the session click on the "Add Media" button. In the "Add Media" window a media name and an optional media description as well as the multicast address, the port number, the conference id (only needed for RTPv1 and VAT), the protocol (RTP or VAT) and the scope for this media need to be specified. Optional you can specify a media command which will be used by the "Start Session Tools" function in the "Tools" menu to start the appropriate application for this media. The tcl procedures how2start_ will add the needed parameters. These procedures can be modified and overwrite the default procedures if put in the ~/.vcr.tcl file in your home directory. At the end a session file name (which has to end with ".vcr") has to be given to the session. Clicking on the "Session Filename" button will open a file selection box to choose a directory and/or filename. .HD Import multiple sessions from the Session Directory .LP With the "Import Session from SD" entry in the "Session" menu one can only import a single sd session. Sometimes, however, media that belong to one session are announced in different sd-sessions. To be able to record such sessions and rather than creating a vcr-session "by hand", one can use the "Import Session from SD" button in the "New Session" window to compose your vcr-session out of one or more sd-sessions. In the "Import Session from SD" window you will get two lists, a session list and a media list. These lists include all the sessions and media found in your ~/.sd_cache file. The media list always displays the media of the selected session. If you select a different session, the media list will be updated automatically. You can import an entire sd session (which is a session title, a session description, a generated session filename and all media supported by vcr) by clicking on the "Get Session" button or double clicking on a session entry in the session list. You can also only import a session title (together with a session description and a generated session filename) with the "Get Title" button (or by double clicking with mouse button 2 on a session entry in the session list). Another possibility is to add one or more media from sd-sessions to your existing vcr-session. To do this, you can select a media in the media list and then click on the "Add Media" button (or just double click on a media entry in the media list). .HD Edit a session or media .LP After a session is loaded/created, the session name and a list of media is displayed in the status area. Double clicking on the session name will have the same effect as the "Edit Session..." entry in the "Session" menu. Double clicking on one of the media in the media list will have the same effect as the "Edit Media" button in the "Edit Session" window. .HD Mute a media .LP A single click with the left mouse button in the media list will select a media so it can be muted/unmuted with the "mute/unmute" button below the media list. If the media is muted, it is shown as "" instead of "media". If more than one media is selected, the "mute/unmute" button will toggle the mute state for all selected media according to their mute state. Clicking on a media entry with the middle mouse button will toggle its mute state, clicking in the media list with the right mouse button will unselect all selected media. .HD Random access with the session slider .LP The slider on the very bottom enables random access within the session. Clicking with the middle mouse button somewhere in the slider will forward or rewind the session to this point. Clicking the left mouse button on the slider left from the marker will rewind the session one second, clicking the left mouse button right from the marker will forward the session one second. At the lower right corner the total length of the session is displayed. Clicking in this field will forward to the end of the session. .HD Record a session .LP To record a session, you need to enable recording with the "Enable Recording" entry in the "Record" menu. By default, MBone VCR does not start to record before it doesn't receive a data signal from any of the media in the session. To start recording even when no data is present, select the ¨Start recording without signal" checkbutton in the "Record menu". To start recording click on the "record" button (third button from the left). Click the "stop" button (fourth button from the left) to stop the recording. In a non-empty session you can only append data so you have to go to the very end to continue recording. .LP .B Note: In order to record your own signal, some tools require that the MBone VCR runs on a different host than these tools since they do .B not do local loopback of the multicast data (e.g. vat and vic). Therefore the "Start Session Tools" window from the "Session" menu offers a entry field "Start tools on host" that will start the tools with an rsh command on the specified host. Note that it is required that your ~/.rhosts file allows such operations. Given that the MBone VCR runs on a remote host .I b with the display redirected to your local workstation .I a you had to specify .I a in the "Start tools on host" entry field in order to run the session tools on your local workstation. .LP Since MBone VCR .B does local loopback, you do not need to run it on a different host than the session tools if you only want to play a session back. In this case you could set the scope to 0 (host) so you won't send out any data to the network. .LP The "Stop Session Tools" entry in the tools menu will allow you to stop the started tools. It will look for the processes in the process table (regardless whether they were startet on the local or a remote host) and if they still run, it will send them a kill signal to stop. .HD Play a session .LP To play a session back you simply click on the "play" button (third button from the right). In order to listen and/or watch the data you need to run the corresponding MBone tools. These can be launched directly from within the MBone VCR with the "Start Session Tools" window in the "Tools" menu. If the option "Autostart Session Tools" in the "Tools" menu is selected, the "Start Session Tools" window will automatically appear when the user plays a session for the first time. .HD Playing at various speeds .LP To change the playback speed you can select "double speed" or "half speed" in the "Speed" menu. Note that this feature is not available for all data formats. If a format is not supported, you might mute the media to listen/watch at least the other media at double/half speed. .HD Fast forward and rewind .LP To fast forward (ff) or rewind (rew) a session you can click on the "ff" button (second from the left) or the "rew" button (second from the right). The speed with which the session will be forwarded/rewound can be changed with the "FF/REW factor .." entry in the "Options" menu. .HD Loop Mode .LP If the "Loop Mode" entry in the "Options" menu is checked during playback, the session will start all over from the beginning if it hits the end. This feature allows to continuously transmit a session. .HD Indices .LP The MBone VCR provides a number of different indices. .B Note: Indices are always media specific so you have to specify an index media with the "Idxmedia" menu on which the index functions are performed. You can always change this media but you won't see indices set on one media if you have selected another. .LP Basically there are two categories of indices: .I automatically generated indices (AGI) and .I user defined indices (UDI) . AGIs are automatically generated by MBone VCR during recording. Examples for AGIs are "next speaker", "next sync unit" or "new format". UDIs can be set by the user either during recording or afterwards. There are five levels of UDIs so a user can use different levels for different purposes. To get/set/delete indices you can use the "Index Control Panel" by clicking on "Toggle indexcontrolpanel". The "Idxmode" menu will change the behavior of the leftmost and the rightmost button in the main window so you can select which function these buttons actually perform. .HD Blank Skip / Auto Blank Skip .LP One of the options in the "Idxmode" menu is "blank skip". This feature will skip blank gaps of the specified length in the media selected by the "Idxmedia" menu and forward the session to the beginning of the next data. "Blank Skip" and "Auto Blank Skip" are basically the same the only difference is that during playback "Auto Blank Skip" will automatically detect and skip blank areas in the media selected by "Idxmedia". .SH "VCR MACRO COMMANDS" The vcr macro commands provide limited control to record and playback sessions during off-hours or to write macros for demo purposes. The supported commands are: .LP .B load .I session_file .LP .B unload .LP .B play .LP .B rec .LP .B ff .LP .B rew .LP .B stop .LP .B at [ .I HH:MM:SS [ .I MM/DD/YY ] ] .LP .B wait .I [[[HH:]MM:]SS] .LP .B speed [ .I normal | .I double | .I half ] .LP .B goto [ .I end | .I start | .I secs ] [ .I next_index [ .I idx ] ] [ .I prev_index [ .I idx ] ] [ .I next_blank [ .I ms ] ] [ .I prev_blank [ .I ms ] ] | .LP .B mute [ .I media_nb (0 ... nb_of_media-1) ] .LP .B auto_start [ .I on|off ] .LP .B blink [ .I on|off ] .LP .B idx_media [ .I media_nb ] .LP .B auto_blank [ .I ms ] .LP .B loop [ .I on|off ] .LP .B rec_enabled [ .I on|off ] .LP .B start_rec [ .I on_signal|no_signal ] .LP .B ff_rew_factor [ .I value ] .LP .B start_tools .LP .B stop_tools .LP .B # .I Comments .LP These commands can be used in a command file passed to the vcr applications by the "-c" commandline parameter. A macro file can also be read with the "Run Macro File" entry in the "Macro" menu. The commands will be executed sequentially, a "wait" command will wait for hh:mm:ss until the next command is read, an at command (if not too late) will wait until the specified time/date. An example for playback could look like this: .LP # load a demo session (recorded earlier) .br load ~/vcr-data/demo.vcr .br # goto position 10 min. .br goto 600 .br # start playing .br play .br # play for 5 min. .br wait 5:00 .br # stop playing .br stop .LP The macro commands can also be used to automatically start recordings at a specific time/date as in: .LP # load a demo session (created earlier) .br load ~/vcr-data/demo.vcr .br # start the session tools .br start_tools .br # goto end (recording is only allowed at the end!) .br goto end .br # enable recording .br rec_enabled on .br # start recording at 1:45pm on May 20th 1995 .br at 13:45:00 05/20/95 .br # start recording .br rec .br # record for 1 hour and 30 mins. .br wait 1:30:00 .br # stop recording .br stop .br # close the session tools .br stop_tools .br # quit the MBone VCR .br quit .LP Or another example could be to playback sessions of a conference recording at a specific time/date as in: .LP # no loop mode .br loop off .br # start playing at 12.00pm on May 20th 1995 .br at 12:00:00 05/20/95 .br # load conf1 session .br load ~/vcr-data/conf1.vcr .br # start playing .br play .br # play for 1.5 hours .br wait 01:30:00 .br # stop playing .br stop .br # unload conf1 .br unload .br # start playing at 2.00pm on May 20th 1995 .br at 14:00:00 05/20/95 .br # load conf2 session .br load ~/vcr-data/conf2.vcr .br # start playing .br play .br # play for 1.5 hours .br wait 01:30:00 .br # stop playing .br stop .br # quit vcr .br quit .LP For example, this macro could be stored in a file conf1-2.cmd and than executed by running: .LP .B vcr -c conf1-2.cmd .br .SH "VCR File Format" The MBone VCR uses the following file format: .br The session is specified in a .B session file that ends in .B .vcr and contains a description of the session, the included media and all the parameters in plain ASCII. .br VCR generates two files per media in the same directory the session file is stored. These files are: .br An .B index file that ends in .B .idx and a .B data file that ends in .B .rec The filenames for these files are automatically generated out of the session filename, the media protocol and the media number. For example, given that a session stored in the session file .B demo.vcr consists of one media which uses RTP as its protocol, then the automatically generated media files would be: .B demo_rtp_1.idx and .B demo_rtp_1.rec .LP The content of the .B .rec file would be the raw data dumped into the file as it was received from the network. The .B .idx file contained one fixed-length header per data packet which holds a mapped timestamp generated from information of the data timestamp, index information, channel information (e.g. data/session port) and an offset to the corresponding data packet in the .B .rec file. .LP The index header structure is defined as: .LP typedef struct VCR_Index { .br uint32 timestamp; .br uint32 offset; .br uint16 length; .br uint8 channel; .br uint8 index; .br }; .br .LP For implementation details of the VCR file format see .I VCRFile.h and .I VCRFile.cc in the MBone VCR source distribution. .SH "FILES" .B $HOME/.vcr.tcl .br vcr tcl startup file; read at beginning of execution. .LP .B $HOME/.vcr.cmd .br vcr cmd startup file; read at beginning of execution. .SH "SEE ALSO" ivs(1), nv(1), vat(1), vic(1) .LP Schulzrinne, Casner, Frederick, Jacobson, .br ``RTP: A Transport Protocol for Real-Time Applications'', .br Internet Draft, available at URL ftp://ftp.isi.edu/internet-drafts/draft-ietf-avt-rtp-* .LP .I ivs is available at URL: .br ftp://avahi.inria.fr/pub/videoconference/ .br .I nv is available at URL: .br ftp://ftp.parc.xerox.com/pub/net-research/ .br .I vat is available at URL: .br ftp://ftp.ee.lbl.gov/conferencing/vat/ .br .I vic is available at URL: .br ftp://ftp.ee.lbl.gov/conferencing/vic/ .br .SH ACKNOWLEDGMENTS .LP The .I MBone VCR was developed during a 15 months stay at the International Computer Science Institute (ICSI) in Berkeley, California. Thanks to the German Academic Exchange Service that provided the financial support for this stay and to ICSI that provided such a productive and well organized infrastructure. Without all this, the development would not have been possible. .LP The initial idea for the .I MBone VCR was born during the definition of a teleseminar application scenario in the Bay Area Gigabit Network (BAGNet) project (see URL: http://icsi.berkeley.edu/BAGNet for details). To implement this teleseminar facility, the testbed used the existing MBone tools over an ATM network. However, the project participants have also seen a need to record, store and playback these seminars and since there was no tool available that could fully satisfy these needs, the idea of the MBone VCR was born. I'd like to thank the BAGNet research community for their valuable input and help during the development of this tool. .LP Many thanks to all members of the Tenet group at ICSI. The numerous online and offline discussions with all of them were very helpful. .LP Special thanks to Van Jacobsen (van@ee.lbl.gov) and Steve McCanne (mccanne@ee.lbl.gov) for their input during the design phase and all the tips and tricks during the implementation. .LP Last but not least very special thanks to my supervisors Domenico Ferrari (ferrari@icsi.berkeley.edu) and Andres Albanese (aa@icsi.berkeley.edu). Their trust and support always gave me the needed motivation. .LP .SH AUTHOR Wieland Holfelder (whd@icsi.berkeley.edu) .br Tenet Group .br International Computer Science Institute, Berkeley, CA .br and University of California at Berkeley .SH "BUG REPORTS" Please send bug reports, suggestions, comments or other feedback to: .br .B mbone-vcr@icsi.berkeley.edu .br .I Thank you for your cooperation. .SH "KNOWN BUGS" RTP Sender Reports and RTP Receiver Reports not yet implemented. .br Double and half speed not yet supported for all data formats. .br It would be nice to replace reading session from ~/.sd_cache with a standardized protocol to the session directory tool (sd). .br Whiteboard (wb) not yet supported. .br No bandwith control during playback. .br VCR macro commands could be more sophisticated. .br Online vcr programming through the GUI desirable. .br Recording is only possible at the end of a session .