AccessGrid Video (Cassette) Recorder - AGVCR

It is written in C with GTK and compiles cleanly under Linux, Windows and Mac OS X. AGVCR simply records RTP and RTCP from any number of unicast or multicast streams (e.g. AccessGrid Audio and Video) together with minimal overhead of timing information and provides the ability to replay that conference to multicast or unicast addresses. Replayed conferences are almost indistinguishable from a live session*.

Playback can be to localhost and using VIC and RAT in a standalone manner from the AG toolkit, it is possible to record an AG meeting, save it to DVD with a copy of AGVCR (see here for a self-contained AGVCR GTK run-time) and hand it to someone to play back at their leisure.

Basic Feature list:

• Simple, easy-to-use interface with DVD or VCR-like operations (forward, skip, rewind, slow-mo, time-search)
• Single program executable (supporting GTK libraries needed, can be stand-alone)
• Record and play back to multicast or unicast network addresses
• Editing of files - make new files out of sections of another, i.e. dubbing.
• Participant list - see who was in a conference and filter recording, playing or editing down to each individual RTP source.
• Encryption - record secure venues and play back to them
• File compatibility between all platforms (Linux, Windows, Mac OS X). Record on one, play on all.
• Can be run without installation, from CD/DVD (using the standalone run-time support files).
• Telnet capable interface, for possible remote/server usage.
• Timer-recording/playback for unattended operation once configured.
• Integration with AccessGrid Venue Client via AGVCR Launcher.
• Windows installer and Mac .app bundle for easy deployment

AGVCR is released under the GNU General Public License (GPL).

• Installation
• Linux
• Windows
• Mac OS X
• Source installation (expert)
• AGVCR Launcher
• Configuring
• Recording
• Disk space
• Record - Paused
• Recording locally
• Recording unicast
• Playing
• Playback on one machine
• Editing
• Filtering
• Encryption
• Self Timers
• Command Line Options
• Mailing List
• Future / TO DO
• Reporting Bugs / Stability
• Using the debug options
• Packet logging
• Known issues
• NOTICE OF DISCLAIMER

AGVCR requires at least GTK 2.6. For binary packages, you must have GTK libraries of at least the version AGVCR was built against. Normally this is taken care of for you by the Windows installer and the Mac bundle.

dpkg -i agvcr_2.2.1_i386.deb 

# AGVCR
deb http://iri.informatics.indiana.edu/~dcpiper/agvcr/debian ./
deb-src http://iri.informatics.indiana.edu/~dcpiper/agvcr/debian ./

rpm -i agvcr-2.2.1-1.i386.rpm 

These source installation instructions are intended for those that have experience compiling software for their machine. Most users will want to skip past this point. If installing via source please note that I am unlikely to be able to offer much by way of support. If you feel things SHOULD work, i.e. you have the version of the GTK development libraries installed that should work but are running into problems you are welcome to drop me a line about it.

tar -zxvf agvcr-2.2.1.tar.gz 
cd agvcr-2.2.1 
./configure
make
make install (to install under /usr/local/bin)

tar -zxvf agvcr-2.2.1.tar.gz 
cd agvcr-2.2.1 
./setup-windows
make

tar -zxvf agvcr-2.2.1.tar.gz 
cd agvcr-2.2.1 
./configure
make
make install (to install under /usr/local/bin)

AGVCR Launcher is a Shared Application for the AccessGrid toolkit. It is a Python program that runs and configures AGVCR from an AccessGrid Virtual Venue. It installs in the same way as all AccessGrid Shared Applications. If you downloaded and installed the Windows installer above then you do not need to perform this step of registering/installing AGVCR_Launcher, it has already been done for you.

AG 2.4

agpm.py -z AGVCR_Launcher1.2.zip

AG 3.x

runag3.py agpm3.py -z AGVCR_Launcher1.2.zip

Mac OS X

cd /Applications/AccessGridToolkit.app/Contents/Resources/bin/
pythonw agpm.py -z AGVCR_Launcher1.2.zip

If you want to have an installation of AGVCR that is accessible from both versions (2 and 3) of AccessGrid that you have installed on your system then you can do so by setting the 'AGVCR_PATH' environment variable and point it to the directory where you installed/unpacked AGVCR and the standalone run-time (if needed). DO Include a trailing directory separator slash in the variable. This applies to all platforms.

