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:
  1. Log in to Session Interface.

  2. Subscribe to any of the available Conference Events using the conference::add_event_handler method.

  3. Create a conference using a conference alias conference::create. You can omit this step if you want to join an existing conference.

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

  5. 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> replay(const std::string &conference_id) = 0

Creates a replay conference and joins to it upon completion.

// Wait for the conference creation
auto conf_info = wait(sdk->conference().replay(some_conf_id));

 // Invoking the method directly requires chaining successive operations
 // via the `then` call
sdk->conference().replay(some_conf_id))
   .then[](auto&& info) {
     // Do something with the returned conf info;
   })
   .on_error([](auto&& e) {
     // Handle exception
   });

Parameters:

conference_id – The ID of the conference to replay.

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) = 0

Starts local capture of screen share.

Deprecated:

As of 2.5.0

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

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> 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_info &&info = {dolbyio::comms::screen_share_content_info::encoder_hint::detailed, dolbyio::comms::screen_share_content_info::max_resolution::actual_captured, dolbyio::comms::screen_share_content_info::downscale_quality::low}) = 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.

  • info – Information for the SDK to adapt the screen 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.

Deprecated:

As of 2.5.0

Parameters:

type – The type of screen share content

Returns:

The result object producing the operation status asynchronously.

virtual async_result<void> screen_share_content_info(dolbyio::comms::screen_share_content_info &&info) = 0

Change the screen share content info 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:

info – Information for the SDK to adapt the screen content being captured.

Returns:

The result object producing the operation status asynchronously.

virtual async_result<void> start_recording() = 0
virtual async_result<void> stop_recording() = 0
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<remote_participant_added> &&callback) = 0

Adds a listener for the remote 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::remote_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::remote_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 remote 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<remote_participant_updated> &&callback) = 0

Adds a listener for remote_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::remote_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::remote_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 remote participant changes status.

Returns:

The result object producing the event_handler_id asynchronously.

virtual async_result<event_handler_id> add_event_handler(event_handler<local_participant_updated> &&callback) = 0

Adds a listener for local_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::local_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::local_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 local participant changes status.

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
virtual async_result<event_handler_id> add_event_handler(event_handler<participant_added> &&callback) = 0
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::local_video_track_added> &&callback) = 0

Adds a listener for local_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::local_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 of a local participant 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::remote_video_track_added> &&callback) = 0

Adds a listener for remote_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::remote_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 of a remote participant 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::local_video_track_removed> &&callback) = 0

Adds a listener for local_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::local_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::local_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::remote_video_track_removed> &&callback) = 0

Adds a listener for remote_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::remote_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::remote_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 of the remote participant 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::video_track_removed> &&callback) = 0
virtual async_result<event_handler_id> add_event_handler(event_handler<dolbyio::comms::video_track_added> &&callback) = 0
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.

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.

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.

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.

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 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, spatial_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 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 local_participant_updated

Emitted when a local participant changes status.

Public Functions

inline local_participant_updated(const participant_info &info, const std::string &conf_id)
local_participant_updated(local_participant_updated&&) = delete
local_participant_updated(const local_participant_updated&) = delete
local_participant_updated &operator=(local_participant_updated&&) = delete
local_participant_updated &operator=(const local_participant_updated&) = delete

Public Members

const local_participant &participant

Updated information about the participant.

const std::string &conference_id

Conference ID.

struct remote_participant_updated

Emitted when a remote participant changes status.

Public Functions

inline remote_participant_updated(const remote_participant &info, const std::string &conf_id)
remote_participant_updated(remote_participant_updated&&) = delete
remote_participant_updated(const remote_participant_updated&) = delete
remote_participant_updated &operator=(remote_participant_updated&&) = delete
remote_participant_updated &operator=(const remote_participant_updated&) = delete

Public Members

const remote_participant &participant

Updated information about the participant.

const std::string &conference_id

Conference ID.

struct remote_participant_added

Emitted when a remote participant successfully joins the conference.

Public Functions

