Welcome

    Welcome to the BigBlueButton project’s 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, you’ll find lots of answers herein that have been collected from discussions on our mailing lists.

    What if I don’t find my answer here

    The BigBlueButton community focuses its support in three mailing lists, each hosted by Google Groups. Each group focuses on a different topic of questions:

    • bigbluebutton-setup – Setup, installation, and configuration questions, such as “How do I configure the BigBlueButton client?”
    • bigbluebutton-users – End user questions, such as “How do I do X with BigBlueButton?”
    • bigbluebutton-dev – All other questions, such as “How do I integrate BigBlueButton with my application?”

    The developer mailing list has over 2000 users, so before you post:

    1. Scan this FAQ to see if your question is answered herein.
    2. Use Google to search for keywords related to your question – there’s a good chance someone might have already asked your question in the Google groups.
    3. If you think you’ve found a bug, first check the issues database to check if it’s already been reported.

    All of the core BigBlueButton contributors subscribe to all three mailing lists. Please don’t cross post to more than one list – you are only causing more effort to answer all the threads.

    Why is this project called BigBlueButton

    The name came from the goal of making the process to setup a virtual classroom as easy as pressing a (metaphorical) big blue button.

    Why is it spelled BigBlueButton (and not Big Blue Button)

    The trademark is written as one word BigBlueButton. Doing so makes it easy for others to use Google to search for information about the project.

    Where is the source

    The BigBlueButton source code is at https://github.com/bigbluebutton/bigbluebutton. As an open source project, you are welcome to fork BigBlueButton and build your own applications upon it.

    What is the open source license used in BigBlueButton

    We use the LGPL license Version 3.0. Some of the open source components we build on use different licenses, such as red5phone uses the GPL license.

    Will BigBlueButton always stay open source

    Yes.

    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 (similar to the Eclipse Foundation) to oversee and accelerate the growth of the BigBlueButton project.

    BigBlueButton Development Process

    There is a very active BigBlueButton community of members on the developer mailing list (over 2000 members and counting!). In the BigBlueButton community at-large all the members, users, developers, educational institutions, and commercial companies are all collaborating together on using and improving BigBlueButton.

    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 project’s 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, you’ll 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 the 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. We’ve 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:

    • Richard Alam, Lead Architect
    • Felipe Cecagno, Client/Server
    • Fred Dixon, Project Manager
    • Anton Georgiev, HTML5 Client
    • Tiago Jacobs, red5
    • Chad Pilkey, Client
    • Calvin Walton, Record and Playback

    Past Committers (fondly remembered):

    • Marco Calderon, Server
    • Jeremy Thomerson, API
    • Denis Zgonjanin, Client
    • Gustavo Salazar, Record and Playback

    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 Richard’s seven year-plus effort 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 mailing list. The BigBlueButton project also participated in 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.

    BigBlueButton Development Process

    Each release cycle goes according to the following steps.

    1. Planning

    During the planning process, the committers decide on the main features for a release by reviewing the BigBlueButton Road Map along with all starred issues and, in particular, issues marked with tags stability and usability.

    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. For example, to track the progress for 0.9.0, see list of issues tagged for 0.9.0.

    For small features, especially bug fixes, the associate issue provides a sufficient record for coordinating and tracking the development effort.

    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.

    For examples of previous posts, see:

    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 a 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 requests that make major changes, the submitter must provide with the pull request additional documentation to make it easy for others to review:

    • What the code does (with reference to the associated issue)
    • What changes were made to implement the feature/fix the bug
    • Document of design changes

    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, BigBlueButton’s CTO.

    If the reviewer of the update believes it will negatively affect 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 of new features are all updated for the release. It’s 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:

    • Localization of the product
    • Updating and completing all documentation
    • Updating packaging so it installs without errors, both on a new install and an upgrade from a previous version

    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 members 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 “we 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 (sample release announcement for 0.8, and release announcement for 0.9).

    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 it’s 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 don’t 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 BigBlueButton’s architecture, components, and how to setup a development environment. The source code for BigBlueButton is hosted at github, so you’ll need to understand how git works and the workflow for distributed software development.

    Like other open source projects, a good place to start is to try fixing an open issue. We’ve tagged a few issues as FirstProject to make it easy for you to find those issues that are both (relatively) simple to fix, but would be meaningful to BigBlueButton.

    You can also browse the bugs by labels: Stability - Usability - Performance - Localization - Research. You could also try tackling one of the enhancements to BigBlueButton.

    Some bugs are more important than others. Stability and usability issues are very important to the BigBlueButton community.

    I’m not a developer, can I still contribute

    Don’t worry if you are not a proficient developer – there are many ways to help out. You can become proficient in the installation and configuration of a BigBlueButton server. Each month, there are many new users in bigbluebutton-setup that need help with setup of BigBlueButton, especially setup behind a firewall. You can contribute a language file. You could point out any errors to this documentation. Such assistance reduces the support load on us and gives us more time to work on improving BigBlueButton.

    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 you have signed a Contributor License Agreement.

    Why do I need to sign a Contributor License Agreement to contribute source code

    Before we can accept contributions to BigBlueButton, we need to ensure there isn’t any ambiguity on the ownership of material committed to the project. Therefore, everyone wishing to send us a pull request for review must have a signed Contributor License Agreement in place. For background on our reasons for doing this, please see http://www.oss-watch.ac.uk/resources/cla.xml.

    To obtain a committer agreement, download BigBlueButton Inc. Contributor Agreement. Except as set out in the agreement, you (and your employer if you have an intellectual property agreement in place) keep all right, title, and interest in your contribution. If you (and your employer) are in agreement with its terms, then sign, scan, and e-mail a copy back to Fred Dixon (ffdixon at bigbluebutton dot org).

    Once we receive the signed Contributor Agreement, we can review your submission for inclusion in BigBlueButton. The process for submission depends on whether it’s fixing a bug (submitting a pull request) or whether it’s an enhancement (submitting a feature).

    Submission of a pull request

    If you want to submit a pull request, your chances of acceptance are greatly improved if the following are true:

    1. You are an active participant in bigbluebutton-dev and have demonstrated an understanding of the product by helping others and participating in discussions on other patches.
    2. Your patch fixes an open issue.
    3. Before submitting your patch, you have announced your intent to bigbluebutton-dev or commented on the issue itself.
    4. You have received positive feedback from a committer on your intent.

    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.

    There are a number of must haves for your submission to be accepted.

    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 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 different license).

    Specifically, for using GitHub, you need to do the following:

    1. Fork BigBlueButton on GitHub
    2. Create a topic branch - git checkout -b my_branch
    3. Push to your branch - git push origin my_branch
    4. Create a Pull Request from your branch

    GitHub provides some good help in the above steps, and there is an excellent Pro Git book 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:

    1. You have had previous pull requests accepted by a committer.
    2. You have posted a message to bigbluebuton-dev mailing list signaling your willingness to work on the enhancement. In your post, you have provided (at minimum) the following: * An overview of the design and implementation of your feature. For examples see: Proposal for Preupload of Documents * An outline of how you intend to test the enhancement. * An estimate of how much time you have to work on the enhancement.
    3. A committer has signaled their intent to work closely with you on the enhancement.

    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 off on your contribution.

    Testing your submission

    Depending on the complexity of your patch or feature, it should be accompanied by test cases or, at minimum, a series of steps to test whether the code is functioning properly.

    We are continuously trying to incorporate more automated testing into the BigBlueButton development process, such as using TestNG.

    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 effort 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 project’s coding and documentation conventions.

    For code written in Java, we follow the Java Coding Convention 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 format.

    For Flex/ActionScript code, follow the AsDoc format.

    Installation

    What are the minimum hardware requirements for the BigBlueButton Server

    As a minimum, we recommend you run BigBlueButton on a dedicated quad-core machine with at least 4 GB of memory and a 2.6+ Ghz processor. For further details see before you install.

    What are the minimum bandwidth requirements for the BigBlueButton Server

    You’ll need good upstream and downstream bandwidth from the server. We recommend (at least) 100 Mbit/second bandwidth in both directions. Having a server with 10 Mbits/sec bandwidth to the internet, for example, will only lead to audio and video issues with users.

    Can I install BigBlueButton on a shared hosting server, such as GoDaddy

    Likely not. First, you need root access to install BigBlueButton. If you have a hosting account that only gives you, for example, FTP access and a cPanel/plesk interface, you will not be able to install BigBlueButton.

    Can I install BigBlueButton on EC2

    Yes. Canonical provides official Ubuntu EC2 AMIs for Ubuntu 14.04 64-bit. To install BigBlueButton on EC2, do the following:

    1. Modify the default security group in (or create a new security group) so you have port 80, 9123, and 1935 open (see FAQ).
    2. Launch a 64-bit “trusty” instance from Canonical’s list of supported AMI. We recommend running BigBlueButton on a c3.xlarge (or greater CPU) instance.
    3. Follow the instructions to install install BigBlueButton.
    4. Update the default configuration to support internal/external IP addresses Audio does not work.

    The IP addresses for an EC2 instance are reset whenever you reboot the instance; however, if you assign the EC2 image an elastic IP address, it will have a consistent IP address that will not change on reboot.

    Also, EC2 gives you a very small root device volume. Some of the directories in BigBlueButton (like log files) can get large and use all the space on the root partition. You’ll want to move over the following three directories from BigBlueButton to an attached EBS volume under /mnt (which by default has 1 GiB):

    sudo bbb-conf --stop
    
    sudo mv /opt/freeswitch/recordings /mnt
    sudo ln -s /mnt/recordings /opt/freeswitch/recordings
    
    sudo mv /usr/share/red5/webapps/video/streams /mnt
    sudo ln -s /mnt/streams /usr/share/red5/webapps/video/streams
    
    sudo /var/log/bigbluebutton /mnt
    sudo ln -s /mnt/bigbluebutton /var/log/bigbluebutton
    
    sudo bbb-conf --start
    

    OS Requirements

    Ubuntu

    BigBlueButton requires Ubuntu 14.04 64-bit. See Install BigBlueButton.

    We (the core developers) have not installed BigBlueButton on any other version of Ubuntu. It probably won’t work.

    CentOS

    There is no support for CentOS.

    We do have experience with CentOS. In April, 2010, we released BigBlueButton 0.64 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 difficult 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 difficulties 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. 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. (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, LibreOffice, etc.) needed to run BigBlueButton on Windows, we haven’t 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 this 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.

    Support for Mobile Devices

    Android

    This work is underway. See presentations from Developer Summit III.

    iOS

    This work is underway. See presentations from Developer Summit III.

    Bandwidth Requirements

    What are the bandwidth requirements for running a BigBlueButton server

    You’ll 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 bandwidth 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:

    • server incoming bandwidth: W*Y
    • server outgoing bandwidth: W*(U-1)*Y (minus one since a broadcaster does not have to subscribe to his own stream)

    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 you’d have a typical classroom situation one presenter broadcasting their webcam to 30 remote students, the calculation is as follows:

    • in: 1*.25 = .25 Mbits/sec incoming, or 3600*.25 = 0.9 GBits/hr
    • out: 1*(30-1)*.25 = 7.25 Mbits/sec outgoing, or 3600*7.25 = 26.1 GBits/hr

    Large “cafe-style chatroom”: 20 viewers, 8 people broadcasting with a webcam:

    • in: 8*.25 = 2 Mbits/sec incoming, or 3600*2 = 7.2 GBits/hr
    • out: 8*(20-1)*.25 = 38 Mbits/sec outgoing, or 3600* = 136.8 Gbits/hr

    Sharing slides takes almost no bandwidth beyond the initial uploading/downloading of slides. When the presenter clicks to show the next slide, the viewers receive a “move next slide” command in their BigBlueButton client, and they load the next slide from the local cache. Chat also takes almost no bandwidth.

    Desktop 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 presenter’s screen is largely idle, the desktop sharing applet will transmit about 0.2 Mbits/sec; at the high end, if the presenter’s 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 their Desktop 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. If the user joins as Listen Only, they only receive audio (not transmit it).

    From the perspective of the user’s 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 insufficient 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 sufficient bandwidth to receive all incoming webcam streams, their clients will show roughly the same quality of video. If 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 affect the streaming to other users.

    What are the minimum bandwidth requirements for a user

    For viewers (students), we recommend users have (at least) 0.5 Mbits/sec – which is 500 Kbits/sec – upstream bandwidth, and (at least) 1 Mbits/sec download bandwidth. The upstream bandwidth is the amount of bandwidth their computer has available to transmit data to the BigBlueButton server.

    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. The results from speedtest.net give the user’s actual bandwidth. This actual number is important because a user may report that their ISP provides them 0.5 Mbits/sec upstream bandwidth; however, speedtest.net may report an actual number that is much lower. The difference 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 BigBlueButton’s desktop sharing will attempt to publish their desktop updates as quickly as possible to the server.

    Is wired connection better than wireless

    Yes. A user may have very good experience with wireless internet, but if others hear their audio as broken or choppy, that user can either move closer to the wireless base station, try a different wireless network, or (best) connect directly to a wired connection.

    Using public WiFi is not always best. It may be OK for surfing the web, but the latency and packet loss might be insufficient 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.

    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 framework (WebRTC). Safari and IE will work as well, but it will use Flash for audio, which is fine, but WebRTC-based audio is better.

    Looking closer at FireFox and Chrome, they have subtle differences.

    Chrome Pros:

    • Excellent support for WebRTC
    • Always has the latest version of Flash
    • Works on Linux (the last supported version of Flash on Linux by Adobe was 11.2)

    Chrome Cons:

    • User may disconnect if computer has multiple network interfaces and one of them changes state
    • User will be unable to launch desktop sharing as of Chrome 42 (though they can temporarily re-enable it)

    FireFox Pros:

    • Excellent support for WebRTC
    • Presenter can launch Java applets

    FireFox Cons:

    • Relies on OS for Flash (could be an out-of-date version of Flash)

    There is no clear winner – both are awesome browsers. In short, if the user is having any problems (such as audio is garbled or they are periodically getting disconnected), we recommend trying both browsers. If the problems persist, it’s likely an issue with their network. BigBlueButton will give them notifications to help troubleshoot.

    If the presenter needs to share their desktop, then we recommend running FireFox.

    How many simultaneous users can BigBlueButton support

    As a rule of thumb, without knowing anything about your server, we recommend running your BigBlueButton with sessions of fifty (50) users or less.

    For example, if after testing your server under load, you find it can support 150 simultaneous users, then we recommend running up to three sessions of 50 users, 6 x 12, 12 x 6, etc.

    See minimum server requirements.

    Of course, there is a big difference between running BigBlueButton on a single core Celeron CPU vs. a quad core X3450 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:

    • Server: CPU memory, disk space, and bandwidth
    • Usage scenarios (# of webcams and use of desktop sharing)
    • Upstream bandwidth from clients
    • Configuration of BigBlueButton
    • Version of BigBlueButton

    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 audio 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. You’ll find once the CPU reaches 80%, the audio starts to degrade. When the audio starts to degrade, you’ve found the maximum number of users for your server.

    If you also want to monitor, there are a number of tools for Ubuntu.

    Additionally, you can see commercial support for help in stress testing your server.

    Where is the admin interface for BigBlueButton

    Early in BigBlueButton’s development history (around 2009), we started to create an admin interface to let administrators create accounts, schedule meetings, configure properties for meetings, etc.

    However, we quickly learned that most installations of BigBlueButton wanted to do one of the following:

    1. Integrate BigBlueButton within their open source application (Joomla, WordPress, Sakai, etc.) and had no use for an administrative application – for example, they wanted to do everything from within WordPress.
    2. Integrate BigBlueButton within their custom web application – they needed an API control to interact with their sessions (create a session, add a user, end a session, etc).
    3. Have a simple stand-alone landing page to create meetings.

    As a result, we stopped building our own admin interface and focused our energies on improving BigBlueButton itself and creating and supporting open source integrations for BigBlueButton with the most popular open source learning and content management systems.

    For a stand-alone landing page, in most cases modifying API demo3.jsp is sufficient. See How do I setup new classrooms in BigBlueButton.

    Voice Conference

    Does BigBlueButton use Asterisk or FreeSWITCH

    BigBlueButton started using Asterisk in the beginning, but over time we switched to FreeSWITCH. As of BigBlueButton 0.8, we stopped testing with Asterisk and now focus on FreeSWITCH. For reasons see: Shifting BigBlueButton to using FreeSWITCH.

    Realistically, today both platforms are very solid. It would be possible to provide support again for Asterisk, but no one in our community has volunteered to take on the project.

    How do I enable background music when there is only one person in the conference

    The music on hold is provided by FreeSWITCH. To enable it, edit confernece.conf.xml (you need to edit it as root).

    sudo vi /opt/freeswitch/conf/autoload_configs/conference.conf.xml
    

    and around line 195 you’ll see

    <!--
          <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)"/>
    -->
    

    Change it to

          <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)"/>
    -->
    
    

    Then restart BigBlueButton

       sudo bbb-conf --restart
    

    and join an audio session. You should now hear music on hold if there is only one user in the session. You can also enable the enter/exit sounds as well in this manner.

    How do I turn off the background noise when no one is speaking

    FreeSWITCH applies 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). To remove the comfort noise, edit /opt/freeswitch/conf/autoload_configs/conference.conf.xml and change

          <param name="comfort-noise" value="true"/>
    

    to

          <param name="comfort-noise" value="false"/>
    

    Then restart BigBlueButton

       sudo bbb-conf --restart
    
    ### How do I forward calls from my Asterisk server to FreeSWITCH in BigBlueButton
    
    Let's assume the following:
    
    

    asterisk server ip: 192.168.1.100 bigbluebutton/freeswitch ip: 192.168.1.200 ~~~

    Changes to your Asterisk server

    Setup your gateway to BigBlueButton/FreeSWITCH. in /etc/asterisk/sip.conf add

    [fs-gw]
    type=peer
    username=fs-gw
    insecure=very
    contactpermit=192.168.1.200/255.255.255.255
    qualify=no
    nat=yes
    host=192.168.1.200
    canreinvite=no
    disallow=all
    allow=ulaw
    

    Route the calls to the gateway. In /etc/asterisk/extensions.conf context where your calls are being handled, forward the calls to the gateway. Here, when someone dials 85001, the call is sent to the fs-gw defined above.

    exten => 85001,1,Dial(SIP/fs-gw/${EXTEN})
    exten => 85001,2,Hangup
    

    Changes to your BigBlueButton/FreeSWITCH server

    In BigBlueButton/FreeSWITCH, make the following changes:

    Lock down so that only Asterisk can forward calls to FreeSWITCH. In /opt/freeswitch/conf/autoload_configs/acl.conf.xml, add the following ACL. We also need to allow BigBlueButton to call into FreeSWITCH, that’s why we add the IP of BigBlueButton/FreeSWITCH into the ACL.

        <list name="asterisk-gw" default="deny">
           <node type="allow" cidr="192.168.1.200/32"/>
           <node type="allow" cidr="192.168.1.100/32"/>
           <node type="allow" cidr="127.0.0.1/32"/>
        </list>
    

    Then we apply the ACL into the profile that receives the calls from external gateways. In /opt/freeswitch/conf/sip_profiles/external.xml, add the ACL under <settings>

      <settings>
        <!-- Apply ACL from asterisk-gw -->
        <param name="apply-inbound-acl" value="asterisk-gw"/>
    ...
    </settings>
    

    To debug, try connecting to FS CLI and increase logging level. Once connected, make your call and see what the logs say.

      cd /opt/freeswitch/bin
      ./fs_cli
    
      Once connected:
      help -- shows the available commands
      console loglevel <level> -- change log level
    
      Ctrl-D to exit
    

    How do I connect BigBlueButton to external FreeSWITCH Server

    BigBlueButton bundles in FreeSWITCH, but you can configure BigBlueButton to use an external FreeSWITCH server.

    First, edit /usr/share/red5/webapps/bigbluebutton/WEB-INF/bigbluebutton.properties

    freeswitch.esl.host=127.0.0.1
    freeswitch.esl.port=8021
    freeswitch.esl.password=ClueCon
    

    Change freeswitch.esl.host to point to your external FreeSWITCH IP address. Change the default freeswitch.esl.password to the ESL password for your server.

    You can use http://strongpasswordgenerator.com/ to generate passwords.

    In your external FreeSWITCH server, edit /opt/freeswitch/conf/autoload_configs/event_socket.conf.xml.

    <configuration name="event_socket.conf" description="Socket Client">
      <settings>
        <param name="nat-map" value="false"/>
        <param name="listen-ip" value="127.0.0.1"/>
        <param name="listen-port" value="8021"/>
        <param name="password" value="ClueCon"/>
        <!-- param name="apply-inbound-acl" value="localnet.auto"/ -->
      </settings>
    </configuration>
    

    Change the listen-ip to your external FreeSWITCH server IP and also change the password to be the same as freeswitch.esl.password.

    Edit /usr/share/red5/webapps/sip/WEB-INF/bigbluebutton-sip.properties

    bbb.sip.app.ip=127.0.0.1
    bbb.sip.app.port=5070
    
    sip.server.username=bbbuser
    sip.server.password=secret
    
    freeswitch.ip=127.0.0.1
    freeswitch.port=5060
    

    Change bbb.sip.app.ip to your BigBlueButton server ip.

    Change sip.server.password to something else.

    Change freeswitch.ip to your external FreeSWITCH ip.

    In your external FreeSWITCH server.

    Edit /opt/freeswitch/conf/directory/default/bbbuser.xml

      <user id="bbbuser">
        <params>
          <!-- omit password for authless registration -->
          <param name="password" value="secret"/>
          <!-- What this user is allowed to access --> 
          <!--<param name="http-allowed-api" value="jsapi,voicemail,status"/> -->
        </params>
    

    Change password to match the password you set in sip.server.password.

    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 .

    We recommend running BigBlueButton on port 80

    We recommend running BigBlueButton on port 80 – specifically, having the nginx server in a BigBlueButton server bind to port 80. In other words, we recommend against running BigBlueButton on port 8081, 8088 or another port.

    Prior to 0.8, bbb-conf would let you configure BigBlueButton to run on a different 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 to connect, BigBlueButton doesn’t load, and/or performance is less than expected (because of resource contention).

    Sometimes these problems do not manifest themselves immediately. In the past, we’ve 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 BigBlueButton’s 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 difference 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.

    What ports must be open for external users to connect to BigBlueButton

    For TCP ports, clients must be able to connect to the BigBlueButton server on port 80 (HTTP), 9123 (Desktop Sharing), and 1935 (RTMP).

    For UDP ports, clients must be able to connect on a port within the range 16384-32767 for WebRTC-based audio.

    Does BigBlueButton support tunneling

    Yes. If a remote user is unable to connect to port 1935, which typically occurs when a remote user’s corporate firewall blocks external access to all other ports except port 80, then their BigBlueButton client will fail to connect to port 1935 and, after about ten seconds, will fall back to tunneling through port 80.

    Tunnelling is not as stable as connecting directly – the BigBlueButton client must make about 10 HTTP requests/second to keep up with the sending/receiving of real-time content. The user will have a more stable connection if their BigBlueButton client can connect directly through port 1935.

    Can I provide external access to a BigBlueButton server behind my firewall

    Yes. A typical scenario is you have BigBlueButton running on an internal computer behind a firewall. You have defined an external hostname, such as external.host.org, that will resolve to the IP address of your firewall. You want external users to access BigBlueButton using that hostname.

    Note: The instructions below require that you use an external hostname (not IP address) for your firewall. If you only have an IP address, you can setup a hostname using a free DNS service such as dny.com.

    First, on your firewall, you need to forward the following TCP/IP and UDP ports to the address of your BigBlueButton server.

    • TCP 80 (HTTP)
    • TCP 9123 (Desktop Sharing)
    • TCP 1935 (RTMP)
    • UDP 16384-32768 (WebRTC)

    If you have configured HTTPS on your BigBlueButton server, then you will need to also forward the following additional ports

    • TCP 443 (HTTPS)
    • TCP 7443 (Web Sockets Secure)

    Here is an example of forwarded ports on the D-Link DIR-665 router (the internal IP address of the BigBlueButton server in this example is 192.168.10.198):

    ports_example

    Next, when the firewall forwards incoming requests to the internal BigBlueButton server at 192.168.10.198, the BigBlueButton server must be listening for these requests. The HTTP headers will identify them as for the server external.host.org, so you must tell BigBlueButton to listen for incoming requests for that hostname (not the internal IP address). Use the following command to change the BigBlueButton configuration files to detect incoming requests to external.host.org.

    sudo bbb-conf --setip external.host.org
    

    Internally, BigBlueButton must be able to call external.host.org to make API requests. In this example, if the internal BigBlueButton server is at 192.168.10.198, add the following line to /etc/hosts (you’ll need to edit this file as root user).

    192.168.10.198 external.host.org
    

    To verify that the BigBlueButton server can access external.host.org, enter the following command

    wget -O - --quiet http://external.host.org/bigbluebutton/api 
    

    This should resolve to:

    <response><returncode>SUCCESS</returncode><version>0.7</version></response> 
    

    Next, to verify that external users can access the BigBlueButton server, try to telnet port 80.

    telnet external.host.org 80
    Connected to external.host.org.
    Escape character is '^]'.
    

    and port 1935

    telnet external.host.org 1935
    Connected to external.host.org.
    Escape character is '^]'.
    

    and port 9123

    telnet external.host.org 9123
    Connected to external.host.org.
    Escape character is '^]'.
    

    If you can connect to the service running on all three ports (nginx, red5, and deskshare), then your external users should be able to connect to BigBlueButton.

    Once BigBlueButton is setup for external access, internal access must also use the external hostname for connecting to the BigBlueButton server. This is because BigBlueButton is now looking for incoming requests from external.host.com not an internal IP address.

    Can I provide secure access to BigBlueButton

    We’ve learned from other projects to be very careful on any statements regarding security. Simply put, BigBlueButton does not offer secure collaboration.

    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. When using WebRTC for audio (FireFox or Chrome) the browser will first use Datagram Transport Layer Security (see DTLS) to provide communications privacy for datagram protocols and then, once the media stream is established, transmit the encrypted audio packets using Secure Real-Time Protocol (see SRTP). You can also add HTTPS to your BigBlueButton server.

    By saying there is some security mechanisms BigBlueButton, does this mean BigBlueButton offers 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 you can influence the priorities), see When will feature X be implemented?.

    Front-ends

    What 3rd party integrations are available

    We provide a number of API demos with BigBlueButton’s install. To modify one of these demos to create your own classrooms, see How to create your own virtual classrooms.

    Also, most people integrate BigBlueButton with an existing system using one of the existing integration modules.

    How do I modify the default landing page

    The default HTML landing page is located in

    /var/www/bigbluebutton-default/index.html
    

    Change this page to create your own landing page.

    How do I modify 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/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 configure BigBlueButton to load a different file. The configuration for location for the default presentation (default.pdf) is stored /var/lib/tomcat7/webapps/bigbluebutton/WEB-INF/classes/bigbluebutton.properties. Specifically, the parameter beans.presentationService.defaultUploadedPresentation.

    How do I change the default locale

    By default, the BigBlueButton client should detect the browser’s locale and use that default language accordingly.

    The default language is English, but you can change that by modifying the value

    localeChain = "en_US";
    

    in bigbluebutton/client/BigBlueButton.html. You can see the list of languages installed with BigBlueButton in the directory /var/www/bigbluebutton/client/locale/.

    How do I change the default presenation

    In the file

    /var/lib/tomcat7/webapps/bigbluebutton/WEB-INF/classes/bigbluebutton.properties
    

    see the setting

    # Default Uploaded presentation file
    beans.presentationService.defaultUploadedPresentation=${bigbluebutton.web.serverURL}/default.pdf
    

    You can change beans.presentationService.defaultUploadedPresentation to point to any valid URL. 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.

    How do I modify the default welcome message

    The default welcome message is built from three parameters: two system-wide parameters and the welcome parameter from the BigBlueButton create API call. You’ll find the two system-wide welcome message in

    /var/lib/tomcat7/webapps/bigbluebutton/WEB-INF/classes/bigbluebutton.properties
    

    as the parameters defaultWelcomeMessage and defaultWelcomeMessageFooter.

    #----------------------------------------------------
    # Default welcome message to display when the participant joins the web
    # conference. This is only used for the old scheduling which will be
    # removed in the future. Use the API to create a conference.
    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). If you change the parameters in bigbluebutton.properties, you must restart BigBlueButton with sudo bbb-conf --restart for the new values to take effect.

    Can I run multiple virtual classrooms in a single BigBlueButton server

    Absolutely. To see an example of this, check out the Join Courses API example. You can modify this demo page to setup your own branded landing page.

    How do I setup new classrooms in BigBlueButton

    If you are using Sakai, Moodle, Drupal, Joomla, Wordpress or other systems that already have a BigBlueButton integration, then installing the integration provides the easiest way to enable your users to access BigBlueButton sessions.

    If you have a bit of programming skills, you can create your own virtual classrooms by modifying this Demo Page on a BigBlueButton server.

    You will find demo3.jsp in the directory /var/lib/tomcat7/webapps/demo/demo3.jsp.

    You can edit the following section

    meeting = new HashMap<String, String>();
    allMeetings.put( "ENGL-2013: Research Methods in English", meeting );	// The title that will appear in the drop-down menu
    	meeting.put("welcomeMsg", 	welcome);			// The welcome message
    	meeting.put("moderatorPW", 	"prof123");			// The password for moderator
    	meeting.put("viewerPW", 	"student123");			// The password for viewer
    	meeting.put("voiceBridge", 	"82013");			// The extension number for the voice bridge (use if connected to phone system)
    	meeting.put("logoutURL", 	"/demo/demo3.jsp");  // The logout URL (use if you want to return to your pages)
    
    

    to define your own modules (such as changing the name to ‘Community Room - 1’). When modifying demo3.jsp, you don’t have to restart any processes: you can modify the source file, then reload the demo page and you’ll see the updated content.

    If you want users to open your demo page by default, you can modify

    /var/www/bigbluebutton-default/index.html
    

    to redirect the users to the demo page.

    How do I integrate BigBlueButton with my own server

    BigBlueButton provides an API for integration with other web-based applications.

    The best approach is to see how others have integrated and adapt their code to your integration. Don’t you just love open source!

    Server Configuration

    Where is the shared secret located

    You’ll find the shared secret (salt) in the file

       /var/lib/tomcat7/webapps/bigbluebutton/WEB-INF/classes/bigbluebutton.properties
    

    Look for the line

       beans.dynamicConferenceService.securitySalt=<value_of_salt>
    

    This is the security salt used for enabling 3rd party plug-ins and external applications to access your BigBlueButton server through it’s API.

    How do I change the shared secret

    To change the security salt, do the following:

    1. 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.
    2. Run the command sudo bbb-conf --setsecret new_salt.

    Note: If you are using a third-party plug-in to connect to BigBlueButton, be sure to use the plug-in’s administrative interface to specify the new value for the shared secret; otherwise, if the shared secrets do not match, the API calls from the third-party plug-in will fail.

    How do I change the maximum allowed size for uploading a presentation

    The default maximum file upload size for BigBlueButton is 30 MB.

    To change it, you need to modify two places: the BigBlueButton client and the nginx configuration.

    To modify the client, you’ll need to edit the client’s config.xml. You need to find the “maxFileSize” attribute and change it to whatever max value you want. If you are using the packaged client edit /var/www/bigbluebutton/client/conf/config.xml. If you have the development environment you need to edit ~/dev/bigbluebutton/bigbluebutton-client/src/conf/config.xml and then rebuild the client.

    Next, change the corresponding limit (again 30 MB) in nginx. Edit the following file

    /etc/bigbluebutton/nginx/web.nginx
    

    and modify the value for client_max_body_size.

           location /bigbluebutton { 
               proxy_pass         http://127.0.0.1:8080; 
               proxy_redirect     default; 
               proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for; 
    
            # Allow 30M uploaded presentation document. 
               client_max_body_size       30m; 
    

    Do a clean restart of BigBlueButton so the cached values are updated. You should now have a different upload limit for uploading presentations from within the BigBlueButton client.

    How do I change the video quality of the shared webcams

    The setting for picture quality of the webcams is in the videoconf module.

    In most cases, you can leave the default settings. However, you can specify the Flash player use the maximum amount of bandwidth (camQualityBandwidth="0") to show a picture of ninety percent quality (camQualityPicture="90").

                            camQualityPicture="70"
    

    To reduce the quality of the picture (and increase the frame rate), lower the value of camQualityPicture. Corresponding, to increase the quality of the picture (and reduce the frame rate), increase the value of camQualityPicture.

    However, as camQualityPicture is already ninety percent, you’ll find that slight increases are not very noticeable in picture quality, but do decrease the frame rate.

    You can change the video quality through the client’s config.xml file, by default located in /var/www/bigbluebutton/client/conf. Scroll down to the entry named VideoconfModule. The value of the videoQuality attribute can be anywhere from 0 to 100. 0 means priority is given to the bandwidth and if bandwidth is low, quality will suffer. Quality of 100 means no video compression will be done at all, and you will get maximum quality at the expense of bandwidth. If the bandwidth is low, the frame rate will suffer.

    For more information see Client Configuration.

    How do I change the /client/BigBlueButton.html portion of the URL

    Using nginx, you can rewrite the incoming URL for /client/BigBlueButton.html to appear as a different link, such as /conference/.

    1. Modify /etc/bigbluebutton/nginx/client.nginx and comment out the following section:
            # BigBlueButton.html is here so we can expire it every 1 minute to
            # prevent caching.
            #location /client/BigBlueButton.html {
            #        root    /var/www/bigbluebutton;
            #        index  index.html index.htm;
            #        expires 1m;
            #}
    
    1. Create the file /etc/bigbluebutton/nginx/rewrite.nginx with the following contents:
    location /client/BigBlueButton.html {
            rewrite ^ /conference permanent;
    }
    
    location /conference {
            alias  /var/www/bigbluebutton/client;
            index BigBlueButton.html;
            expires 1m;
    }
    
    1. Restart nginx with the following command:
       sudo /etc/init.d/nginx restart
    

    Now login to the demo page and you’ll see the URL now shows /conference/ instead of /client/BigBlueButton.html.

    Does BigBlueButton offer secure collaboration

    There has been no effort 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 offered in BigBlueButton.

    Does BigBlueButton offer permanent sessions

    The BigBlueButton server does not support persistent or permanent sessions where users can leave and return the next day, for example, and have their slides and chat messages persist.

    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 don’t 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.

    It’s similar with the BigBlueButton server. The lifespan of a session on the BigBlueButton server begins when a front-end 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 server’s memory) when the last person leaves, whereupon BigBlueButton clears the session from memory.

    How do I always record a meeting

    By default, the BigBlueButton server will produce a recording when (1) the meeting has been created with record=true in the create API call and (2) 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, edit /var/lib/tomcat7/webapps/bigbluebutton/WEB-INF/classes/bigbluebutton.properties and change

    # Start recording when first user joins the meeting.
    # For backward compatibility with 0.81 where whole meeting
    # is recorded.
    autoStartRecording=false
    
    # Allow the user to start/stop recording.
    allowStartStopRecording=true
    

    to

    # 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
    

    Using BigBlueButton

    Desktop Sharing

    What is needed to run desktop sharing

    BigBlueButton uses a Java applet to capture screen updates. BigBlueButton requires Java 7u52 (or later).

    Desktop sharing works for Mac, Unix, and PC platforms.

    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. To download Java onto your computer, visit the Java download page.

    If you can run the above test applet from your browser, you can run the desktop sharing in BigBlueButton. There are no additional requirements (beyond having Flash installed) for viewers to run BigBlueButton and view the presenter’s desktop.

    How can I make desktop sharing faster

    First, a bit of background: to share your screen, BigBlueButton runs a Java applet (Flash can’t see your screen). The Java applet takes a few screen shots each second, divides up each captured screen shot into a checkerboard, and figures out which checkerboard tile is different than the previous screen shot. Those different tiles are then compressed and sent to the BigBlueButton server for broadcast to viewers.

    The compression algorithm is lossless, which means remote viewers see a pixel-for-pixel view of the presenter’s desktop. If the presenter’s screen size is above 1280 x 1024, the applet will scale the screen shot to fit within 1280 x 1024 dimension before dividing it into a checkerboard. This reduces the overall data sent to the server.

    The benefit of the above approach is unlike most commercial web conferencing systems that download a binary file (i.e. DLL) on your windows machine (and then not provide any support for Mac or Unix), BigBlueButton’s desktop sharing runs on Mac, Unix, and PC computers. However, the applet approach is going to be slower than a native code as the applet can only look at the screen as a bitmap – it doesn’t have any concept of what the operating system is actually drawing. And the algorithm is simple: if a tile has changed, send it to the server.

    If the tile is mostly a solid color, it’s compression works very well: the size of the compressed tile is small and is quickly sent to the server. However, for example, if the tile portion is a 32-bit image, it will be larger and will take longer to send to the server.

    The speed of the desktop sharing is largely determined by the upstream bandwidth of the presenter’s computer. Most internet connections provide non-symmetrical bandwidth, which means users have a narrow upstream bandwidth and a larger downstream bandwidth. This narrow upstream bandwidth limits the rate at which the presenter’s computer can send updated tiles to the BigBlueButton server. Running desktop sharing on a LAN is usually (much) faster than over the Internet as the corresponding upstream (and overall) bandwidth is greater.

    There are four options to improving the speed of desktop sharing:

    1) Reduce the amount of data sent to the server

    To reduce the amount of data being sent to the server (and thus increase the refresh rates for desktop sharing), the presenter can do the following:

    1. Share a smaller region of your desktop (this is a good approach if you want to share only a specific window)
    2. Reduce the screen size to 1024x768 or 800x600 (this is in essence similar to sharing a region)
    3. Replace any 32-bit desktop background image with a solid color (this greatly increases the refresh rates when the presenter’s desktop becomes visible)
    4. Lower your screen depth from 32-bit to 16-bit

    2) Increase upstream bandwidth available to desktop sharing

    To increase upstream bandwidth, the presenter can turn off any applications that are using bandwidth, such as file transfer or P2P applications. Turn off sharing of webcam as well.

    3) Improve the algorithm for desktop sharing

    There some open issues for improving the desktop sharing, see 1895.

    4) Improve the architecture for desktop sharing

    Another approach is to explore creating platform specific code that would be downloaded by the Java applet and run natively (this is how commercial web conferencing systems achieve their speed).

    There are lots of opportunities to explore on how to increase the speed of desktop sharing in BigBlueButton. To understand how the BigBlueButton project allocates resources for each release, see When will feature X be implemented?.

    Can I share a specific window when sharing my desktop

    While you can’t choose a specific window, you can share a region of your desktop and place the window within that region.

    Presentations

    Can I upload Microsoft Office documents to BigBlueButtonn

    Yes. BigBlueButton uses LibreOffice 4.3 for converting Microsoft Office documents into PDF for display in BigBlueButton.

    If possible, for best results, save your Word or PowerPoint document as PDF. If you are using Office 2007, we recommend using Microsoft’s free download to enable Office 2007 to save any document to PDF: download link.

    You’ll always get the best results with PDF.

    Will my animations in PowerPoint convert when uploading to BigBlueButton

    Since BigBlueButton must convert your PowerPoint document to PDF (using LibreOffice), none of the animations (visual or audio) will be converted. What you’ll see is a PDF page corresponding to the final state of each slide.

    I uploaded a document but some fonts are missing after conversion

    If you upload a PDF document, all your fonts will come through with the document. In other words, for best results, if possible always create a PDF and upload it for conversion.

    If you upload a Word or Power Point document that has special fonts, such as Chinese language, the document must first be converted by LibreOffice into PDF. Unless you’ve configured the LibreOffice 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.

       sudo apt-get install libreoffice-l10n-ja
       sudo apt-get install fonts-ipaexfont
       sudo /etc/init.d/bbb-office restart
    

    I can’t upload a presentation from Linux

    We’ve noticed that on some UNIX systems, such as Linux (openSUSE 11.2 x64), when you click the ‘upload presentation’ button (lower left-hand of Presentation window), Flash will not let you upload a presentation.

    If you encounter this problem, try the following:

    1. Click ‘upload presentation’
    2. Close the File Open dialog box
    3. Click the (+) button next to the file name for the presentation (the File Open dialog box reappears)
    4. Select a file to upload in the File Open dialog box
    5. Click ‘Open’
    6. Click ‘Upload’

    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.

    Does BigBlueButton support mulit-user whiteboard

    Currently, the presenter is the only person that can annotate the current presentation using whiteboad tools. A moderator can make any user presenter (including themselves).

    We have multi-user whiteboard as an open enhancement request (see Extend whiteboard to enable multiple users at the same time).

    Can I increase the 200 page limit for uploads

    BigBlueButton, by default, restricts uploads to 200 pages. To increase this value, open /var/lib/tomcat7/webapps/bigbluebutton/WEB-INF/classes/bigbluebutton.properties and change the maxNumPages value:

    #----------------------------------------------------
    # Maximum number of pages allowed for an uploaded presentation (default 200).
    maxNumPages=200
    

    After you save the changes to bigbluebutton.properties, restart the BigBlueButton server with

    sudo bbb-conf --restart
    

    Video

    I’m on Ubuntu and I can’t share my webcam

    See Ubuntu’s documentation for Webcam Troubleshooting.

    How do I restrict the webcam to only the presenter’s

    You can restrict sharing of webcam to only the current presenter. To do so, open config.xml in the parameters for videomodule, change the following:

    presenterShareOnly="false"
    

    to

    presenterShareOnly="true"
    

    Voice Conference

    Why can’t others hear me in the voice conference

    If others in the voice conference don’t hear you when you speak, it’s likely that Flash has picked the wrong microphone on your computer. You can change this with the following steps:

    1. Right-click within the BigBlueButton client
    2. Choose “Settings…” from the flash pop-up menu
    3. Click the microphone icon
    4. Try choosing a different microphone from the drop-down list

    You see a volume indicator next to the drop down for choosing a microphone. Try selecting a different microphone. When you select the active microphone, you’ll 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.

    Why do others only hear part of my audio

    FreeSWITCH has automatic audio clipping, which means it will not transmit a speaker’s audio if the volume is too low. If the speaker’s audio is low, FreeSWITCH might take a moment to recognize that someone is speaking before transmitting, causing others to hear your audio only after you have started speaking a few words.

    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
    

    and set energy-level to a lower value (.e.g 100)

       <profile name="wideband">
         <param name="energy-level" value="100"/>
    

    Save the file, then do sudo bbb-conf --restart to restart BigBlueButton.

    Why is there an echo in the voice conference

    In BigBlueButton, we use the built-in acoustic echo cancellation, so in most cases, you should not hear any echo from remote users.

    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 (close 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.

    How do I get the best audio

    We recommend users to use either FireFox or Chrome – both support web real-time communications (WebRTC) audio. BigBlueButton will use WebRTC for audio 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 efficiently and may have a greater latency).

    How to setup an external phone number for the FreeSWITCH server

    FreeSWITCH is a soft switch and can accept incoming phone numbers. In the industry, these incoming phone numbers are called direct inward dialing (DID) numbers. You can obtain a DID from a SIP trunk provider, which is a third-party company that essentially maps a DID (a phone number) to an IP address on the internet. When users dial that phone number, the SIP trunk provider converts the voice call to a digital format (such as µlaw), and authenticates and forwards the call using SIP to an IP address on your BigBlueButton server. SIP stands for “session initiation protocol” and it’s a protocol (like HTTP) for initiating a transfer of data, in this case setting up a two-way audio stream.

    Setting up DIDs involves configuration of FreeSWITCH. If you’ve never done this before, be prepared to read some documentation. It’s not going to be a one or two hour job. See FreeSWITCH documentation. If you want help in setting up DIDs, contact one of the companies offering BigBlueButton support or a SIP Trunk provider.

    Setting up DIDs will give users with poor internet connection the option of dialing into the voice conference using a phone. The trade off is that it will cost money to provide SIP trunking to your FreeSWITCH server.

    If you are hosting your BigBlueButton server in an university, college, or within a commercial company, there may already be a VoIP network setup from which you may be able to obtain a DID.

    Why is the audio not synced with the video

    The audio and video packets go through two separate paths: the audio packets go through FreeSWITCH while the video packets go through red5. There is no synchronization between these paths.

    See architecture overview.

    The processing of packets differs 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. It’s 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 off 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 off the h.264 codec in BigBlueButton 0.9.x (and earlier), edit /var/www/bigbluebutton/client/conf/config.xml and set enableH264 = "false".

                    <module name="VideoconfModule" url="..." 
                           ..
                            enableH264 = "false"
    

    In BigBlueButton 1.0-beta (and later), edit /var/www/bigbluebutton/client/conf/profiles.xml and set <enableH264>false</enableH264> for the video profile you want to modify.

    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.

    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 I make BigBlueButton full screen I can’t enter any text into chat

    By design, Adobe disables keyboard input of Flash applications when they go full-screen.

    This prevents the scenario where a malicious Flash application tries to masquerade as your desktop showing a web browser, for example, with a login screen to your bank account.

    As of BigBlueButton 0.71, we’ve removed the full screen button and instead recommend users make their browser full screen. This has the same effect, but allows you to use your keyboard.

    Record and Playback

    Where is the record button

    In BigBlueButton, the external application that uses the BigBlueButton API can now pass an additional parameter record=true when creating a session. This additional parameter instructs the BigBlueButton server to record the session and make a recording available through subsequent getRecordings calls.

    There is no user interface for the presenter to turn on or turn off a recording.

    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 it’s duration or the end is called on the meeting.

    What parts of the session does BigBlueButton record

    BigBlueButton records all activity in the presentation, chat, webcams, and desktop sharing for playback.

    What browsers support playback

    BigBlueButton supports playback in Chrome and FireFox.

    In BigBlueButton, the audio from a recorded session is encoded into Vorbis, an open 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 Wikipedia article.

    What is the disk space usage for storing 1 hour of recordings

    Storage values for different types of session in BigBlueButton 0.81.

    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).

    Media Shared Archive Publish Total
    audio 111 MB/h 11 MB/h 122 MB/h
    audio + webcam (1 webcam) 131 MB/h 51 MB/h 182 MB/h
    audio + desktop sharing 236 MB/h 73 MB/h 309 MB/h

    Archive

    For audio, the storage of the audio stream is 110 MB/h. The storage is a .wav file

    For audio + webcam, the additional storage is for saving each individual webcam stream. A one hour webcam stream at 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 one 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

    For audio + desktop sharing, there is a single WebM that is 72M.

    Can I see the total time of the session

    The information displayed during playback is browser specific.

    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.

    How do I modify the default playback format

    The ingest and processing scripts, written in Ruby, process the recorded events and media to create a playback option. The default scripts, called presentation.rb (there is a script for processing and publishing), are located in

    /usr/local/bigbluebutton/core/scripts/process/presentation.rb
    /usr/local/bigbluebutton/core/scripts/publish/presentation.rb
    

    BigBlueButton uses popcorn.js, an HTML5 media framework, for playback.

    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.

    How do I download a recorded session

    When looking to download a recorded session, most expect a single link to download the video file.

    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 small 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.

    Developing for BigBlueButton

    Setup

    Setting up the Dev environment

    See Developing BigBlueButton for full instructions.

    Where can I download the latest build

    You can checkout the latest code from Git. See BigBlueButton GitHub repository.

    I want to develop from Windows

    We recommend you setup a Ubuntu 14.04 64-bit VM, using VMWare Fusion or Virtual Box, and then install BigBlueButton on the VM, then install the development environment.

    Once you have the development environment setup, you can mount the VM drive to Windows. When you launch Eclipse of Flex Builder, simply create your workspace on the VM drive. This way you’ll be developing in Windows with the source on the VM. Once you’re ready to deploy, switch to the VM console and deploy using ant. We’ve found this is the easiest way to develop for BigBlueButton.

    What if I want to develop for the Client only

    If you are just working on the client side, you need to edit the file config.xml (located in the src/conf folder) to point to a running instance of BigBlueButton. Change all the IP addresses in the file to the IP of your BBB server or BBB VM. In the entry for the Viewers Module, change the attribute host to host=”conf/join-mock.xml”. This will enable you to launch and test the client directly from the Flex environment, bypassing the Web component of BigBlueButton.

    You need to create the following 2 directories on your BBB server, if they’re 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. This task is included in your client directory in the build.xml file. It needs to run separately because otherwise Java will run out of memory if all tasks are ran together. You can run the localization task from the command line or from Flex if you’ve set up ant to work with Flex Builder. You can find instructions on how to get Ant working with Flex here.

    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 user’s 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.

    Users on Windows 7 get disconnected after a minute

    The default config of Windows 7 (and Vista) does “ICMPv6 Router Solicitation” while running the Flash client. Some routers discard the Teredo packets, thereby causing the BigBlueButton client to disconnect at regular intervals. One solution is to disable Teredo packets in the client by entering the following:

    netsh interface ipv6 set teredo disable
    

    To run this command, you’ll need to enter ‘cmd’ in the program search field (available when you click the start menu). When you type ‘cmd’, you’ll see the ‘command prompt’ appear. Right-click and choose “Run as Administrator”.

    Client hangs loading at 100%

    The BigBlueButton client needs to connect to Adobe for downloading libraries. Clients will hang, if they connect to a BigBlueButton server without internet connectivity.

    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 internet connection and use BigBlueButton on a closed network.

    Users do not appear in the listeners window

    For a user to appear in the listener’s window, the 3rd party application using the BigBlueButton API to create a room must pass a voiceBridge parameter with the create call. See create meeting call. This is done using the built-in API demos

    Next, BigBlueButton must successfully connect to FreeSWITCH’s SIP port and FreeSWITCH’s Event Socket Layer. To resolve connection problems, see question below.

    Why can’t I accept the Flash Security Dialog on Linux

    On some versions of Linux desktop when loading the BigBlueButton client, the user is unable to accept the Flash security dialog asking for permissions to access the computer’s microphone and webcam.

    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.

    To add an exception, do the following.

    1. Open the following URL in a browser Flash Security Manager settings. (This will open the security manager settings for the local computer).
    2. Click on the tab with screen showing an eye (Web Privacy Settings).
    3. Look through the list for the hostname for your BigBlueButton server.
    4. Click ‘Always Allow’ radio button.

    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

       sudo bbb-conf --check
    

    To see if it can determine configuration errors.

    If you are running BigBlueButton on EC2, then note that EC2 uses both a public and private IP address. For example, on an EC2 instance if you type ifconfig you’ll see that eth0 is bound to an internal private IP address.

    Here’s a sample output: ~~~ eth0 Link encap:Ethernet HWaddr 12:31:33:22:25:c2 inet addr:10.242.78.44 Bcast:10.242.7.255 Mask:255.255.254.0 inet6 addr: fe80::1034:33ff:fd02:23c2/64 Scope:Link UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1 RX packets:4004469 errors:0 dropped:0 overruns:0 frame:0 TX packets:5024657 errors:0 dropped:0 overruns:0 carrier:0 collisions:0 txqueuelen:1000 RX bytes:642594447 (642.5 MB) TX bytes:2670592958 (2.6 GB) ~~~

    See audio is not working for how to resolve this.

    I have 2 microphones and want to choose one to join the voice conference

    When you’re inside the client, right-click, go to Settings > Microphone Icon > select your microphone, and talk to see if it works by checking the volume bar.

    Some users are experiencing audio problems

    When using FireFox or Chrome, BigBlueButton uses the high-quality OPUS codec that transmits and receives audio packets over UDP.

    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:

    1) Check CPU availability on your BigBlueButton server

    Login to your BigBlueButton server during a session and watch it’s 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), you’ll see eight virtual CPUs.

    The overall CPU usage should stay below 70%. If the overall CPU usage consistently stays above 70%, you’ll 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 sharing 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 affect audio quality.

    2) Check bandwidth provided to BigBlueButton server’s ISP

    To test your server’s bandwidth, you’ll need a second server on the internet that has at least as good bandwidth as your 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 server’s traffic during the beginning of a class. There are many Unix commands to monitor traffic, one of which is bmon.

       sudo apt-get install bmon
    

    bmon will show you the amount of incoming data (RX rate) and transmitted (TX data) in kilobytes or megabytes, so you’ll 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 don’t 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 users will start to degrade as there is insufficient 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.

    3) Check Network connection for clients

    You may have a dedicated server with sufficient bandwidth, but if a remote users’ internet connection is poor, their audio 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 user’s actual internet bandwidth, have them visit http://speedtest.net/. The results at http://speedtest.net/ will give a fairly accurate test of the user’s upload and download speeds. If these numbers are much less than 0.5 Mbits/sec upload speed and 1.0 Mbits/sec download speed, their audio will be poor. One quick check is to ask users to turn off 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 user’s 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, join them in the room, and check their audio again. If the audio sounds better, then it might be the user’s 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 user’s 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.

    4) Check the browser

    We recommend that users use FireFox or Chrome for transmitting/receiving the best audio. Both these browser support web real-time communications framework.

    Presentation

    Why can’t I resize my portrait document

    BigBlueButton is designed so the viewers of the presentation window are always in sync with the presenter’s view. It’s not possible for the presenter to point at something and a viewer to say “I don’t 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 different sized windows, due to the sizes of your respective monitors, but you both always see the same content. As of BigBlueButton 0.71, this mode is equivalent to always running in “fit to page” mode. A presenter can zoom in and out, and when you zoom out completely BigBlueButton shows the entire page.

    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 – it’s 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

    Chrome 42 has stopped launching Java applets

    As of Chrome 42, Google has disabled launching of Java Applets by default. BigBlueButton currently uses a Java applet for desktop sharing. You can re-enable support for Chrome to launch the desktop sharing applet using the following steps:

    1. In Chrome’s URL bar enter ~~~ chrome://flags/#enable-npapi ~~~
    2. Click the Enable link for the Enable NPAPI configuration option
    3. Click the Relaunch button that now appears at the bottom of the configuration page.

    You should now be able to start BigBlueButton’s desktop sharing applet again within Chrome.

    However, this workaround will only work until Chrome 45 is released (September 2015), whereupon Google will completely remove support for Chrome launching Java applets. Going forward, we recommend using FireFox for desktop sharing as it retains the ability for launching Java applets. For more information see Chrome plugin and Java and Google Chrome.

    See also using FireFox with BigBlueButton’s 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

    Status Code: 500
    Exception Type: null
    Message:  null
    Exception: java.lang.NullPointerException
       at org.apache.jsp.demo.demo1_jsp.getJoinURL(demo1_jsp.java:168)
       at org.apache.jsp.demo.demo1_jsp._jspService(demo1_jsp.java:624)
       at org.apache.jasper.runtime.HttpJspBase.service(HttpJspBase.java
       ...
    

    That error is thrown by line 168 of bbb_api.jsp. Here’s 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 isn’t returning valid XML, and that is causing parseXml() to fail and throw an exception.

    The main reason getURL() fails is the URL it’s passed isn’t 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
    

    You’ll see two parameters defined:

    <%!
      // 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/";
    %>
    

    What’s likely happening is that BigBlueButtonURL isn’t 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 won’t have meeting abcdef running, but you should get back an XML file similar to the following:

    <response>
      <returncode>FAILED</returncode>
      <messageKey>checksumError</messageKey>
      <message>You did not pass the checksum security check</message>
    </response>
    

    Now, this URL isn’t actually called by your web browser; rather, it’s 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

    My slides upload but never finish converting

    Try restarting tomcat7, and then red5. On Ubuntu:

    sudo /etc/init.d/tomcat7 restart
    sudo /etc/init.d/red5 restart
    

    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.

    UTF characters won’t display correctly in the Client

    If you’re using Linux, UTF characters won’t display correctly. This is a limitation with Flash on linux.

    Which log files should I check for errors

    Log and configuration file information can be found here.

    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. That’s no small task, and we’ve been working hard on it for over seven years.

    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 (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. If the feature you are requesting is not on our road map, you could open a new issue 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 to accelerate your feature.

    For (2), often we’ll revisit a previously implemented feature to improve it’s 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.

    How can I donate money to the project

    The BigBlueButton project doesn’t take donations. We think it’s a poor business model for running an open source project as it suggests the developers are working for charity.

    If you want to help the project financially, then approach some of the companies offering commercial support for BigBlueButton and engage their services. This creates a healthy ecosystem around the project where companies are encouraged to contribute their resources to improve the project to create a larger pool of potential customers.

    In other words, in the BigBlueButton project, we would rather earn our revenues (we’re entrepreneurs too!).

    How do I change the brand of BigBlueButton

    There have been a number of companies (and individuals) posting to the mailing list asking for help in branding BigBlueButton.

    In recent releases you can now brand 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 efforts, we believe the best option is to have the individual contact one of the companies that provide commercial 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 efforts to support a white labeled version of BigBlueButton won’t take away from core development, but rather support it.