BigBlueButton API reference¶

Servers and server groups¶

Data structures to handle BigBlueButton servers.

This module also contains group handling support and the implementation of the communication with the API itself. Meetings and attendees manage themselves by talking to the BigBlueButton object linked to them. All other methods should be called on a BigBlueButtonGroup, which takes care of routing to the appropriate server(s).

class bigbluebutton.api.bigbluebutton.BigBlueButton(group: bigbluebutton.api.bigbluebutton.BigBlueButtonGroup, name: str, url: str, salt: str, host: Optional[str] = None, request_timeout: Union[float, Tuple[float, float]] = 0.5, 10, cache_timeout: float = 30)[source]¶

One BigBlueButton server.

A BigBlueButton instance holds the information needed to communicate with the BigBlueButton server. When creating meetings, it passes itself to the Meeting object, and provides methods for the Meeting object to manage itself.

A BigBlueButton server always belongs to a BigBlueButtonGroup, which it gets passed in the constructor and it registers itself with.

Parameters

group (BigBlueButtonGroup) – Reference to the BigBlueButtonGroup this server belongs to
name (str) – Descriptive name of this server
url (str) – Full URL to the API endpoint of this BigBlueButton server (with trailing /)
salt (str) – API secret, as reported by bbb-conf on the server
host (Optional[str]) – Hostname of the server, e.g. for SSH access (guessed from URL if unset)
request_timeout (Union[float, Tuple[float, float]]) – Timeout for API requests, either one value or a two-tuple defining TCP and HTTP request timeouts

__init__(group: bigbluebutton.api.bigbluebutton.BigBlueButtonGroup, name: str, url: str, salt: str, host: Optional[str] = None, request_timeout: Union[float, Tuple[float, float]] = 0.5, 10, cache_timeout: float = 30) → None ¶

Return type: None

create_meeting(do_create=True, *args, **kwargs)[source]¶

Create a meeting on thie BigBlueButton server.

args and kwargs are passed verbatim into the Meeting constructor. The additional parameter do_create determines whether the API is actually called to create the meeting. If it is False, tje object is returned but the meeting is not transferred to the BigBlueButton server.

This method first looks up whether a meeting with the passed meeting_id and reuse that object if a meeting is found. If none is found, a new object is created and the create API call sent to the server (if do_create is not set to False).

The BigBlueButton API guarantees that the create call is idempotent, so calling this method on a meeting ID of an existing meeting is safe. But, as every server is part of a server group, consumers should always call create_meeting on a BigBlueButtonGroup instead (or use its meeting property to make use of caching).

Parameters: do_create (bool) – True to call the create API method on the server, False to only create the Meeting object
Return type: Meeting
Returns: The found or newly created Meeting object

get_meetings()[source]¶

Get all meetings known on the BigBlueButton server.

This method calls the getMeetings API call on the BigBlueButton server and constructs Meeting objects from all meetings in the result. For meetings that are already known as objects, the appropriate object is returned; for all unknown meetings, new objects are created.

As every server is part of a server group, consumers should always call BigBlueButtonGroup.create_meeting() instead.

Return type: Dict[str, Meeting]
Returns: A dictionary mapping meeting IDs to Meeting objects

get_sysstat()[source]¶

Get the output of the sadf/sar command (from the sysstat package) through SSH.

The result is used when load-balancing API requests.

To use this functaionality, the sadf Python package (in the “sysstat” extra) must be installed.

Return type: Optional[SadfReport]

refresh()[source]¶

Refresh various aspects of this server.

Meetings
Sysstat data

Return type: None

static request_checksum(call, query, salt)[source]¶

Compute the checksum needed to authenticate API requests to a BigBlueButton server.

The checksum has to be sent with every API request and is constructed like this:

Build the full query string (already done when passed into this method)

Prepend the name of the API call, without delimiter

Append the API salt (shared secret, key,…) provided by the BBB server

Calculate the SHA1 sum of the resulting string

>>> BigBlueButton.request_checksum("isMeetingRunning", "meetingID=Foo", "MyTestSalt")
'f59b73c5cf1db387da4ca7d937049420d4c50a12'

The resulting checksum is added tothe original query string as a parameter called checksum.

Parameters

call (str) – Name of the API method to call (last part of URL)
query (str) – urlencoded query string with call parameters
salt (str) – The API secret the server expects requests to be signed with

Return type

str

Returns

The checksum (to be appended as the checksum parameter)

ssh_command(command, input_=None)[source]¶

Execute a shell command through an SSH connection to the server.

This method constructs an ssh command and runs it as a subprocess, without shell expansion. However, shell expansion WILL take place on the server side.