Linux

If you have an executable of AGVCR in the PATH of the user that is running the Virtual Venue, you do not need to indicate its location using the AGVCR_PATH variable. The Debian and RedHat packages will place 'agvcr' in /usr/bin, which will be in your default PATH.

Windows

With the Windows installer, the AGVCR_PATH is already set for you.

Mac OS X

Use the 'Configure' dialog to choose the .app bundle of AGVCR instead of setting an environment variable. Be sure to pick the actual bundle file itself.

NOTE:When installing AGVCR_Launcher on AG2.4, use 'pythonw' at the start of the command line to 'agpm.py'

After installation is complete, you can open the Venue Client and add 'AGVCR Launcher' as a shared application. This application shares no data and only serves as a way to start AGVCR with the venue's stream information instead of entering it in manually. The filename will default to the name of the Virtual Venue plus the current date. Choose 'Configure' from the AGVCR Launcher Shared Application context menu to access the configuration dialog the first time you run it (right click on the AGVCR Launcher shared app). You will probably want to set the default directory for saving files that is passed to AGVCR when it starts. Once set, your copy of AGVCR Launcher will remember its local configuration and you can just double-click to launch AGVCR on any instance of the Shared Application.

When configuring AGVCR automatically from the Venue via this Shared Application is launched from it is only configured for that venue. If you change venues then you will need to initiate a new 'AGVCR Launcher' instance in the new venue and re-launch AGVCR for AGVCR's configuration to 'follow'. Once launched, AGVCR does not yet communicate with the Venue Client so it will not know when the venue changes.

The AGVCR interface consists of the menu bar, the connection and file information, participant list, the status indicator and the tabs for player, recorder and editing modes.

To configure the program, select 'Set Config' from the 'File' menu. See 'Setting the Configuration' for details.

To quickly change the current file, a file selector button is also placed on the main window for convenience. It operates in the same way as the one in the config dialog.

First of all you will need to obtain the IP addresses and ports for the AccessGrid Audio and Video streams, plus any other ancilliary streams that you wish to record also.

AccessGrid 2.x or 3.x

Go to the AccessGrid Venue that you wish to record. You do not need to wait for all participants to join but there must be audio and video streams active in the venue for the IP address to be allocated. In the 'Venue' menu, select 'Properties' to show the audio and video IP and ports, host and TTL (TTL is normally 127, which is what AGVCR defaults to).

You can also use the AGVCR Launcher to run and configure AGVCR automatically from an AccessGrid Virtual Venue.

AccessGrid 1.x, or other RTP/RTCP based meeting

Obtain the IP addresses and port numbers from VIC and RAT directly from the programs or contact the meeting holder.

Filling in the dialog

Making sure to get the correct IP/port associated with Audio and Video, enter the information into the configuration dialog (available under the File->Options menu item). If you happen to type the information in in the wrong order, simply change the selector for 'AG Audio' or 'AG Video'. It does not matter which way they are specified in the configuration.

You will need to set a file for recording or playback. Either type in a file (will be the local directory) or click on the file selector button.

To add more stream lines while editing, click the '+' button.

When you are done, click 'OK'.

Saving the configuration

To save the configuration information as a default, enter what information you'd like saved (e.g. encryption keys) and then select 'Save Config' from the 'File' menu of the main window.

The calibration information of the player is saved too when saving the configuration. It can be cleared by clicking the 'Clear Calibration Data' button. It is not recommended that calibration data be passed between machines.

Once configured, the program window should look something like this:

Recording a conference

Before recording any sort of meeting or conference, it is important to ask the consent of all those that will be recorded.

To record a conference, first make sure the configuration is set correctly. See 'Setting the Configuration'. Select the 'Record' tab.

When you are ready, click the 'Record' button to being recording data from the given streams. You will see in the top part of the window that the number of bytes received for each stream is given. You can pause recording at any time, however packets still need to be processed from the network as the connections are still kept active during 'paused' mode. As such, the stream indicators will continue to list bytes received even when the 'bytes recorded' is not increasing, since no data is being written to the file. Click 'pause' again to un-pause recording.

