Professional Documents
Culture Documents
Home (/)
FAQ
OVERVIEW
1.1
(/overview/overview.html) FAQ
Architecture Welcome
(/overview/architecture.html) What if I dont find my answer here
INSTALL
Why is this project called BigBlueButton
Why is it spelled BigBlueButton (and not Big Blue Button)
Install
(/install/install.html) Where is the source
What is the open source license used in BigBlueButton
GreenLight
(/install/green- Will BigBlueButton always stay open source
light.html) BigBlueButton Development Process
bbb-conf
Development Priorities
(/install/bbb- BigBlueButton Committer
conf.html) BigBlueButton Development Process
LTI (/install/lti.html) 1. Planning
Configuration Files 2. Design
(/install/configuration- 3. Development
files.html) 4. Beta Testing
Client Configuration 5. Release Candidate
(/install/client- 6. General Release
configuration.html) Contributing to BigBlueButton
DEVELOP
How can I contribute
Im not a developer, can I still contribute
Setup Development
Environment Why do I need to sign a Contributor License Agreement to contribute source code
(/dev/setup.html) Submission of a pull request
Accessibility Submission of a feature
(/dev/accessibility.html) Testing your submission
WebHooks Coding conventions
(/dev/webhooks.html) Installation
Branding What are the minimum hardware requirements for the BigBlueButton Server
(/dev/branding.html) What are the minimum bandwidth requirements for the BigBlueButton Server
Localization Can I install BigBlueButton on a shared hosting server, such as GoDaddy
(/dev/localization.html) Can I install BigBlueButton on EC2
API (/dev/api.html) OS Requirements
Ubuntu
Recording
(/dev/recording.html) CentOS
Windows
SUPPORT
OS X
Road Map
Support for Mobile Devices
(/support/road-
Android
map.html)
iOS
FAQ
Bandwidth Requirements
(/support/faq.html)
What are the bandwidth requirements for running a BigBlueButton server
Release Notes
What are the minimum bandwidth requirements for a user
(/support/release-
Is wired connection better than wireless
notes.html)
Configuration
HTML5 (DEV)
What are the minimum requirements for the BigBlueButton client
HTML5 Project How many simultaneous users can BigBlueButton support
Structure
Where is the admin interface for BigBlueButton
(/html/project-
Networking
structure.html)
How do I change the hostname of my BigBlueButton server
HTML5 Coding
We recommend running BigBlueButton on port 80
Practices
(/html/coding- What ports must be open for external users to connect to BigBlueButton
practices.html) Does BigBlueButton support tunneling
HTML5 Overview Can I provide secure access to BigBlueButton
(/html/html5- Front Ends
overview.html) Does BigBlueButton come with a front end?
HTML5 Design Can I run multiple virtual classrooms in a single BigBlueButton server
(/html/html5- How do I setup new classrooms in BigBlueButton
design.html)
How do I integrate BigBlueButton with my own server
HTML5 Server Configuration
Development
Does BigBlueButton oer secure collaboration
(/html/html5-
Does BigBlueButton oer permanent sessions
dev.html)
Using BigBlueButton
LABS (DEV)
Screen Sharing
HTML5 Video What is needed to run desktop sharing
(/labs/html5- Can I share a specific window when sharing my desktop
video.html)
Presentations
WebRTC Screen Can I upload Microsoft Oce documents to BigBlueButtonn
Share (/labs/webrtc-
Will my animations in PowerPoint convert when uploading to BigBlueButton
screen-share.html)
I uploaded a document but some fonts are missing after conversion
Deskshare TLS over
I cant upload a presentation from Linux
Stunnel
Does BigBlueButton support mulit-user whiteboard
(/labs/deskshare-
tls.html) Video
Im on Ubuntu and I cant share my webcam
Captioning
(/labs/captioning.html) Voice Conference
Why cant others hear me in the voice conference
Why do others only hear part of my audio
Why is there an echo in the voice conference
How do I get the best audio
Why is the audio not synced with the video
Chat
How can I copy all chat messages to the clipboard
Record and Playback
Where is the record button
What parts of the session does BigBlueButton record
What browsers support playback
What is the disk space usage for storing 1 hour of recordings
Can I see the total time of the session
How do I modify the default playback format
How do I download a recorded session
Developing for BigBlueButton
Setup
Setting up the Dev environment
Where can I download the latest build
I want to develop from Windows
What if I want to develop for the Client only
My client fails at startup with RSL error; Error 2035:URL Not Found
Troubleshooting
Connectivity
Users on Chrome get randomly disconnected
Users on Windows 7 get disconnected after a minute
Client hangs loading at 100%
Users do not appear in the listeners window
Why cant I accept the Flash Security Dialog on Linux
Audio
When I click on the headset icon, nothing happens
I have 2 microphones and want to choose one to join the voice conference
Some users are experiencing audio problems
Presentation
Why cant I resize my portrait document
Desktop Sharing
Development
Using the API examples, I get a java.lang.NullPointerException when trying to join a room
Administration
bbb-conf check reports Host IP does not match BigBlueButton
UTF characters wont display correctly in the Client
Which log files should I check for errors
Other Questions
When will feature X be implemented
How can I donate money to the project
How do I change the brand of BigBlueButton
Welcome
Welcome to the BigBlueButton projects Frequently Asked Questions (FAQ).
We (the core developers) created this FAQ to quickly answer common questions around installation, configuration, and
using BigBlueButton. If you are a developer, youll find lots of answers herein that have been collected from discussions
on our mailing lists.
The developer mailing list has over 2000 users, so before you post:
All of the core BigBlueButton contributors subscribe to all three mailing lists. Please dont cross post to more than one
list you are only causing more eort to answer all the threads.
We started BigBlueButton as an open source project, and we intend to keep it that way. One of the main goals we had
was to create a large open source community around the project. To further this goal, we are in the process of putting
together an independent not-for-profit BigBlueButton organization (http://bigbluebutton.org/2010/07/12/bigbluebutton-
foundation/) (similar to the Eclipse Foundation) to oversee and accelerate the growth of the BigBlueButton project.
As with any open source project, the continued growth of the community depends on the quality of the software. The
quality of the software, in turn, depends on the developers involved and the process we use to build a release.
Development Priorities
The core group of BigBlueButton committers have adopted an open source development process with the following
priorities (in order):
Stability
Usability
Features
Modularity
Scalability
It cannot be overstated that the projects focus is primarily on stability. For a university or college to deploy
BigBlueButton for live classes, or for a commercial company to embed BigBlueButton into their product, the software
must be extremely stable. To that end, youll notice from the previous release notes that we tend to spend months
testing each release candidate before issuing a release.
Achieving stability is no easy task. BigBlueButton itself is built upon many great open source projects (such as
FreeSWITCH, redis, Akka, red5, and others) with sub-systems responsible for sharing of slides, video, audio, text, and
desktop sharing. The stability of the product today is a direct result of the committers, the development process, and th
community all working together. We release on quality, not dates.
Usability ranks a close second. Without a simple-to-use (we like to call it elegant) user interface, BigBlueButton would
neither be adopted, nor viewed as a compelling alternative to more complex (and proprietary) equivalents.
Features are the focus of each release, and we focus on the features that our core market (on-line learning) will benefit
from most.
Modularity enables components of BigBlueButton to be developed, refactored, and upgraded in parallel. During each
release we invariably rewrite parts of BigBlueButton to improve modularity. Much of this is invisible to end-users, but it
keeps the technical debt low so we can innovate faster with each release.
Scalability is important as our market grows. We designed BigBlueButton to be a highly collaborative system. Weve
seen examples where there have been 21 webcams shared in a session! If we wanted to handle hundreds of
simultaneous users, we would have restricted the sharing of webcams and audio channels. There is no such restriction
in BigBlueButton.
BigBlueButton Committer
Like many open source projects, at the core of the project are a team of developers that have responsibility for core
development and overall quality of the project. The current committers are as follows:
Committers:
The committers have earned this responsibility through years of contribution to BigBlueButton and to related open
source projects (i.e. red5). In particular, we very much respect Richards seven year-plus eort to create BigBlueButton.
As the Lead Architect for our project, he has the final say.
The committers are very active in the support and mentoring of other developers in the bigbluebutton-dev
(https://groups.google.com/forum/#!forum/bigbluebutton-dev) mailing list. The BigBlueButton project also participated
the 2010 Google Summer of Code (Google paid for two students to work on the project).
The committers group is not closed. Any developer that wishes to become a committer can achieve it through
participation. The decision of expanding the committers group rests with the committers.
1. Planning
During the planning process, the committers decide on the main features for a release by reviewing the BigBlueButton
Road Map (/support/road-map.html) along with all starred issues and, in particular, issues marked with tags stability
(https://github.com/bigbluebutton/bigbluebutton/issues?q=is%3Aissue+is%3Aopen+label%3AStability) and usability
(https://github.com/bigbluebutton/bigbluebutton/issues?
utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20label%3Ausability).
We review the features according to the development priorities for our target market (see When will feature X be
implemented?).
2. Design
After the planning phase, each feature for the release is assigned an issue in the BigBlueButton Issue Tracker (if it does
not already have one). This allows the community to track the progress of each release. See List of open
issues/enhancements (https://github.com/bigbluebutton/bigbluebutton/issues).
For small features, especially bug fixes, the associate issue provides a sucient record for coordinating and tracking th
development eort.
For more complex features, such as record and playback, API changes, or creation of an HTML5 client, the lead
developer for the feature would post specifications to BigBlueButton-dev for review and comment.
3. Development
During the development phase, the committers hold bi-weekly (and sometimes weekly) calls as development proceeds
towards beta.
Each committer works on a fork of the BigBlueButton Master. When a feature is ready for commit, the committer sends
pull request to merge the work into the Master branch. Since the core group is still small and the committers are
communicating during development, Richard and others know when any major pull requests are coming.
The submitter of the pull request is responsible for ensuring the feature works correctly against Master. For pull request
that make major changes, the submitter must provide with the pull request additional documentation to make it easy fo
others to review:
Each commit is reviewed by another committer who is familiar as well with the area of the product. Any substantive
commit to the core is reviewed by Richard Alam, BigBlueButtons CTO.
If the reviewer of the update believes it will negatively aect stability or usability, the request will be rejected and the
developer will need to rework the request based on feedback by the reviewer.
Once an update has been committed, it is tested by other developers in the latest build. In that way a build will iterate
through development towards beta. The release stays in development until all core development is finished and all
obvious bugs have been fixed.
Before the beta release, the documentation for installation, setting up of the development environment, and overview o
new features are all updated for the release. Its ready for others to install and test.
4. Beta Testing
Once a release is moved to beta, the public Ubuntu packages are updated so others in the BigBlueButton community
can begin installing and using the build.
The product will go through one (or more) betas until the community reports no more major bugs. Additional work that
occurs during this phase includes:
We strive to have very stable beta releases. As the release moves through iterations in beta, members of the community
will start to run BigBlueButton on production servers. (Yes, some run it for months on production.)
When all the bugs are fixed and issues are closed, the product moves to Release Candidate.
5. Release Candidate
For us the release candidate is done which means issue a release is changing only the label of the build.
We tend to wait for (at least) two weeks of community use before we change the label to release. Again, stability is
paramount for reaching a release candidate build.
During the stage at release candidate the core committers monitor the mailing lists, twitter, and feedback from member
to look for any bugs or issues that would impact the delivery of general release.
Many times during the beta and release candidate process we are asked What is your release date?. Our motto is w
release on quality, not dates.
6. General Release
After a (roughly) two week period in which no one has reported any issues for a release candidate, the committers
change the label (such as 0.9.0-RC to 0.9.0) and announce the release (see release announcement for 0.9
(https://groups.google.com/d/msg/bigbluebutton-dev/TAJ369nPZU4/7DK-TH3JWocJ) and release announcement for
1.0 (https://groups.google.com/d/msg/bigbluebutton-dev/8E3AYUcO6Uw/m5r2xgPeBgAJ)).
Contributing to BigBlueButton
How can I contribute
BigBlueButton exists because many developers have contributed their time and expertise to its development.
At first glance at the underlying architecture, BigBlueButton may seem complex, but its not really once you get to know
the system. The BigBlueButton client is written in ActionScript. The BigBlueButton server components are written in a
combination of Java, Grails, and Scala. You dont need to learn all these languages to help out, but you should be very
comfortable programming in Java as ActionScript, Grails, and Scala are all similar to Java.
Before you can contribute as a developer, you need to invest some time into understanding BigBlueButtons architectur
(/overview/architecture.html#architecture-overview), components (http://bigbluebutton.org/components/), and how to
setup a development environment (/dev/setup.html). The source code for BigBlueButton is hosted at github
(https://github.com/bigbluebutton/bigbluebutton), so youll need to understand how git works (http://git-scm.com/book
and the workflow for distributed software development.
Like other open source projects, a good place to start is to try fixing an open issue
(https://github.com/bigbluebutton/bigbluebutton/issues). Weve tagged a few issues as FirstProject
(https://github.com/bigbluebutton/bigbluebutton/issues?q=is%3Aissue+is%3Aopen+label%3AFirstProject) to make it
easy for you to find those issues that are both (relatively) simple to fix, but would be meaningful to BigBlueButton.
Some bugs are more important than others. Stability and usability issues are very important to the BigBlueButton
community.
Any contribution by external members for inclusion into BigBlueButton will be reviewed by one (or more) of the
committers. The process for submission and review depends on the complexity of the contribution and requires that yo
have signed a Contributor License Agreement.
Once we receive the signed Contributor Agreement, we can review your submission for inclusion in BigBlueButton.
process for submission depends on whether its fixing a bug (submitting a pull request) or whether its an enhancement
(submitting a feature).
The ideal patch submission has all the above true, which essentially means you have built a relationship of trust with
other BigBlueButton developers and have been visible on your willingness to contribute your skills to the project.
1. You have forked BigBlueButton on GitHub and submitted the patch as a pull request (this makes it much easier for a
committer to review and incorporate your patch).
2. You have signed a committers agreement (/support/faq.html#why-do-i-need-to-sign-a-contributor-license-
agreement-to-contribute-source-code) so there is no ambiguity that your contributions may be released under an
open source license.
3. Your submission is LGPL V3 (unless it modifies existing code that is under a dierent license).
GitHub provides some good help (http://help.github.com/) in the above steps, and there is an excellent Pro Git book
(http://git-scm.com/book/en/v2) by Scott Chacon available on-line.
Submission of a feature
Some of the items in our issue tracker are enhancements to the core product. If you are interested in contributing an
enhancement, your chances of acceptance are greatly improved if the following are true:
Like other open source projects, the participation of a committer is central to the above process as they will take the
responsibility for reviewing and signing o on your contribution.
We are continuously trying to incorporate more automated testing into the BigBlueButton development process, such a
using TestNG (http://testng.org/doc/index.html).
We know that the most important part of any submission is the ability for others to test that it works correctly. Any
documentation, sample code, or unit tests that you can provide will greatly reduce the eort of the committer to review
your submission.
Coding conventions
Take a look at the existing code in BigBlueButton and follow it as an example of the projects coding and documentatio
conventions.
For code written in Java, we follow the Java Coding Convention (http://www.oracle.com/technetwork/java/codeconvtoc
136057.html) with minor changes. We will be documenting those changes in this wiki.
For documentation of code method especially those classes that provides an API to other classes should be
documented using the JavaDoc (http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html)
format.
Installation
What are the minimum hardware requirements for the
BigBlueButton Server
See before you install (/install/install.html#before-you-install).
OS Requirements
Ubuntu
BigBlueButton requires Ubuntu 16.04 64-bit. See Install BigBlueButton (/install/install.html).
We (the core developers) have not installed BigBlueButton on any other version of Ubuntu. It probably wont work.
CentOS
There is no support for CentOS.
We do have experience with CentOS. In April, 2010, we released BigBlueButton 0.64 (/support/release-
notes.html#release-0.64:-lickety-split) with RMP packages for CentOS 5.4. However, based on our experience of
developing, building, and testing both Ubuntu and CentOS packages, we stopped supporting RPM packages after that
release.
Why?
In a nutshell: quality. We found it very dicult to test and maintain packaging for both RPM based systems (primarily
CentOS) and Ubuntu. Rather than try to maintain them both and have them kind of work, which leads to many, many
posts in our forums when users encounter diculties with an install, we decided to invest heavily in testing and
maintaining the Ubuntu packages. They are now very solid and well tested.
If you really want support for CentOS, you can contact one of the following companies for commercial support
(http://bigbluebutton.org/commercial-support). Any financial contribution you make for updating and maintaining the
CentOS packages will directly benefit other CentOS users in the community.
You can see further discussion on the support for CentOS in issue 1379
(https://github.com/bigbluebutton/bigbluebutton/issues/1379). (Update: We are getting increasing interest in RPMs for
BigBlueButton. We may be updating this section in the future.)
Windows
While technically it should be possible to manually install each of components (red5, tomcat7, nginx, LibreOce, etc.)
needed to run BigBlueButton on Windows, we havent tried it, nor have we tested it.
If you are a brave soul and want to take a BigBlueButton server and manually install the equivalent components (and
configuration files) onto a Windows server, it should technically be possible. However, beware, no one who has tried thi
has lived to post a success message to our mailing list :-).
OS X
There is no native installation for Mac OS X.
The easiest way to get your own BigBlueButton server under OS X is to install VMWare Fusion, create a Ubuntu 14.04
64-bit VM, and install BigBlueButton using the installation instructions (/install/install.html).
iOS
This work is underway. See presentations from Developer Summit IX (https://youtu.be/aw1mjgzXSK0).
Bandwidth Requirements
What are the bandwidth requirements for running a BigBlueButton server
Youll need good upstream and downstream bandwidth from the server. We recommend (at least) 100 MBits/second
bandwidth in both directions.
When sharing a webcam as a moderator, BigBlueButton lets you select 320x240, 640x480, or 1280x720. For bandwidt
calculations, each resolution corresponds (roughly) to a .25 Mbits/sec, 0.40 Mbits/sec, and 0.60 Mbits/sec video stream
respectively.
For example, if you have a room with 5 users, each sharing their webcam at 320x240, then you can calculate the
bandwidth usage as follows:
Y = .25 Mbits/sec
W = amount of webcams that are streaming
U = amount of users that are watching
For calculations:
For example, with 5 users in a room with 5 webcams streaming, the bandwidth calculation is as follows:
in: 5 * .25 = 1.25 Mbits/sec incoming bandwidth needed to the server, or 3600 * 1.25 = 4.5 GBits/hr
out: 5 * (5-1) * .25 = 5 Mbits/sec outgoing bandwidth needed from the server, or 3600 * 5 = 18 Gbits/hr
If youd have a typical classroom situation one presenter broadcasting their webcam to 30 remote students, the
calculation is as follows:
Screen sharing sharing takes the most bandwidth. The actual bandwidth for desktop sharing depends on the size of the
area chosen by the presenter (full screen and region) and how often their screen updates. At the low end, if the
presenters screen is largely idle, the screen sharing application will transmit about 0.2 Mbits/sec; at the high end, if the
presenters screen is updating frequently, the BigBlueButton server could transmit 1.0 Mbits/sec. For a session with N
users, BigBlueButton server would also transmit N desktop sharing streams (the presenter gets a stream as well for the
Screen Sharing Preview window).
A VoIP connection to the BigBlueButton server takes roughly 0.04 Mbits/sec receiving and 0.04 Mbits/sec transmitting
for each user. The bandwidth for VoIP grows linearly with number of users. For example, if there are 20 students in a
classroom, then the bandwidth requirements for the server to support VoIP is 20 * 0.04 Mbits/sec = 0.8 Mbits/sec.
the user joins as Listen Only, they only receive audio (not transmit it).
From the perspective of the users bandwidth needs, if a student is broadcasting their webcam and microphone they
require a minimum (roughly) 0.3 Mbits/sec (.25 + .04) upstream bandwidth. If the student is in a session with four other
people that are all broadcasting their webcams as well, the student will require the roughly 1 Mbits/sec incoming
bandwidth for the 4 * 0.25 = 1 Mbits/sec incoming webcams and 0.04 Mbits/sec for the incoming audio.
The BigBlueButton server will lower the bandwidth to a user if their bandwidth is insucient to receive all stream. For
example, in the scenario above where there are 5 students in a session, each sharing a webcam, if 4 students have
sucient bandwidth to receive all incoming webcam streams, their clients will show roughly the same quality of video.
one of the students is on a lower bandwidth, then they will get less frequent updates on the video streams and may get
lower quality of audio. The user who is on lower bandwidth does not aect the streaming to other users.
These are not hard and fast numbers, as it depends on the activity of the viewer. If the viewer is not broadcasting any
webcam, the amount of upstream bandwidth used would be less than 0.5 Mbits/sec.
A good way for users to check their bandwidth is to visit speedtest.net (http://speedtest.net/). The results from
speedtest.net give the users actual bandwidth. This actual number is important because a user may report that their IS
provides them 0.5 Mbits/sec upstream bandwidth; however, speedtest.net may report an actual number that is much
lower. The dierence may be throttling by the ISP and background activity on their computer (such as background
downloads, file sharing clients, etc).
For presenters, we recommend as much upstream bandwidth as possible. For example, if the presenter shares their
desktop, then BigBlueButtons desktop sharing will attempt to publish their desktop updates as quickly as possible to
the server.
Using public WiFi is not always best. It may be OK for surfing the web, but the latency and packet loss might be
insucient for real-time transmission of audio or video.
Configuration
What are the minimum requirements for the BigBlueButton
client
For bandwidth, we recommend 1Mbits download and 0.5 Mbits upload speed. Users can test their actual bandwidth
using speedtest.net (http://speedtest.net/).
For hardware, we recommend a dual-core CPU with at least 2G of memory. We recommend any operating system
capable of running the latest versions of Google Chrome and Mozilla FireFox.
For browser, We recommend running either FireFox or Chrome. Why? Both browsers provide excellent support for web
real-time communications (WebRTC). Safari, IE, and Edge will work as well, but FireFox and Chrome will deliver better
audio in lower bbandwidth conditions.
In short, if the user is having any problems (such as audio is garbled or they are periodically getting disconnected), we
recommend trying either FireFox or Chrome. If the problems persist, its likely an issue with their network. BigBlueButto
will give them notifications (/09overview.html#configuration-notifications) to help troubleshoot.
If the presenter needs to share their desktop, then we recommend running FireFox.
For example, if after testing your server under load, you find it can support 150 simultaneous users, then we recommen
running up to three sessions of 50 users, 6 x 12, 12 x 6, etc.
Of course, there is a big dierence between running BigBlueButton on a single core Celeron CPU vs. a quad core X345
processor. The latter will be able to hold more simultaneous users than the former.
Members of our community periodically host stress tests for BigBlueButton, which gives others a data point on what a
particular server was able to handle. Take any stress test with a grain of salt. There are many variables at play:
In BigBlueButton, it also depends on what users do in a session. If you have a session with 20 users and all share their
webcam (yes, this is possible) will generate 400 streams (10 incoming streams to the server and 390 outgoing streams)
If you have a session with 20 users and all share their microphones, there will be a two-way audio stream for each user
to the BigBlueButton server; whereas if 19 of the users join the Listen Only stream, then there is only two two-way audi
streams to the BigBlueButton server (one for the presenter and the other for the listen only stream).
If you are unsure of how many users your server will support, we strongly recommend you first stress test your own
server with a group of users to get real-world data.
To test your own server, have five people login and have each open multiple browser tabs, each tab logging into
BigBlueButton and joining the audio conference. With 5 friends, you can simulate 10, 20, 30, etc. users. Youll find once
the CPU reaches 80%, the audio starts to degrade. When the audio starts to degrade, youve found the maximum
number of users for your server.
Additionally, you can see commercial support (http://bigbluebutton.org/commercial-support/) for help in stress testing
your server.
The most common way to use BigBlueButton is to use an existing application that has a plugin. See list of integrations
(https://bigbluebutton.org/integrations/).
Networking
How do I change the hostname of my BigBlueButton server
If you change the hostname (or IP address) of your BigBlueButton server, you can easily change all the related
BigBlueButton configuration files using the bbb-conf tool (/install/bbb-conf.html).
Prior to 0.8, bbb-conf would let you configure BigBlueButton to run on a dierent port, but that lead to a number of
problems that are not immediately obvious:
1. BigBlueButton client cannot use HTTP tunneling if the BigBlueButton server is not listening on port 80
2. Port conflicts with existing applications
3. Resource contention with existing applications
To an experienced system administrator, the above problems are not insurmountable, but most people setting up
BigBlueButton are not experienced system administrators. Therefore, changing the port results in clients being unable t
connect, BigBlueButton doesnt load, and/or performance is less than expected (because of resource contention).
Sometimes these problems do not manifest themselves immediately. In the past, weve had people posting to our
forums describing how their BigBlueButton server occasionally has problems or does not let users connect. In some
cases, after a lengthy exchange of posts/e-mails back and forth, they would grant us temporary remote access to their
server to try and figure out the error in BigBlueButton. Only then would we discover the server is running multiple web
applications that are conflicting with BigBlueButtons configuration, significantly reducing the resources available to
BigBlueButton or both. In these cases, there was no error with BigBlueButton, but in the configuration.
We understand that administrators want to run multiple applications on a single server. This makes sense when you are
running multiple web-based applications. If a web application returns a web page in 350 milliseconds instead of 250
milliseconds due to resource contention, the perceptual dierence to the user is minimal. At worst, the user will think
your web application is a little slow, but it still works.
However, BigBlueButton is a real-time application processing voice and video. The human ear is very attuned to delays
in audio. If BigBlueButton is returning audio packets later than normal or the audio becomes garbled because the CPU
is unable to process the audio packets quickly enough due to resource contention, a delay in audio is much more
perceptible to a user than a delay in loading a web page.
For the above reasons, we recommend you setup BigBlueButton on a dedicated server listening to port 80. We also
recommend you not run any other applications (such as plesk) on the same server.
For UDP ports, clients must be able to connect on a port within the range 16384-32767 for WebRTC-based audio.
There are some security mechanisms in BigBlueButton. For example, each API request made to the BigBlueButton
server is first validated by the server using a checksum computed from a shared secret (see API Security Model
(http://docs.bigbluebutton.org/dev/api.html#api-security-model). When using WebRTC for audio (FireFox or Chrome) th
browser will first use Datagram Transport Layer Security (see DTLS
(https://en.wikipedia.org/wiki/Datagram_Transport_Layer_Security)) to provide communications privacy for datagram
protocols and then, once the media stream is established, transmit the encrypted audio packets using Secure Real-Tim
Protocol (see SRTP (https://en.wikipedia.org/wiki/Secure_Real-time_Transport_Protocol)). You can also add HTTPS
(/install/install.html#configuring-https-on-bigbluebutton) to your BigBlueButton server.
By saying there is some security mechanisms BigBlueButton, does this mean BigBlueButton oers secure
collaboration? No. (No system is really secure, there are only levels of security). It does mean there are opportunities to
make BigBlueButton more secure with each release. To understand how we prioritize features for a release (and how yo
can influence the priorities), see When will feature X be implemented? (/support/faq.html#when-will-feature-x-be-
implemented).
Front Ends
Does BigBlueButton come with a front end?
Yes. You can install GreenLight (/install/green-light.html) on your server. GreenLight lets users quickly and easily create
meetings, invite others, join meetings, and manage the recordings.
Alternatively, if you have a bit of programming skills, you can create your own set of room by modifying this Demo Page
(http://demo.bigbluebutton.org/demo/demo3.jsp) on a BigBlueButton server.
to define your own modules (such as changing the name to Community Room - 1). When modifying demo3.jsp , you
dont have to restart any processes: you can modify the source file, then reload the demo page and youll see the
updated content.
If you want users to open your demo page by default, you can modify
/var/www/bigbluebutton-default/index.html
The best approach is to see how others have integrated and adapt their code to your integration. Dont you just love
open source!
Server Configuration
Does BigBlueButton oer secure collaboration
There has been no eort to make the communications in BigBlueButton secure. For example, BigBlueButton does not
use https for the URLs, nor does it use RTMPS for the sending of data.
All API requests must have a checksum that is computed using a share secret, but otherwise there is no security oere
in BigBlueButton.
This is by design. Why is this the case? This design makes it easy for system administrators to upgrade or replace a
BigBlueButton server without migrating/updating any database. As an analogy, the BigBlueButton server works like a
web server. When loading content from web server, you dont tell a web server I need to load a file at 2:00 PM
tomorrow; rather, you just load a file when needed. The web server responds to the request and, when finished, it
forgets about the request and moves onto the next.
Its similar with the BigBlueButton server. The lifespan of a session on the BigBlueButton server begins when a front-en
sends a create API request to the BigBlueButton server. Once a room is created (the create request succeeded),
users can join the session and interact within the session. The session ends (and is cleared from the servers memory)
when the last person leaves, whereupon BigBlueButton clears the session from memory.
Using BigBlueButton
Screen Sharing
What is needed to run desktop sharing
Only the presenter needs to have Java installed to share their desktop. You can test if your system has Java installed
using the following link (http://java.com/en/download/help/testvm.xml). To download Java onto your computer, visit the
Java download page. (http://www.java.com/en/download/index.jsp)
Presentations
Can I upload Microsoft Oce documents to BigBlueButtonn
Yes. BigBlueButton uses LibreOce 4.3 for converting Microsoft Oce documents into PDF for display in
BigBlueButton.
If possible, for best results, save your Word or PowerPoint document as PDF. If you are using Oce 2007, we
recommend using Microsofts free download to enable Oce 2007 to save any document to PDF: download link
(http://www.microsoft.com/downloads/details.aspx?FamilyID=4d951911-3e7e-4ae6-b059-
a2e79ed87041&displaylang=en).
If you upload a Word or Power Point document that has special fonts, such as Chinese language, the document must
first be converted by LibreOce into PDF. Unless youve configured the LibreOce server running within BigBlueButton
to have the necessary fonts, then you will see empty spaces (or boxes) for the missing fonts.
To add the Japanese fonts, enter the following commands on the BigBlueButton server.
These steps trigger the opening of the File Open dialog box by a user action, which seems to work better than the
automatic display of the File Open dialog box when there is currently no presentation loaded.
We have multi-user whiteboard as an open enhancement request (see Extend whiteboard to enable multiple users at th
same time (https://github.com/bigbluebutton/bigbluebutton/issues/2055)).
Video
Im on Ubuntu and I cant share my webcam
See Ubuntus documentation for Webcam Troubleshooting
(https://help.ubuntu.com/community/Webcam/Troubleshooting).
Voice Conference
Why cant others hear me in the voice conference
If others in the voice conference dont hear you when you speak, its likely that Flash has picked the wrong microphone
on your computer. You can change this with the following steps:
You see a volume indicator next to the drop down for choosing a microphone. Try selecting a dierent microphone.
When you select the active microphone, youll immediately see activity in the volume indicator when you speak.
Close this Flash settings dialog and others in the voice conference should now hear you.
You can also change the settings on FreeSWITCH to lower default threshold for audio. To lower the threshold, switch to
the root account, then edit
/opt/freeswitch/conf/autoload_configs/conference.conf.xml
<profile name="wideband">
>
<param name="energy-level" value="100"/>
/>
In any event, we always recommend that you have your remote users use a headset with microphone. This will ensure
the best audio in a session.
If a remote user is using a laptop with a built-in microphone, you should not hear an echo. However, if two remote users
are using laptops with built-in microphones and neither is using a headset and both are sitting close to each other (clos
enough for the microphone in one laptop to pickup the audio from the speakers in the other laptop), then you will hear
an echo. The reason is the built-in echo cancellation only works with the audio coming from the host laptop the audio
coming from the second laptop will be picked up as an external audio source.
If a student is causing echo, the best way to solve this problem, if you are logged in as a moderator, is to mute the user
by clicking the microphone icon to the left of their name.
Overall, the best solution is ask all users to use a headset this will ensure no background noise or echo.
Both these browsers support web real-time communications (WebRTC) audio. BigBlueButton will use WebRTC for audi
if the user is on FireFox or Chrome browser; otherwise, it will fall-back and use the Flash-based audio (which does not
transmit as eciently and may have a greater latency).
The processing of packets diers as well. For video, on the server, red5 does not do much with the video packets it
just re-broadcasts them to all the clients currently subscribed to the video stream. Its basically a straight pass through
of the packets. On the client, BigBlueButton uses the default h.264 to encode/decode the packets. The encoding
process introduces slight delay as the codec must capture a few video frames before encoding.
You can experiment with turning o the h.264 codec to reduce video delay. The result of this change is the video quality
will reduce and the bandwidth required for video will double. To turn o the h.264 codec in BigBlueButton 0.9.x (and
earlier), edit /var/www/bigbluebutton/client/conf/config.xml and set enableH264 = "false" .
For audio, the latency depends on whether the user is transmitting their audio using web real-time commuications
(WebRTC) in FireFox or Chrome or transmitting using Flash. WebRTC provides the lowest latency. For more information
see how do I get the best audio (/support/faq.html#how-do-i-get-the-best-audio).
Chat
How can I copy all chat messages to the clipboard
Right-click within the chat area and choose the option Copy All Text.
When instructed through the API call, the BigBlueButton server will record all of the meeting, from the time the first
person joins to when the last person leaves. A meeting may also end when it reaches its duration or the end
(/dev/api.html#end) is called on the meeting.
In BigBlueButton, the audio from a recorded session is encoded into Vorbis (http://en.wikipedia.org/wiki/Vorbis), an ope
source audio format that is not patent encumbered. Playback of Vorbis audio is supported in FireFox and Chrome, but
not IE and Safari.
BigBlueButton will playback the webcams from a session using the WebM container, which, thanks to Google, provides
a high-quality open source video codec VP8. Playback of video in VP8 is supported by FireFox and Chrome, but not IE
and Safari. See HTML5 video (http://en.wikipedia.org/wiki/HTML5_video) Wikipedia article.
The file sizes are for a one hour session. When a recorded session ends, BigBlueButton archives all the raw content,
then runs the recording scripts to create a publish format (presentation).
For audio + webcam, the additional storage is for saving each individual webcam stream. A one hour webcam stream a
the default resolution (320x240) is 20M.
For audio + deskshare, the additional storage is for the desktop sharing stream (there will only be one stream at any on
time). A one hour desktop sharing stream is 125M.
Playback
For playback, the audio, webcams, and desktop share are processed into a single playback file WebM (VP8 Codec).
For audio only, the WebM file is 5.4M. There is an additional Vorbis Audio File that is 5M.
For audio + webcam only, there is a single webM file that is 51M
In Chrome, the audio playback component shows only the current time index for the playback. To see the overall length
of the session, you can scrub to the end of the audio after the audio file has loaded.
In FireFox, the audio playback component shows both the current time index and total time of the audio file.
/usr/local/bigbluebutton/core/scripts/process/presentation.rb
/usr/local/bigbluebutton/core/scripts/publish/presentation.rb
By modifying presentation.rb, you could, for example, exclude chat from the layout, add themes or colors, change the
layout of the HTML5 web page, add a download link to the content, etc.
In contrast, BigBlueButton does not create a video file for playback. Video files for a three hour lecture can get very
large. Instead, BigBlueButton creates an HTML5 page that references PNG images and audio, and time indexes the
PNG images against the audio to match their display in the session. The result is the source playback files are very sma
and can be hosted on any web server. The drawback is there will be a pause for the browser to download all this
content, but, once downloaded, there is no more load on the web server.
Once you have the development environment setup, you can mount the VM drive to Windows. When you launch Eclips
of Flex Builder, simply create your workspace on the VM drive. This way youll be developing in Windows with the sourc
on the VM. Once youre ready to deploy, switch to the VM console and deploy using ant. Weve found this is the easies
way to develop for BigBlueButton.
You need to create the following 2 directories on your BBB server, if theyre not already there:
/var/bigbluebutton/conference-mock-default/room-mock-default and change the owner to tomcat7:tomcat7 (chown -R
tomcat7.tomcat7 /var/bigbluebutton/conference-mock-default)
My client fails at startup with RSL error; Error 2035:URL Not Found
This is related to localization. Before you launch your client, you need to first separately run the ant localization task. Th
task is included in your client directory in the build.xml file. It needs to run separately because otherwise Java will run o
of memory if all tasks are ran together. You can run the localization task from the command line or from Flex if youve se
up ant to work with Flex Builder. You can find instructions on how to get Ant working with Flex here
(http://livedocs.adobe.com/flex/3/html/help.html?content=anttasks_1.html).
Troubleshooting
Connectivity
Users on Chrome get randomly disconnected
When running BigBlueButton in Google Chrome, if the user is connected to both wired and wireless at the same time,
and the wireless state changes (such as disconnecting or switching between wireless networks), Chrome sends a
network change event to BigBlueButton and drops the users connection.
If this occurs, the solution is to either disable wireless networking while using BigBlueButton or switch to FireFox.
FireFox uses Adobe Flash Plugin whereas Google Chrome bundles the flash plugin within the browser.
To run this command, youll need to enter cmd in the program search field (available when you click the start menu).
When you type cmd, youll see the command prompt appear. Right-click and choose Run as Administrator.
This usually occurs if they install BigBlueButton on a server (or download the VM), then place the server on a local
network with no connectively to the internet.
If the BigBlueButton client is able to connect to download the additional libraries, you can subsequently disable interne
connection and use BigBlueButton on a closed network.
Next, BigBlueButton must successfully connect to FreeSWITCHs SIP port and FreeSWITCHs Event Socket Layer.
resolve connection problems, see question below.
The solution is use the Flash security manager to add an exception for the BigBlueButton host. Doing so will no longer
have Flash prompt for access to the microphone/webcam.
Now launch the BigBlueButton client. You should no longer be prompted for the Flash Security Dialog.
Audio
When I click on the headset icon, nothing happens
First, as with most errors, run
If you are running BigBlueButton on EC2, then note that EC2 uses both a public and private IP address. For example, o
an EC2 instance if you type ifconfig youll see that eth0 is bound to an internal private IP address.
I have 2 microphones and want to choose one to join the voice conference
When youre inside the client, right-click, go to Settings > Microphone Icon > select your microphone, and talk to see if
works by checking the volume bar.
When using Flash-based audio, BigBlueButton uses 16 KHz wideband speexs audio codec, which is a high-quality
audio codec that compresses very well. If you run a BigBlueButton server within a LAN environment, you can get a
sense of the audio quality. It should sound much richer than a plain ordinary telephone system (which is 8 Khz audio).
To setup BigBlueButton for external users, such as on-line classes, we recommend running BigBlueButton on a
dedicated (non-virtual) server with 100Mbits/sec bandwidth to/from the server. Furthermore, we remote users have a
minimum upstream bandwidth of 0.5 Mbits/sec and downstream bandwidth of 1.0 Mbits/sec.
When remote users experience audio problems, check the following areas:
Login to your BigBlueButton server during a session and watch its CPU using the command top . When running top
press 1 to see a list of all CPUs and their load. You should see Cpu0, Cpu1, etc. If you are running a quad-core CPU
with hyper-threading (recommended), youll see eight virtual CPUs.
The overall CPU usage should stay below 70%. If the overall CPU usage consistently stays above 70%, youll likely get
audio troubles as the BigBlueButton server will not have enough available CPU to keep up with the audio packets.
If your BigBlueButton server is virtualized, there is no guarantee how much CPU time your server gets. If you are sharin
the CPU of your BigBlueButton server with other virtualized servers on the host, it will take longer for BigBlueButton to
process audio packets. This setup may also aect audio quality.
To test your servers bandwidth, youll need a second server on the internet that has at least as good bandwidth as you
server. Make sure the second server is external and uses the ISP internet connection. When there is no significant
network activity on your BigBlueButton server (such as no active BigBlueButton sessions), try transferring a large file
to/from your BigBlueButton server to the second external server using scp . This will give you a rough estimate of the
maximum transfer rates. Check with your ISP if these transfer rates are low.
Next, try monitoring your servers trac during the beginning of a class. There are many Unix commands to monitor
trac, one of which is bmon .
bmon will show you the amount of incoming data (RX rate) and transmitted (TX data) in kilobytes or megabytes, so you
need to multiply by 8 to get bits/sec.
As BigBlueButton users join the audio on your server, you should see both TX and RX numbers increase. If you dont
see these numbers increase when new users join or, for example, when a presenter uploads new slides, or when
someone shares a webcam, etc. then you have hit the bandwidth cap on your server. At this point, the audio for all user
will start to degrade as there is insucient bandwidth for new users or any common operations (such as uploading
slides).
For getting a better estimate of the amount of bandwidth required for your users, see this FAQ entry.
You may have a dedicated server with sucient bandwidth, but if a remote users internet connection is poor, their aud
quality will not be good.
We recommend that users have 0.5 Mbits/sec upload speed and 1.0 Mbits/sec download speed. Of course, these are
not hard numbers, and BigBlueButton will certainly work with less bandwidth, but if your clients have bandwidth in this
range, they should experience good audio.
To test a users actual internet bandwidth, have them visit http://speedtest.net/. The results at http://speedtest.net/ will
give a fairly accurate test of the users upload and download speeds. If these numbers are much less than 0.5 Mbits/se
upload speed and 1.0 Mbits/sec download speed, their audio will be poor. One quick check is to ask users to turn o
any file transfer they have in the background (such as bittorrent clients) and run the test again.
Many times, issues with audio quality can be solved with better network connectivity. Check if the user transmitting
audio is on a wireless connection. Have the switch to a wired connection, if possible, or move closer to the wireless
base station.
Also, if the users client takes over a minute to load, they are likely tunnelling through port 80, which will further degrade
the audio.
In general, if all users are encountering audio problems, the issue might be with the BigBlueButton CPU being
overloaded or the bandwidth to the BigBlueButton server is saturated.
If a specific user is having poor audio quality (i.e. only their audio is choppy but everyone else sounds good), have the
individual do a speed test. Furthermore, if possible, if you are in the session with them and can verify their audio is poor
have them cross-check using demo.bigbluebutton.org (which is on a dedicated, high-bandwidth connection).
Specifically, have that user login to one of the sample rooms (http://demo.bigbluebutton.org/demo/demo2.jsp), join the
in the room, and check their audio again. If the audio sounds better, then it might be the users internet connection
to/from your BigBlueButton server is dropping more packets than to/from the BigBlueButton demo server.
Flash restricts applications to use TCP/IP for audio, if the users network connection to the BigBlueButton server is
experiencing packet loss (dropped packets). Their computer will resend dropped packets, which will incur audio
problems if this occurs frequently.
We recommend that users use FireFox or Chrome for transmitting/receiving the best audio. Both these browser suppor
web real-time communications framework.
Presentation
Why cant I resize my portrait document
BigBlueButton is designed so the viewers of the presentation window are always in sync with the presenters view.
not possible for the presenter to point at something and a viewer to say I dont see what you are pointing at.
To keep the presentation windows in sync, when you upload a presentation (landscape or portrait), the size of the
presentation window becomes a ratio of the presentation. You and the viewer may have dierent sized windows, due to
the sizes of your respective monitors, but you both always see the same content.
For landscape documents, the fit to page approach works well. Monitors are landscape, so presenting a landscape
document makes good use of the screen space.
However, for portrait documents, the fit to page approach means that text is usually too small to read. The presenter
can zoom in to a portion of the document, but BigBlueButton does not change the width of the presentation window
itself its keeping that ratio to ensure both presenter and viewer are in sync.
We plan to add a fit to width option in BigBlueButton in a future iteration, one that both keeps the viewers and
presenters in sync, but allows the presenter to better show portrait documents.
Desktop Sharing
Development
Using the API examples, I get a java.lang.NullPointerException when trying to
join a room
Using the API demos, after reconfiguring your networking or changing the hostname, you may see
That error is thrown by line 168 of bbb_api.jsp. Heres the surrounding code
try {
// Attempt to create a meeting using meetingID
String xml = getURL(base_url_create + create_parameters +
"&checksum=" + checksum("create" + create_parameters + salt) );
doc = parseXml(xml);
} catch (Exception e) {
e.printStackTrace(); /* 168 */
}
What happens is that the getURL() command isnt returning valid XML, and that is causing parseXml() to fail and
throw an exception.
The main reason getURL() fails is the URL its passed isnt valid. This URL is built using the variable base_url_create
which is created from the parameters set in bbb_api_conf.jsp, which are located in
/var/lib/tomcat7/webapps/demo/bbb_api_conf.jsp
<%!
// This is the security salt that must match the value set in the
BigBlueButton server
String salt = "<salt>";
// This is the URL for the BigBlueButton server
String BigBlueButtonURL = "http://<your_hostname>/bigbluebutton/";
%>
Whats likely happening is that BigBlueButtonURL isnt resolving to a valid host. You can verify this by using its value to
interactively make an API call from your browser. To do this, enter the following URL in your browser:
http://<your_hostname>/bigbluebutton/api/isMeetingRunning?meetingID=abcdef
Of course, you wont have meeting abcdef running, but you should get back an XML file similar to the following:
<response>
<returncode>
<returncode>FAILED</returncode>
</returncode>
<messageKey>
<messageKey>checksumError</messageKey>
</messageKey>
<message>
<message>You did not pass the checksum security check</message>
</message>
</response>
Now, this URL isnt actually called by your web browser; rather, its called by the BigBlueButton server. So login to your
BigBlueButton server and enter the following command:
wget http://<your_hostname>/bigbluebutton/api/isMeetingRunning?meetingID=abcdef -O -
and see if it again returns a valid XML. If you get back a blank document or a server error, then this is the reason why
you are getting the above exception. You need to change your networking setup or the value of BigBlueButtonURL so
that http://<your_hostname>/bigbluebutton/ correctly resolves on the BigBlueButton server.
Administration
bbb-conf check reports Host IP does not match BigBlueButton
This is really more of a warning than an error. If you are using a DNS name, and that DNS name resolves to the IP
address, or you have an external DNS name that is port forwarded to BigBlueButton, you can safely ignore the warning
Other Questions
When will feature X be implemented
Keep in mind that BigBlueButton is largely built by a group of (very determined) open source developers that volunteer
their time. Some of us work for companies that provide commercial support for BigBlueButton (see
http://bigbluebutton.org/support).
Our goal is to make BigBlueButton the leading open source web conferencing system for on-line learning. Thats no
small task, and weve been working hard on it for over seven years (http://bigbluebutton.org/history/).
Time is a precious commodity. In general, when planning a release, we look at the outstanding issues in the following
order:
1. What are the most important items on our road map (/support/road-map.html) (these features target on-line learning
2. What refactoring/features do the core committers believe are necessary to improve the code
base/maintainability/usability of the product?
3. What features are our community asking to implement (specifically, those not related to distance education, like
control of remote desktop)?
For a detailed breakdown of the items in (1) see our road map (/support/road-map.html). If the feature you are requestin
is not on our road map, you could open a new issue (https://github.com/bigbluebutton/bigbluebutton/issues) and make
a convincing argument that the feature belongs in (1).
Also, if you are a commercial company that builds upon BigBlueButton for your own products, you can engage one of
the companies that provide commercial support (http://bigbluebutton.org/commercial-support/) to accelerate your
feature.
For (2), often well revisit a previously implemented feature to improve its performance or refactor the code. This work
usually occurs when we want to enhance a feature (we usually refactor it when doing so) or add new capabilities (such
as refactoring the underlying messages to support the HTML5 client).
For (3), you have options. BigBlueButton is an open source project: if you (or your organization) want to improve
BigBlueButton, we welcome your contribution. See Contributing to BigBlueButton. If you want to engage other
companies to accelerate the feature, see the companies that provide commercial support
(http://bigbluebutton.org/support).
If you want to help the project financially, then approach some of the companies oering commercial support
(http://bigbluebutton.org/support) for BigBlueButton and engage their services. This creates a healthy ecosystem aroun
the project where companies are encouraged to contribute their resources to improve the project to create a larger poo
of potential customers.
In other words, in the BigBlueButton project, we would rather earn our revenues (were entrepreneurs too!).
In recent releases you can now brand (/dev/branding.html) the BigBlueButton interface. However, the URL shows the
word bigbluebutton. There are a lot of places in the code that need to be manually changed (and tested) to change this
string, and these manual changes would need to be updated (and tested anew) for each new version of BigBlueButton.
From the point of view of the open source project, having the word bigbluebutton in the URL spreads awareness of the
project and increases the community, which benefits everyone. We know that many companies have released products
based on BigBlueButton, and they enjoy the commercial benefits of building on open source, and the project enjoys the
increased awareness. Everyone wins.
Still, from time to time, we see individual posts in our developer mailing list (usually from a commercial company) asking
for help to completely remove all references to BigBlueButton. Rather than have the core developers support such
branding eorts, we believe the best option is to have the individual contact one of the companies that provide
commercial support (http://bigbluebutton.org/support) for BigBlueButton.
Doing this removes the inevitable problems that arise when manual code changes break in a new release thereby
creating a flood of forum posts with the title My branding changes no longer work please help me!!
Most importantly for everyone, the eorts to support a white labeled (http://en.wikipedia.org/wiki/White-label_product)
version of BigBlueButton wont take away from core development, but rather support it.