The subprocess result is returned verbatim.

Parameters

command (Sequence[str]) – Sequence of command words, like in argv
input – Text to pipe into the command on stdin

Return type

CompletedProcess

Returns

The verbatim subprocess object (including stdout, stderr, and return code)

class bigbluebutton.api.bigbluebutton.BigBlueButtonGroup(name: str, workers: int = 10, logout_url: Optional[str] = None, origin: str = 'python-bigbluebutton2', origin_server_name: str = <factory>, generate_meeting_id_cb: Optional[Callable[[], str]] = None)[source]¶

A set of BigBlueButton servers.

All API operations should be called on this object, instead of a single server. It takes care of aggregating results from the backend servers (e.g. for getMeetings) and of routing requests to the correct server (e.g. for loadbalancing on create).

Servers (BigBlueButton objects) register themselves to the group passed as first argument on instantiation.

If only one server has to be handled, still place it in a group.

Parameters

name (str) – Descriptive name of this server group
workers (int) – Number of servers to operate on parallely, e.g. when retrieving meetings or running SSH commands)
logout_url (Optional[str]) – Default URL to redirect clients to on meeting end
origin (str) – Name of the origin software passed as meeting meta-data
origin_server_name (str) – Hostname of the origin, passed as meeting meta-data; defaults to the systems’s local FQDN
generate_meeting_id_cb (Optional[Callable[[], str]]) – Callable to run for generating meeting IDs

__init__(name: str, workers: int = 10, logout_url: Optional[str] = None, origin: str = 'python-bigbluebutton2', origin_server_name: str = <factory>, generate_meeting_id_cb: Optional[Callable[[], str]] = None) → None ¶

Return type: None

create_meeting(do_create=True, *args, **kwargs)[source]¶

Create a new meeting on one of the backend servers.

For the arguments, see the documentation on Meeting.

This method first tries to find an existing meeting. The original create API method in BigBlueButton is idempotent, so we must ensure we also fulfill this requirement when handling several servers. If this group already has a list of known meetings, and the meeting is found in it, the call is redirected to the backend server it is linked to. If it is not found, get_meetings() is called to refresh the cache to be certain.

If all attempts to find a meeting with the ID fail, or no ID is passed, a backend server is selected using select_api() and the create call routed there.

Return type: Meeting

end_meeting(meeting_id, password=None)[source]¶

End a meeting determined from the passed ID.

If the meeting is not found, this method silently does nothing.

If a password is passed as second argument, it is compared against the moderarotr password of the meeting before the end request is even sent to the backend.

Return type: None

generate_meeting_id()[source]¶

Generate a unique meeting ID.

By default, this returns a GUID, unless a callback was defined in the generate_meeting_id_cb attribute.

Return type: str

get_meetings()[source]¶

Update meeting information on all server objects.

It is aggregated into the meetings attribute.

If forcefully updating the metting information cache is not intended, the meeting property should be used instead.

Return type: Dict[str, Meeting]

get_sysstat()[source]¶

Get sysstat information from all backend servers.

For the arguments and behaviour, see the documentation of BigBlueButton.get_sysstat().

The result is a dictionary with the server name as key and the result of the server’s get_sysstat method as values.

Return type: Dict[str, Optional[SadfReport]]

handle_from_data(method, attrs=None, content=None, filter_meta=None)[source]¶

Handle an API call from a method, a dict of parameters, and a text body.

This method is useful to pass on structures like HTTP requests on to the library, e.g. when writing a proxy or load balancer. The method name and parameter dictionary are expected to match the official BigBlueButton API.

The return value is a dictionary representation of the XML document as would be returned by a BigBlueButton server when called with the same parameters.

Return type: Dict[str, Any]

is_meeting_running(meeting_id)[source]¶

Determine whether a meeting with a given ID is running on any backend server.

Return type: bool

property meetings¶

All meetings known on all servers in the group.

Each meeting will reference the backend server it is actually running on, so calling methods on the Meeting objects returned in this property always does “the right thing”.

Return type: Dict[str, Meeting]

new(name, *args, **kwargs)[source]¶

Createa new BigBlueButton server object in this group.

The server object will register itself in this group.

For the arguments, see the documentation of BigBlueButton.

Return type: BigBlueButton

refresh()[source]¶

Refresh all backend servers.

For a description of the behaviour, see the documentation of BigBlueButton.refresh().

Return type: None

select_api(criteria=None)[source]¶

Select a target server in the group by some creiteria.

This method runs a ranking algorithm on all servers in the group, then returns the server with the highest ranking. This can be used for load-balancing and similar tasks.