You can click the 'Add 30 minutes' button to optionally set an end time on the recording, similar to the 'One Touch Record' functionality of a VCR. You can click this button as many times as you like and it will extend the recording duration by 30 minutes each time. Click the 'Record indefinitely' button to clear the current Recording timer.

It is recommended that AGVCR record to disks/partitions with a large amount of free space that can be used for holding the recordings since they get large very quickly. It is difficult to judge just how much disk space a particular meeting will take.

While recording, the available disk space of the volume/partition that the current file is being written to is measured. The rate the file is being written to is worked out over an average and then an estimation is made on how long it is possible to record given that rate. It tends to fluctuate since the network traffic is never constant but an overall idea can be obtained on roughly how long there is before the recorder runs out of disk space.

If the recorder runs out of disk space before being able to properly 'close' the file, a corrupt file could result. So, if the available disk space reaches less than 20MB the recorder will automatically stop to preserve what was recorded.

If desired, you can click the 'pause' button on the record tab to enter 'Record - Paused' mode. While in this mode, the network connections will be read and packets parsed for participant information, but nothing will be written to the file. Select 'Record' or 'Pause' again to record data.

When you are finished recording, click stop. The AGVCR file will be closed and can then be copied if need be.

It is possible to record yourself 'locally', i.e. just the audio and video from a single machine. The method is similar to the local playback method described below. Please see the FAQ for details.

When having to record from unicast connections, i.e. using a bridge because of a failure in the multicast, it is important to remember that only AGVCR can be running since only one application can listen to receive data from the same port. This is due to the way the bridge sends data to a client machine and is not a fault in AGVCR. In order to account for this it is recommended that AGVCR be installed on a separate machine from the one normally used for participating in an AccessGrid session.

Please note that only AGVCR recorded files can be played back through AGVCR.

Configure the player in the same way as before for recording. i.e. multicast addresses and ports to play to and select the AGVCR file that you wish played. Select 'OK' on the configuration dialog and then select the 'Play' tab. The configured streams and the file have to match in order to be played back successfully. Stream type information is embedded in the file to help keep track of the type of connection used when the recording was played.

When ready, click the 'Play' button to begin playback of the file. While playing, you can click on any of the playback buttons to pause/fast forward,rewind etc.

The 'Seek' slider lets you set a percentage to move to within the file and then click 'Go' to have the player seek to that position in the file and resume playback.

The 'Jump to Time' box allows you to enter a time counting from zero when the recording was started in HH:MM:SS.MSECS format. You can use this to jump to an event in the file a certain known time after the recording was started. Click the 'Go' button after setting the time.

To play back a recording on one machine, a copy of VIC and RAT need to be available with the command path or local directory that AGVCR is run.

You may launch VIC and RAT while AGVCR is running by clicking on the 'launch stream apps' button represented by the 'rocket' icon. The applications will be started against the currently configured streams. If you change the configuration of the streams, you must manually close the applications yourself. Management and increased control of the launched applications will be in a later release.

To launch VIC and RAT when starting AGVCR, use the -x switch like so:

agvcr -a myhost/myaudioport -v myhost/myvideoport -x -f <file>

or

agvcr -x -f <file>

If using this mode '-x' with no audio and video host/port, defaults of localhost ports will be set. If you are choosing your own though, just be sure to use port numbers with a difference of at least 2. See 'Command Line Options' for more information. Using the default localhost address will work on any machine, so it's suitable for putting into shell or batch scripts. i.e. to distribute a recording on a DVD-R with a simple 'click here to play' icon.

For more information on making a CD/DVD, see the relevant FAQ entry.

To obtain VIC and RAT executables separately from the AccessGrid software, as well as the standalone GTK runtime for AGVCR, please see the downloads section.

AGVCR can edit previously recorded files into new files.

For editing, only the file name needs to be specified in the configuration dialog. When a filename is set, an edit output filename will automatically be generated, i.e. if 'myfile' was set, then the editing output filename would be 'myfile-2'.

You can specify start and end times either by clicking on the 'set mark' buttons during playback or by entering a specific time (to the millisecond) where the start and end points of the new recording should be. A time of 00:00:00.000 indicates either the start or the end of the file, depending on which time it is referring to.

e.g. From Time: 00:00:23.000 To Time: 00:00:00.000 will output everything in the original file after 23 seconds from its start.

