Getting Started

This guide explains how to create a simple web application that supports making a video call using the Dolby.io Communications APIs. It is a good starting point that you can follow along in your code editor. This starter project will provide the foundation upon which you can add additional components as you build out your own solutions for meetings, events, collaboration, or education.

The Dolby.io Communications UIKit for React is designed to help React developers reduce the complexity of building a Dolby.io video call application for web.

This guide demonstrates how to use video call UI components to quickly build the essential components of a video call application. Be sure to complete the Connect your app to Dolby.io section before moving onto the Add video call components section.

Each component demonstrated within Add video call components can be built independently of the others. The code blocks within each section only include the code for that individual component, and exclude the components from other sections.

For a complete code sample of the app created in this getting started guide, see Summary.

The package consists of four basic elements:

  • Providers: The main components for initializing integration with Dolby.io Communications APIs and state management.
  • Hooks: Functions responsible for video call logic of video call applications.
  • UI components: Components that cover the most popular patterns of video conferencing applications.
  • Video call components: UI components with built-in logic for the most widely used video call features.

📘

Video Call Kickstart App

For an example of an application created using this UIKit, see the Video Call Kickstart App.

For a complete list of components and their usage, see the documentation folder.

Prerequisites

Make sure that you have:

  • A Dolby.io account
  • A working webcam and a microphone
  • The Client Access Token copied from the Dolby.io dashboard. To create the token, log in to the Dolby.io dashboard, create an application and navigate to API keys category. Navigate to the client access token section and copy the token.
  • The supported browser, either Chrome 100+, Safari 15+, Firefox 100+, or Edge 100+.

Please review Supported Environments for more information on Dolby.io communication APIs.

Setup

# Create a new React application
npx create-react-app my-app

# Change into the app directory
cd my-app

# Install the UI kit with npm...
npm install @dolbyio/comms-uikit-react --save

# ...or yarn (skip this if you used npm)
yarn add @dolbyio/comms-uikit-react

# Start the dev server
npm start

Connect your app to Dolby.io

This section will guide you on opening a connection to the Dolby.io Communications APIs, which will enable the use of video call features in your app.

Initialize the SDK

Dolby.io integration is provided by a CommsProvider component, which should be imported and configured at the root of your web app, eg. src/App.js.

// src/App.js

import logo from './logo.svg';
import './App.css';

// 1. Import `CommsProvider` from the UI kit.
import { CommsProvider } from '@dolbyio/comms-uikit-react';

// 2. Define the `CommsProvider` configuration. We need two properties, a `token` and an async function that refreshes it.
const token = 'YOUR_CLIENT_ACCESS_TOKEN_HERE';
const refreshToken = async () => token;

// 3. Wrap the existing app code with the configured `CommsProvider`, passing in the `token` and `refreshToken` properties.
function App() {
  return (
    <CommsProvider token={token} refreshToken={refreshToken}>
      <div className="App">...</div>
    </CommsProvider>
  );
}

export default App;

📘

This approach is only for demo purposes. To properly initialize your app for production, see API Authentication and Client Authentication.

Open a session

A session is a connection between the client application and the Dolby.io Communications APIs.

// src/App.js

// 1. Import `Session` from the UI kit.
import { CommsProvider, Session } from '@dolbyio/comms-uikit-react';

// 2. Define the `Session` configuration. You should provide a name using a `participantInfo` object, eg. the name of the participant who established the session.
const participantInfo = { name: 'John Doe' };

// 3. Insert the `Session` component, along with the `participantInfo` property, anywhere inside of `CommsProvider`.
function App() {
  return (
    <CommsProvider token={token} refreshToken={refreshToken}>
      <div className="App">
        <Session participantInfo={participantInfo}>...</Session>
      </div>
    </CommsProvider>
  );
}

If you would like to create a session using your own component, refer to the useSession hook.

Add video call components

Once your app has made the connection to Dolby.io, you can access its video call components.

Create a conference

A conference connects participants to one another, enabling them to communicate using audio and/or video.

// src/App.js

// 1. Import `Conference` from the UI kit.
import { CommsProvider, Session, Conference } from '@dolbyio/comms-uikit-react';

// 2. Define the `Conference` configuration. You can specify whether to join the conference with audio and/or video enabled, in addition to an alias which can be made visible to all participants.
const audio = true;
const video = true;
const alias = 'My Meeting';

/*
  3. Insert the `Conference` component, along with the `audio`, `video` and `alias` properties, anywhere inside of `Session`.

  IMPORTANT: Rendering a <Conference /> component will establish a call using Dolby.io. If you're using your free minutes for this demo, remember to leave the conference or close the browser tab when you're done.
*/

function App() {
  return (
    <CommsProvider token={token} refreshToken={refreshToken}>
      <div className="App">
        <Session participantInfo={participantInfo}>
          <Conference audio={audio} video={video} alias={alias}>
            ...
          </Conference>
        </Session>
      </div>
    </CommsProvider>
  );
}

