Conference Service
Note
Features, such as recording and injecting media are only available for server applications.
The Conference Service allows the application to manage the conference life-cycle and interact with the conference. During a conference, the SDK may receive:
A single audio stream that contains mixed audio of all un-muted participants
Video streams from all participants who joined the conference with their cameras enabled
One screen-share stream
- The basic usage of the Conference Service is as follows:
Log in to Session Interface.
Subscribe to any of the available Conference Events using the
conference::add_event_handler
method.Create a conference using a conference alias
conference::create
. You can omit this step if you want to join an existing conference.Join a conference using the
conference::join
orconference::listen
method. This method returns the conference_info structure (see Other Structures) describing the conference. In the case of failure, you will receive an exception returned in the async_result.To leave the conference, call the
conference::leave
method.
Conference Interface
#include <dolbyio/comms/conference.h>
The interface for the Conference Service. Methods of this interface provide the ability to create, join, and leave conferences and subscribe to events. The conference service methods are all asynchronous in nature, refer to Asynchronous Operations for more information. Structures which are part of the interface can be passed to and returned by the service.
-
class conference
Provides methods of the Conference Service.
- Attention
The conference interface that contains methods that return async_result. Each function that returns async_result is asynchronous and the operation is executed during the SDK event loop. The caller can block the calling thread until the operation completes using the wait helper. The caller can also chain consecutive operations, which are dependent on the completion of this method, using the async_result::then calls. Each async_result chain needs to be terminated with an async_result::on_error.
Public Functions
-
virtual async_result<conference_info> demo(enum spatial_audio_style spatial_audio_style) = 0
Creates a demo conference and joins to it upon completion.
// Wait for the conference creation auto conf_info = wait(sdk->conference().demo(spatial_audio_style::shared)); // Invoking the method directly requires chaining successive operations // via the `then` call sdk->conference().demo(spatial_audio_style::shared)) .then[](auto&& info) { // Do something with the returned conf info; }) .on_error([](auto&& e) { // Handle exception });
- Parameters:
spatial_audio_style – A spatial audio style to be used in the conference.
- Returns:
The result object producing the conference_info asynchronously.
-
virtual async_result<conference_info> create(const conference_options &options) = 0
Creates a conference and returns information about the conference upon completion.
// Wait for the conference creation auto conf_info = wait(sdk->conference().create(options)); // Invoking the method directly requires chaining successive operations // via the `then` call sdk->conference().create(options)) .then[](auto&& info) { // Do something with the returned conf info; }) .on_error([](auto&& e) { // Handle exception });
- Parameters:
options – The conference options.
- Returns:
The result object producing the conference_info asynchronously.
-
virtual async_result<conference_info> join(const conference_info &conf, const join_options &join) = 0
Joins an existing conference as an active user who can both receive media from the conference and inject media into the conference.
// Wait for the conference creation auto conf_info = wait(sdk->conference().join(conf_options, join_options)); // Invoking the method directly requires chaining successive operations // via the `then` call sdk->conference().join(conf_options, join_options)) .then[](auto&& info) { // Do something with the returned conf info; }) .on_error([](auto&& e) { // Handle exception });
- Parameters:
conf – The conference options that need to contain conference_id.
join – The join options for the SDK user.
- Returns:
The result object producing the conference_info asynchronously.
-
virtual async_result<conference_info> listen(const conference_info &conf, const listen_options &listen) = 0
Joins an existing conference as a listener who can receive audio and video streams, but cannot send any stream to the conference.
// Invoke the method via wait blocks until the method succeeds or fails wait(sdk->conference().listen(conf, join)); // Invoking the method directly requires chaining successive operations // via the `then` call sdk->conference().listen(conf, join) .then([](conference_info&&) { // The user joined the conference }) .on_error([](auto&& e) { // Handle exception });
- Parameters:
conf – The conference options that need to contain conference_id.
listen – The join options for the SDK user.
- Returns:
The result object producing the conference_info asynchronously.
-
virtual async_result<void> leave() = 0
Leaves a conference.
// Invoke the method via wait blocks until the method succeeds or fails wait(sdk->conference().leave()); // Invoking the method directly requires chaining successive operations // via the `then` call sdk->conference().leave() .then([]() { // The user left the conference }) .on_error([](auto&& e) { // Handle exception });
- Returns:
The result object producing the operation status asynchronously.
-
virtual async_result<void> send(const std::string &message, std::vector<std::string> &&participant_ids = {}) = 0
Sends a message to the current conference. The message size is limited to 16KB.
// Invoke the method via wait blocks until the method succeeds or fails wait(sdk->conference().send("some message", std::move(participant_ids))); // Invoking the method directly requires chaining successive operations // via the `then` call sdk->conference().send("some message", std::move(participant_ids)) .then([]() { // The message was sent }) .on_error([](auto&& e){ // Rethrow and handle the exception });
- Parameters:
message – The message.
participant_ids – List of all participants to send the message to. Leaving this empy will broadcast message to all participants.
- Returns:
The result object producing the operation status asynchronously.
-
virtual async_result<void> mute(bool muted) = 0
Mutes and un-mutes the local participant’s microphone.
// Invoke the method via wait blocks until the method succeeds or fails wait(sdk->conference().mute(true)); // Invoking the method directly requires chaining successive operations // via the `then` call sdk->conference().mute(true) .then([]() { // The microphone is now muted }) .on_error([](auto&& e){ // The operation failed, and microphone is not muted });
- Parameters:
muted – A boolean value that indicates the required mute state. True mutes the microphone, false un-mutes the microphone.
- Returns:
The result object producing the operation status asynchronously.
-
virtual async_result<void> remote_mute(bool muted, const std::string &participant_id) = 0
Mutes and un-mutes a specified remote participant.
// Invoke the method via wait blocks until the method succeeds or fails wait(sdk->conference().remote_mute(true, participant_id)); // Invoking the method directly requires chaining successive operations // via the `then` call sdk->conference().remote_mute(true, participant_id) .then([]() { // The remote participant is now muted }) .on_error([](auto&& e){ // The operation failed, and remote participant is not muted });
- Attention
This method is only available for non-Dolby Voice conferences.
- Parameters:
muted – A boolean value that indicates the required mute state. True mutes the remote participant, false un-mutes the remote participant.
participant_id – The ID of the remote participant to be muted.
- Returns:
The result object producing the operation status asynchronously. If attempted for a Dolby Voice Conference, the async_result will fail.
-
virtual async_result<void> mute_output(bool muted) = 0
Mutes and un-mutes the output audio device.
// Invoke the method via wait blocks until the method succeeds or fails wait(sdk->conference().mute_output(true)); // Invoking the method directly requires chaining successive operations // via the `then` call sdk->conference().mute_output(true) .then([]() { // The output is now muted }) .on_error([](auto&& e){ // The operation failed, and output is not muted });
- Attention
This method is only available in Dolby Voice conferences.
- Parameters:
muted – A boolean value that indicates the required mute state. True mutes the output device, false un-mutes the output device.
- Returns:
The result object producing the operation status asynchronously.
-
virtual async_result<void> update_spatial_audio_configuration(dolbyio::comms::spatial_audio_batch_update &&configuration) = 0
Updates the spatial audio configuration to enable experiencing spatial audio during a conference. This method contains information about participants’ locations, the direction the local participant is facing in space, and a spatial environment of an application, so the audio renderer understands which directions the application considers forward, up, and right and which units it uses for distance. This method is available only for participants who joined a conference using the join method with the spatial_audio parameter enabled. Depending on the selected spatial_audio_style, the method requires either providing only the position of the local participant or the positions of all participants. When using the individual spatial_audio_style, remote participants’ audio is disabled until the participants are assigned to specific locations and each time new participants join the conference, the positions need to be updated.
// Invoke the method via wait blocks until the method succeeds or fails wait(sdk->conference().update_spatial_audio_configuration(configuration)); // Invoking the method directly requires chaining successive operations // via the `then` call sdk->conference().update_spatial_audio_configuration(configuration) .then([]() { // Configuration is now updated }) .on_error([](auto&& e) { // Handle exception });
- Parameters:
configuration – The object with the new configuration set.
- Returns:
The result object producing the operation status asynchronously.
-
virtual async_result<void> set_spatial_position(const std::string &participant_id, const spatial_position &position) = 0
Updates the spatial audio configuration to enable experiencing spatial audio during a conference. This method contains information about the participant’s location. This method is available only for participants who joined a conference using the join method with the spatial_audio parameter enabled. Depending on the selected spatial_audio_style, the method requires either providing only the position of the local participant or the positions of all participants. When using the individual spatial_audio_style, remote participants’ audio is disabled until the participants are assigned to specific locations and each time new participants join the conference, the positions need to be updated.
// Invoke the method via wait blocks until the method succeeds or fails wait(sdk->conference().set_spatial_position(participant_id, position)); // Invoking the method directly requires chaining successive operations // via the `then` call sdk->conference().set_spatial_position(participant_id, position) .then([]() { // Position is now updated }) .on_error([](auto&& e) { // Handle exception });
- Parameters:
participant_id – The participant whose position is updated.
position – The location of given participant.
- Returns:
The result object producing the operation status asynchronously.
-
virtual async_result<void> set_spatial_direction(const spatial_direction &direction) = 0
Updates the spatial audio configuration to enable experiencing spatial audio during a conference. This method contains information about the direction the local participant is facing in space. This method is available only for participants who joined a conference using the join method with the spatial_audio parameter enabled.
// Invoke the method via wait blocks until the method succeeds or fails wait(sdk->conference().set_spatial_direction(direction)); // Invoking the method directly requires chaining successive operations // via the `then` call sdk->conference().set_spatial_direction(direction) .then([]() { // Direction is now updated }) .on_error([](auto&& e) { // Handle exception });
- Parameters:
direction – The direction the local participant is facing.
- Returns:
The result object producing the operation status asynchronously.
-
virtual async_result<void> set_spatial_environment(const spatial_scale &scale, const spatial_position &forward, const spatial_position &up, const spatial_position &right) = 0
Updates the spatial audio configuration to enable experiencing spatial audio during a conference. This method contains information about a spatial environment of an application, so the audio renderer understands which directions the application considers forward, up, and right and which units it uses for distance. This method is available only for participants who joined a conference using the join method with the spatial_audio parameter enabled.
// Invoke the method via wait blocks until the method succeeds or fails wait(sdk->conference().set_spatial_environment(scale, forward, up, right)); // Invoking the method directly requires chaining successive operations // via the `then` call sdk->conference().set_spatial_environment(scale, forward, up, right) .then([]() { // Environment is now updated }) .on_error([](auto&& e) { // Handle exception });
- Parameters:
scale – A scale that defines how to convert units from the coordinate system of an application (pixels or centimeters) into meters used by the spatial audio coordinate system.
forward – A vector describing the direction the application considers as forward. The value can be either +1, 0, or -1 and must be orthogonal to up and right.
up – A vector describing the direction the application considers as up. The value can be either +1, 0, or -1 and must be orthogonal to forward and right.
right – A vector describing the direction the application considers as right. The value can be either +1, 0, or -1 and must be orthogonal to forward and up.
- Returns:
The result object producing the operation status asynchronously.
-
virtual async_result<conference_info> get_current_conference() const = 0
Gets the full information about the currently active conference.
// Invoke the method via wait blocks until the method succeeds or fails wait(sdk->conference().get_current_conference()); // Invoking the method directly requires chaining successive operations // via the `then` call sdk->conference().get_current_conference() .then([](conference_info&& info) { // Process conference information }) .on_error([](auto&& e){ // The operation failed, no active conference });
- Returns:
The result object producing the operation status asynchronously.
-
virtual async_result<void> decline_invitation(const std::string &conf_id) = 0
Declines a conference invitation.
// Invoke the method via wait blocks until the method succeeds or fails wait(sdk->conference().decline_invitation(conf_id)); // Invoking the method directly requires chaining successive operations // via the `then` call sdk->conference().decline_invitation(conf_id) .then([]() { // Invitation declined successfully }) .on_error([](auto&& e) { // Failed to decline invitation });
- Parameters:
conf_id – The conference ID.
- Returns:
The result object producing the operation status asynchronously.
Starts local capture of screen share.
This method may be called only if a conference is active.
This method can also be used to switch screen share sources at any point. If you have passed in a video_frame_handler to the previous start call and would like to continue using this handler, you must pass the same handler into the subsequent call used to switch sources. This will have the effect of just switching sources, keeping the rest of the pipeline in tact.
The SDK supports switching seamlesly between various screen capture sources, without readding a video track to the peer connection. However, if switching from low resolution Window capture to high resolution Fullscreen capture the Window capture screen share must be stopped before the Fullscreen capture can be started.
- Parameters:
source – The screen source to capture from.
handler – The screen share streams video frame handler.
type – The type of content being captured.
- Returns:
The result object producing the operation status asynchronously.
Stops the screen share capture.
- Returns:
The result object producing the operation status asynchronously.
Change the screen share content type if the screen share is already active. If screen share is not yet active the content type is to be set during the start_screen_share call.
- Parameters:
type – The type of screen share content
- Returns:
The result object producing the operation status asynchronously.
-
virtual async_result<event_handler_id> add_event_handler(event_handler<conference_status_updated> &&callback) = 0
Adds a listener for the conference_status_updated events.
// Invoke the method via wait blocks until the method succeeds or fails handlers.push_back(wait(sdk->conference().add_event_handler( [](const dolbyio::comms::conference_status_updated& e) { // Process the event }))); // Invoking the method directly requires chaining successive operations // via the `then` call sdk->conference().add_event_handler( [](const dolbyio::comms::conference_status_updated& e) { // Process the event })) .then([this](event_handler_id&& handler) { this->handlers.push_back(std::move(handler)); }) .on_error([](auto&& e) { // Handle exception });
- Parameters:
callback – The function object that is invoked when the conference status changes.
- Returns:
The result object producing the event_handler_id asynchronously.
-
virtual async_result<event_handler_id> add_event_handler(event_handler<participant_added> &&callback) = 0
Adds a listener for the participant added events.
// Invoke the method via wait blocks until the method succeeds or fails handlers.push_back(wait(sdk->conference().add_event_handler( [](const dolbyio::comms::participant_added& e) { // Process the event }))); // Invoking the method directly requires chaining successive operations // via the `then` call sdk->conference().add_event_handler( [](const dolbyio::comms::participant_added& e) { // Process the event })) .then([this](event_handler_id&& handler) { this->handlers.push_back(std::move(handler)); }) .on_error([](auto&& e) { // Handle exception });
- Parameters:
callback – The function object that is invoked when a participant is added to the conference.
- Returns:
The result object producing the event_handler_id asynchronously.
-
virtual async_result<event_handler_id> add_event_handler(event_handler<participant_updated> &&callback) = 0
Adds a listener for participant_updated events.
// Invoke the method via wait blocks until the method succeeds or fails handlers.push_back(wait(sdk->conference().add_event_handler( [](const dolbyio::comms::participant_updated& e) { // Process the event }))); // Invoking the method directly requires chaining successive operations // via the `then` call sdk->conference().add_event_handler( [](const dolbyio::comms::participant_updated& e) { // Process the event })) .then([this](event_handler_id&& handler) { this->handlers.push_back(std::move(handler)); }) .on_error([](auto&& e) { // Handle exception });
- Parameters:
callback – The function object that is invoked when a conference participant changes status.
- Returns:
The result object producing the event_handler_id asynchronously.
-
virtual async_result<event_handler_id> add_event_handler(event_handler<active_speaker_changed> &&callback) = 0
Adds a listener for active_speaker_changed events.
// Invoke the method via wait blocks until the method succeeds or fails handlers.push_back(wait(sdk->conference().add_event_handler( [](const dolbyio::comms::active_speaker_changed& e) { // Process the event }))); // Invoking the method directly requires chaining successive operations // via the `then` call sdk->conference().add_event_handler( [](const dolbyio::comms::active_speaker_changed& e) { // Process the event })) .then([this](event_handler_id&& handler) { this->handlers.push_back(std::move(handler)); }) .on_error([](auto&& e) { // Handle exception });
- Parameters:
callback – The function object that is invoked when the active speaker changes.
- Returns:
The result object producing the event_handler_id asynchronously.
-
virtual async_result<event_handler_id> add_event_handler(event_handler<video_forwarded_changed> &&callback) = 0
Adds a listener for video_forwarded_changed events.
- Parameters:
callback – The function object that is invoked when the forwarded video streams change.
- Returns:
The result object producing the event_handler_id asynchronously.
-
virtual async_result<event_handler_id> add_event_handler(event_handler<dolbyio::comms::video_track_added> &&callback) = 0
Adds a listener for video_track_added events.
// Invoke the method via wait blocks until the method succeeds or fails handlers.push_back(wait(sdk->conference().add_event_handler( [](const dolbyio::comms::video_track_added& e) { // Process the event }))); // Invoking the method directly requires chaining successive operations // via the `then` call sdk->conference().add_event_handler( [](const dolbyio::comms::video_track_added& e) { // Process the event })) .then([this](event_handler_id&& handler) { this->handlers.push_back(std::move(handler)); }) .on_error([](auto&& e) { // Handle exception });
- Parameters:
callback – The function object that is invoked when a new video track is added to a conference.
- Returns:
The result object producing the event_handler_id asynchronously.
-
virtual async_result<event_handler_id> add_event_handler(event_handler<dolbyio::comms::video_track_removed> &&callback) = 0
Adds a listener for video_track_removed events.
// Invoke the method via wait blocks until the method succeeds or fails handlers.push_back(wait(sdk->conference().add_event_handler( [](const dolbyio::comms::video_track_removed& e) { // Process the event }))); // Invoking the method directly requires chaining successive operations // via the `then` call sdk->conference().add_event_handler( [](const dolbyio::comms::video_track_removed& e) { // Process the event })) .then([this](event_handler_id&& handler) { this->handlers.push_back(std::move(handler)); }) .on_error([](auto&& e) { // handle exception });
- Parameters:
callback – The function object that is invoked when a video track is removed from a conference.
- Returns:
The result object producing the event_handler_id asynchronously.
-
virtual async_result<event_handler_id> add_event_handler(event_handler<dolbyio::comms::audio_track_added> &&callback) = 0
Adds a listener for audio_track_added events.
// Invoke the method via wait blocks until the method succeeds or fails handlers.push_back(wait(sdk->conference().add_event_handler( [](const dolbyio::comms::audio_track_added& e) { // Process the event }))); // Invoking the method directly requires chaining successive operations // via the `then` call sdk->conference().add_event_handler( [](const dolbyio::comms::audio_track_added& e) { // Process the event })) .then([this](event_handler_id&& handler) { this->handlers.push_back(std::move(handler)); }) .on_error([](auto&& e) { // Handle exception });
- Parameters:
callback – The function object that is invoked when a new audio track is added to a conference.
- Returns:
The result object producing the event_handler_id asynchronously.
-
virtual async_result<event_handler_id> add_event_handler(event_handler<dolbyio::comms::audio_track_removed> &&callback) = 0
Adds a listener for audio_track_removed events.
// Invoke the method via wait blocks until the method succeeds or fails handlers.push_back(wait(sdk->conference().add_event_handler( [](const dolbyio::comms::audio_track_removed& e) { // Process the event }))); // Invoking the method directly requires chaining successive operations // via the `then` call sdk->conference().add_event_handler( [](const dolbyio::comms::audio_track_removed& e) { // Process the event })) .then([this](event_handler_id&& handler) { this->handlers.push_back(std::move(handler)); }) .on_error([](auto&& e) { // Handle exception });
- Parameters:
callback – The function object that is invoked when an audio track is removed from a conference.
- Returns:
The result object producing the event_handler_id asynchronously.
-
virtual async_result<event_handler_id> add_event_handler(event_handler<dolbyio::comms::dvc_error_exception> &&callback) = 0
Uses the add_event_handler method for dvc_error_exception to handle DVC errors when the media engine encounters an error from the DVC library.
// Invoke the method via wait blocks until the method succeeds or fails handlers.push_back(wait(sdk->conference().add_event_handler( [](const dolbyio::comms::dvc_error_exception& e) { // Process the event }))); // Invoking the method directly requires chaining successive operations // via the `then` call sdk->conference().add_event_handler( [](const dolbyio::comms::dvc_error_exception& e) { // Process the event })) .then([this](event_handler_id&& handler) { this->handlers.push_back(std::move(handler)); }) .on_error([](auto&& e) { // Handle exception });
- Parameters:
callback – The function object that is called with the dvc_error_exception.
- Returns:
The result object producing the event_handler_id asynchronously.
-
virtual async_result<event_handler_id> add_event_handler(event_handler<dolbyio::comms::peer_connection_failed_exception> &&callback) = 0
Uses the add_event_handler method for peer_connection_failed_exception to handle errors which are generated when the PeerConnection has entered a failed state.
// Invoke the method via wait blocks until the method succeeds or fails handlers.push_back(wait(sdk->conference().add_event_handler( [](const dolbyio::comms::peer_connection_failed_exception& e) { // Process the event }))); // Invoking the method directly requires chaining successive operations // via the `then` call sdk->conference().add_event_handler( [](const dolbyio::comms::peer_connection_failed_exception& e) { // Process the event })) .then([this](event_handler_id&& handler) { this->handlers.push_back(std::move(handler)); }) .on_error([](auto&& e) { // Handle exception });
- Parameters:
callback – The function object that is called with the peer_connection_failed_exception.
- Returns:
The result object producing the event_handler_id asynchronously.
-
virtual async_result<event_handler_id> add_event_handler(event_handler<conference_message_received> &&callback) = 0
Adds a listener for conference_message_received events.
// Invoke the method via wait blocks until the method succeeds or fails handlers.push_back(wait(sdk->conference().add_event_handler( [](const dolbyio::comms::conference_message_received& e) { // Process the event }))); // Invoking the method directly requires chaining successive operations // via the `then` call sdk->conference().add_event_handler( [](const dolbyio::comms::conference_message_received& e) { // Process the event }) .then([this](event_handler_id&& handler) { this->handlers.push_back(std::move(handler); }) .on_error([](auto&& e){ // Handle an exception });
- Parameters:
callback – The function object that is invoked when a message is received in the conference.
- Returns:
The async_result class that wraps a solver that can contain the event_handler_id object.
SUCCESS: The solver returns a void operator and the callback attached via the async_result::then method is invoked.
FAILURE: The solver fails with the std::exception_ptr exception that describes the error. The exception pointer is passed to the callback and can be set and handled via async_result::on_error, async_result::then, or async_result::consume_errors.
-
virtual async_result<event_handler_id> add_event_handler(event_handler<conference_invitation_received> &&callback) = 0
Adds a listener for conference invitation events.
// Invoke the method via wait blocks until the method succeeds or fails handlers.push_back(wait(sdk->conference().add_event_handler( [](const dolbyio::comms::conference_invitation_received& e) { // Process the event }))); // Invoking the method directly requires chaining successive operations // via the `then` call sdk->conference().add_event_handler( [](const dolbyio::comms::conference_invitation_received& e) { // Process the event }) .then([this](event_handler_id&& handler) { this->handlers.push_back(std::move(handler); }) .on_error([](auto&& e){ // Handle an exception });
- Parameters:
callback – The function object that is invoked when a conference invitation is received.
- Returns:
The async_result class that wraps a solver that can contain the event_handler_id object.
SUCCESS: The solver returns a void operator and the callback attached via the async_result::then method is invoked.
FAILURE: The solver fails with the std::exception_ptr exception that describes the error. The exception pointer is passed to the callback and can be set and handled via async_result::on_error, async_result::then, or async_result::consume_errors.
-
virtual async_result<event_handler_id> add_event_handler(event_handler<audio_levels> &&callback) = 0
Adds a listener for audio_levels events.
- Parameters:
callback – The function object that is invoked periodically in the active conference.
- Returns:
The async_result class that wraps a solver that can contain the event_handler_id object.
SUCCESS: The solver returns a void operator and the callback attached via the async_result::then method is invoked.
FAILURE: The solver fails with the std::exception_ptr exception that describes the error. The exception pointer is passed to the callback and can be set and handled via async_result::on_error, async_result::then, or async_result::consume_errors.
-
virtual async_result<event_handler_id> add_event_handler(event_handler<recording_status_updated> &&callback) = 0
Adds a listener for recording_status_updated events.
- Parameters:
callback – The function object that is invoked when the recording status event is received.
- Returns:
The async_result class that wraps a solver that can contain the event_handler_id object.
SUCCESS: The solver returns a void operator and the callback attached via the async_result::then method is invoked.
FAILURE: The solver fails with the std::exception_ptr exception that describes the error. The exception pointer is passed to the callback and can be set and handled via async_result::on_error, async_result::then, or async_result::consume_errors.
-
struct conference_options
The conference options structure that provides additional information about a conference.
Public Members
-
std::optional<std::string> alias
The alias of the conference.
-
struct params
The conference parameters.
Public Members
-
bool dolby_voice = true
A boolean that indicates whether the SDK should create a Dolby Voice conference where each participant receives one audio stream.
-
bool stats = false
A boolean that indicates whether the conference should include additional statistics.
-
dolbyio::comms::video_codec video_codec = video_codec::h264
The preferred video codec.
-
enum spatial_audio_style spatial_audio_style = spatial_audio_style::individual
An enum that defines how the spatial location is communicated between the SDK and the Dolby.io server.
-
std::optional<enum rtcp_mode> rtcp_mode = {}
The Rtcp Mode to be used for the conference. If not specified the rtcp_mode::average will be used.
-
bool live_recording = false
A boolean that indicates whether the conference is to be recorded on the backend.
-
bool dolby_voice = true
-
std::optional<std::string> alias
-
struct connection_options
The options that define how the application expects to join a conference in terms of media preference.
Public Members
-
std::optional<int> max_video_forwarding
Sets the maximum number of video streams that may be transmitted to the SDK. Valid parameter values are between 0 and 25. If this parameter is not set, the default value for the maximum number of video streams that can be transmitted to the SDK is 25.
-
std::optional<video_forwarding_strategy> forwarding_strategy
Sets how the SDK should select conference participants whose videos will be transmitted to the local participant. There are two possible values; the selection can be either based on the participants’ audio volume or the distance from the local participant. If this parameter is not set, the default value the last_speaker strategy.
-
std::optional<std::string> conference_access_token
The conference access token that is required to join a protected conference if the conference is created using the create REST API. The application needs to externally fetch and provide the token to the SDK when it calls the join or listen method.
-
bool spatial_audio = false
Enables spatial audio for the joining participant. This boolean should be set to true if the spatial_style is not disabled. For more information, refer to our sample application code.
-
bool simulcast = false
Enables simulcast support in the conference.
-
std::optional<int> max_video_forwarding
-
struct join_options
The options for joining a conference as an active user.
Public Members
-
connection_options connection
The options for connecting to the conference.
-
media_constraints constraints
The media constraints for the active user.
-
connection_options connection
-
struct listen_options
The options for listening to a conference as listener.
Public Members
-
connection_options connection
The options for connecting to the conference.
-
listen_mode type = listen_mode::regular
The listen mode.
-
connection_options connection
-
struct media_constraints
The local media constraints for application joining a conference.
Public Members
-
bool audio = false
A boolean that indicates whether the application should capture local audio and send it to a conference.
-
bool video = false
A boolean that indicates whether the application should capture local video and send it to a conference.
-
bool send_only = false
Allows the user to join a conference as a sender only. This is strictly intended for applications that want to inject media without recording. Applications which set this flag will not receive media.
-
bool audio = false
Spatial Audio
#include <dolbyio/comms/spatial_audio_types.h>
The spatial audio methods that allow placing conference participants spatially in a 3D rendered audio scene and hear the audio from the participants rendered at the given locations.
-
struct spatial_position
The participant’s position in space defined using Cartesian coordinates.
Public Functions
-
inline constexpr spatial_position(double x, double y, double z)
The constructor for spatial position.
- Parameters:
x – The x-coordinate of a new audio location.
y – The y-coordinate of a new audio location.
z – The z-coordinate of a new audio location.
-
inline constexpr spatial_position(double x, double y, double z)
-
struct polar_position
The participant’s position in a spherical coordinate system.
Public Functions
-
inline constexpr polar_position(double azimuth, double elevation, double distance)
The constructor for the polar position in spherical coordinate system.
- Parameters:
azimuth – The angle of rotation from the initial meridian plane.
elevation – The polar angle to the point, angle with respect to the polar axis.
distance – The radial distance to the point from the origin.
-
inline constexpr polar_position(double azimuth, double elevation, double distance)
-
struct spatial_direction
The direction a participant is facing in space. The spatial direction is specified as a set of three Euler rotations about the corresponding axis in the order of z-x-y.
Public Functions
-
inline constexpr spatial_direction(double x, double y, double z)
The constructor taking the three Euler rotations.
- Parameters:
x – A rotation about the x-axis.
y – A rotation about the y-axis.
z – A rotation about the z-axis.
-
inline constexpr spatial_direction(double x, double y, double z)
-
struct spatial_scale
Information on how to convert units from the application’s coordinate system (pixels or centimeters) into meters used by the spatial audio coordinate system.
Public Functions
-
inline constexpr spatial_scale(double x, double y, double z)
The constructor taking the three scale parameters creating the scale vector.
- Parameters:
x – The x component of the vector.
y – The y component of the vector.
z – The z component of the vector.
-
inline constexpr spatial_scale(double x, double y, double z)
-
class spatial_audio_batch_update
Batched spatial audio updates that can be passed to the conference service.
This class contains the ordered list of spatial audio updates which will be performed atomically in the conference. If you wish to update multiple spatial audio parameters, for example multiple spatial positions in the individual mode, use this method to batch all relevant updates in a single batch update object. This approach prevents delays between the application of the provided parameters.
Public Types
-
using action = std::variant<position, spatial_direction, environment>
A helper for defining a variant for position, direction, and environment.
Public Functions
-
void set_spatial_position(const std::string &participant_id, const spatial_position &position)
Sets a remote participant’s position in space. If the remote participant does not have an established location, the participant does not have a default position and will remain muted until a position is specified.
- Parameters:
participant_id – The ID of the remote participant.
position – The position of the remote participant.
-
void set_spatial_direction(const spatial_direction &direction)
Sets the direction the local participant is facing in space.
- Parameters:
direction – The direction the participant is facing.
-
void set_spatial_environment(const spatial_scale &scale, const spatial_position &forward, const spatial_position &up, const spatial_position &right)
Configures a spatial environment of an application, so the audio renderer understands which directions the application considers forward, up, and right and which units it uses for distance.
- Attention
Setting spatial environment causes invalidating all participants’ positions and the local participant’s direction. If no new values for positions, local participant’s position in the shared more, or local direction are provided, the previously supplied values are reused and translated against the new environment. This is not the desired behaviour, because the original values provided by the application were intended to be used with the previously set environment, not the new one. If the environment update is required, it should be the first operation in the batch that should be followed with the update of local participant’s direction and participants’ positions in the same batch object.
- Parameters:
scale – A scale that defines how to convert units from the coordinate system of an application (pixels or centimeters) into meters used by the spatial audio coordinate system.
forward – A vector describing the direction the application considers as forward. The value can be either +1, 0, or -1 and must be orthogonal to up and right.
up – A vector describing the direction the application considers as up. The value can be either +1, 0, or -1 and must be orthogonal to forward and right.
right – A vector describing the direction the application considers as right. The value can be either +1, 0, or -1 and must be orthogonal to up and forward.
-
inline const std::vector<action> &get_actions() const
Gets the const reference to current actions which were applied this spatial_audio_batch_update.
- Returns:
Reference to currently set actions.
-
inline std::vector<action> &&move_actions() &&
Gets an R-value reference to the current actions that were applied to the spatial_audio_batch_update. This API moves the actions in the process.
- Returns:
The R-value reference to the currently set actions.
-
struct environment
A structure describing the spatial environment of an application, so the audio renderer understands which directions the application considers forward, up, and right and which units it uses for distance.
Public Functions
-
inline constexpr environment(const spatial_scale &scale, const spatial_position &forward, const spatial_position &up, const spatial_position &right)
The constructor taking the spatial scale, and spatial positions for the three directions.
- Parameters:
scale – A scale that defines how to convert units from the coordinate system of an application (pixels or centimeters) into meters used by the spatial audio coordinate system.
forward – A vector describing the direction the application considers as forward. The value can be either +1, 0, or -1 and must be orthogonal to up and right.
up – A vector describing the direction the application considers as up. The value can be either +1, 0, or -1 and must be orthogonal to forward and right.
right – A vector describing the direction the application considers as right. The value can be either +1, 0, or -1 and must be orthogonal to forward and up.
Public Members
-
spatial_scale scale
A scale that defines how to convert units from the coordinate system of an application (pixels or centimeters) into meters used by the spatial audio coordinate system.
-
spatial_position forward
A vector describing the direction the application considers as forward. The value can be either +1, 0, or -1 and must be orthogonal to up and right.
-
spatial_position up
A vector describing the direction the application considers as up. The value can be either +1, 0, or -1 and must be orthogonal to forward and right.
-
spatial_position right
A vector describing the direction the application considers as right. The value can be either +1, 0, or -1 and must be orthogonal to forward and up.
-
inline constexpr environment(const spatial_scale &scale, const spatial_position &forward, const spatial_position &up, const spatial_position &right)
-
struct position
A structure describing the position of a conference participant.
Public Functions
-
inline position(const std::string &participant_id, const spatial_position &pos)
The constructor taking the participant ID and the preferred spatial position of the participant.
- Parameters:
participant_id – The participant ID.
pos – The preferred position for the participant.
Public Members
-
std::string participant_id
The participant ID.
-
spatial_position pos
The preferred position for the participant.
-
inline position(const std::string &participant_id, const spatial_position &pos)
-
using action = std::variant<position, spatial_direction, environment>
-
enum class dolbyio::comms::spatial_audio_style
The possible spatial audio styles of the conference. Setting spatial_audio_style is possible only if the dolby_voice flag is set to true. You can either use the individual or shared option.
Values:
-
enumerator disabled
Spatial audio is disabled.
-
enumerator individual
The individual option sets the spatial location that is based on the spatial scene, local participant’s position, and remote participants’ positions. This allows a client to control the position using the local, self-contained logic. However, the client has to communicate a large set of requests constantly to the server, which increases network traffic, log subsystem pressure, and complexity of the client-side application.
Spatial audio for shared scenes, The shared option sets the spatial location that is based on the spatial scene and the local participant’s position, while the relative positions among participants are calculated by the Dolby.io server. This way, the spatial scene is shared by all participants, so that each client can set its own position and participate in the shared scene. This approach simplifies communication between the client and the server and decreases network traffic.
-
enumerator disabled
Conference Events
The Conference Service events that are emitted by the SDK. You can subscribe to the events using the conference::add_event_handler
methods.
-
struct active_speaker_changed
Emitted whenever the active speaker changes. An empty list of speakers indicates that there is no active speaker.
-
struct conference_status_updated
Emitted whenever conference status changes.
Public Functions
-
inline conference_status_updated(conference_status value, const std::string &conf_id = std::string())
A constructor that takes the status of the event.
- Parameters:
value – The current status of a conference.
conf_id – The ID of the conference for which the status changed.
-
inline bool is_ended() const
Returns true if the conference is ended.
The status like creating or created describe an inactive conference, but are not ended. The left, error or destroyed statuses describe an ended conference. The ended conference may require cleanup on the application side, depending on how the application interacts with the SDK events.
- Returns:
true if the conference has ended, false if it’s active or was never active.
Public Members
-
conference_status status
The conference status.
-
std::string id
The unique identifier of the conference.
-
inline conference_status_updated(conference_status value, const std::string &conf_id = std::string())
-
enum class dolbyio::comms::conference_status
Possible values representing the current status of a conference.
Values:
-
enumerator creating
The SDK is creating a new conference.
-
enumerator created
The conference is created.
-
enumerator joining
The local participant is joining a conference.
-
enumerator joined
The local participant successfully joined the conference.
-
enumerator leaving
The local participant is leaving the conference.
-
enumerator left
The local participant left the conference.
-
enumerator destroyed
The conference is destroyed on the server.
-
enumerator error
A conference error occurred.
-
enumerator creating
-
struct participant_added
Emitted when a participant successfully joins the conference.
Public Functions
-
inline participant_added(const participant_info &info, const std::string &conf_id)
-
participant_added(participant_added&&) = delete
-
participant_added(const participant_added&) = delete
-
participant_added &operator=(participant_added&&) = delete
-
participant_added &operator=(const participant_added&) = delete
Public Members
-
const participant_info &participant
Information about the participant.
-
const std::string &conference_id
Conference ID.
-
inline participant_added(const participant_info &info, const std::string &conf_id)
-
struct participant_updated
Emitted when a participant changes status.
Public Functions
-
inline participant_updated(const participant_info &info, const std::string &conf_id)
-
participant_updated(participant_updated&&) = delete
-
participant_updated(const participant_updated&) = delete
-
participant_updated &operator=(participant_updated&&) = delete
-
participant_updated &operator=(const participant_updated&) = delete
Public Members
-
const participant_info &participant
Updated information about the participant.
-
const std::string &conference_id
Conference ID.
-
inline participant_updated(const participant_info &info, const std::string &conf_id)
-
struct video_track_added
Emitted when a new video track is received.
Public Members
-
video_track track
The track being added.
-
video_track track
-
struct video_track_removed
Event indicates that a video track is no longer being received.
Public Members
-
video_track track
The track being removed.
-
video_track track
-
struct audio_track_added
Emitted when a new audio track is received.
Public Members
-
std::string peer_id
The ID of the participant to whom the audio track belongs.
-
std::string stream_id
The ID of the stream to which the audio track belongs.
-
std::string track_id
The ID of the audio track.
-
bool remote
Boolean indicating whether the track is from a remote participant.
-
std::string peer_id
-
struct audio_track_removed
Emitted when an audio track is removed and no longer received.
Public Members
-
std::string peer_id
The ID of the participant to whom the audio track belonged.
-
std::string stream_id
The ID of the stream to which the audio track belonged.
-
std::string track_id
The ID of the video track.
-
bool remote
Boolean indicating whether the track is from a remote participant.
-
std::string peer_id
-
struct recording_status_updated
Emitted when the conference starts or stops being recorded by the backend.
Public Types
Public Members
-
std::string conference_id
The unique identifier of the conference.
-
std::string user_id
The unique identifier of the participant who started/stopped the recording.
-
recording_status status
The status of the recording update.
-
std::optional<long> start_timestamp
Timestamp of when the recording was started. Optional is empty if status is not recording.
-
std::string conference_id
-
struct video_forwarded_changed
Emitted whenever the list of forwarded video streams changes.
-
struct conference_message_received
Emitted when a new message is received in the current conference.
Public Members
-
std::string conference_id
The unique identifier of the current conference.
-
std::string user_id
The unique identifier of the participant who sent the message.
-
struct participant_info::info sender_info
Additional information about the sender of the message.
-
std::string message
The message.
-
std::string conference_id
-
struct conference_invitation_received
Emitted when a new conference invitation is received.
Public Members
-
std::string conference_id
The unique identifier of the conference.
-
std::string conference_alias
The Alias for the conference.
-
struct participant_info::info sender_info
Additional information about the sender of the invitation.
-
std::string conference_id
-
struct audio_level
A single participant audio level.
Public Members
-
std::string participant_id
The ID of the participant to whom the talking level corresponds.
-
float level = {0.0}
Talking level of participant values from 0.0 to 1.0.
Public Static Attributes
-
static constexpr float speaking_threshold = 0.05f
The audio level below which the participant is considered inaudible (background noise may make the level not drop to 0).
-
std::string participant_id
-
struct audio_levels
Emitted periodically in conference to deliver participant audio levels.
Participants not present in the collecition are not speaking.
Public Members
-
std::vector<dolbyio::comms::audio_level> levels
The list of all active speakers with their audio levels.
-
std::vector<dolbyio::comms::audio_level> levels
Other Structures
Other structures used by the Conference Service, which are not defined in the Conference Interface interface.
-
struct conference_info
Contains the conference information. This structure provides conference details that are required to join a specific conference. The SDK returns conference_info to describe the created or joined conference.
Public Members
-
std::string id
The unique conference identifier.
-
std::optional<std::string> alias = {}
The conference alias. The alias is optional in the case of using the conference ID.
-
bool is_new = false
Indicates whether the conference represented by the object has just been created.
-
conference_status status
The current status of the conference.
-
std::vector<conference_access_permissions> permissions = {}
Permissions that allow a conference participant to perform limited actions during a protected conference.
-
std::unordered_map<participant_info::id, participant_info> participants = {}
Conference participants
-
std::optional<enum spatial_audio_style> spatial_audio_style = {}
The spatial audio style used in the joined conference. This is only set when the conference has been successfully joined.
- Since
2.1.0
-
dolbyio::comms::video_codec video_codec = {}
The video codec to be used in the conference.
- Since
2.4.0
-
bool audio_only = {}
Indicates whether the conference represented by the object is audio only.
- Since
2.4.0
-
bool dolby_voice = {}
- Since
2.4.0 Indicates whether the conference represented by the object is a Dolby Voice conference.
-
std::vector<recording_format> recording_formats = {}
Indicates the possible recording formats the conference recording can be stored in.
- Since
2.4.0
-
dolbyio::comms::rtcp_mode rtcp_mode = {}
The bitrate adaptation mode used for the video transmission.
- Since
2.4.0
-
bool live_recording = {}
Indicates whether the conference is being recorded. If true the video recorded file shall be available at the end of the call and downloadable immediately.
- Since
2.4.0
-
std::string id
-
enum class dolbyio::comms::conference_access_permissions
Conference Access Permissions provided to a particpant who is invited to a conference.
Values:
-
enumerator invite
Allows a participant to invite participants to a conference.
-
enumerator join
Allows a participant to join a conference.
-
enumerator send_audio
Allows a participant to send an audio stream during a conference.
-
enumerator send_video
Allows a participant to send a video stream during a conference.
Allows a participant to share their screen during a conference.
Allows a participant to share a video during a conference.
Allows a participant to share a file during a conference.
-
enumerator send_message
Allows a participant to send a message to other participants during a conference. Message size is limited to 16KB.
-
enumerator record
Allows a participant to record a conference.
-
enumerator stream
Allows a participant to stream a conference.
-
enumerator kick
Allows a participant to kick other participants from a conference.
-
enumerator update_permissions
Allows a participant to update other participants’ permissions.
-
enumerator invite
-
enum class dolbyio::comms::listen_mode
The listen mode for the conference joined as a listener.
Values:
-
enumerator regular
Receive multiple video streams from senders.
-
enumerator rts_mixed
Receive a realtime mixed stream.
-
enumerator regular
-
struct participant_info
Contains the current status of a conference participant and information whether the participant’s audio is enabled.
Public Types
-
using id = std::string
Public Functions
-
participant_info() = default
-
inline participant_info(id &&user_id, std::optional<participant_type> type, std::optional<participant_status> status, info info, std::optional<bool> is_sending_audio, std::optional<bool> audible_locally)
Public Members
-
std::optional<participant_type> type = {}
The type of the participant.
-
std::optional<participant_status> status = {}
The current status of the participant.
-
std::optional<bool> is_sending_audio = {}
A boolean that informs whether the participant is sending audio into conference.
-
std::optional<bool> audible_locally = {}
Indicates whether a remote participant is audible locally. This will always be false for the local participant.
-
struct info
Information about a conference participant.
Public Members
-
std::optional<std::string> name = {}
The participant’s name.
-
std::optional<std::string> external_id = {}
The external unique identifier that the customer’s application can add to the participant while opening a session. If a participant uses the same external ID in conferences, the participant’s ID also remains the same across all sessions.
-
std::optional<std::string> avatar_url = {}
The URL of the participant’s avatar.
-
std::optional<std::string> name = {}
-
using id = std::string
-
enum class dolbyio::comms::participant_status
The possible statuses of conference participants.
Values:
-
enumerator reserved
A participant is invited to a conference and is waiting for an invitation.
-
enumerator connecting
A participant received a conference invitation and is connecting to the conference.
-
enumerator on_air
A participant successfully connected to the conference.
-
enumerator decline
An invited participant declined the conference invitation.
-
enumerator inactive
A participant does not send any audio, video, or screen-share stream to the conference.
-
enumerator left
A participant left the conference.
-
enumerator warning
A participant experiences a peer connection problem.
-
enumerator error
A participant cannot connect to the conference due to a peer connection failure.
-
enumerator reserved
-
enum class dolbyio::comms::participant_type
The type of participant.
Values:
-
enumerator user
A participant who can send and receive an audio and video stream during a conference.
-
enumerator listener
A participant who can receive audio and video streams, but cannot send any stream to a conference.
-
enumerator user
-
enum class dolbyio::comms::recording_format
The possible recording formats for the conference.
Values:
-
enumerator mp3
MP3 coding format for digital audio.
-
enumerator mp4
MP4 container used for storing video and audio.
-
enumerator mp3
-
enum class dolbyio::comms::rtcp_mode
The bitrate adaptation mode used for the video transmission.
Values:
-
enumerator worst
Adjusts the transmission bitrate to the receiver who has the worst network conditions.
-
enumerator average
Averages the available bandwidth of all the receivers and adjusts the transmission bitrate to this value. This is the default value used.
-
enumerator max
Does not adjust the transmission bitrate to the receiver’s bandwidth.
-
enumerator worst
The screen share content type provides a hint to the SDK as to what type of content is being captured by the screen share. This can be used to help when making decisions for choosing encoder settings based on what aspects of the content are important. For instance if network conditions worsen is it more important to keep a higher resolution of screen share or frame rate to keep the motion more fluid.
Values:
The default value not specifying content type.
Content is very detailed, encoder should keep resolution high if it can.
Content is text.
Content is fluid like a video for instance, encoder should keep frame rate higher.
-
enum class dolbyio::comms::video_codec
The preferred video codec, either H264 or VP8.
Values:
-
enumerator none
No codec used (meaning no video).
-
enumerator h264
The H264 codec.
-
enumerator vp8
The VP8 codec.
-
enumerator none
-
enum class dolbyio::comms::video_forwarding_strategy
Defines how the SDK should select conference participants whose videos will be transmitted to the local participant. There are two possible values; the selection can be either based on the participants’ audio volume or the distance from the local participant. By default, the SDK uses the last_speaker strategy.
Values:
-
enumerator last_speaker
Selects participants based on their audio volume, which means that the local participant receives video streams only from active speakers.
-
enumerator closest_user
Selects participants based on the distance from the local participant. This means that the local participant receives video streams only from the nearest participants. This strategy is available only for participants who enabled spatial audio.
-
enumerator last_speaker