e.g. From Time: 00:00:00.000 To Time: 00:01:00.000 will output everything in the original file up to 1 minute.

e.g. From Time: 00:01:00.000 To Time: 00:01:45.000 will output everything in the original file between 1 minute to 1 minute 45 seconds in the original recording, the resulting file will be 45 seconds long.

Once you are ready to process the file, click the 'Process Edit' button and you will be presented with the 'Filter' dialog (see below) to select what streams to include. Once you click 'Ok' the new file will be generated from the old one. Leaving the start and end times at 00:00:00.000 will process the entire file from start to finish, giving a duplicate of the original and leaving the original start time intact. Note that if encryption (see below) is enabled then the MD5 of the resultant file will differ from the original, this is due to the randomization of the encryption algorithm since the original file is decrypted with the main File Key but the output file is re-encrypted with the Output File Key.

Start times for recorded files are altered too, so a file recorded at 3:15pm for 5 minutes and then edited into a file starting from 1 minute into it would show as its start time 3:16, since that's when the actual events portrayed took place.

AGVCR is able to filter any packet stream (audio, video etc.) to remove a source from the output data. This filtering is available in all 3 modes - Recording, Playing or Editing.

As a default, all participants and their sources are enabled. These can be seen in the participant window on the right hand side of the interface. By checking or un-checking the relevant boxes you can affect whether the stream is allowed through or not. For recording, this affects whether the selected stream is recorded to the file or not. In playback, it determines whether the stream is output on this particular play of the file. No preferences are saved with a file for what streams should be active or not.

It is possible to change how sources are enabled by changing the 'New Sources:' option in the configuration dialog:

• Manually Enabled - AGVCR will only enable the source once you click its checkbox
• Only Enable When Categorized - AGVCR will only enable the source if a NAME SDES field is received and the entry is categorized (visible) in the participant window.
• Always Enabled (even if not on list) - AGVCR will always enable the new source upon receiving the first RTP packet. This is the default behavior.

To make permanent changes, you can edit the file too. As mentioned in the editing section a dialog is presented to allow stream selection for the output file.

Then you can click on any participant or source just like you can in the main window to adjust what will be output.

Once done, click 'Ok' to use your selection.

If, from the selection, a particular packet stream will have no sources then it will be removed from the output file altogether as if it was never recorded. i.e. if you only selected to output 'AG Audio' streams then the output file will ONLY have an 'AG Audio' stream type in it, allowing it to be played without having to specify an 'AG Video' network source. This is useful if the recording has some ancilliary streams such as MLB, ScreenStreamer etc. that are not wanted in a recording you want to hand to someone.

Note that if the 'Strip uncategorized sources?' checkbox is enabled then a source that does not appear on the participant list but has been seen as a source will be removed from the output recording.

AGVCR supports encryption for recording from secure venues and also playing any AGVCR file back to a secure venue. Encryption is supported on AG Audio and AG Video streams only at this time and is designed to be compatible with the encryption algorithms and methods in VIC and RAT. To use encryption, start AGVCR in the same way you would normally. In keeping with VIC and RAT, the key is specified as a single string. A blank string disables encryption for the relevant section, Network or File.

To specify DES encryption, the string should be any non-blank string.

AccessGrid 2.x Venues typically pass a Rijndael key string. It looks like 'Rijndael/key' where 'key' is what is used in the actual encryption or decryption.

AGVCR uses two keys, a 'Network Key' and a 'File Key'. These control both encryption and decryption with either the network data or file data respectively.

Network Key

Specify this to AGVCR in the same way it is passed to VIC and RAT, i.e. the whole keystring. It is possible to set the key within the AGVCR config by opening VIC's menu, selecting and copying the key string and pasting it into the 'Network Key' section of the AGVCR configuration dialog, or just type it in yourself.

It should be obvious, but the Network Key string MUST be exactly the same as that in all participant VIC and RAT instances that are supposed to be recorded or receive playback. Please pay attention to the spelling of 'Rijndael'.

Once enabled, this Network Key will be used to decrypt data from the network and encrypt data sent to the network.

File Key

