Server Customization
BigBlueButton has many configuration files that offer you opportunities to customize your installation.
General
Preserving changes to configuration files
BigBlueButton's components use various configuration files which are included with the installation packages. If you were to make a change to these configuration files, your changes would be lost when an updated version of the package is installed during upgrades. To prevent this loss of customizations, most components also accept overriding configuration files from /etc/bigbluebutton
. That directory is not interfered with by BigBlueButton (except in cases when using the command bbb-conf --setip
or --setsecret
placing new values you specify).
For the full list of the configuration files and their overriding counterpart, see Configuration Files
Preserving customizations using apply-conf.sh
Note that starting with BigBlueButton 2.6 we strongly recommend adding your custom settings to /etc/bigbluebutton
instead. See the list of override files
Whenever you upgrade a server to the latest version of BigBlueButton, either using the manual upgrade steps or the bbb-install.sh script, if you have made custom changes to BigBlueButton's configuration files [that are deployed from packages], the packaging scripts may overwrite these changes.
To make it easier to apply your configuration changes, you can create a BASH script at /etc/bigbluebutton/bbb-conf/apply-config.sh
that contains commands to apply your changes. The bbb-conf
script, which is run as part of the last steps in a manual upgrade steps or using bbb-install.sh
, will detect apply-config.sh
and invoke it just before starting all of BigBlueButton's components.
In this way, you can use apply-conf.sh
to apply your custom configuration changes after all packages have updated but just before BigBlueButton starts.
For example, if you create /etc/bigbluebutton/bbb-conf/apply-config.sh
with the following contents and make it executable with chmod +x /etc/bigbluebutton/bbb-conf/apply-config.sh
#!/bin/bash
# Pull in the helper functions for configuring BigBlueButton
source /etc/bigbluebutton/bbb-conf/apply-lib.sh
enableUFWRules
then when called by bbb-conf
, the above apply-conf.sh
script will
- use the helper function
enableUFWRules
to restrict access to specific ports, and
Notice that apply-conf.sh
includes a helper script apply-lib.sh.
This helper script contains some functions to make it easy to apply common configuration changes, along with some helper variables, such as HTML5_CONFIG
.
The contents of apply-config.sh
are not owned by any package, so it will never be overwritten.
Common Customizations
Recording
Delete raw data from published recordings
When a meeting finishes, the BigBlueButton server archives the meeting data (referred to as the "raw" data).
Retaining the raw data lets you rebuild a recording if there was a processing issue, to enabled a new recording format, or if it was accidentally deleted by a user; however, the tradeoff is the storage of raw data will consume more disk space over time.
By default, BigBlueButton server automatically remove the raw data for a recording after 14 days of its being published. You can adjust this by editing the file /etc/cron.daily/bigbluebutton
. Look for this line near the top of the file:
published_days=14
And adjust it to the desired number of days. If you would instead like to completely disable the cleanup of raw recording data, comment out the following line, near the bottom of the file:
remove_raw_of_published_recordings
Delete recordings older than N days
To delete recordings older than 14 days, create the file /etc/cron.daily/bbb-recording-cleanup
with the contents
#!/bin/bash
MAXAGE=14
LOGFILE=/var/log/bigbluebutton/bbb-recording-cleanup.log
shopt -s nullglob
NOW=$(date +%s)
echo "$(date --rfc-3339=seconds) Deleting recordings older than ${MAXAGE} days" >>"${LOGFILE}"
for donefile in /var/bigbluebutton/recording/status/published/*-presentation.done ; do
MTIME=$(stat -c %Y "${donefile}")
# Check the age of the recording
if [ $(( ( $NOW - $MTIME ) / 86400 )) -gt $MAXAGE ]; then
MEETING_ID=$(basename "${donefile}")
MEETING_ID=${MEETING_ID%-presentation.done}
echo "${MEETING_ID}" >> "${LOGFILE}"
bbb-record --delete "${MEETING_ID}" >>"${LOGFILE}"
fi
done
for eventsfile in /var/bigbluebutton/recording/raw/*/events.xml ; do
MTIME=$(stat -c %Y "${eventsfile}")
# Check the age of the recording
if [ $(( ( $NOW - $MTIME ) / 86400 )) -gt $MAXAGE ]; then
MEETING_ID="${eventsfile%/events.xml}"
MEETING_ID="${MEETING_ID##*/}"
echo "${MEETING_ID}" >> "${LOGFILE}"
bbb-record --delete "${MEETING_ID}" >>"${LOGFILE}"
fi
done
Change the value for MAXAGE
to specify how many days to retain the presentation
format recordings on your BigBlueButton server. After you create the file, make it executable.
$ chmod +x /etc/cron.daily/bbb-recording-cleanup
Move recordings to a different partition
Most of BigBlueButton's storage occurs in the /var/bigbluebutton
directory (this is where all the recordings are stored). If you want to move this directory to another partition, say to /mnt/data
, do the following
$ sudo bbb-conf --stop
$ mv /var/bigbluebutton /mnt/data
$ ln -s /mnt/data/bigbluebutton /var/bigbluebutton
$ sudo bbb-conf --start
Migrate recordings from a previous version
Depending of the previous version there may be some differences in the metadata generated. In order to fix that it will be necessary to execute the corresponding scripts for updating the migrated recordings.
$ cd /usr/local/bigbluebutton/core/scripts
From version 0.9
$ sudo ./bbb-0.9-beta-recording-update
$ sudo ./bbb-0.9-recording-size
From version 1.0
$ sudo ./bbb-1.1-meeting-tag
If for some reason the scripts have to be run more than once, use the --force modifier.
$ sudo ./bbb-x.x-script --force
Enable playback of recordings on iOS
The presentation
playback format encodes the video shared during the session (webcam and screen share) as .webm
(VP8) files; however, iOS devices only support playback of .mp4
(h.264) video files. To enable playback of the presentation
recording format on iOS devices, edit /usr/local/bigbluebutton/core/scripts/presentation.yml
and uncomment the entry for mp4
.
video_formats:
- webm
- mp4
This change will cause BigBlueButton to generate an additional .mp4
file for the video components (webcam and screen share) that was shared during the session. This change only applies to new recordings. If you want this change to apply to any existing recordings, you need use the bbb-record
command to rebuild them.
This change will increase the processing time and storage size of recordings with video files as it will now generate two videos: .webm
and .mp4
for the webcam and screen share videos.
Always record every meeting
By default, the BigBlueButton server will produce a recording when both of the following are true:
- the meeting has been created with
record=true
in the create API call, and - a moderator has clicked the Start/Stop Record button (at least once) during the meeting.
However, you can configure a BigBlueButton server to record every meeting and disable the ability for a moderator to stop the recording. Edit /etc/bigbluebutton/bbb-web.properties
and set the following properties:
# Start recording when first user joins the meeting.
# For backward compatibility with 0.81 where whole meeting
# is recorded.
autoStartRecording=true
# Allow the user to start/stop recording.
allowStartStopRecording=false
To apply the changes, restart the BigBlueButton server using the command
$ sudo bbb-conf --restart
Transfer recordings
When setting up BigBlueButton on a server, you may want to transfer recordings from an older server. If your old server has all of the original recording files in the /var/bigbluebutton/recording/raw
directory, then you can transfer these files to the new server using rsync
.
For example, running this rsync
command new server will copy over the recording file from the old server.
$ rsync -rP root@old-bbb-server.example.com:/var/bigbluebutton/recording/raw/ /var/bigbluebutton/recording/raw/
Alternatively, you could create a tar archive of the /var/bigbluebutton/recording/raw
directory, and copy it with scp, or use a shared NFS mount.
After you copy over the files (either through rsync or tar-and-copy), you will then need to fix the permissions on the new server using the following chown
command.
$ chown -R bigbluebutton:bigbluebutton /var/bigbluebutton/recording/raw
After transfer of recordings, view a sampling of the recordings to ensure they playback correctly (they should).
Re-process raw recordings
If you have transferred over the raw content, you can also reprocess the recordings using the newer scripts to rebuild them with the latest playback format (including any bug fixes made in the latest version). Note: Re-processing can take a long time (around 25% to 50% of the original length of the recordings), and will use a lot of CPU on your new BigBlueButton server while you wait for the recordings to process.
If you are interested in reprocessing the older recordings, try it first with one or two of the larger recordings. If there is no perceptible difference, you don't need to reprocess the others.
And initiate the re-processing of a single recording, you can do
$ sudo bbb-record --rebuild <recording_id>
where <recording_id>
is the the file name of the raw recording in /var/bigbluebutton/recording/raw
, such as
$ sudo bbb-record --rebuild f4ae6fd61e2e95940e2e5a8a246569674c63cb4a-1517234271176
If your old server has all of the original recording files in the /var/bigbluebutton/recording/raw
directory, then you can transfer these files to the new server, for example with rsync:
If you want to rebuild all your recordings, enter the command
Warning: If you have a large number of recordings, this will rebuild all of them, and not process any new recordings until the rebuild process finishes. Do not do this unless this is you intent. Do not do this command to troubleshoot recording errors, instead see Recording Troubleshooting.
$ sudo bbb-record --rebuildall
The BigBlueButton server will automatically go through the recordings and rebuild and publish them. You can use the bbb-record --watch
command to see the progress.
Transfer published recordings from another server
If you want to do the minimum amount of work to quickly make your existing recordings on an older BigBlueButton server, transfer the contents of the /var/bigbluebutton/published
and /var/bigbluebutton/unpublished
directories. In addition, to preserve the backup of the original raw media, you should transfer the contents of the /var/bigbluebutton/recording/raw
directory.
Here is an example set of rsync commands that would accomplish this; run these on the new server to copy the files from the old server.
$ rsync -rP root@old-bbb-server:/var/bigbluebutton/published/ /var/bigbluebutton/published/
$ rsync -rP root@old-bbb-server:/var/bigbluebutton/unpublished/ /var/bigbluebutton/unpublished/
$ rsync -rP root@old-bbb-server:/var/bigbluebutton/recording/raw/ /var/bigbluebutton/recording/raw/
Other methods of transferring these files can also be used; for example, you could create a tar archive of each of the directories, and transfer it via scp, or use a shared NFS mount.
You will then need to fix the permissions on the newly copied recordings:
$ chown -R bigbluebutton:bigbluebutton /var/bigbluebutton/published /var/bigbluebutton/unpublished /var/bigbluebutton/recording/raw
If the recordings were copied from a server with a different hostname, you will have to run the following command to fix the stored hostnames. (If you don't do this, it'll either return a 404 error, or attempt to load the recordings from the old server instead of the new server!)
Note that this command will restart the BigBlueButton server, interrupting any live sessions.
$ sudo bbb-conf --setip <ip_address_or_hostname>
For example,
$ sudo bbb-conf --setip bigbluebutton.example.com
The transferred recordings should be immediately visible via the BigBlueButton recordings API.
Change processing time
On a 2.2.x BigBlueButton server, the server will process recordings as meetings finish. You can restrict the recording processing interval to specific hours by creating the file /etc/systemd/system/bbb-record-core.timer.d/override.conf
with the contents
[Timer]
OnActiveSec=
OnUnitInactiveSec=
OnCalendar=21,22,23,00,01,02,03:*:00
Persistent=false
and do systemctl daemon-reload
. This file overrides the timing of when systemd runs bbb-record-core.target
. In the above example, recordings will start processing between 21:00 and 03:59.
Allow all recordings to be returned
In 2.6.x a new configuration property, allowFetchAllRecordings
, was added to bigbluebutton.properties
. This property determines whether every recording on the server can be returned in a single response from a getRecordings
call. By default this property is set to true
. On a server with a large number of recordings an attempt to return every recording in a single response can cause a large amount of load on the server and therefore it is advised that this property be switched to false
. When this is done any request to getRecordings
that does not specify any recording or meeting IDs as well as no pagination parameters will return no recordings to prevent all recordings from being returned.
Increase the number of recording workers
Warning
If the
defaultKeepEvents
ormeetingKeepEvents
setting in bbb-web is enabled, you must not increase the number of BigBlueButton recording workers. Doing so could result in data loss, as meeting events will not be correctly archived.For more information, see BigBlueButton issue #12503.
Run systemctl edit bbb-rap-resque-worker.service
, and insert the following into the editor, replacing the number with the desired number of recordings to process concurrently.
[Service]
Environment=COUNT=3
Then restart the worker process: systemctl restart bbb-rap-resque-worker.service
If you run systemctl status bbb-rap-resque-worker.service
now, you will see that it has the desired number of workers ready to process recordings in parallel:
● bbb-rap-resque-worker.service - BigBlueButton resque worker for recordings
Loaded: loaded (/usr/lib/systemd/system/bbb-rap-resque-worker.service; disabled; vendor preset: enabled)
Drop-In: /etc/systemd/system/bbb-rap-resque-worker.service.d
└─override.conf
Active: active (running) since Sat 2021-01-09 12:19:22 UTC; 6s ago
Main PID: 23630 (sh)
Tasks: 15 (limit: 4915)
CGroup: /system.slice/bbb-rap-resque-worker.service
├─23630 /bin/sh -c /usr/bin/rake -f ../Rakefile resque:workers >> /var/log/bigbluebutton/bbb-rap-worker.log
├─23631 /usr/bin/ruby /usr/bin/rake -f ../Rakefile resque:workers
├─23650 resque-2.0.0: Waiting for rap:archive,rap:publish,rap:process,rap:sanity,rap:captions
├─23651 resque-2.0.0: Waiting for rap:archive,rap:publish,rap:process,rap:sanity,rap:captions
└─23652 resque-2.0.0: Waiting for rap:archive,rap:publish,rap:process,rap:sanity,rap:captions
Install additional recording processing formats
In addition to the presentation
format that is installed and enabled by default, there are several optional recording formats available for BigBlueButton 2.6:
notes
: Makes the shared notes from the meeting available as a document.screenshare
: Generate a single video file from the screensharing and meeting audio.podcast
: Generate an audio-only recording.video
: Generate a recording containing the webcams, presentation area, and screensharing combined into a single video file.
The processing scripts and playback support files for these recording formats can be installed from the packages named bbb-playback-formatname
(e.g. bbb-playback-video
)
There is currently an issue where the recording formats are not automatically enabled when they are installed - see #12241 for details.
In order to enable the recording formats manually, you need to edit the file /usr/local/bigbluebutton/core/scripts/bigbluebutton.yml
. Look for the section named steps:
. In this section, the recording processing workflow is defined, including what recording processing steps are performed, and what order they need to be performed in.
To enable a new recording format, you need to add a new step named process:formatname
that runs after the step named captions, and a new step named publish:formatname
that runs after process:formatname
. You may have to convert some of the steps to list format.
For example, here are the stock steps in BigBlueButton 2.6 with the presentation
format enabled:
steps:
archive: 'sanity'
sanity: 'captions'
captions: 'process:presentation'
'process:presentation': 'publish:presentation'
If you additionally enable the video
recording format, the steps will have to be changed to look like this:
steps:
archive: 'sanity'
sanity: 'captions'
captions:
- 'process:presentation'
- 'process:video'
'process:presentation': 'publish:presentation'
'process:video': 'publish:video'
This pattern can be repeated for additional recording formats. Note that it's very important to put the step names containing a colon (:
) in quotes.
After you edit the configuration file, you must restart the recording processing queue: systemctl restart bbb-rap-resque-worker.service
in order to pick up the changes.
The following script will enable the video recording format a BigBlueButton 2.6+ server.
!/bin/bash
mkdir -p /etc/bigbluebutton/recording
cat > /etc/bigbluebutton/recording/recording.yml << REC
steps:
archive: "sanity"
sanity: "captions"
captions:
- process:presentation
- process:video
process:presentation: publish:presentation
process:video: publish:video
REC
if ! dpkg -l | grep -q bbb-playback-video; then
apt install -y bbb-playback-video
systemctl restart bbb-rap-resque-worker.service
fi
Enable generating mp4 (H.264) video output
By default, BigBlueButton generates recording videos as .webm
files using the VP9 video codec. These are supported in most desktop web browsers, but might not work on iOS mobile devices. You can additionally enable the H.264 video codec in some recording formats (Keep in mind that the following .yml
files mentioned ahead only exist when the respective format package is installed):
video
Edit the file /usr/local/bigbluebutton/core/scripts/video.yml
and uncomment the lines under the formats:
label for the mimetype video/mp4
.
The encoding options can be adjusted to speed up encoding or increase quality of video generation as desired.
presentation
Edit the file /usr/local/bigbluebutton/core/scripts/presentation.yml
and uncomment the entry for mp4
:
video_formats:
- webm
- mp4
screenshare
Edit the file /usr/local/bigbluebutton/core/scripts/screenshare.yml
and uncomment the lines under the :formats:
label for the mime type video/mp4
:
- :mimetype: 'video/mp4; codecs="avc1.640028, mp4a.40.2"'
:extension: mp4
:parameters:
- [ '-c:v', 'libx264', '-crf', '21', '-preset', 'medium', '-profile:v', 'high', '-level', '40', '-g', '240',
'-c:a', 'aac', '-b:a', '96K',
'-threads', '2', '-f', 'mp4', '-movflags', 'faststart' ]
The encoding options can be adjusted to speed up encoding or increase quality of video generation as desired.
Video
Reduce bandwidth from webcams
You can use a banwidth usage on your BigBlueButton server using a tool such as bmon
(sudo apt-get install bmon
). You can change the maximum bandwidth settings for each webcam options (low, medium, high, high definition) by editing /usr/share/bigbluebutton/html5-client/private/config/settings.yml
and modifying the entries for
cameraProfiles:
- id: low
name: Low quality
default: false
bitrate: 100
- id: medium
name: Medium quality
default: true
bitrate: 200
- id: high
name: High quality
default: false
bitrate: 500
- id: hd
name: High definition
default: false
bitrate: 800
The settings for bitrate
are in kbits/sec (i.e. 100 kbits/sec). After your modify the values, save the file, restart your BigBlueButton server sudo bbb-conf --restart
to have the settings take effect. The lowest setting allowed for WebRTC is 30 Kbits/sec.
If you have sessions that like to share lots of webcams, such as ten or more, then setting the bitrate
for low
to 50 and medium
to 100 will help reduce the overall bandwidth on the server. When many webcams are shared, the size of the webcams get so small that the reduction in bitrate
will not be noticeable during the live sessions.
Disable webcams
You can disable webcams by setting enableVideo
to false
in the /etc/bigbluebutton/bbb-html5.yml
file for the HTML5 client.
yq e -i '.public.kurento.enableVideo = false' /etc/bigbluebutton/bbb-html5.yml
and run bbb-conf --restart
Disable screen sharing
You can disable screen sharing by setting enableScreensharing
to false
in the /etc/bigbluebutton/bbb-html5.yml
file for the HTML5 client.
yq e -i '.public.kurento.enableScreensharing = false' /etc/bigbluebutton/bbb-html5.yml
Reduce bandwidth for webcams
If you expect users to share many webcams, you can reduce bandwidth for webcams.
echo " - Setting camera defaults"
yq e -i '.public.kurento.cameraProfiles.(id==low).bitrate = 50' /etc/bigbluebutton/bbb-html5.yml
yq e -i '.public.kurento.cameraProfiles.(id==medium).bitrate = 100' /etc/bigbluebutton/bbb-html5.yml
yq e -i '.public.kurento.cameraProfiles.(id==high).bitrate = 200' /etc/bigbluebutton/bbb-html5.yml
yq e -i '.public.kurento.cameraProfiles.(id==hd).bitrate = 300' /etc/bigbluebutton/bbb-html5.yml
yq e -i '.public.kurento.cameraProfiles.(id==low).default = true' /etc/bigbluebutton/bbb-html5.yml
yq e -i '.public.kurento.cameraProfiles.(id==medium).default = false' /etc/bigbluebutton/bbb-html5.yml
yq e -i '.public.kurento.cameraProfiles.(id==high).default = false' /etc/bigbluebutton/bbb-html5.yml
yq e -i '.public.kurento.cameraProfiles.(id==hd).default = false' /etc/bigbluebutton/bbb-html5.yml
Change screen sharing quality parameters
Screen sharing quality can be tweaked to either improve quality or reduce bandwidth usage. There are different configurations for live meetings and recordings and they need to be changed independently from each other.
For recordings, the following parameters can be changed (presentation format):
/usr/local/bigbluebutton/core/scripts/presentation.yml
:deskshare_output_width
(default: 1280)/usr/local/bigbluebutton/core/scripts/presentation.yml
:deskshare_output_height
(default: 720)/usr/local/bigbluebutton/core/scripts/presentation.yml
:deskshare_output_framerate
(default: 5)
As an example, suppose you want to increase the output resolution and framerate of the recorded screen share media to match a 1080p/15 FPS stream. The following changes would be necessary:
$ yq w -i /usr/local/bigbluebutton/core/scripts/presentation.yml deskshare_output_width 1920
$ yq w -i /usr/local/bigbluebutton/core/scripts/presentation.yml deskshare_output_height 1080
$ yq w -i /usr/local/bigbluebutton/core/scripts/presentation.yml deskshare_output_framerate 15
For live meetings, the following parameters can be changed:
/etc/bigbluebutton/bbb-html5.yml
:public.kurento.screenshare.bitrate
/etc/bigbluebutton/bbb-html5.yml
:public.kurento.screenshare.constraints
The bitrate is specified in kbps and represents screen sharing's maximum bandwidth usage. Setting it to a higher value may improve quality but also increase bandwidth usage, while setting it to a lower value may reduce quality but will reduce average bandwidth usage.
The constraints are specified as an YAML object with the same semantics as the MediaTrackConstraints from the WebRTC specification. We recommend checking the aforementioned MDN link as well as the Media Capture and Streams API spec for an extensive list of constraints.
To set new screen sharing constraints, translate the JSON constraints object into an YAML format object and put it into public.kurento.screenshare.constraints
. Restart bbb-html5 afterwards.
As an example, suppose you want to set the maximum screen sharing resolution to 1080p, alter the maximum bitrate to 2000 kbps and set a 10 FPS target. The following would need to be added to etc/bigbluebutton/bbb-html5.yml
:
public:
kurento:
screenshare:
bitrate: 2000
constraints:
audio: true
video:
width:
max: 1920
height:
max: 1080
frameRate:
ideal: 10
max: 10
Limit overall media streams
On any setup for BigBlueButton server there is a cap for how many media streams can be shared. A media stream is created when a user broadcasts or receives a webcam or screen share video, or when a user joins audio listening only. If your server will be using webcams, you can set limits per user, per room, and an overall limit per server in /usr/local/bigbluebutton/bbb-webrtc-sfu/config/default.yml
. The default is no limit.
mediaThresholds:
global: 0
perRoom: 0
perUser: 0
For example, the following settings would limit the overall number of media across all meetings to 1000 streams, the maximum number of webcam streams per meeting to 300, and no limit on the number of webcam streams per user.
mediaThresholds:
global: 1000
perRoom: 300
perUser: 0
On a BigBlueButton 2.3 (or later) server, you can place the above in /etc/bigbluebutton/bbb-webrtc-sfu/production.yml
, which bbb-webrtc-sfu
will use to override the settings in default.yml
(even after package upgrades).
If any of these thresholds are reached, then a user will receive a "Media resources not available (2002)" error when sharing webcams.
BigBlueButton will dynamically reduce the number of webcams in a meeting as the meeting grows larger. These are set in /usr/share/bigbluebutton/html5-client/private/config/settings.yml
, but you can override them by placing them in /etc/bigbluebutton/bbb-html5.yml
.
For example, the following /etc/bigbluebutton/bbb-html5.yml
file would ensure that no single meeting will have more than 300 streams. For example, in a meeting with 30 users, the moderator will see 25 webcams and the viewers 6 webcams. This gives 25 + 29 _ 6 = 196 webcam streams. If the meeting grows to 100 users, the moderator will see 8 webcams and viewers will see 2 webcams. This gives 8 + 99 _ 2 = 206 webcam streams.
public:
app:
defaultSettings:
application:
paginationEnabled: true
kurento:
pagination:
desktopPageSizes:
moderator: 0
viewer: 5
mobilePageSizes:
moderator: 2
viewer: 2
paginationToggleEnabled: false
paginationThresholds:
enabled: true
thresholds:
- desktopPageSizes:
moderator: 25
viewer: 6
users: 30
- desktopPageSizes:
moderator: 20
viewer: 5
users: 40
- desktopPageSizes:
moderator: 16
viewer: 4
users: 50
- desktopPageSizes:
moderator: 12
viewer: 4
users: 60
- desktopPageSizes:
moderator: 8
viewer: 3
users: 70
- desktopPageSizes:
moderator: 8
viewer: 2
users: 80
- desktopPageSizes:
moderator: 8
viewer: 2
users: 90
- desktopPageSizes:
moderator: 8
viewer: 2
users: 100
HERE
Use custom images for virtual background
Starting from version 2.4 BigBlueButton offers virtual background for webcams.
To use your own background images copy them into the directory
/usr/share/bigbluebutton/html5-client/resources/images/virtual-backgrounds
.
For each image copy a thumbnail of the image of 50x50 pixels size into
/usr/share/bigbluebutton/html5-client/resources/images/virtual-backgrounds/thumbnails
.
To generate thumbnails you can use the following shell snippet:
#!/bin/bash
FULL="/usr/share/bigbluebutton/html5-client/resources/images/virtual-backgrounds"
THUMB="${FULL}/thumbnails"
cd "$FULL"
for pic in *.jpg; do
convert "$pic" -resize 50x50^ -gravity Center -extent 50x50 "${THUMB}/${pic}"
done
Reference them in the configuration file /etc/bigbluebutton/bbb-html5.yml
:
public:
virtualBackgrounds:
fileNames:
- image1.jpg
- image2.jpg
- image3.jpg
Background images should not be too large as clients have to download them. You
can optimize them using the jpegoptim
command which is available as an Ubuntu
package.
Audio
Mute all users on startup
If you want to have all users join muted, you can add an overwrite in /etc/bigbluebutton/bbb-web.properties
and set this as a server-wide configuration.
# Mute the meeting on start
muteOnStart=false
After making them modification, restart your server with sudo bbb-conf --restart
to apply the changes.
Turn off "you are now muted"
You can remove this sound for all users by editing /opt/freeswitch/etc/freeswitch/autoload_configs/conference.conf.xml
and moving the lines containing muted-sound
and unmuted-sound
into the commented section.
<profile name="cdquality">
<param name="domain" value="$${domain}"/>
<param name="rate" value="48000"/>
<param name="interval" value="20"/>
<param name="energy-level" value="100"/>
<!-- <param name="sound-prefix" value="$${sounds_dir}/en/us/callie"/> -->
<param name="muted-sound" value="conference/conf-muted.wav"/>
<param name="unmuted-sound" value="conference/conf-unmuted.wav"/>
<param name="alone-sound" value="conference/conf-alone.wav"/>
<!--
<param name="moh-sound" value="$${hold_music}"/>
<param name="enter-sound" value="tone_stream://%(200,0,500,600,700)"/>
<param name="exit-sound" value="tone_stream://%(500,0,300,200,100,50,25)"/>
-->
<param name="kicked-sound" value="conference/conf-kicked.wav"/>
<param name="locked-sound" value="conference/conf-locked.wav"/>
<param name="is-locked-sound" value="conference/conf-is-locked.wav"/>
<param name="is-unlocked-sound" value="conference/conf-is-unlocked.wav"/>
<param name="pin-sound" value="conference/conf-pin.wav"/>
<param name="bad-pin-sound" value="conference/conf-bad-pin.wav"/>
<param name="caller-id-name" value="$${outbound_caller_name}"/>
<param name="caller-id-number" value="$${outbound_caller_id}"/>
<param name="comfort-noise" value="true"/>
<!-- <param name="conference-flags" value="video-floor-only|rfc-4579|livearray-sync|auto-3d-position|minimize-video-encoding"/> -->
<!-- <param name="video-mode" value="mux"/> -->
<!-- <param name="video-layout-name" value="3x3"/> -->
<!-- <param name="video-layout-name" value="group:grid"/> -->
<!-- <param name="video-canvas-size" value="1920x1080"/> -->
<!-- <param name="video-canvas-bgcolor" value="#333333"/> -->
<!-- <param name="video-layout-bgcolor" value="#000000"/> -->
<!-- <param name="video-codec-bandwidth" value="2mb"/> -->
<!-- <param name="video-fps" value="15"/> -->
</profile>
Enable background music when only one person is in a session
p
FreeSWITCH enables you to have music play in the background when only one users is in the voice conference. To enable background music, edit /opt/freeswitch/conf/autoload_configs/conference.conf.xml
(as root) and around line 204 you'll see the music on hold (moh-sound) commented out
<!--
<param name="moh-sound" value="$${hold_music}"/>
<param name="enter-sound" value="tone_stream://%(200,0,500,600,700)"/>
<param name="exit-sound" value="tone_stream://%(500,0,300,200,100,50,25)"/>
-->
Uncomment it and save this file.
<param name="moh-sound" value="$${hold_music}"/>
<!--
<param name="enter-sound" value="tone_stream://%(200,0,500,600,700)"/>
<param name="exit-sound" value="tone_stream://%(500,0,300,200,100,50,25)"/>
-->
The default BigBlueButton installation does not come with any music files. You'll need to upload a music file in WAV format to the server and change a reference in /opt/freeswitch/conf/vars.xml
.
For example, to use the file /opt/freeswitch/share/freeswitch/sounds/en/us/callie/ivr/48000/ivr-to_listen_to_moh.wav
as music on hold, edit /opt/freeswitch/conf/vars.xml
and change the line
<X-PRE-PROCESS cmd="set" data="hold_music=local_stream://moh"/>
to
<X-PRE-PROCESS cmd="set" data="hold_music=/opt/freeswitch/share/freeswitch/sounds/en/us/callie/ivr/48000/ivr-to_listen_to_moh.wav" />
and then restart BigBlueButton
$ bbb-conf --restart
and join an audio session. You should now hear music on hold if there is only one user in the session.
Add a phone number to the conference bridge
The built-in WebRTC-based audio in BigBlueButton is very high quality audio. Still, there may be cases where you want users to be able to dial into the conference bridge using a telephone number.
Before you can configure FreeSWITCH to route the call to the right conference, you need to first obtain a phone number from a Internet Telephone Service Providers and configure FreeSWITCH accordingly to receive incoming calls via session initiation protocol (SIP) from that provider. Ensure that the context is public
and that the file is called /opt/freeswitch/conf/sip_profiles/external/YOUR-PROVIDER.xml
. Here is an example; of course, hostname and ALL-CAPS values need to be changed:
<include>
<gateway name="ANY-NAME-FOR-YOUR-PROVIDER">
<param name="proxy" value="sip.example.net"/>
<param name="username" value="PROVIDER-ACCOUNT"/>
<param name="password" value="PROVIDER-PASSWORD"/>
<param name="extension" value="EXTERNALDID"/>
<param name="register" value="true"/>
<param name="context" value="public"/>
</gateway>
</include>
To route the incoming call to the correct BigBlueButton audio conference, you need to create a dialplan
which, for FreeSWITCH, is a set of instructions that it runs when receiving an incoming call. When a user calls the phone number, the dialplan will prompt the user to enter a five digit number associated with the conference.
To create the dialplan, use the XML below and save it to /opt/freeswitch/conf/dialplan/public/my_provider.xml
. Replace EXTERNALDID
with the value specified as the extension
in the SIP profile (such as 6135551234, but see above).
<extension name="from_my_provider">
<condition field="destination_number" expression="^EXTERNALDID">
<action application="start_dtmf" />
<action application="answer"/>
<action application="sleep" data="1000"/>
<action application="play_and_get_digits" data="9 9 3 30000 # conference/conf-pin.wav ivr/ivr-that_was_an_invalid_entry.wav pin \d+"/>
<!-- Uncomment the following block if you want to mask the phone number in the list of participants. -->
<!-- Instead of `01711233121` it will then show `xxx-xxx-3121`. -->
<!--
<action application="set_profile_var" data="caller_id_name=${regex(${caller_id_name}|^.*(.{4})$|xxx-xxx-%1)}"/>
-->
<action application="transfer" data="SEND_TO_CONFERENCE XML public"/>
</condition>
</extension>
<extension name="check_if_conference_active">
<condition field="${conference ${pin} list}" expression="/sofia/g" />
<condition field="destination_number" expression="^SEND_TO_CONFERENCE$">
<action application="set" data="bbb_authorized=true"/>
<action application="transfer" data="${pin} XML default"/>
</condition>
</extension>
<extension name="conf_bad_pin">
<condition field="${pin}" expression="^\d{5}$">
<action application="answer"/>
<action application="sleep" data="1000"/>
<action application="play_and_get_digits" data="9 9 3 30000 # conference/conf-bad-pin.wav ivr/ivr-that_was_an_invalid_entry.wav pin \d+"/>
<action application="transfer" data="SEND_TO_CONFERENCE XML public"/>
</condition>
</extension>
Change ownership of this file to freeswitch:daemon
$ chown freeswitch:daemon /opt/freeswitch/conf/dialplan/public/my_provider.xml
and then restart FreeSWITCH:
$ sudo systemctl restart freeswitch
Try calling the phone number. It should connect to FreeSWITCH and you should hear a voice prompting you to enter the five digit PIN number for the conference. Please note, that dialin will currently only work if at least one web participant has joined with their microphone.
To always show users the phone number along with the 5-digit PIN number within BigBlueButton, not only while selecting the microphone participation, edit /etc/bigbluebutton/bbb-web.properties
and set the phone number provided by your Internet Telephone Service Provider
#----------------------------------------------------
# Default dial access number
defaultDialAccessNumber=613-555-1234
and set defaultWelcomeMessageFooter
to
defaultWelcomeMessageFooter=<br><br>To join this meeting by phone, dial:<br> %%DIALNUM%%<br>Then enter %%CONFNUM%%# as the conference PIN number.
Save /etc/bigbluebutton/bbb-web.properties
and restart BigBlueButton again. Each user that joins a session will see a message in the chat similar to.
To join this meeting by phone, dial:
613-555-1234
and enter 12345 as the conference PIN number.
Finally, setup the firewall rules so you are only accepting incoming calls from the IP address of your SIP provider. For example, if your SIP provider forwards incoming calls from 64.2.142.33, then setup the following firewall rules on your server.
iptables -A INPUT -i eth0 -p tcp --dport 5060 -s 0.0.0.0/0 -j REJECT
iptables -A INPUT -i eth0 -p udp --dport 5060 -s 0.0.0.0/0 -j REJECT
iptables -A INPUT -i eth0 -p tcp --dport 5080 -s 0.0.0.0/0 -j REJECT
iptables -A INPUT -i eth0 -p udp --dport 5080 -s 0.0.0.0/0 -j REJECT
iptables -I INPUT -p udp --dport 5060 -s 64.2.142.33 -j ACCEPT
With these rules, you won't get spammed by bots scanning for SIP endpoints and trying to connect.
Turn on the "comfort noise" when no one is speaking
FreeSWITCH has the ability to add a "comfort noise" that is a slight background hiss to let users know they are still in a voice conference even when no one is talking (otherwise, they may forget they are connected to the conference bridge and say something unintended for others).
If you want to enable, edit /opt/freeswitch/conf/autoload_configs/conference.conf.xml
, look for the block <profile name="cdquality">
, and change the value for comfort-noise
. You can specify a level of noise, such as 0 (no noise), 350, 1400, etc. Try different values to get the level you desire.
<param name="comfort-noise" value="1400"/>
You need to restart BigBlueButton between each change. For more information, see comfort-noise in FreeSWITCH documentation.
$ sudo bbb-conf --restart
Presentation
Change the default presentation
When a new meeting starts, BigBlueButton displays a default presentation. The file for the default presentation is located in /var/www/bigbluebutton-default/assets/default.pdf
. You can replace the contents of this file with your presentation. Whenever a meeting is created, BigBlueButton will automatically load, convert, and display this presentation for all users.
Alternatively, you can change the global default by adding an overwriting rule in /etc/bigbluebutton/bbb-web.properties
specifying the URL for beans.presentationService.defaultUploadedPresentation
.
# Default Uploaded presentation file
beans.presentationService.defaultUploadedPresentation=${bigbluebutton.web.serverURL}/default.pdf
You'll need to restart BigBlueButton after the change with sudo bbb-conf --restart
.
If you want to specify the default presentation for a given meeting, you can also pass a URL to the presentation as part of the create meeting API call.
Increase the 200 page limit for uploads
BigBlueButton, by default, restricts uploads to 200 pages. To increase this value, add an overwrite rule in /etc/bigbluebutton/bbb-web.properties
and set the maxNumPages
value:
#----------------------------------------------------
# Maximum number of pages allowed for an uploaded presentation (default 200).
maxNumPages=200
After you save the changes to /etc/bigbluebutton/bbb-web.properties
, restart the BigBlueButton server with
$ sudo bbb-conf --restart
Increase the file size for an uploaded presentation
The default maximum file upload size for an uploaded presentation is 30 MB.
The first step is to change the size restriction in nginx. Edit /etc/bigbluebutton/nginx/web.nginx
(2.4) or /usr/share/bigbluebutton/nginx/web.nginx
(2.5) and modify the values for client_max_body_size
.
location ~ "^\/bigbluebutton\/presentation\/(?<prestoken>[a-zA-Z0-9_-]+)/upload$" {
....
# Allow 30M uploaded presentation document.
client_max_body_size 30m;
....
}
location = /bigbluebutton/presentation/checkPresentation {
....
# Allow 30M uploaded presentation document.
client_max_body_size 30m;
....
}
Next change the restriction in bbb-web. Add an overwrite rule in /etc/bigbluebutton/bbb-web.properties
and set the value maxFileSizeUpload
.
# Maximum file size for an uploaded presentation (default 30MB).
maxFileSizeUpload=30000000
You will have to additionally increase the size for the HTML5 client, edit /usr/share/bigbluebutton/html5-client/private/config/settings.yml
and modify uploadSizeMax
.
Restart BigBlueButton with sudo bbb-conf --restart
. You should now be able to upload larger presentations within the new limit.
Add custom fonts for presentation conversion
Starting with BigBlueButton 2.3 we added support for using additional fonts when converting presentation files.
On the server where you want the new fonts supported you would want to download the fonts (.ttf) file. For example:
wget https://github.com/bigbluebutton/bigbluebutton/files/6391912/Street.Ruler.zip
unzip Street.Ruler.zip
Then copy the font (.ttf) to /usr/share/fonts/
sudo cp 'Street Ruler.ttf' /usr/share/fonts/
That's all! The font will be available on next presentations.
Change the limit of 300 annotations per page
In BigBlueButton 2.6 we introduced a cap for how many annotations can be added to a single whiteboard (slide). The default value is set to 300. The reason for this cap is that when a large number of annotations was added, it was often times done in the case of multi user whiteboard being enabled and a student trying to be funny. This had a negative effect on other participants in the session, specifically on limited CPU devices. In almost all cases we observed during the testing phase of BigBlueButton 2.6 this cap was sufficient for the normal run of classes. In very rare instances normal use of the whiteboard led to hitting the cap.
In order to change the value (on per-server basis) to, say, 500 annotations in your deployment, add the following to /etc/bigbluebutton/bbb-html5.yml
public:
whiteboard:
maxNumberOfAnnotations: 500
and restart BigBlueButton via sudo bbb-conf --restart
Frontends
Remove the API demos
If you have earlier installed the API demos for testing (which makes it possible for anyone to use your BigBlueButton server without authentication) and want to now remove them, enter the command:
$ sudo apt-get purge bbb-demo
Modify the default landing page
The default HTML landing page is located in
/var/www/bigbluebutton-default/assets/index.html
Change this page to create your own landing page (and keep a back-up copy of it as it will be overwritten during package updates to bbb-conf
).
Use the Greenlight front-end
BigBlueButton comes with Greenlight, a front-end application written in Ruby on Rails that makes it easy for users to create meetings, invite others, start meetings, and manage recordings.
For more information see Installing Greenlight.
Networking
Setup a firewall
Configuring IP firewalling is essential for securing your installation. By default, many services are reachable across the network. This allows BigBlueButton operate in clusters and private data center networks -- but if your BigBlueButton server is publicly available on the internet, you need to run a firewall to reduce access to the minimal required ports.
If your server is behind a firewall already -- such as running within your company or on an EC2 instance behind a Amazon Security Group -- and the firewall is enforcing the above restrictions, you don't need a second firewall and can skip this section.
BigBlueButton comes with a UFW based ruleset. It it can be applied on restart and restricts access only to the following needed ports:
- TCP/IP port 22 for SSH
- TCP/IP port 80 for HTTP
- TCP/IP port 443 for HTTPS
- UDP ports 16384 to 32768 for media connections
Note: if you have configured sshd
(the OpenSSH daemon) to use a different port than 22, then before running the commands below, change ufw allow OpenSSH
to ufw allow <port>/tcp
where <port>
is the port in use by sshd
. You can see the listening port for sshd
using the command # netstat -antp | grep sshd
. Here the command shows sshd
listening to the standard port 22.
$ netstat -antp | grep sshd
tcp 0 0 0.0.0.0:22 0.0.0.0:* LISTEN 1739/sshd
tcp6 0 0 :::22 :::* LISTEN 1739/sshd
To restrict external access minimal needed ports for BigBlueButton.
BigBlueButton supplies a helper function that you can call in /etc/bigbluebutton/bbb-conf/apply-conf.sh
to setup a minimal firewall (see Setup Firewall).
You can also do it manually with the following commands
$ apt-get install -y ufw
ufw allow OpenSSH
ufw allow "Nginx Full"
ufw allow 16384:32768/udp
ufw --force enable
These ufw
firewall rules will be automatically re-applied on server reboot.
Besides IP-based firewalling, you can explore web application firewalls such as ModSecurity that provide additional security by checking requests to various web-based components.
Setup Firewall
To configure a firewall for your BigBlueButton server (recommended), add enableUFWRules
to /etc/bigbluebutton/bbb-conf/apply-config.sh
, as in
enableUFWRules
With enableUFWRule
added to apply-config.sh
, whenever you do bbb-conf
with --restart
or --setip
, you'll see the following output
sudo bbb-conf --restart
Restarting BigBlueButton ..
Stopping BigBlueButton
Applying updates in /etc/bigbluebutton/bbb-conf/apply-config.sh:
- Enable Firewall and opening 22/tcp, 80/tcp, 443/tcp and 16384:32768/udp
Rules updated
Rules updated (v6)
Rules updated
Rules updated (v6)
Rules updated
Rules updated (v6)
Rules updated
Rules updated (v6)
Firewall is active and enabled on system startup
Starting BigBlueButton
Change UDP ports
By default, BigBlueButton uses the UDP ports 16384-32768 which are used by FreeSWITCH, mediasoup and bbb-webrtc-recorder to send real-time packets (RTP).
FreeSWITCH uses the range 16384 - 24576, which is defined in /opt/freeswitch/etc/freeswitch/autoload_configs/switch.conf.xml
<!-- RTP port range -->
<param name="rtp-start-port" value="16384"/>
<param name="rtp-end-port" value="24576"/>
bbb-webrtc-recorder uses the range 24577 - 32768, which is defined in /etc/bbb-webrtc-recorder/bbb-webrtc-recorder.yml
(default) or /etc/bigbluebutton/bbb-webrtc-recorder.yml
(override)
[...]
webrtc:
rtcMinPort: 24577
rtcMaxPort: 32768
[...]
mediasoup also uses 24577 - 32768 by default (defined in /usr/local/bigbluebutton/bbb-webrtc-sfu/config/default.yml
). If it needs to be changed, bbb-webrtc-sfu's override configuration file (located in /etc/bigbluebutton/bbb-webrtc-sfu/production.yml
) should be used. For example, setting the range to 50000 - 51999 should be of the following format (YAML syntax, /etc/bigbluebutton/bbb-webrtc-sfu/production.yml
):
mediasoup:
worker:
rtcMinPort: 50000
rtcMaxPort: 51999
Apply custom settings for TURN server
If always want a specific TURN server configuration, the following to apply-config.sh and modify aaa.bbb.ccc.ddd
and secret
with your values.
echo " - Update TURN server configuration turn-stun-servers.xml"
cat <<HERE > /usr/share/bbb-web/WEB-INF/classes/spring/turn-stun-servers.xml
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans-2.5.xsd">
<bean id="stun0" class="org.bigbluebutton.web.services.turn.StunServer">
<constructor-arg index="0" value="stun:aaa.bbb.ccc.ddd"/>
</bean>
<bean id="turn0" class="org.bigbluebutton.web.services.turn.TurnServer">
<constructor-arg index="0" value="secret"/>
<constructor-arg index="1" value="turns:aaa.bbb.ccc.ddd:443?transport=tcp"/>
<constructor-arg index="2" value="86400"/>
</bean>
<bean id="stunTurnService"
class="org.bigbluebutton.web.services.turn.StunTurnService">
<property name="stunServers">
<set>
<ref bean="stun0"/>
</set>
</property>
<property name="turnServers">
<set>
<ref bean="turn0"/>
</set>
</property>
</bean>
</beans>
HERE
HTML5 client
Change the default welcome message
The default welcome message is built from three parameters: two system-wide parameters (see below) and the welcome
parameter from the BigBlueButton create
API call.
You'll find the two system-wide welcome parameters defaultWelcomeMessage
and defaultWelcomeMessageFooter
in /usr/share/bbb-web/WEB-INF/classes/bigbluebutton.properties
.
defaultWelcomeMessage=<default welcome message>
defaultWelcomeMessageFooter=<default welcome message footer>
When a front-end creates a BigBlueButton session, it may also pass a welcome
parameter in the create API call.
The final welcome message shown to the user (as blue text in the Chat window) is a composite of welcome
+ defaultWelcomeMessage
+ defaultWelcomeMessageFooter
.
The welcome message is fixed for the duration of a meeting. If you want to see the effect of changing the welcome
parameter, you must end the current meeting or wait until the BigBlueButton server removes it from memory (which occurs about two minutes after the last person has left). You can overwrite these values in file /etc/bigbluebutton/bbb-web.properties
, just remember to restart BigBlueButton with sudo bbb-conf --restart
for the new values to take effect.
Modify localization for the client (override with the latest locale)
A common use case is to modify a particular string from the locales or to include newer localizations from upstream.
For example, if you would like to replace de.json
with the version from a specific branch/tag of the repository, you could do the following:
cd /usr/share/bigbluebutton/html5-client/locales/
mv de.json /tmp/de.json.old
wget https://raw.githubusercontent.com/bigbluebutton/bigbluebutton/v3.0.x-release/bigbluebutton-html5/public/locales/de.json
cd /usr/share/bigbluebutton/html5-client/locales/
rm de.json
wget https://raw.githubusercontent.com/bigbluebutton/bigbluebutton/v3.0.x-release/bigbluebutton-html5/public/locales/de.json
bbb-conf --restart
Start a new meeting on the server, switch to German localization in Settings, clear the cache if needed -- frequently locales are cached.
Please use caution when replacing/editing locales. If you followed the steps above you should have a backup copy of de.json
(with ".old" appended) in /tmp
in case you need to revert.
Note that the json files across BigBlueButton versions are not always interchangeable. The workflow described above is only really meant for cases like
- I would like to tweak a translation for my own use
- I would like to adopt a change from upstream without having to wait for the official release in a few days
- This is part of my customization setup and I know what I need to test. I also know how to recover if needed
Change favicon
First method:
To change the favicon, overwrite the file /var/www/bigbluebutton-default/assets/favicon.ico
.
You'll need to update file each time the bbb-config
package updates.
Second method:
Create a custom directory under /var/www/bigbluebutton-default/
like /var/www/bigbluebutton-default/site
and copy your favicon.ico into this directory. Add a new file favicon.nginx
to /etc/bigbluebutton/nginx
and add the following lines:
location = /favicon.ico {
alias /var/www/bigbluebutton-default/site/favicon.ico;
After a restart of nginx, your customized favicon.ico will be delivered. This change will affect BigBlueButton and Greenlight and will persist during updates.
Change title in the HTML5 client
The configuration file for the HTML5 client is located in /usr/share/bigbluebutton/html5-client/private/config/settings.yml
. It contains all the settings for the HTML5 client.
To change the title, edit settings.yml
and change the entry for public.app.clientTitle
public:
app:
...
clientTitle: BigBlueButton
You'll need to update this entry each time the package bbb-html5
updates. The following script can help automate the change
$ TARGET=/usr/share/bigbluebutton/html5-client/private/config/settings.yml
$ yq e -i ".public.app.clientTitle = \"New Title\"" $TARGET
Apply lock settings to restrict webcams
To enable lock settings for Share webcam
by default (viewers are unable to share their webcam), add the following to /etc/bigbluebutton/bbb-web.properties
.
# Prevent viewers from sharing webcams
lockSettingsDisableCam=true
After restart, if you open the lock settings you'll see Share webcam
lock enabled.
Change the default path for HTML5 client
The default URL path for the client is /html5client
, and it can be changed to match your preferences.
Edit nginx configuration file (/usr/share/bigbluebutton/nginx/bbb-html5.nginx
), replacing all instances of /html5client
with the new path;
Do the same in /usr/share/bbb-web/WEB-INF/classes/bigbluebutton.properties
in the following lines:
defaultHTML5ClientUrl=${bigbluebutton.web.serverURL}/html5client
In configuration file for the HTML5 client, located in /usr/share/bigbluebutton/html5-client/private/config/settings.yml
, change the entry for public.app.basename
:
public:
app:
...
basename: '/html5client'
Finally, run the following command to reload configuration:
sudo service nginx reload && sudo bbb-conf --restart
Enable live captions
BigBlueButton has the ability to use Chrome's built-in speech-to-text API to give users the option to have their audio live captioned for other users in the session. When live captions are enabled on the server, a user can choose their language from the drop-down list when joining audio.
These captions will automatically appear in the recordings. To enable live captions, edit /etc/bigbluebutton/bbb-html5.yml
and add the following
public:
app:
# You may have other setting itms here
audioCaptions:
enabled: true
Restart BigBlueButton with sudo bbb-conf --restart
and you should now see the options for live captions when joining audio.
Configuration of gladia.io
To use gladia.io for automatic speech-to-text transcriptions, you first need to obtain an API key from gladia.io. You can sign up for free credentials to test the integration.
Next, you must be using BigBlueButton 2.7.4+ (pass -v focal-270
) or BigBlueButton 3.0.0-alpha.7+ (pass -v jammy-300
) or later on a BigBlueButton server with a public IP and hostname.
Once you have BigBlueButton installed, run sudo apt install bbb-transcription-controller
to install BigBlueButton's transcription service which supports gladia.io.
Next, run sudo bbb-conf --setip <hostname>
where <hostname> is the external hostname of the server (same as was passed to bbb-install.sh). This will update the bbb-transcription-controller configuration.
Next, to enable gladia.io, run the following two commands
sudo yq e -i '.public.app.audioCaptions.enabled = true' /etc/bigbluebutton/bbb-html5.yml
sudo yq e -i '.public.app.audioCaptions.provider = "gladia"' /etc/bigbluebutton/bbb-html5.yml
Next, set the gladia.io API key using the command below, replacing <gladia_api_key> with a glada.io API key obtained above.
sudo yq e -i '.gladia.startMessage = "{\"x_gladia_key\": \"<gladia-api-key>\", \"sample_rate\": 0, \"bit_depth\": 16, \"model_type\": \"fast\", \"endpointing\": 10 }"' /usr/local/bigbluebutton/bbb-transcription-controller/config/default.yml
Restart the BigBlueButton server with bbb-conf --restart
. You will now be able to select a speech-to-text option when joining audio (including auto translate). When one or more users have selected the option, a CC button will appear at the bottom and a Transcript panel will also be available.
Configuration of global settings
The configuration file for the HTML5 client is located in /usr/share/bigbluebutton/html5-client/private/config/settings.yml
. It contains all the settings for the HTML5 client.
Modify the HTML5 client title
All changes to global HTML5 client settings are done in the file above. So to change the title, edit settings.yml
and change the entry for public.app.clientTitle
Configure guest policy
The policy for guest management on the server is is set in the properties file for bbb-web
, which is located at /usr/share/bbb-web/WEB-INF/classes/bigbluebutton.properties
.
You can overwrite the default guest policy in /etc/bigbluebutton/bbb-web.properties
. Just add the value you prefer, save the file and restart BigBlueButton.
# Default Guest Policy
# Valid values are ALWAYS_ACCEPT, ALWAYS_DENY, ASK_MODERATOR
#
defaultGuestPolicy=ALWAYS_ACCEPT
Show a custom logo on the client
Ensure that the parameter displayBrandingArea
is set to true
in bbb-html5's configuration, restart BigBlueButton server with sudo bbb-conf --restart
and pass logo=<image-url>
in Custom parameters when creating the meeting.
Other meeting configs available
These configs can be set in /etc/bigbluebutton/bbb-web.properties
Parameter | Description | Options | Default value |
---|---|---|---|
defaultMeetingLayout | Default Meeting Layout | CUSTOM_LAYOUT, SMART_LAYOUT, PRESENTATION_FOCUS, VIDEO_FOCUS | CUSTOM_LAYOUT overwritable |
defaultMaxUsers | Maximum number of users a meeting can have | Integer (0=disable) | 0 overwritable |
maxUserConcurrentAccesses | Maximum number of sessions that each user (extId) can open simultaneously in the same meeting | Integer (0=disable) | 3 |
defaultMeetingDuration | Duration of the meeting in minutes | Integer (0=disable) | 0 overwritable |
clientLogoutTimerInMinutes | Number of minutes to logout client if user isn't responsive | Integer (0=disable) | 0 |
meetingExpireIfNoUserJoinedInMinutes | End meeting if no user joined within a period of time after meeting created | Integer | 5 |
meetingExpireWhenLastUserLeftInMinutes | Number of minutes to end meeting when the last user left | Integer (0=disable) | 1 |
endWhenNoModerator | End meeting when there are no moderators after a certain period of time | true/false | false overwritable |
endWhenNoModeratorDelayInMinutes | Number of minutes to wait for moderator rejoin before end meeting | Integer | 1 overwritable |
userInactivityInspectTimerInMinutes | User inactivity audit timer interval | Integer (0=disable) | 0 |
userInactivityThresholdInMinutes | Number of minutes to consider a user inactive. | Integer | 30 |
userActivitySignResponseDelayInMinutes | Number of minutes for user to respond to inactivity warning before being logged out | Integer | 5 |
webcamsOnlyForModerator | Allow webcams streaming reception only to and from moderators | true/false | false overwritable |
meetingCameraCap | Per meeting camera share limit | Integer (0=disable) | 0 overwritable |
userCameraCap | Per user camera share limit | Integer (0=disable) | 3 overwritable |
maxPinnedCameras | Maximum number of cameras pinned simultaneously | Integer (0=disable) | 3 |
muteOnStart | Mute the meeting on start | true/false | false overwritable |
allowModsToUnmuteUsers | Gives moderators permission to unmute other users | true/false | false overwritable |
allowModsToEjectCameras | Gives moderators permission to close other users' webcams | true/false | false overwritable |
usersTimeout | Timeout (millis) to remove a joined user after her/him left meeting without a rejoin | Integer | 60000 (60s) |
waitingGuestUsersTimeout | Timeout (millis) to remove guest users that stopped fetching for her/his status | Integer | 30000 (30s) |
enteredUsersTimeout | Timeout (millis) to remove users that called the enter API but did not join | Integer | 45000 (45s) |
breakoutRoomsRecord | Enable Recordings in Breakout Rooms | true/false | false overwritable |
breakoutRoomsPrivateChatEnabled | Enable private chat in Breakout Rooms | true/false | true overwritable |
notifyRecordingIsOn | Notify users that recording is on | true/false | false overwritable |
learningDashboardCleanupDelayInMinutes | Number of minutes that Learning Dashboard will be available after the end of the meeting | Integer (0=disable) | 2 overwritable |
serviceEnabled | API enabled | true/false | true |
allowRequestsWithoutSession | Allow requests without JSESSIONID to be handled | true/false | false |
supportedChecksumAlgorithms | List of supported hash algorithms for validating checksums | sha1, sha256, sha384, sha512 | sha1, sha256, sha384, sha512 |
allowRevealOfBBBVersion | Allow endpoint with current BigBlueButton version | true/false | false |
recordFullDurationMedia | Controls whether media should be captured on their full duration if the meeting's recorded property is true | true/false | false |
overwritable
: Config will be overwritten if the param is present in the API/create
request
Passing user metadata to the client on join
The HTML5 client supports a list of parameters that can be added to the join
API call which modify the look and default behaviour of the client. This list is accurate as of BigBlueButton version 2.2.17 (build 937). These parameters override the global defaults set in settings.yml
. As the parameters are passed on call to join, it allows for some powerful customization that can vary depending on which user is joining the session.
Useful tools for development:
- A tool like (https://meyerweb.com/eric/tools/dencoder/) is useful in the encoding-decoding process for the fields expecting encoded value passed (see below).
- The API mate allows you to directly experiment with these user metadata. To use the API mate, run the following command on your BigBlueButton machine:
sudo bbb-conf --secret
. This creates a link for you with your secret as a parameter so you can get started experimenting right away.
Application parameters
Parameter | Description | Default value |
---|---|---|
userdata-bbb_ask_for_feedback_on_logout= | If set to true , the client will display the ask for feedback screen on logout | false |
userdata-bbb_auto_join_audio= | If set to true , the client will start the process of joining the audio bridge automatically upon loading the client | false |
userdata-bbb_client_title= | Specifies a string to set as the HTML5 client title | BigBlueButton |
userdata-bbb_force_listen_only= | If set to true , attendees will be not be able to join with a microphone as an option (does not apply to moderators) | false |
userdata-bbb_listen_only_mode= | If set to false , the user will not be able to join the audio part of the meeting without a microphone (disables listen-only mode) | true |
userdata-bbb_skip_check_audio= | If set to true , the user will not see the "echo test" prompt when sharing audio | false |
userdata-bbb_skip_check_audio_on_first_join= | (Introduced in BigBlueButton 2.3) If set to true , the user will not see the "echo test" when sharing audio for the first time in the session. If the user stops sharing, next time they try to share audio the echo test window will be displayed, allowing for configuration changes to be made prior to sharing audio again | false |
userdata-bbb_skip_echotest_if_previous_device= | (Introduced in BigBlueButton 3.0) If set to true , the user will not see the "echo test" if session has valid input/output devices stored previously | false |
userdata-bbb_override_default_locale= | (Introduced in BigBlueButton 2.3) If set to de , the user's browser preference will be ignored - the client will be shown in 'de' (i.e. German) regardless of the otherwise preferred locale 'en' (or other) | null |
userdata-bbb_hide_presentation_on_join | (Introduced in BigBlueButton 2.6) If set to true it will make the user enter the meeting with presentation minimized (Only for non-presenters), not permanent. |
| userdata-bbb_direct_leave_button
| (Introduced in BigBlueButton 2.7) If set to true
it will make a button to leave the meeting appear to the left of the Options menu. | false
| | false
|
Branding parameters
Parameter | Description | Default value |
---|---|---|
userdata-bbb_display_branding_area= | If set to true , the client will display the branding area in the upper left hand corner | true |
Shortcut parameters
Parameter | Description | Default value |
---|---|---|
userdata-bbb_shortcuts= | The value passed has to be URL encoded. For example if you would like to disable shortcuts, pass %5B%5D which is the encoded version of the empty array [] | See settings.yml |
Kurento parameters
Parameter | Description | Default value |
---|---|---|
userdata-bbb_auto_share_webcam= | If set to true , the client will start the process of sharing webcam (if any) automatically upon loading the client | false |
userdata-bbb_preferred_camera_profile= | Specifies a preferred camera profile to use out of those defined in the settings.yml | none |
userdata-bbb_enable_video= | If set to false , the client will display the webcam sharing button (in effect disabling/enabling webcams) | true |
userdata-bbb_record_video= | If set to false , the user won't have her/his video stream recorded | true |
userdata-bbb_skip_video_preview= | If set to true , the user will not see a preview of their webcam before sharing it | false |
userdata-bbb_skip_video_preview_on_first_join= | (Introduced in BigBlueButton 2.3) If set to true , the user will not see a preview of their webcam before sharing it when sharing for the first time in the session. If the user stops sharing, next time they try to share webcam the video preview will be displayed, allowing for configuration changes to be made prior to sharing | false |
userdata-bbb_skip_video_preview_if_previous_device= | (Introduced in BigBlueButton 3.0) If set to true , the user will not see a preview of their webcam before sharing it if session has a valid input device stored previously | false |
userdata-bbb_mirror_own_webcam= | If set to true , the client will see a mirrored version of their webcam. Doesn't affect the incoming video stream for other users. | false |
userdata-bbb_fullaudio_bridge= | Specifies the audio bridge to be used in the client. Supported values: sipjs , fullaudio . | fullaudio |
userdata-bbb_transparent_listen_only= | If set to true , the experimental "transparent listen only" audio mode will be used | false |
Presentation parameters
Parameter | Description | Default value |
---|---|---|
userdata-bbb_force_restore_presentation_on_new_events= | If set to true , new events related to the presentation will be pushed to viewers. See this PR for more information | false |
Whiteboard parameters
Parameter | Description | Default value |
---|---|---|
userdata-bbb_multi_user_pen_only= | If set to true , only the pen tool will be available to non-participants when multi-user whiteboard is enabled | false |
userdata-bbb_presenter_tools= | Pass in an array of permitted tools from settings.yml . The options we support are: select , hand , draw , eraser , arrow , text , note , rectangle and *more . Example: userdata-bbb_presenter_tools=['eraser', 'note'] will allow only the eraser and note tools. | all enabled |
userdata-bbb_multi_user_tools= | Pass in an array of permitted tools for non-presenters from settings.yml . The options we support are: select , hand , draw , eraser , arrow , text , note , rectangle and *more . Example: userdata-bbb_multi_user_tools=['eraser', 'note'] will allow only the eraser and note tools. | all enabled |
*more: More includes the rest of the extra shapes, those being: rectangle , ellipse , diamond , triangle , trapezoid , rhombus , hexagon , cloud , star , oval , x-box , check-box , arrow-left , arrow-up , arrow-down , arrow-right , frame , line , laser . |
The use of *more will include all shapes listed above.
Theming & styling parameters
Parameter | Description | Default value |
---|---|---|
userdata-bbb_custom_style= | URL encoded string with custom CSS | none |
userdata-bbb_custom_style_url= | This parameter acts the same way as userdata-bbb_custom_style except that the CSS content comes from a hosted file | none |
userdata-bbb_prefer_dark_theme= | This parameter makes the dark theme come in as default | false |
Layout parameters
Parameter | Description | Default value |
---|---|---|
userdata-bbb_auto_swap_layout= | If set to true , the presentation area will be minimized when a user joins a meeting. (Removed in 2.6) | false |
userdata-bbb_hide_presentation= | If set to true , the presentation area will not be displayed. (Removed in 2.6) | false |
userdata-bbb_hide_presentation_on_join= | If set to true , the presentation area will start minimized, but can be restored | false |
userdata-bbb_show_participants_on_login= | If set to false , the participants panel (and the chat panel) will not be displayed until opened. | true |
userdata-bbb_show_public_chat_on_login= | If set to false , the chat panel will not be visible on page load until opened. Not the same as disabling chat. | true |
userdata-bbb_hide_nav_bar= | If set to true , the navigation bar (the top portion of the client) will not be displayed. Introduced in BBB 2.4-rc-3. | false |
userdata-bbb_hide_actions_bar= | If set to true , the actions bar (the bottom portion of the client) will not be displayed. Introduced in BBB 2.4-rc-3. | false |
userdata-bbb_default_layout= | The initial layout on client load. Options are: CUSTOM_LAYOUT , SMART_LAYOUT , PRESENTATION_FOCUS , VIDEO_FOCUS . If none is provided, the meeting layout (preset in bbb-web) will be used. Introduced in BBB 3.0.0-alpha.5. | none |
Examples
Changing the background color of the HTML client
You can change the background color of the HTML5 client with the following stylesheet:
:root {
--loader-bg: #000;
}
.overlay--1aTlbi {
background-color: #000 !important;
}
body {
background-color: #000 !important;
}
You can add this code to a hosted .css file and pass userdata-bbb_custom_style_url=https://someservice.com/customStyles.css
Alternatively (for simple changes) you can achieve the same without hosted file.
You can try this in API-MATE - you need the non-encoded version of the CSS
userdata-bbb_custom_style=:root{--loader-bg:#000;}.overlay--1aTlbi{background-color:#000!important;}body{background-color:#000!important;}
If you are adding this to a join-url you need to URI encode the string (see a sample encoding tool above)
%3Aroot%7B--loader-bg%3A%23000%3B%7D.overlay--1aTlbi%7Bbackground-color%3A%23000!important%3B%7Dbody%7Bbackground-color%3A%23000!important%3B%7D
Send client logs to the server
Step-by-step instructions for how to configure logs from clients to be logged in a server log file are located in Administration -> Configuration Files
Collect feedback from the users
The BigBlueButton client can ask the user for feedback when they leave a session. This feedback gives the administrator insight on a user's experiences within a BigBlueButton sessions.
To enable the feedback and it's logging to your server, run the following script.
#!/bin/bash
HOST=$(cat /etc/bigbluebutton/bbb-web.properties | grep -v '#' | sed -n '/^bigbluebutton.web.serverURL/{s/.*\///;p}')
HTML5_CONFIG=/usr/share/bigbluebutton/html5-client/private/config/settings.yml
PROTOCOL=$(cat /etc/bigbluebutton/bbb-web.properties | grep -v '#' | grep '^bigbluebutton.web.serverURL' | sed 's/.*\(http[s]*\).*/\1/')
apt-get install -y nginx-full
yq e -i '.public.clientLog.external.enabled = true' $HTML5_CONFIG
yq e -i ".public.clientLog.external.url = \"$PROTOCOL://$HOST/html5log\"" $HTML5_CONFIG
yq e -i '.public.app.askForFeedbackOnLogout = true' $HTML5_CONFIG
mkdir -p /etc/bigbluebutton/nginx/
cat > /etc/bigbluebutton/nginx/html5-client-log.nginx << HERE
location /html5log {
access_log /var/log/nginx/html5-client.log postdata;
echo_read_request_body;
}
HERE
cat > /etc/nginx/conf.d/html5-client-log.conf << HERE
log_format postdata '\$remote_addr [\$time_iso8601] \$request_body';
HERE
# We need nginx-full to enable postdata log_format
if ! dpkg -l | grep -q nginx-full; then
apt-get install -y nginx-full
fi
touch /var/log/nginx/html5-client.log
chown bigbluebutton:bigbluebutton /var/log/nginx/html5-client.log
The feedback will be written to /var/log/nginx/html5-client.log
, which you would need to extract and parse. You can also use the following command to monitor the feedback
tail -f /var/log/nginx/html5-client.log | sed -u 's/\\x22/"/g' | sed -u 's/\\x5C//g'
There used to be an incorrect version of the script above on the docs. If you face any issues after updating it, refer to this issue for solutions.
Other configuration changes
Extract the shared secret
Any front-end to BigBlueButton needs two pieces of information: the hostname for the BigBlueButton server and its shared secret (for authenticating API calls). To print out the hostname and shared secret for you BigBlueButton server, enter the command bbb-conf --secret
:
$ bbb-conf --secret
URL: https://bigbluebutton.example.com/bigbluebutton/
Secret: 577fd5f05280c10fb475553d200f3322
Link to the API-Mate:
https://mconf.github.io/api-mate/#server=https://10.0.3.132/bigbluebutton/&sharedSecret=577fd5f05280c10fb475553d200f3322
The last line gives a link API-Mate, an excellent tool provided by Mconf Technologies (a company that has made many contributions to the BigBlueButton project over the years) that makes it easy to create API calls.
Change the shared secret
To validate incoming API calls, all external applications making API calls must checksum their API call using the same secret as configured in the BigBlueButton server.
You’ll find the shared secret in /etc/bigbluebutton/bbb-web.properties
securitySalt=<value_of_salt>
To change the shared secret, do the following:
- Generate a new Universal Unique ID (UUID) from a UUID generator such as at http://www.somacon.com/p113.php. This will give a long string of random numbers that will be impossible to reverse engineer.
- Run the command
sudo bbb-conf --setsecret new_secret
.
Note: If you have created you own front-end or are using a third-party plug-in to connect to BigBlueButton, its shared secret; otherwise, if the shared secrets do not match, the checksum for the incoming API calls will not match and the BigBlueButton server will reject the API call with an error.
Install callback for events (webhooks)
Want to receive callbacks to your application when an event occurs in BigBlueButton? BigBlueButton provides an optional web hooks package that installs a node.js application listens for all events on BigBlueButton and sends POST requests with details about these events to hooks registered via an API. A hook can be any external URL that can receive HTTP POST requests.
To install bbb-webhooks
$ sudo apt-get install bbb-webhooks
For information on configuring bbb-webhooks, see bbb-webhooks.