If you would like to create a conference using your own component, refer to the useConference hook.

Display participants

The ParticipantsList component can display a list of participants in the current conference and their status, eg. whether the participant is currently speaking.

// src/App.js

// 1. Import `ParticipantsList` from the UI kit.
import { CommsProvider, Session, Conference, ParticipantsList } from '@dolbyio/comms-uikit-react';

// 2. Define the `ParticipantsList` configuration. You can customize the text shown for each participant and their status.
const localText = 'you'; // The local participant's name.
const muteText = 'mute'; // Displayed in a tooltip when a participant is not muted.
const unmuteText = 'unmute'; // Displayed in a tooltip when a participant is muted.
const soundOnText = 'sound on'; // Displayed in a tooltip when a participant is speaking.
const soundOffText = 'sound off'; // Displayed in a tooltip when a participant is not speaking.

// 3. Insert the `ParticipantsList` component, along with the text properties, anywhere inside of `Conference`.
function App() {
  return (
    <CommsProvider token={token} refreshToken={refreshToken}>
      <div className="App">
        <Session participantInfo={participantInfo}>
          <Conference audio={audio} video={video} alias={alias}>
            {/*} Code from previous examples has been removed for brevity */}
            <ParticipantsList
              localText={localText}
              muteText={muteText}
              unmuteText={unmuteText}
              soundOnText={soundOnText}
              soundOffText={soundOffText}
            />
          </Conference>
        </Session>
      </div>
    </CommsProvider>
  );
}

If you would like to display participants using your own component, refer to the useParticipants hook.

Display video

The ParticipantsGrid component displays the video streams of conference participants in a grid tile layout.

// src/App.js

// 1. Import `ParticipantsGrid` from the UI kit.
import { CommsProvider, Session, Conference, ParticipantsGrid } from '@dolbyio/comms-uikit-react';

// 2. Define the `ParticipantsGrid` configuration. You can customize the text shown for the current participant and their status.
const localText = 'you'; // The local participant's name.

// 3. Insert the `ParticipantsGrid` component, along with the `localText` property, anywhere inside of `Conference`.
function App() {
  return (
    <CommsProvider token={token} refreshToken={refreshToken}>
      <div className="App">
        <Session participantInfo={participantInfo}>
          <Conference audio={audio} video={video} alias={alias}>
            {/*} Code from previous examples has been removed for brevity */}
            <ParticipantsGrid localText={localText} />
          </Conference>
        </Session>
      </div>
    </CommsProvider>
  );
}

Show user controls

The LocalToggleAudioButton and LocalToggleVideoButton components enable the local participant to toggle their microphone and camera on or off.

// src/App.js

// 1. Import `LocalToggleAudioButton` and `LocalToggleVideoButton` from the UI kit.
import {
  CommsProvider,
  Session,
  Conference,
  LocalToggleAudioButton,
  LocalToggleVideoButton,
} from '@dolbyio/comms-uikit-react';

// 2. Insert the `LocalToggleAudioButton` and `LocalToggleVideoButton` components anywhere inside of `Conference`.
function App() {
  return (
    <CommsProvider token={token} refreshToken={refreshToken}>
      <div className="App">
        <Session participantInfo={participantInfo}>
          <Conference audio={audio} video={video} alias={alias}>
            {/*} Code from previous examples has been removed for brevity */}
            <LocalToggleAudioButton />
            <LocalToggleVideoButton />
          </Conference>
        </Session>
      </div>
    </CommsProvider>
  );
}

If you would like to control audio or video using your own components, refer to the useAudio and useVideo hooks.

Change input or output devices

The local participant can change their preferred camera, microphone or output speaker using the CameraSelect, MicrophoneSelect and SpeakersSelect components.

// src/App.js

// 1. Import `CameraSelect`, `MicrophoneSelect` and `SpeakersSelect` from the UI kit.
import {
  CommsProvider,
  Session,
  Conference,
  CameraSelect,
  MicrophoneSelect,
  SpeakersSelect,
} from '@dolbyio/comms-uikit-react';

// 2. Define the `CameraSelect`, `MicrophoneSelect`, and `SpeakersSelect` configurations. Each component takes a `label` property (shown above the component) and a `placeholder` property (shown when no option is selected).
const cameraLabel = 'Camera';
const cameraPlaceholder = 'Choose a camera';

const microphoneLabel = 'Microphone';
const microphonePlaceholder = 'Choose a microphone';

const speakersLabel = 'Speaker';
const speakersPlaceholder = 'Choose a speaker';

// 3. Insert the `CameraSelect`, `MicrophoneSelect` and `SpeakersSelect` components, along with the `label` and `placeholder` properties, anywhere inside of `Conference`.
function App() {
  return (
    <CommsProvider token={token} refreshToken={refreshToken}>
      <div className="App">
        <Session participantInfo={participantInfo}>
          <Conference audio={audio} video={video} alias={alias}>
            {/*} Code from previous examples has been removed for brevity */}
            <CameraSelect label={cameraLabel} placeholder={cameraPlaceholder} />
            <MicrophoneSelect label={microphoneLabel} placeholder={microphonePlaceholder} />
            <SpeakersSelect label={speakersLabel} placeholder={speakersPlaceholder} />
          </Conference>
        </Session>
      </div>
    </CommsProvider>
  );
}

