Getting Started

This guide will help you create a simple conference application.

Contents of the SDK package

All C++ SDK packages are available on GitHub: https://github.com/DolbyIO/comms-sdk-cpp/releases.

The following table lists the contents of the C++ SDK package:

Directory

Contents

include

Header files that create the public API

lib

Shared libraries constituting the C++ SDK

share

Cmake files for building target, samples, docs, and licenses

bin

Prebuilt sample application binaries

Note

On macOS, it is necessary to unquarantine SDK libraries and sample binaries. Otherwise, quarantine attributes prevent their usage. The simplest way to unquarantine is to strip the quarantine attributes recursively for all the files in the package. The following example presents how to do it via terminal and the macOS attribute stripping command line tool:

xattr -d -r com.apple.quarantine sdk-release/

CA certificates

The SDK uses Certificate Authority (CA) certificates to authenticate the identity of remote servers during an SSL handshake. The SDK library provides two options for selecting CA certificates:

The SDK library contains built-in CA certificates that are used by default.
The SDK library checks the value of the DOLBYIO_COMMS_CA_CERT_FILE environment variable. If the ENV variable points to a proper certificate file, these certificates are loaded.

The SDK does not try to use the system-installed CA cert files.

Getting the access token

Applications using the C++ SDK must provide an access token when creating the SDK. The sample applications provided as a part of the sdk-release package require the access token to be provided as a command line parameter when launching the executable. To get the access token from the Dolby.io dashboard, follow these instructions: https://docs.dolby.io/communications-apis/docs/overview-developer-tools

After getting the access token, you can build and run the Server and Client sample applications.

Spatial audio conferences

If you join a spatial audio conference using either Client sample application or Server sample application, you need to set your spatial position. All sample applications set the default spatial position for local participant to (0,0,0). For more information on interactively changing the position, please refer the interactive commands section of the aforementioned sample applications.

Client sample application

A basic Client C++ sample application allows joining a conference, using spatial audio configurations, sending the local participant’s audio to the conference, and playing audio received from the conference. The application is available in the sdk-release/share/dolbyio/comms/sample/client_app/ directory of the package. This directory contains C++ code for the application and the respective CMakeLists.txt file, which you can use to build the application.

The steps performed by the sample application are:

Parses command line parameters. The required parameters are: user access token, user name, and conference alias or conference ID.

Creates and initializes the SDK.

Opens a Dolby.io session. The session::open call returns a user_info object which contains the participant ID.

Creates and joins a specific conference.

Provides locally captured audio to the conference and plays received audio.

Sets the local participant’s initial position if the joined conference uses spatial audio. This requires using the participant ID returned by the open method. A spatial position must be set for the local participant before the conference, to allow remote participants to hear the local participant.

Manages local audio devices using the device_management interface.

Leaves the conference.

Closes the Dolby.io session.

The sample application makes use of the dolbyio::comms::wait() call for all asynchronous operations.

Build and run the sample application

Build the sample application in a few simple steps from the sample/ directory:

$ cd sdk-release/share/dolbyio/comms/sample/
$ mkdir build
$ cd build/ && cmake ../
$ cmake --build .
[ 12%] Building CXX object utilities/CMakeFiles/interactor_utils.dir/commands_handler.cc.o
[ 25%] Building CXX object utilities/CMakeFiles/interactor_utils.dir/sdk/interactions.cc.o
[ 37%] Building CXX object utilities/CMakeFiles/interactor_utils.dir/sdk/events.cc.o
[ 50%] Linking CXX static library libinteractor_utils.a
[ 50%] Built target interactor_utils
[ 62%] Building CXX object utilities/CMakeFiles/client_utils.dir/sdk/device_manager/interactions.cc.o
[ 75%] Linking CXX static library libclient_utils.a
[ 75%] Built target client_utils
[ 87%] Building CXX object client_app/CMakeFiles/client_app.dir/client_app.cc.o
[100%] Linking CXX executable client_app
[100%] Built target client_app

Run the created client_app executable using the following command line parameters

Argument

Description

-u

The participant’s name.

-e

The external ID

-k

The access token

-c

The conference alias (DEMO to join a demo conference)

-t

The conference access token

-i

The conference ID

-l

The logging level (0-5)

-j

The user type (user or listener)

-s

The send-only mode

-m

The initial media to send

-spatial

Spatial audio (shared|individual|disabled)

-force_opus

Forces the Opus codec usage (yes|no)

-log_speaker

Logs the active speaker changes (yes|no)

For example:

$ ./client_app -u USERNAME -k ACCESS_TOKEN -i CONF_ID -l LOG_LEVEL -j user -m A -spatial shared

Note

