• Prerequisites
• Overview
• Before you install
• Ensure records video and desktop session
• Install ffmpeg
• Install Ingest and Processing package for Matterhorn
• Configure the Matterhorn server to accept incoming files
• Generate a ssh public key
• Test SSH Connection
• About Matterhorn ingestion
• Your First Recording
• Troubleshooting
• Getting Help

Prerequisites

You need to have to have installed BigBlueButton 0.8. On a separate server (not the same server as BigBlueButton) install Matterhorn 1.1 , Matterhorn 1.2 or Matterhorn 1.3 (recommended).

Note: If you follow Matterhorn 1.2 installation steps, it will be a good idea to change the current checkout url (http://opencast.jira.com/svn/MH/tags/1.2.0/) by this tag http://opencast.jira.com/svn/MH/tags/1.2.1-rc1/. Matterhorn 1.2.1 has not been officially released but this tag fixes some problems with 3rd party source packages.

Overview

Matterhorn is an open source lecture capture and video management system for education. When integrated with Matterhorn (see instructions below), BigBlueButton can record video, desktop, and audio and send the files to Matterhorn for processing and playback.

From a technical point of view, in the BigBlueButton API, when you pass the parameter 'record=true' with create, BigBlueButton will create a session and record the slides, chat, audio, desktop, and webcam for later processing.

After the session finishes, the BigBlueButton server will run one (or more) ingest and processing scripts that will process the captured data into a format for playback.

The instructions below show you how to install and configure the Matterhorn ingest and processing scripts. When called by BigBlueButton, these scripts will create two video files: one with webcam + audio, the other for desktop sharing, along with an XML file (called dublin core) and bundle everything into a single zip file. It will then scp the zip file to your Matterhorn server for processing.

The Matterhorn ingest and processing will scale the resolution of the desktop video to 640x480 before sending to Matterhorn.

If you encounter any problems with these instructions, please post to bigbluebutton setup mailing list.

Before you install

You'll need to ensure your /etc/apt/sources.list has the multiverse enabled. If you get an error message such as libfaac-dev can't be found with the instructions below, see Dependencies not met.

Ensure BigBlueButton records video and desktop session

BigBlueButton uses two red5 applications -- bbb-video and bbb-deskshare -- to share video and desktop. In BigBlueButton 0.8-beta-4, these applications are configured to not record media by default (to reduce disk space usage).

To record video, edit /usr/share/red5/webapps/video/WEB-INF/red5-web.xml and set recordVideoStream to true.

         <bean id="web.handler" class="org.bigbluebutton.app.video.VideoApplication">
                <property name="recordVideoStream" value="true"/>
                <property name="eventRecordingService" ref="redisRecorder"/>
        </bean>

To record desktop sharing, edit /usr/share/red5/webapps/deskshare/WEB-INF/red5-web.xml and at line 41 set the value for constructor-arg to true.

  <bean id="streamManager" class="org.bigbluebutton.deskshare.server.stream.StreamManager">
    <constructor-arg index="0" value="true"/>
    <constructor-arg index="1" ref="recordingService"/>
  </bean>

Install ffmpeg

To install ffmpeg, login to your BigBlueButton server with root access. Copy the following script and and save as a file install_ffmpeg.sh on your server

# install dependencies
sudo apt-get install build-essential git-core checkinstall yasm texi2html libfaac-dev libopencore-amrnb-dev libopencore-amrwb-dev libsdl1.2-dev libtheora-dev libvorbis-dev libx11-dev libxfixes-dev libxvidcore-dev zlib1g-dev

# Install x264
cd /usr/local/src
sudo git clone git://git.videolan.org/x264
cd /usr/local/src/x264
# Build from a certain commit so installs are consistent
sudo git checkout 392e762151d1657abc8ae5d345c144c3ef280819
sudo git checkout -b 392e762151d1657abc8ae5d345c144c3ef280819
sudo ./configure --enable-static
sudo make
sudo checkinstall --pkgname=x264 --default --pkgversion="3:$(./version.sh | awk -F'[" ]' '/POINT/{print $4"+git"$5}')" --backup=no --deldoc=yes

# Install LAME (optional)
sudo apt-get remove libmp3lame-dev
sudo apt-get install nasm
cd /usr/local/src
sudo wget http://downloads.sourceforge.net/project/lame/lame/3.98.4/lame-3.98.4.tar.gz
sudo tar xzvf lame-3.98.4.tar.gz
cd /usr/local/src/lame-3.98.4
sudo ./configure --enable-nasm --disable-shared
sudo make
sudo checkinstall --pkgname=lame-ffmpeg --pkgversion="3.98.4" --backup=no --default     --deldoc=yes