The ranking algorithm works like this:

Start with giving each server a ranking of N points.
Apply a list of checkers on each server. Each checker returns a factor by which to multiply the last known ranking (between 0 and 1).
Return the server with the highest ranking. If multiple servers share the same highest ranking, fall back to round robin.

A ranking of 0 means a server is unavailable. Servers with a ranking of 0 are never returned.

Parameters: criteria (Optional[Dict[str, Any]]) – A dictionary of criteria taken into account by each checker. See the documentation of the checkers in the :module:`bigbluebutton.api.loadbalancing` module for details on what criteria exist and how they influence server selection.
Return type: BigBlueButton
Returns: One BigBlueButton server that best matches the criteria

ssh_command(command, input_=None)[source]¶

Call an SSH command on each backend server in this group.

For the arguments and behaviour, see the documentation of BigBlueButton.ssh_command().

The return value is a dictionary with the server name as key and the result of the server’s ssh_command method as value.

Return type: Dict[str, CompletedProcess]

Meetings¶

Data structures for BigBLueButton meetings and handling code

class bigbluebutton.api.meeting.Meeting(api: BigBlueButton, meeting_id: Optional[str] = None, meeting_name: Optional[str] = None, attendee_pw: Optional[str] = None, moderator_pw: Optional[str] = None, welcome: Optional[str] = None, dial_number: Optional[str] = None, voice_bridge: Optional[str] = None, max_participants: Optional[int] = None, logout_url: Optional[str] = None, record: Optional[bool] = None, duration: Optional[int] = None, meta: Dict[str, str] = <factory>, moderator_only_message: Optional[str] = None, auto_start_recording: Optional[bool] = None, allow_start_stop_recording: Optional[bool] = None, webcams_only_for_moderator: Optional[bool] = None, logo: Optional[str] = None, banner_text: Optional[str] = None, banner_color: Optional[str] = None, copyright: Optional[str] = None, mute_on_start: Optional[bool] = None, allow_mods_to_unmute_users: Optional[bool] = None, lock_settings_disable_cam: Optional[bool] = None, lock_settings_disable_mic: Optional[bool] = None, lock_settings_disable_private_chat: Optional[bool] = None, lock_settings_disable_public_chat: Optional[bool] = None, lock_settings_disable_note: Optional[bool] = None, lock_settings_locked_layout: Optional[bool] = None, lock_settings_lock_on_join: Optional[bool] = None, lock_settings_lock_on_join_configurable: Optional[bool] = None, guest_policy: Optional[str] = None, create_time: int = 0)[source]¶

Define the meta-data of a meeting and its state.

The meeting is always linked to one BigBlueButton, on which it executes any API calls.

__init__(api: BigBlueButton, meeting_id: Optional[str] = None, meeting_name: Optional[str] = None, attendee_pw: Optional[str] = None, moderator_pw: Optional[str] = None, welcome: Optional[str] = None, dial_number: Optional[str] = None, voice_bridge: Optional[str] = None, max_participants: Optional[int] = None, logout_url: Optional[str] = None, record: Optional[bool] = None, duration: Optional[int] = None, meta: Dict[str, str] = <factory>, moderator_only_message: Optional[str] = None, auto_start_recording: Optional[bool] = None, allow_start_stop_recording: Optional[bool] = None, webcams_only_for_moderator: Optional[bool] = None, logo: Optional[str] = None, banner_text: Optional[str] = None, banner_color: Optional[str] = None, copyright: Optional[str] = None, mute_on_start: Optional[bool] = None, allow_mods_to_unmute_users: Optional[bool] = None, lock_settings_disable_cam: Optional[bool] = None, lock_settings_disable_mic: Optional[bool] = None, lock_settings_disable_private_chat: Optional[bool] = None, lock_settings_disable_public_chat: Optional[bool] = None, lock_settings_disable_note: Optional[bool] = None, lock_settings_locked_layout: Optional[bool] = None, lock_settings_lock_on_join: Optional[bool] = None, lock_settings_lock_on_join_configurable: Optional[bool] = None, guest_policy: Optional[str] = None, create_time: int = 0) → None ¶

Return type: None

create()[source]¶

Create the meeting on the linked BigBlueButton server.

Return type: None

end()[source]¶

Ask the server to forcefully end the meeting.

This only sends the end API call to the server. According to the BigBlueButton documentation, the call imemdiately returns, but it can take several seconds for all componentes to pick up the request and actually end the meeting. Accordingly, it is is up to the developer to track the progress by calling is_meeting_running() or get_meeting_info() again later on.