Providing the -i command line parameter causes that the application joins the specific conference if the conference with the provided ID already exists. Providing -c causes that the application joins the specific conference. If the requested conference does not exist on the Dolby.io backend, the application creates and joins the conference. Providing a DEMO value of the -c parameter causes that the application creates and joins a demo conference. If you do not provide CONFERENCE_ID nor CONFERENCE_ALIAS when joining, the application will open a session with the Dolby.io backend and wait for interactions. In this scenario, it is possible to listen for subscription or invitation events, get invited to conferences and invite others.

3. Interact with the client_app executable using one of the following command line options which can be provided whilst the application is running. The application will prompt the user for input and explain each of the options. If the chosen option requires more input, the user will be explicitly prompted for this as well.

Option

Description

q

Quits the application

stop-audio

Stops the local audio

start-audio

Starts the local audio

stop-audio-remote

Stops remote audio in a Dolby Voice conference

start-audio-remote

Starts remote audio in a Dolby Voice conference

m

Sends a message to a conference

P

Lists conference participants

S

Sets a spatial audio configuration

mute

Mutes the local participant’s microphone

unmute

Un-mutes the local participant’s microphone

mute-remote

Mutes a remote participant in a non-Dolby Voice conference

unmute-remote

Un-mutes a remote participant in a non-Dolby Voice conference

k

Sets output audio mute

K

Sets output audio un-mute

invite

Invites a participant to a conference

subscribe

Subscribes to all conference events

unsubscribe

Unsubscribes from all conference events

join

Joins a conference by providing ID

create

Creates a conference by providing alias

accept

Accepts a conference invitation

decline

Declines a conference invitation

audio-level

Get audio level for a single participant

audio-levels

Get audio levels for all participants in a conference

Note

For an optimal experience with the client application, please use only the interactive options listed above. While running the application, the interactive options “V” and “v” are displayed as possible options. Do not use these as video is not supported for client applications yet.

Server sample application

A basic Server C++ sample application allows joining a conference, recording streams using the default recorder, and injecting streams using the default injector and sample media source file library. The application is available in the sdk-release/share/dolbyio/comms/share/sample/server_app/ directory of the package. This directory contains C++ code for the application and the respective CMakeLists.txt file, which can be used to build the application.

The sample application can perform the following steps:

Parse command line parameters. The required parameters are: user access token, user name, and conference alias or conference ID.

Create and initialize the SDK.

Create an instance of the Default Media Recorder.

Configure the instance of the Media Recorder to capture PCM audio and encoded video.

Set the recorder instance as the media sink for the Conference Service.

Create an instance of the Default Media Injector.

Create an instance of the Media Source File module and provide it the previously created injector.

Set the injector instance as the media source for the Conference Service.

Open a Dolby.io session.

Create and join a specific conference.

After joining a conference with audio and video set to be injected to the conference, start capturing media using the Media Source File library.

Set the local participant’s initial position if the joined conference uses spatial audio. This requires using the participant ID returned by the open method. A spatial position must be set for the local participant before the conference, to allow remote participants to hear the local participant.

Leave the respective conference.

Close the Dolby.io session.

The sample application makes use of the dolbyio::comms::wait() call for all asynchronous operations. Additionally, the sample application makes use of the Default Media Recorder module. If you prefer to write your own Media Recorder, see the Example Recorder Implementation section. The sample application also uses the Default Media Injector module and the sample Media Source File library. If you would like to write your own Media Injector, see the Example Injector Implementation section. If you would like to write your own Media Source for the injector, check the Media Source File section, as well as the sample library itself.

Build and run the sample server application

Build the sample application from the sample/ directory in a few simple steps:

$ cd sdk-release/share/dolbyio/comms/sample/
$ mkdir build
$ cd build/ && cmake ../
$ cmake --build .
[  7%] Building CXX object media_source/CMakeFiles/media_source_file.dir/file/source_capture.cc.o
[ 15%] Building CXX object media_source/CMakeFiles/media_source_file.dir/file/libav_wrapper/avcontext.cc.o
[ 23%] Building CXX object media_source/CMakeFiles/media_source_file.dir/file/libav_wrapper/decoder.cc.o
[ 30%] Building CXX object media_source/CMakeFiles/media_source_file.dir/file/libav_wrapper/frame.cc.o
[ 38%] Building CXX object media_source/CMakeFiles/media_source_file.dir/file/utils/audio_buffer.cc.o
[ 46%] Building CXX object media_source/CMakeFiles/media_source_file.dir/file/utils/media_frame.cc.o
[ 53%] Linking CXX static library libmedia_source_file.a
[ 53%] Built target media_source_file
[ 53%] Built target server_utils
[ 61%] Building CXX object server_app/CMakeFiles/server_app.dir/server_app.cc.o
[ 69%] Building CXX object server_app/CMakeFiles/server_app.dir/__/utilities/sdk/interactions.cc.o
[ 76%] Building CXX object server_app/CMakeFiles/server_app.dir/__/utilities/sdk/events.cc.o
[ 84%] Building CXX object server_app/CMakeFiles/server_app.dir/__/utilities/media/injection/interactions.cc.o
[ 92%] Building CXX object server_app/CMakeFiles/server_app.dir/__/utilities/media/recording/interactions.cc.o
[100%] Linking CXX executable server_app
[100%] Built target server_app