inline remote_participant_added(const remote_participant &info, const std::string &conf_id)
remote_participant_added(remote_participant_added&&) = delete
remote_participant_added(const remote_participant_added&) = delete
remote_participant_added &operator=(remote_participant_added&&) = delete
remote_participant_added &operator=(const remote_participant_added&) = delete

Public Members

const remote_participant &participant

Information about the participant.

const std::string &conference_id

Conference ID.

struct local_video_track_added

Emitted when a new remote video track is received.

Public Members

local_video_track track

The track being added.

struct local_video_track_removed

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

Public Members

local_video_track track

The track being removed.

struct remote_video_track_added

Emitted when a new remote video track is received.

Public Members

remote_video_track track

The track being added.

struct remote_video_track_removed

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

Public Members

remote_video_track track

The track being removed.

struct participant_added

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
const std::string &conference_id
struct participant_updated

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
const std::string &conference_id
struct video_track_added

Public Members

generic_video_track track

The track being added.

struct video_track_removed

Public Members

generic_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 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<int64_t> 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)
inline bool is_in_conference() const noexcept
inline bool operator<(const participant_info &other) const noexcept
inline bool operator==(const participant_info &other) const noexcept

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 average

Averages the available bandwidth of all the receivers and adjusts the transmission bitrate to this value. This is the default value used.

enumerator worst

Adjusts the transmission bitrate to the receiver who has the worst network conditions.

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.

Deprecated:

2.5.0

Note

This enum is deprecated as of 2.5.0 please use the screen_share_content_info.

Values:

enumerator unspecified

The content hint is not specified, encoder will choose settings based on the fact track is screen share only.

enumerator detailed

Content is detailed, encoder should keep resolution high if it can.

enumerator text

Content is text, encoder should keep resolution high if it can.

enumerator fluid

Content is fluid like a video for instance, encoder should keep frame rate higher.

struct screen_share_content_info

The information about the capture screen share content to be provided to the SDK. Applications should make used of this to optimize for the content they are sharing. For example sharing dynamic content like a youtube video the ideal settings are encoder_hint::fluid, max_resolution::downscale_to_1080p, downscale_quality::high.

Public Types

enum class encoder_hint

The encoder hint 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 content hint is not specified, encoder will choose settings based on the fact track is screen share only.

enumerator detailed

Content is detailed, encoder should keep resolution high if it can.

enumerator text

Content is text, encoder should keep resolution high if it can.

enumerator fluid

Content is fluid, full of motion, encoder should keep frame rate higher.

enum class max_resolution

The max resolution for the capture screen content to be shared as. If the actual captured resolution is higher than the set max resolution the SDK will downscale to the max resolution. The SDK captures screen content based on the chosen displays resolution. The max resolution will be downscaled too if the captured resolution is higher, otherwise this has no effect. Therefore the screen content will never be shared at a resolution higher than the one set here, but if the captured display has lower resolution the content will not be upscaled.

Values:

enumerator downscale_to_1080p

Downscale the height to 1080p, the width will be chosen to respect the actual aspect ratio of the raw captured frame. Downscaling will only happen if the captured resolution is higher.

enumerator downscale_to_1440p

Downscale the height to 1440p, the width will be chosen to respect the actual aspect ratio of the raw captured frame. Downscaling will only happen if the captured resolution is higher.

enumerator actual_captured

No downscaling, send the content to the encoder in the actual captured resolution.

enum class downscale_quality

The quality for the downscaling algorithm to be used. The higher the quality the clearer the picture will be by more CPU usage to perform the downscaling.

Values:

enumerator low

Use the quicker algorithm, fast and lowest cpu used but low quality.

enumerator medium

Use the linear filter algorithm used mainly for horizontal scaling.

enumerator high

Use the bilinear filter algorithm, faster than highest but not as good quality. If downscaling fluid screen content from 4K to 1080p this should be used.

enumerator highest

Use the box filter algorithm, uses the most CPU and is the slowest but produces the best quality. If downscaling detailed screen content from 4K to 2K this should be used.

Public Members

encoder_hint hint

The encoding hint for the screen share content used by the SDK.

max_resolution resolution

The maximum resolution of the screen capture to be shared it.

downscale_quality quality

Downscaling algorithm quality used by the SDK.

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.