The other key entry, the 'File Key' is for encrypting and decrypting data to and from the file. It is specified in the same way as the Network Key (except place it in the 'File Key' section of the config dialog). The File Key can be the same as the Network Key, or it can be different or left blank.

Once enabled, this File Key will be used to decrypt data read from the file and encrypt data written to the file.

The Output File Key on the Editor tab is for whether the output from the editor will be encrypted or not. As a default the key will be the same as the input file. It is of course possible to encrypt a previously non-encrypted file by just entering in an encryption key into this box. Conversely it is possible to remove encryption from a file by making sure the box is blank before starting the editor.

See Command Line Options for details on how to specify these keys on the command line.

To use the self-timers, select 'Self-Timers' from the File menu.

Click the 'Add' button to open an empty dialog or 'Add From Main' to open the dialog but populate it with information from the main configuration (if any exists).

The timer configuration dialog is similar to the main configuration except that it adds two fields for start and end time in MM/DD/YYYY HH:MM:SS format.

For obvious reasons, the start time must be in the future, and the end time must be later than the start time.

Once you are happy with the timer's configuration, click 'Ok'

The timer is ready and will execute the appropriate function at the required time. Please note, if recording the filename indicated by the timer program will be overwritten without warning. This is to prevent the program 'hanging' waiting on user input should the file exist already.

To save the timers for later, if you want to close AGVCR, please make sure to select 'Save Config' from the 'File' menu.

It is possible to configure and use the program from the command line too. Here is a list of the accepted command line arguments and their usage.

Usage: agvcr [options]
Options:
  --audio|-a <host>/<port>/[ttl]        Add an AG Audio source at host/port/ttl
        e.g. 224.0.0.2/54321/127 (ttl optional)
  --video|-v <host>/<port>/[ttl]        Add an AG Video source at host/port/ttl
        e.g. 224.0.0.2/55555/127 (ttl optional)
  --src|-s <type>/<host>/<port>[/ttl]   add a <type> source at host/port/ttl
        e.g. mlb/224.0.0.2/50000/127 (ttl optional)
        where <type> is one of: audio video mlb screenstreamer dvts
  --file|-f <file>                      Filename record to or play from
  --play|-p                             Automatically start playing on startup
  --record|-r                           Automatically start recording on startup
  --no-calibration|-n                   Do not calibrate the player
  --loop|-l <times>                     Number of loops to play a file back
        0 = loop continuously
  --control[=port]                      Enable TCP remote control, optionally specify port to listen on (default is 11272).
                                        Must be greater than 1024.
  --launch-stream-apps|-x               Launch stream apps (such as VIC and RAT) at the configured host/ports on startup
                                        (if no hosts are specified, a localhost default will be used)
  --network-key <key>                   Set key for encrypting/decrypting network traffic to <key>
  --file-key <key>                      Set key for encrypting/decrypting file data to <key>
  --key|-k <key>                        Set both network and file keys to <key>
  --config|-c <config>                  Config file to use.
        Default config search order:
                Current directory: .agvcr.conf
                User's home directory: /home/dcpiper/.agvcr.conf
                System directory: /etc/agvcr.conf
  --no-gui                              Do not enable the GTK interface. It will, by definition, enable the TCP control port.
  --log <log file>                      Set main log file to <log file>
  --log-bad-packets[=log file]          Log all bad packets, optionally to specified [log file]
  --log-incoming-packets[=log file]     Log all incoming packets, optionally to specified [log file]
  --log-outgoing-packets[=log file]     Log all outgoing packets, optionally to specified [log file]
  --debug|-d                            Set some initial debug flags that are useful on startup
  --help|-h                             This help screen

Setting the Audio and Video from Command Line Options will default them in the configuration dialog. They are still free to be changed after the program has loaded. TTL is optional and defaults to 127 if not specified. Using -x will start a copy of VIC and RAT, providing they are in your command path or current directory where you run AGVCR from.

There is a mailing list for AGVCR so that people can keep up to date on announcements of new versions. I am also interested in having the list for suggestions or discussions of new features. Bug reports may be sent to the list also so that other users are aware of it (if it turns out to be a bug).

How to Subscribe

You can subscribe to the AGVCR mailing list by sending an email message to with "Subscribe AGVCR-L" in the body of the message.

How to Unsubscribe

