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. Create the media recording module instance. If you want to use the Default Recorder, use the Default Recorder Interface API, specifically the recorder::create method.

  3. Provide the output directory location for the recorder module.

  4. Set the media recording module as the Media Sink for the Conference Service. This allows passing the service a pointer to the created recorder instance. After this step, the recorder module should be set with the conference::set_media_sink.

  5. Create the Media Injector Module instance using the Default Injector provided through the Default Media Injector API. Specifically the injector_paced or the injector_passthrough constructors.

  6. Create a Media Injection Source that adds the ability to provide raw frames to the Media Injector Module. This can be an application which reads from a file, gets remote stream, and provides the media frames to the injector. This Media Injection Source should be passed as a reference to the Media Injector Module on creation.

  7. Set the Injector Module instance as the Media Source for the Conference Service via the conference::set_media_source method.

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

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

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

  11. To leave the conference, call the conference::leave method.

By default, Dolby Voice Conference Server audio processing is disabled. You can enable the processing by setting the audio_processing flag to true in dolbyio::comms::services::conference::media_constraints.

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 dolbyio::comms::services::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(bool spatialAudio = true) = 0

Creates a demo conference and joins to it upon completion.

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

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

Parameters:

spatialAudio – A boolean flag enabling spatial audio for the joining participant. The default value is true.

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) = 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"));

// Invoking the method directly requires chaining successive operations
// via the `then` call
 sdk->conference().send("some message")
 .then([]() {
    // the message was sent
 })
 .on_error([](auto&& e){
    // rethrow and handle the exception
 });

Parameters:

message – The message.

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 mic 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 mic 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 faced by the local participant.

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> set_media_sink(media_sink_interface *sink) = 0

Sets the Media Recorder instance as the Media Sink for the SDK. The Media Recorder module handles pipelines for receiving, encoding, and muxing audio and video frames. The module also captures and processes audio and video tracks produced by WebRTC. The plugin::recorder module is available as the default recorder, although application users can also provide their own recorders.

// Invoke the method via wait blocks until the method succeeds or fails
wait(sdk->conference().set_media_sink(recorder));

// Invoking the method directly requires chaining successive operations
// via the `then` call
sdk->conference().set_media_sink(recorder)
  .then([]() {
    // Media capturer is now set
  })
  .on_error([](auto&& e) {
    // handle exception
  });
Attention

The media recorder can not be set when a conference is active.

Note

The concept of a media sink for recording media is intended for Server application.

Parameters:

sink – The pointer to the instance of the Media Sink interface, which can be either the default recorder created through the plugin::recorder interface or an implemented customized recording module.

Returns:

The result object producing the operation status asynchronously.

virtual async_result<void> set_media_source(media_source_interface *source) = 0

Sets the Media Injector instance as the Media Source for the SDK. The Media Injector module handles the injection of audio and video frames into WebRTC media pipelines. The module allows providing raw media frames from any source, for example, an external stream or a media file. The plugin::injector_paced and plugin::injector_passthrough modules are available as default injectors, although applications can also provide their own.

// Invoke the method via wait blocks until the method succeeds or fails
wait(sdk->conference().set_media_source(injector));

// Invoking the method directly requires chaining successive operations
// via the `then` call
sdk->conference().set_media_source(injector)
  .then([]() {
    // Media source is now set
  })
  .on_error([](auto&& e) {
    // handle exception
  });
Attention

The media injector can not be set when a conference is active.

Note

The concept of a media source for injection media is intended for Server application.

Parameters:

source – The pointer to the instance of the Media Source interface, which can be either the default injector or an implemented customized injector module.

Returns:

The result object producing the operation status asynchronously.

virtual async_result<void> start_video() = 0

Deprecated:

Use local_video::start instead.

virtual async_result<void> stop_video() = 0

Deprecated:

Use local_video::stop instead.

virtual async_result<void> start_audio() = 0

Deprecated:

Use local_audio::start instead.

virtual async_result<void> stop_audio() = 0

Deprecated:

Use local_audio::stop instead.

virtual async_result<void> start_remote_audio(const std::string &participant_id) = 0

Deprecated:

Use remote_audio::start instead.

virtual async_result<void> stop_remote_audio(const std::string &participant_id) = 0

Deprecated:

Use remote_audio::stop instead.

virtual async_result<void> set_audio_processing(bool audio_processing) = 0

Deprecated:

Use local_audio::set_capture_mode instead.

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 deline invitation
  });

Parameters:

conf_id – The conference ID.

