How Recordings Work

This page explains how the recordings are fetched and managed by BigbluebuttonRails.

Overview

BigbluebuttonRails includes a model, a controller and views to deal with recordings.

A recording model belongs to a server (the BigbluebuttonServer from which the recording was fetched) and to a room (a BigbluebuttonRoom matched to be the room that generated this recording, see "Updating the recordings" below). The room doesn't need to belong to the same server the recording belongs to. So, for example, a recording can belong to room 1 and server 1 even if room 1 belongs to server 2.

Recordings are identified by recordid, an attribute generated by BigBlueButton using a hash of the meetingID that generated the recording plus a timestamp of when the recording was started. This recordid is guaranteed to be unique within a single instance of BigbluebuttonRails.

Recordings have other two important attributes worth mentioning: metadata and playback formats.

Metadata are objects of the model BigbluebuttonMetadata that store the metadata in the recording. A BigbluebuttonMetadata has basically a name and a content. The metadata for a recording is set when the meeting is created. This is why BigbluebuttonRooms now also have metadata, so that when a meeting is created BigbluebuttonRails can pass these metadata to BigBlueButton and make them available later on in the recordings fetched from the server. For more information see the create API call in BigBlueButton's documentation: https://code.google.com/p/bigbluebutton/wiki/API#Create_Meeting

Playback formats are objects of the model BigbluebuttonPlaybackFormat and have basically a type and a URL. The type is a name given to the playback type, such as presentation or slides. The URL is the address of the playback page the user should go to to play the recording. A recording can have multiple playback types, and the first one is assumed to be the default.

Updating the list of recordings

Using a background job

Updating the recordings can consume quite some time if your server has a lot of recordings, so it is recommended to run it periodically in the background. To do that, you can use the gem whenever (that uses cron underneath).

This gem provides a rake task to fetch the recordings from the webconference servers and update the application database. This task can be triggered from whenever/cron to update the entire recordings database.

The command below will fetch recordings for all servers and update the database with all recordings found:

rake bigbluebutton_rails:recordings:update

To set up whenever, first add it to your application Gemfile:

gem 'whenever', :require => false

When you ran the generator :install previously, it created a file at config/schedule.rb inside your application. This file is used to configure whenever. Once this file is in place, running the following command will update your cron tab to update the recordings periodically.

whenever --update-crontab

Check out whenever to learn more about it.

Using the controllers

Another way to update the recordings is using the actions provided in the controllers. The controllers for servers and rooms have an action called fetch_recordings that will fetch all the recordings in that server or in for that room (calling a getRecordings) and synchronize the recordings database.

These actions are available in links in the views and can be called at any time, but it is not recommended to make the one in the servers controller available to the normal user, since its execution might take quite some time to complete and usually you wouldn't want a user to be triggering lots of demanding calls to your server. The links can be useful for admins though, or even to dynamically update the recordings for a single room using the method in the rooms controller (that usually would be a lot faster than fetching all available recordings).

In this last case, consider that when the user loads the page that shows his recordings the application could trigger an ajax call to update the recording list for that single room. It's a matter of calling Bigbluebutton::RoomsController#fetch_recordings through an URL such as /bigbluebutton/rooms/room-1/fetch_recordings (via POST) and then re-rendering the list of recordings.

Matching recordings and rooms

When recordings are fetched from a webconference server we need a way to find out to which room they belong. The way BigbluebuttonRails does that is using metadata fields.

In short, when a room is created it generates a unique ID saved in its attribute uniqueid that will be passed as metadata when the a meeting is created. This unique ID will then be available in all the recordings, so we can use them to find out the room that generated the recording.

This unique ID is a random hash plus a timestamp, a value considered random enough to be always unique across multiple instances of BigbluebuttonRails. You can see how it is generated here: https://github.com/mconf/bigbluebutton_rails/blob/master/app/models/bigbluebutton_room.rb#L387

A thread about this has been posted to the bigbluebutton-dev mailing list. You can see in it a bit more information about why things are done like this: https://groups.google.com/d/msg/bigbluebutton-dev/Cz9zcPbRZfI/OWXT8gqpi2cJ

Available and unavailable recordings

When recordings are fetched from a server, they will only be added or updated in the database, but never removed.

Recordings that already exist in the database will be updated: all the attributes received will override the attributes in the database. Recordings that do not exist in the database will be included. And recordings that exist in the database but do not exist in the response given by the server (meaning that the recording existed in the server in the past but doesn't exist anymore) are marked as 'unavailable'.

Unavailable recordings is just a way to tell the user that the playback links are not available. This can be used by the application to show a message to the user or even hide the playback links.

Since recordings are never automatically removed from the database they can only be removed calling their destroy action explicitly. It is available in the views and can be made available to admins. Also, in the future BigbluebuttonRails might add a method to remove all unavailable recordings at once.

Important considerations

• When syncing recordings the old ones are not removed, only marked as unavailable.

• "If there are recordings with the same recordID in two different servers, what will happen when recordings are synchronised in the db? Currently the recordID of a recordings is unique, so probably only the first recording will be saved." For now, we assume that recordings will never have duplicated IDs. The ID is a hash (generated from the meetingID) plus a timestamp. To have duplicated recordIDs, two meetings have to start at the exact same time using the same meetingID in two different servers. Possible but very unlikely to happen.

• Unique IDs in rooms can possibly be duplicated in different instances of BigbluebuttonRails, even though it is really, really unlikely to happen. If it happens, rooms would share recordings even though they shouldn't. This can be solved by modifying the uniqueid of one of the rooms and modifying also the metadata in the servers to match the new uniqueid.