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 or conference::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.

virtual async_result<void> start_screen_share(const dolbyio::comms::screen_share_source &source, const std::shared_ptr<dolbyio::comms::video_frame_handler> &handler, dolbyio::comms::screen_share_content_type type = dolbyio::comms::screen_share_content_type::detailed) = 0

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.

virtual async_result<void> stop_screen_share() = 0

Stops the screen share capture.

Returns:: The result object producing the operation status asynchronously.

virtual async_result<void> screen_share_content_type(dolbyio::comms::screen_share_content_type type) = 0

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.

params params: The conference parameters.

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.

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.

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.

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.

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.

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.

Public Members

double x: The x-coordinate of a new audio location..

double y: The y-coordinate of a new audio location.

double z: The z-coordinate of a new audio location.

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.

Public Members

double azimuth: The angle of rotation from the initial meridian plane.

double elevation: The polar angle to the point, angle with respect to the polar axis.

double distance: The radial distance to the point from the origin.

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.

Public Members

double x: A rotation about the x-axis.

double y: A rotation about the y-axis.

double z: A rotation about the z-axis.

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.

Public Members

double x: The x component of the vector.

double y: The y component of the vector.

double z: The z component of the vector.

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.

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.

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.

enumerator shared: 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.

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.

Public Members

std::string conference_id: The unique identifier for the current conference.

std::vector<std::string> active_speakers: The list of all active speakers.

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.

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.

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.

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.

struct video_track_added

Emitted when a new video track is received.

Public Members

video_track track: The track being added.

struct video_track_removed

Event indicates that a video track is no longer being received.

Public Members

video_track track: The track being removed.

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.

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.

struct recording_status_updated

Emitted when the conference starts or stops being recorded by the backend.

Public Types

enum class recording_status

Enum describing the recording status.

Values:

enumerator recording: Conference is being recorded.

enumerator not_recording: Conference is not being recorded.

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.

struct video_forwarded_changed

Emitted whenever the list of forwarded video streams changes.

Public Members

std::string conference_id: The unique identifier for the current conference.

std::vector<std::string> video_forwarded_participants: The list of all participants whose camera streams are forwarded.

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.

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.

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

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.

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

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.

enumerator share_screen: Allows a participant to share their screen during a conference.

enumerator share_video: Allows a participant to share a video during a conference.

enumerator share_file: 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.

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.

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

id user_id = {}: The unique identifier of the participant.

std::optional<participant_type> type = {}: The type of the participant.

std::optional<participant_status> status = {}: The current status of the participant.

info info: Additional information about 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.

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.

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.

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.

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.

enum class dolbyio::comms::screen_share_content_type

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:

enumerator unspecified: The default value not specifying content type.

enumerator detailed: Content is very detailed, encoder should keep resolution high if it can.

enumerator text: Content is text.

enumerator fluid: 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.

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.