If so some reason you want to unsubscribe from the AGVCR mailing list (I really recommend everyone that uses AGVCR be on the list!) you can do so by sending an email message to with "Unsubscribe AGVCR-L" in the body of the message.

Future ideas and improvements for AGVCR include:

Definite (it's on the TODO list):

• Editing: 'crop' a section from a file.
• Editing: optionally output single video and audio streams switched by talking participant.
• AGVCR Launcher needs to correctly find out unicast addresses
• IPV6 support

Possible (It's been noted and I'll consider it, probably after the above list is taken care of):

• 'Remote control' app for operating a remote AGVCR
• Audio silence detection (don't play or record silent audio)
• Conversion of recordings into MPEG movies
• Splicing recordings together
• 'Announce' via RTCP that AGVCR is running.
• VIC window placements (?)

AGVCR is a project in development, but current releases of AGVCR should be at acceptable levels of stability for most users. New features are often being added which may break things, but I do perform testing to hopefully minimize this. Changes and bugfixes will be noted within the 'News' section.

Please check back on this website before testing or using the program to make sure you're using the latest version out there. If I find any show-stopper bugs I will endeavor to either mention it as a known issue or to just get a fix out there. Major bugs/fixes will have the version number changed. If it's something minor, a version may be re-released with the fix even though the version number hasn't changed. Check the filename dates on the downloads.

AGVCR has debugging options available that will help in tracking down the source of a problem. Go to the 'Help' menu and select the 'Debugging' entry.

The debug options dialog is a list of options with checkboxes next to them to select what facility is enabled. It is not recommended that you simply activate all options since the level of output would be immense. Instead, it is preferred that only the appropriate area be enabled, i.e. if the problem occured when reading from the file, you would select the 'file' facility and possibly 'vcrpacket'. I don't expect people to debug things by themselves so if you report a problem I will give advice on what options to set to re-try your issue and then send the resulting log file to me so I can hopefully gain a better understanding of what happened.

The debug log is called 'agvcr.log' and is placed in the system temporary directory. Under Linux and Mac OS X this is /tmp/, for Windows it is typically C:\Windows\Temp. The contents of the file are replaced every time the program is run. To change the default log file the --log parameter may be specified on the command line, or while the program is running you can change it from the debug options dialog. If specified on the command line, place it before the --debug flag so that debug information will not be written to the default log file before the --log parameter is processed.

Some debugging options are only useful if specified when the program is starting up, for example, processing of command-line arguments. You can get AGVCR to start debugging configuration file and command line argument settings by specifying a --debug or -d flag on the command line when starting the program. Note however that only arguments AFTER the --debug|-d flag will have debugging information shown, so specify it right after the executable file if that's what you want.

AGVCR supports logging of all packets, incoming or outgoing or just ones that failed validity checks, i.e. 'bad' packets. To enable these options you can specify the appropriate command line flags or by enabling them in the 'Packet Logging' tab of the debug options dialog. As with the main log file, once packet logging starts the contents of the file will be overwritten.

If you find a bug that isn't already a known issue, please do . Thanks!

If a problem is found in my testing, or reported by me, I will try and update this list to help others that might be experiencing it. I will then try and solve these issues as soon as possible.

• JPEG playback to VIC does not work (possibly it's problems with capture?)
• Encryption sometimes not stripped out of an edited file even when no key is set.
• Entering in a time when the host is in daylight savings time results in incorrect time.
• Offsetting the times by -1 hr is a workaround. Trying to get timezone able to be output and parsed.
• A 'Maximum number of source entries reached' message will occur with certain participants.
• Will investigate if it's bad packet data or a problem in the RTP/RTCP parser. - not seen for a long time? if no reports, I will drop this as an ongoing 'issue'.

The faculty, staff and students, affiliates and Trustees of Indiana University, herein referred to as 'The University', do not provide warranty of this software of any kind. Users of this software, herein referred to as the User, bear sole responsibility for its use. The University cannot be held liable for unauthorized recording of conferences, meetings, videos, sounds and images or any invasions of privacy that occur from the User using this software. It is up to the User to obtain any and all permissions from meeting participants before using this software.

So, ask permission from those that you're going to record before you record them. If they agree you may always ask them to re-state their acceptance of being recorded in the recording itself. That way you have a record of their acceptance.