Return type: None

classmethod get_kwargs_from_url_args(urlargs)[source]¶

Construct a dictionary suitable for passing as kwargs to the constructor.

The passed urlargs are expected to be a dictionary of URL arguments following the BigBlueButton HTTP API schema.

This is useful to generate a meeting object from a URL call from a foreign BBB client, an API reply, or comparable things.

Return type: Dict[str, Any]

get_meeting_info()[source]¶

Update the meeting information from the server.

The results are cached in the corresponding attributes.

Return type: Meeting
Returns: the Meeting object itself, after being updated

is_meeting_running()[source]¶

Call the isMeetingRunning API method.

The result is cached in the running attribute and immediately returned.

Return type: bool
Returns: True if the server reports the meeting as running, False if not

property origin¶

Origin of the meeting

Derived from the meta-data values bbb-origin and bbb-origin-server-name, which are de facto standard fields.

Return type: str

to_dict(*args, **kwargs)[source]¶

Return relevant data of this meeting as a dictionary.

The dictionary can be used to build an XML document compatible with BigBlueButton API clients.

If names of attributes are passed as positional arguments, only these attributes are returned in the dictionary.

If attribute names are passed as names of keyword arguments, they are renamed to the string passed as value in the dictionary.

Return type: Dict[str, Any]

Attendees¶

Data structures for manageing meeting attendees

class bigbluebutton.api.attendee.Attendee(meeting: Meeting, full_name: str, user_id: Optional[str] = None, role: Optional[bigbluebutton.api.attendee.Role] = None, is_presenter: bool = False, is_listening_only: bool = False, has_joined_voice: bool = False, has_video: bool = False, client_type: Optional[str] = None)[source]¶

One attendee that participates in one meeting.

This object holds the information about one participant and is linked to exactly one meeting.

__init__(meeting: Meeting, full_name: str, user_id: Optional[str] = None, role: Optional[bigbluebutton.api.attendee.Role] = None, is_presenter: bool = False, is_listening_only: bool = False, has_joined_voice: bool = False, has_video: bool = False, client_type: Optional[str] = None) → None ¶

Return type: None

classmethod get_kwargs_from_url_args(urlargs, meeting)[source]¶

Construct a dictionary suitable for passing as kwargs to the constructor.

The passed urlargs are expected to be a dictionary of URL arguments following the BigBlueButton HTTP API schema.

This is useful to generate an attendee object from a URL call from a foreign BBB client, an API reply, or comparable things.

Return type: Dict[str, Any]

join(browser=False, do_join=True)[source]¶

Join an attendee corresponding to this object into the meeting it is linked to.

To request the join, this method can either call the API directly and return the URL to the (HTML5) client, or only construct the API call URL and then hand it off to the default browser (if the browser argument is set to True) or return it plain without calling (if the do_join argument is set to False).

In BigBlueButton’s default configuration, in addition to the session token in the client URL, a valid JSESSIONID cookie is required, so using the client URL outside the original request scope only works if the server supports it.

Return type: Optional[str]

to_dict(*args, **kwargs)[source]¶

Return relevant data of this attendee as a dictionary.

The dictionary can be used to build an XML document compatible with BigBlueButton API clients.

If names of attributes are passed as positional arguments, only these attributes are returned in the dictionary.

If attribute names are passed as names of keyword arguments, they are renamed to the string passed as value in the dictionary.

Return type: Dict[str, Any]

class bigbluebutton.api.attendee.Role[source]¶: Enumeration of roles an attendee can have

Utilities¶

Utility functions used by different parts of bigbluebutton2

bigbluebutton.api.util.camel_to_snake(camel)[source]¶

Convert camel or lower camel case name to PEP-8 compliant snake case used in our classes.

>>> camel_to_snake("meetingID")
'meeting_id'

Return type: str

bigbluebutton.api.util.get_target_type(cls, attr)[source]¶

Guess the type of a field in a class by looking at its type annotation.

It either returns the type hint itself, or the first type argument if it is a composite (e.g. int for a typing.Union[int, float] or a typing.Optional[int].

WARNING: This is not generic code, but tailored to the use cases in the specific data classes in this code base.

Return type: type

bigbluebutton.api.util.snake_to_camel(snake)[source]¶

Convert PEP-8 complicant snake case name to special lower camel case.

>>> snake_to_camel("test_string")
'testString'
>>> snake_to_camel("meeting_id")
'meetingID'

Return type: str

bigbluebutton.api.util.to_field_type(cls, attr, value)[source]¶

Convert a string value to a type fitting the type of a field by looking at its type hint.

Return type: Any