Recording
This document assumes the reader understands the current BigBlueButton architecture.
Overview
BigBlueButton records all the events and media data generated during a BigBlueButton session for later playback.
If you want to see the Record and Playback (RaP) feature in action, use Greenlight on the demo server and record a session demo. You can then play it back after it is listed under "Recorded Sessions" on the same page. Processing and publishing the media for playback after the end of your session may take a few minutes.
Like BigBlueButton sessions, the management of recordings should be handled by third-party software. Third-party software consumes the BigBlueButton API to accomplish that. As a user, you may want to use third-party software which sets the right value to the parameter "record". As a developer, you may want to use a (not official) library that implements the API calls in your preferred language or implement it by yourself.
From a technical point of view, in the BigBlueButton API, when you pass the parameter record=true
with create, BigBlueButton will create a session that has recording enabled. In this case, it will add a new button to the toolbar at the top of the window with a circle icon which a moderator in the session can use to indicate sections of the meeting to be recorded.
In a session with recording enabled, BigBlueButton will save the slides, chat, audio, desktop sharing (deskshare), whiteboard events, shared notes, captions, poll results, and webcams for later processing. This is the unique way to record a meeting, because it provides the ability for different workflows to create recordings with different properties, combining the media in unique ways.
After the session finishes, the BigBlueButton server will run an archive script that copies all of the related files to a single directory. It then checks to see if the moderator has clicked the "Record" button during the session to indicate a section of the meeting that should be turned into a recording. If the recording button was not clicked during the session, the files are queued to be deleted after two weeks. (You can override this and force a recording to be processed; see the bbb-record --rebuild
command below.)
After the recording is archived, BigBlueButton will run one (or more) ingest and processing scripts, named workflows, that will process and publish the captured data into a format for playback.
![Record and Playback - Overview](/img/diagrams/Record and Playback Service Diagram-RAP - Overview.png)
Record and Playback Phases
BigBlueButton processes the recordings in the following order:
- Capture
- Archive
- Sanity
- Process
- Publish
- Playback
Capture
The Capture phase involves enabling the BigBlueButton modules (chat, presentation, video, voice, etc.) to emit events over an event bus for capture on the BigBlueButton server. Components that generate media (webcam, voice, deskshare) must also store their data streams on the server.
Whiteboard, cursor, chat and other events are stored on Redis. Webcam videos (.flv) and deskshare videos (.flv) are recorded by Red5. The audio conference file (.wav) is recorded by FreeSWITCH. Shared notes and captions are taken from Etherpad.
Archive
The Archive phase involves placing the captured media and events into a raw directory. That directory contains ALL the necessary media and files to work with.
![Record and Playback - Archive](/img/diagrams/Record and Playback Service Diagram-RAP - Archive.png)
Sanity
The Sanity phase involves checking that all the archived files are valid for processing. For example that media files have not zero length and events were archived.
![Record and Playback - Sanity](/img/diagrams/Record and Playback Service Diagram-RAP - Sanity.png)
Process
The Process phase involves processing the valid archived files of the recording according to the workflow (e.g., presentation). Usually, it involves parsing the archived events, converting media files to other formats or concatenating them, etc.
![Record and Playback - Process](/img/diagrams/Record and Playback Service Diagram-RAP - Process.png)
Publish
The Publish phase involves generating metadata and taking many or all the processed files and placing them in a directory exposed publicly for later playback.
![Record and Playback - Publish](/img/diagrams/Record and Playback Service Diagram-RAP - Publish.png)
Post-Scripts
Post-scripts allow you to perform site-specific actions after each of the Archive, Process, and Publish steps of the Recording processing.
Some examples of things you might use the post-scripts to do:
- Send you an email after a recording is published.
- Back up a recording to another server after your recording is archived or published.
- Send a text message after a recording is published.
- Compress media files and make them publicly available for download after it is published.
- Delete raw media files after the recording processing completes.
Playback
The Playback phase involves taking the published files (audio, webcam, deskshare, chat, events, notes, captions, polls, metadata) and playing them in the browser.
Using the workflow presentation, playback is handled by HTML, CSS, and Javascript libraries; it is fully available in Mozilla Firefox and Google Chrome (also in Android devices). In other browsers like Opera or Safari the playback will work without all its functionality, e.g., thumbnails won't be shown. There is not a unique video file for playback, there is not an available button or link to download the recording. We have opened an issue for this enhancement.
Media storage
Some Record and Playback phases store the media they handle in different directories:
Captured files
- AUDIO:
/var/freeswitch/meetings
- WEBCAM:
/var/lib/bbb-webrtc-recorder/recordings/<meetingid>
- SCREEN SHARING:
/var/lib/bbb-webrtc-recorder/screenshare/<meetingid>
- SLIDES:
/var/bigbluebutton/<meetingid>
- NOTES:
http://localhost:9002/p
- EVENTS:
Redis
Archived files
The archived file are located in /var/bigbluebutton/recording/raw/<internal-meeting-id>/
.
Sanity checked files
The sanity files are store in the same place as the archived files.
Processed files
The processed files can be found in /var/bigbluebutton/recording/process/presentation/<internal-meeting-id>/
.
Published files
The published files are in /var/bigbluebutton/recording/publish/presentation/<internal-meeting-id>/
.
Playback files
The playback files are found in /var/bigbluebutton/published/presentation/<internal-meeting-id>/
.
Manage recordings
BigBlueButton does not have an administrator web interface to control the sessions or recordings as in both cases they are handled by 3rd party software, but it has a useful tool to monitor the state and control your recordings through the phases described above.
In the terminal of your server you can execute bbb-record
, which will show you each option with its description:
BigBlueButton Recording Diagnostic Utility (BigBlueButton Version 2.5.N)
bbb-record [options]
Reporting:
--list List all recordings
--list-recent List recent recordings
--list-recent --withDesc List recent recordings and show their description
--list-workflows List available recording workflows
Monitoring:
--watch Watch processing of recordings
--watch --withDesc Watch processing of recordings and show their description
Administration:
--rebuild <internal meetingID> rebuild the output for the given internal meetingID
--rebuildall rebuild every recording
--delete <internal meetingID> delete one meeting and recording
--deleteall delete all meetings and recordings
--debug check for recording errors
--check check for configuration errors
--enable <workflow> enable a recording workflow
--disable <workflow> disable a recording workflow
--tointernal <external meetingId> get the internal meeting ids for the given external meetingId
--toexternal <internal meetingId> get the external meeting id for the given internal meetingId
--republish <internal meetingID> republish the recording for meetingID.
(Only for Matterhorn Integration)
Useful settings
Name | Path (file) | Description |
---|---|---|
webcamsOnlyForModerator | /usr/share/bbb-web/WEB-INF/classes/bigbluebutton.properties | If true, only the moderator's cam will be showed in playback depending on how the show_moderator_viewpoint . It can be changed in the ongoing meeting |
show_moderator_viewpoint | /usr/local/bigbluebutton/core/scripts/bigbluebutton.yml | If false, the viewer's point of view will be showed, meaning that if the above property is set to true, only the moderator's camera will be displayed. |