If you would like to control input devices using your own components, refer to the useCamera, useMicrophone and useSpeaker hooks.

Leave a conference

The LeaveConferenceButton component, when pressed, will enable the local participant to leave the conference.

// src/App.js

// 1. Import `LeaveConferenceButton` from the UI kit.
import { CommsProvider, Session, Conference, LeaveConferenceButton } from '@dolbyio/comms-uikit-react';

// 2. Define the `LeaveConferenceButton` configuration, You can customize the text shown in a tooltip when hovering over the button.
const tooltipText = 'Leave';

// 3. Insert the `LeaveConferenceButton` component, along with the `tooltipText` property, anywhere inside of `Conference`.
function App() {
  return (
    <CommsProvider token={token} refreshToken={refreshToken}>
      <div className="App">
        <Session participantInfo={participantInfo}>
          <Conference audio={audio} video={video} alias={alias}>
            {/*} Code from previous examples has been removed for brevity */}
            <LeaveConferenceButton tooltipText={tooltipText} />
          </Conference>
        </Session>
      </div>
    </CommsProvider>
  );
}

If you would like to leave a conference using your own component, refer to the useConference hook.

Summary

The following code snippet is a complete sample of the code created in this guide:

import {
  CommsProvider,
  Session,
  Conference,
  ParticipantsList,
  ParticipantsGrid,
  LocalToggleAudioButton,
  LocalToggleVideoButton,
  LeaveConferenceButton,
  CameraSelect,
  MicrophoneSelect,
  SpeakersSelect,
} from '@dolbyio/comms-uikit-react';
import './App.css';

// Define the `CommsProvider` configuration. We need two properties, a `token` and an async function that refreshes it.
const token = 'YOUR_CLIENT_ACCESS_TOKEN_HERE';
const refreshToken = async () => token;

// Define the `Session` configuration. You should provide a name using a `participantInfo` object, eg. the name of the participant who established the session.
const participantInfo = { name: 'John Doe' };

// Define the `Conference` configuration. You can specify whether to join the conference with audio and/or video enabled, in addition to an alias which can be made visible to all participants.
const audio = true;
const video = true;
const alias = 'My Meeting';

// Define the `ParticipantsList` configuration. You can customize the text shown for each participant and their status.
const localText = 'you'; // The local participant's name.
const muteText = 'mute'; // Displayed in a tooltip when a participant is not muted.
const unmuteText = 'unmute'; // Displayed in a tooltip when a participant is muted.
const soundOnText = 'sound on'; // Displayed in a tooltip when a participant is speaking.
const soundOffText = 'sound off'; // Displayed in a tooltip when a participant is not speaking.

// Define the `ParticipantsGrid` configuration. You can customize the text shown for the current participant and their status.

// const localText = 'you';

/*
  We are re-using the previously declared `localText` in this example for `ParticipantsGrid` but you can use any value you prefer
*/

// Define the `CameraSelect`, `MicrophoneSelect`, and `SpeakersSelect` configurations. Each component takes a `label` property (shown above the component) and a `placeholder` property (shown when no option is selected).
const cameraLabel = 'Camera';
const cameraPlaceholder = 'Choose a camera';

const microphoneLabel = 'Microphone';
const microphonePlaceholder = 'Choose a microphone';

const speakersLabel = 'Speaker';
const speakersPlaceholder = 'Choose a speaker';

// Define the `LeaveConferenceButton` configuration. You can customize the text shown in a tooltip when hovering over the button.
const tooltipText = 'Leave';

function App() {
  return (
    <CommsProvider token={token} refreshToken={refreshToken}>
      <div className="App">
        <Session participantInfo={participantInfo}>
          {/* IMPORTANT: Rendering a <Conference /> component will establish a call using Dolby.io. If you're using your free minutes for this demo, remember to leave the conference or close the browser tab when you're done. */}
          <Conference audio={audio} video={video} alias={alias}>
            <ParticipantsList
              localText={localText}
              muteText={muteText}
              unmuteText={unmuteText}
              soundOnText={soundOnText}
              soundOffText={soundOffText}
            />
            <ParticipantsGrid localText={localText} />
            <LocalToggleAudioButton />
            <LocalToggleVideoButton />
            <CameraSelect label={cameraLabel} placeholder={cameraPlaceholder} />
            <MicrophoneSelect label={microphoneLabel} placeholder={microphonePlaceholder} />
            <SpeakersSelect label={speakersLabel} placeholder={speakersPlaceholder} />
            <LeaveConferenceButton tooltipText={tooltipText} />
          </Conference>
        </Session>
      </div>
    </CommsProvider>
  );
}

export default App;

Did this page help you?