Returns:

The result object producing the operation status asynchronously.

virtual async_result<float> get_audio_level(const std::string &participant_id) = 0

Gets a specific participant’s audio level.

// Invoke the method via wait blocks until the method succeeds or fails
float audio_level = wait(sdk->conference().get_audio_level(participant_id));

// Invoking the method directly requires chaining successive operations
// via the `then` call
sdk->conference().get_audio_level(participant_id)
  .then([](float&& audio_level) {
    // use the returned audio level
  })
  .on_error([](auto&& e) {
    // handle exception
  });

Parameters:

participant_id – The ID of the participant.

Returns:

The object producing the audio level (between 0.0 and 1.0) asynchronously.

virtual async_result<std::vector<dolbyio::comms::audio_level>> get_all_audio_levels() = 0

Gets audio levels for all participants whose audio level is greater than or equal to 0.05.

// Invoke the method via wait blocks until the method succeeds or fails
auto audio_levels = wait(sdk->conference().get_all_audio_levels());

// Invoking the method directly requires chaining successive operations
// via the `then` call
sdk->conference().get_all_audio_levels()
  .then([](std::vector<dolbyio::comms::audio_level>&& audio_levels) {
    // process the returned audio levels
  })
  .on_error([](auto&& e) {
    // handle exception
  });

Returns:

The object producing the vector of audio_level structs {participant_id, audio_level (between 0.0 and 1.0)} 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 will be 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 will be 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 will be 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_change> &&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_change& 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_change& 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 will be 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<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 will be 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 will be 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 will be 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 will be 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 libray.

// 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 will be 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 will be invoked when a conference invitation 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.

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

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. Leaving this parameter unset results in 25 as the maximum number of video streams that can be transmitted to the SDK.

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.

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.

deprecated_field<bool> audio_processing = {}

Deprecated. Use sdk->audio().local().set_capture_mode() after join.

bool send_only = false

Allows the user to join a conference as a sender only. This is strictly intended for Server Side SDK applications that want to inject media without recording. This flag is ignored by the Client SDK applications.

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 dolbyio::comms::spatial_position

The participant’s position in space defined using Cartesian coordinates.

Public Functions

inline 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 dolbyio::comms::polar_position

The participant’s position in a spherical coordinate system.

Public Functions

inline 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 dolbyio::comms::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 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 dolbyio::comms::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 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 dolbyio::comms::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 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 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 dolbyio::comms::active_speaker_change

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 dolbyio::comms::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.

Public Members

conference_status status

The conference status.

std::string id

The unique identifier of the conference.

struct dolbyio::comms::participant_added

Emitted when a participant successfully joins the conference.

Public Functions

participant_added() = default
inline participant_added(participant_info &&info, const std::string &conf_id)

Public Members

participant_info participant

Information about the participant.

std::string conference_id

Conference ID.

struct dolbyio::comms::participant_updated

Emitted when a participant changes status.

Public Functions

participant_updated() = default
inline participant_updated(participant_info &&info, const std::string &conf_id)

Public Members

participant_info participant

Updated information about the participant.

std::string conference_id

Conference ID.

struct dolbyio::comms::video_track_added

Emitted when a new video track is received.

Public Members

std::string peer_id

The ID of the participant to whom the video track belongs.

std::string stream_id

The ID of the stream to which the video track belongs.

std::string track_id

The ID of the video track.

std::string sdp_track_id

The id of the track in the SDP matching the sender side

bool is_screenshare = false

A boolean that indicates whether the video track is a screen share track.

bool capturer_status = false

A boolean that indicates whether there is a sink attached to the video track.

bool remote

Boolean indicating whether the track is from a remote participant.

struct dolbyio::comms::video_track_removed

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

Public Members

std::string peer_id

The ID of the participant to whom the track belonged.

std::string stream_id

The ID of the stream to which the video track belonged.

std::string track_id

The ID of the video track.

std::string sdp_track_id

The ID of the track in the SDP matching the sender side.

bool is_screenshare = false

A boolean that indicates whether the video track was a screen share track.

bool capturer_status = false

A boolean that indicates whether there was a sink attached to the video track.

bool remote

Boolean indicating whether the track is from a remote participant.

struct dolbyio::comms::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 dolbyio::comms::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.

Other Structures

Other structures used by the Conference Service, which are not defined in the Conference Interface interface.

struct dolbyio::comms::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 been just 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 will only be set when the conference has been successfully joined.

Since

2.1.0

struct dolbyio::comms::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 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 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.