Run the created sample_app executable using the following command line parameters

Argument

Description

-u

The user name

-e

The external ID

-k

The access token

-c

The conference alias (DEMO to join demo conference)

-t

The conference access token

-i

The conference ID

-l

The logging level (0-5)

-d

The relative path to OutputDirectory

-v

The video format for recording

-a

The audio format for recording

-j

The user type (user or listener)

-m

The initial media to inject

-f

The name of a media file to inject

-s

The send-only mode

-V

The maximum Video Forwarding value (0-25)

-spatial

Spatial audio (shared|individual|disabled)

-log_speaker

Logs the active speaker changes (yes|no)

For example:

$ ./server_app -u USERNAME -k ACCESS_TOKEN -i CONF_ID -v ENCODED_OPTIMIZED -a PCM -l LOG_LEVEL -j user -m AV -f test_file.mp4 -spatial shared

This example starts the application that:

Dumps the recorder streams in the encoded and PCM format respectively

Joins a conference as a user

Starts injecting audio and video from the test_file.mp4 to the conference

Note

Providing the -i command line parameter causes that the application joins the specific conference if the conference with the provided ID already exists. Providing -c causes that the application joins the specific conference. If the requested conference does not exist on the Dolby.io backend, the application creates and joins the conference. Providing a DEMO value of the -c parameter causes that the application creates and joins a demo conference. If you do not provide CONFERENCE_ID nor CONFERENCE_ALIAS when joining, the application will open a session with the Dolby.io backend and wait for interactions. In this scenario, it is possible to listen for subscription or invitation events, get invited to conferences and invite others.

3. Interact with the server_app executable using one of the following command line options, which can be provided whilst the application is running. The application will prompt the user for input and explain each of the options. If the chosen option requires more input, the user will be explicitly prompted for this as well. Also, all options denoted with a * indicate that application will directly interact with the Media Source File library.

Option

Description

q

Quits the application

f*

Sets a new media file to play

F*

Adds a new media file to a playlist

p*

Pauses the file injection

r*

Resumes the paused file injection

s*

Seeks to time in the file

stop-audio

Stops the local audio and audio injection

start-audio

Start the local audio and audio injection

stop-audio-remote

Stops remote audio in a Dolby Voice conference

start-audio-remote

Starts remote audio in a Dolby Voice conference

m

Sends a message to the conference

P

Lists conference participants

S

Sets a spatial audio configuration

mute

Mutes the local participant’s microphone

unmute

Un-mutes the local participant’s microphone

mute-remote

Mutes remote participant in a non-Dolby Voice conference

unmute-remote

Un-mutes remote participant in a non-Dolby Voice conference

v

Stops the local video and video injection

V

Starts the local video and video injection

invite

Invites a participant to a conference

subscribe

Subscribes to all conference events

unsubscribe

Un-subscribes from all conference events

join

Joins a conference by providing ID

create

Creates a conference by providing alias

accept

Accepts a conference invitation

decline

Declines a conference invitation

audio-level

Get audio level for a single participant

audio-levels

Get audio levels for all participants in a conference

Please note that in the sample application methods that start and stop audio and video consist of two parts. For example, for starting video, the first step uses the dolbyio::comms::services::conference::start_video() method, which attaches a video track to the active PeerConnection. This method resolves once the video track has been successfully added. Once this method is resolved, the injection of video from the Media Source starts. The following code block presents the entire procedure:

sdk->conference()
.start_video()
.then([injection_src]() {
  std::cerr << "start video success" << std::endl;
  if (injection_src)
    injection_src->set_video_capture(true);
})
.on_error([](std::exception_ptr&& e) {
  try {
    std::rethrow_exception(e);
  } catch (std::exception& e) {
    std::cerr << "start video failed: " << e.what() << std::endl;
  }
});

Issues Linking?

If you have problems with running the application due to a not-found media library, set the LD_LIBRARY_PATH to the location of the sdk-release/lib directory. If you plan to move the libraries to different locations, include these locations in the paths. The path can be set as follows:

$ export LD_LIBRARY_PATH=/path/to/sdk-release/lib/:$LD_LIBRARY_PATH