# Install FFMPEG
cd /usr/local/src
sudo git clone git://git.videolan.org/ffmpeg
cd /usr/local/src/ffmpeg
sudo git checkout n0.8.1
sudo git checkout -b n0.8.1
sudo ./configure --enable-gpl --enable-version3 --enable-nonfree --enable-postproc --enable-libfaac --enable-libopencore-amrnb --enable-libopencore-amrwb --enable-libtheora --enable-libvorbis --enable-libx264 --enable-libxvid --enable-x11grab --enable-libmp3lame
sudo make
sudo checkinstall --pkgname=ffmpeg --pkgversion="8:$(./version.sh)" --backup=no --deldoc=yes --default

hash x264 ffmpeg ffplay ffprobe
sudo make tools/qt-faststart
sudo checkinstall --pkgname=qt-faststart --pkgversion="$(./version.sh)" --backup=no --deldoc=yes --default install -D -m755 /usr/local/src/ffmpeg/tools/qt-faststart /usr/local/bin/qt-faststart

Run the script using the following commands

chmod +x install_ffmpeg.sh
./install_ffmpeg.sh

This script will take about thirty minutes to run, depending on your internet connection.

Install Ingest and Processing package for Matterhorn

   sudo apt-get install bbb-playback-matterhorn

Configure the Matterhorn server to accept incoming files

The ingest and processing scripts will use a public/private key to move files to the Matterhorn server.

Generate a ssh public key

This key will let BigBlueButton server send files to Matterhorn server without prompting a password. The example below uses the 'root' user on your Matterhorn server. If you have the matterhorn server running under a different account, such as matterhorn_user, use that account in the instructions below instead of the root account.

   ssh-keygen -t rsa

When it asks for a passphrase, just press enter (we don’t want to be prompted for a password). The public key will be generated in /home/firstuser/.ssh/id_rsa.pub.

Next, we'll copy the private key to the BigBlueButton scripts directory change it’s permissions to 600 (otherwise, the publish script will fail to push the recording to the Matterhorn server).

sudo cp ~/.ssh/id_rsa /usr/local/bigbluebutton/core/scripts/matt_id_rsa
sudo chmod 600 /usr/local/bigbluebutton/core/scripts/matt_id_rsa
sudo chown tomcat6:tomcat6 /usr/local/bigbluebutton/core/scripts/matt_id_rsa

Set configuration parameters about BigBlueButton-Matterhorn connection in /usr/local/bigbluebutton/core/scripts/matterhorn.yml

These parameters will be read during publish phase.

# The ip address of the matterhorn server.
server: 192.168.0.147
# The username we use to SCP the processed recording to matterhorn.
user: root
# The private key to use to SCP into matterhorn
key: /usr/local/bigbluebutton/core/scripts/matt_id_rsa
# The directory in the matterhorn server where the
# processed recording will be delivered for publishing to matterhorn.
# NOTE: Make sure that the directory is writeable by the above user.
inbox: /opt/matterhorn/felix/inbox/

In Matterhorn server

Create a directory for ssh keys

sudo mkdir /root/.ssh

Create a file for authorized keys (only if it does not exist)

sudo nano /root/.ssh/authorized_keys

Add the public key generated in BigBlueButton server to authorizes keys in Matterhorn server. Copy the content of the file /home/firstuser/.ssh/id_rsa.pub that is located in BigBlueButton server to /root/.ssh/authorized_keys in Matterhorn server

Test SSH Connection

You can do a small test for checking the ssh connection by running a remote command, for example you can use the ls command and list the files inside the matterhorn folder

sudo -su tomcat6 ssh -i /usr/local/bigbluebutton/core/scripts/matt_id_rsa  -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -o CheckHostIP=no root@192.168.0.147 'ls /opt/matterhorn/felix/'

Now ingestion should work during the publish phase.

About Matterhorn ingestion

• By default the directory where zipped packages are ingested in Matterhorn server is $FELIX_HOME/inbox

To change inbox directory, change the parameter felix.fileinstall.dir in /opt/matterhorn/1.1.0/docs/felix/load/org.apache.felix.fileinstall-inbox.cfg

• A zipped package is deleted from inbox after it is ingested

• If the zipped package sent from BigBlueButton is not a valid media package it is sent to ${org.opencastproject.storage.dir}/files/collection where org.opencastproject.storage.dir is a parameter configured in $FELIX_HOME/conf/config.properties

Your First Recording

Open the home page on the BigBlueButton server. For example:

   http://192.168.0.35/

Click "View API Examples". Click "Record (Matterhorn)". Fill out the entry for the meeting.

Create and Start the BigBlueButton Session. Now:

• Join to the voice conference
• Start the webcam
• Start desktop sharing

You must start all three, if you omit one then the recording will not be processed by BigBlueButton's matterhorn scripts.

When you are done presenting logout from the conference. After a couple of minutes the process and publish phase will start and it will send a zip file with the files necessary for matterhorn to process. You can check in the logs of matterhorn when the zip file is being processed:

After matterhorn finish processing the zip file, you will be able to reproduce the playback from the matterhorn server:

Troubleshooting

You can check the logs of recording in the bigbluebutton server: /var/log/bigbluebutton

Getting Help

If you have any problems not answered by this document, or you have questions/feedback/bugs, please post to bigbluebutton-setup.