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.
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.
If you prefer to get started by reviewing a complete code sample of this guide, see the example here.
To see a video call kickstart app that shows the UIKit in action, check out our GitHub.
For a complete list of components and their usage, go to the documentation folder.
- A Dolby.io account
- A working webcam and microphone
- A Dolby.io client access token
- Voxeet Web SDK >=3.6.0 or later
- Node.js 16.x or later
- A supported browser, either Chrome 100+, Safari 15+, Firefox 100+, or Edge 100+
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 independent of the others. The code blocks within each section only include the code for that individual component, and exclude the components from other sections.
If you prefer to get started by reviewing a complete code sample containing all of the features in this guide, see the example here.
# Create a new React application
npx create-react-app my-app
# Change into the app directory
cd my-app
# Install the Voxeet SDK and UI kit with npm...
npm install @voxeet/voxeet-web-sdk @dolbyio/comms-uikit-react --save
# ...or yarn (skip this if you used npm)
yarn add @voxeet/voxeet-web-sdk @dolbyio/comms-uikit-react
# Start the dev server
npm startThis section will guide you on opening a connection to the Dolby.io APIs, which will enable the use of video calling features in your app.
Dolby.io integration is provided by a CommsProvider component (for communication with our APIs) and a ThemeProvider component (provides the look and feel), 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` and `ThemeProvider` from the UI kit.
import { CommsProvider, ThemeProvider } 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 `ThemeProvider` and the configured `CommsProvider`, passing in the `token` and `refreshToken` properties. We'll also add a fixed height to the app as we'll need this later in the guide.
function App() {
return (
<ThemeProvider>
<CommsProvider token={token} refreshToken={refreshToken}>
<div className="App" style={{ height: 400 }}>
...
</div>
</CommsProvider>
</ThemeProvider>
);
}
export default App;This approach is only for demo purposes. To properly initialize your app for production, see API Authentication and Client Authentication.
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, ThemeProvider, 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 (
<ThemeProvider>
<CommsProvider token={token} refreshToken={refreshToken}>
<div className="App" style={{ height: 400 }}>
<Session participantInfo={participantInfo}>...</Session>
</div>
</CommsProvider>
</ThemeProvider>
);
}If you would like to create a session using your own component, refer to the useSession hook.
Once your app has made the connection to Dolby.io, you can access its video call features.
A conference connects participants to one another, enabling them to communicate using audio and/or video.
// src/App.js
// 1. Import `Conference`, `JoinConferenceButton` and `LeaveConferenceButton` from the UI kit.
import {
CommsProvider,
ThemeProvider,
Session,
Conference,
JoinConferenceButton,
LeaveConferenceButton,
} from '@dolbyio/comms-uikit-react';
// 2. import `useState` from React.
import { useState } from 'react';
// 3. Define the `JoinConferenceButton` configuration. You can specify whether to join the conference with audio and/or video enabled, in addition to a meetingName and username (usually the name of current user) which can be made visible to all participants.
const joinOptions = {
constraints: {
audio: true,
video: true,
},
};
const meetingName = 'My Meeting';
const username = 'John Doe';
// 4. Define the tooltips that are shown when hovering over the Join or Leave buttons.
const joinTooltipText = 'Join meeting';
const leaveTooltipText = 'Leave meeting';
function App() {
// 5. Define the state for the conference ID.
const [conferenceId, setConferenceId] = useState();
/*
6. Insert the `Conference`, `JoinConferenceButton` and `LeaveConferenceButton` components, along with the `joinOptions` and `meetingName` properties, anywhere inside of `Session`. We want to show "JoinConferenceButton" when there's no conference ID, and "Conference" (which includes the `LeaveConferenceButton`) when there is.
We also pass `setConferenceId` as a callback to the `onSuccess` properties for both buttons which will set (or unset) the conference ID when the action is successful.
IMPORTANT: Rendering a <Conference /> component will establish a call using Dolby.io, If you are using your free minutes for this demo, remember to leave the conference or close the browser tab when you're done!
*/
return (
<ThemeProvider>
<CommsProvider token={token} refreshToken={refreshToken}>
<div className="App" style={{ height: 400 }}>
<Session participantInfo={participantInfo}>
{!conferenceId ? (
<JoinConferenceButton
joinOptions={joinOptions}
meetingName={meetingName}
username={username}
tooltipText={joinTooltipText}
onSuccess={(id) => setConferenceId(id)}
>
Join Video Call
</JoinConferenceButton>
) : (
<Conference id={conferenceId}>
<LeaveConferenceButton tooltipText={leaveTooltipText} onSuccess={() => setConferenceId(null)} />
</Conference>
)}
</Session>
</div>
</CommsProvider>
</ThemeProvider>
);
}If you would like to create, join or leave a conference using your own components, refer to the useConference hook.
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, ThemeProvider, 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 (
<ThemeProvider>
<CommsProvider token={token} refreshToken={refreshToken}>
<div className="App" style={{ height: 400 }}>
<Session participantInfo={participantInfo}>
<Conference id={conferenceId}>
{/*} Code from previous examples has been removed for brevity */}
<ParticipantsList
localText={localText}
muteText={muteText}
unmuteText={unmuteText}
soundOnText={soundOnText}
soundOffText={soundOffText}
/>
</Conference>
</Session>
</div>
</CommsProvider>
</ThemeProvider>
);
}If you would like to display participants using your own component, refer to the useParticipants hook.
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, ThemeProvider, 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 (
<ThemeProvider>
<CommsProvider token={token} refreshToken={refreshToken}>
<div className="App" style={{ height: 400 }}>
<Session participantInfo={participantInfo}>
<Conference id={conferenceId}>
{/*} Code from previous examples has been removed for brevity */}
<ParticipantsGrid localText={localText} />
</Conference>
</Session>
</div>
</CommsProvider>
</ThemeProvider>
);
}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,
ThemeProvider,
Session,
Conference,
LocalToggleAudioButton,
LocalToggleVideoButton,
} from '@dolbyio/comms-uikit-react';
// 2. Insert the `LocalToggleAudioButton` and `LocalToggleVideoButton` components anywhere inside of `Conference`.
function App() {
return (
<ThemeProvider>
<CommsProvider token={token} refreshToken={refreshToken}>
<div className="App" style={{ height: 400 }}>
<Session participantInfo={participantInfo}>
<Conference id={conferenceId}>
{/*} Code from previous examples has been removed for brevity */}
<LocalToggleAudioButton />
<LocalToggleVideoButton />
</Conference>
</Session>
</div>
</CommsProvider>
</ThemeProvider>
);
}If you would like to control audio or video using your own components, refer to the useAudio and useVideo hooks.
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,
ThemeProvider,
Session,
Conference,
CameraSelect,
MicrophoneSelect,
SpeakersSelect,
} from '@dolbyio/comms-uikit-react';
// 2. Define the `CameraSelect`, `MicrophoneSelect`, and `SpeakersSelect` configurations: each component takes a `label` prop (shown above the component) and a `placeholder` prop (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 (
<ThemeProvider>
<CommsProvider token={token} refreshToken={refreshToken}>
<div className="App" style={{ height: 400 }}>
<Session participantInfo={participantInfo}>
<Conference id={conferenceId}>
{/*} 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>
</ThemeProvider>
);
}If you would like to control input devices using your own components, refer to the useCamera, useMicrophone and useSpeaker hooks.
The UI components use custom hooks to connect to the Dolby.io Communications APIs.
If you would like to connect to the Dolby.io Communications APIs using your own UI components, you can use the following exported hooks to add conferencing features to your application:
| Hook | Description |
|---|---|
| useSession | Enables opening and closing sessions, as well as information about the local participant. |
| useConference | Enables creating, joining or leaving conferences. |
| useParticipants | Provides information about participants in the current conference and their status. |
| useAudio | Can be used to mute or unmute audio for local and remote participants. |
| useVideo | Can be used to enable or disable the camera for the local participant. |
| useCamera | Lists and selects available cameras, in addition to requesting camera permissions from the user. |
| useMicrophone | Lists and selects available microphones, in addition to requesting microphone permissions from the user. |
| useSpeaker | Lists and selects available output speakers. |
Themes allow you to customize all design aspects of your project in order to meet the specific needs of your business or brand and have a consistent tone of your application. Themes allow you to configure colors of components, the darkness of surfaces, level of shadow, and the opacity of ink elements.
The ThemeProvider component enables customisation. When used as is, it will provide a default look and feel for your app, but customisation is possible. For more information, see ThemeProvider.
// src/App.js
// 1. Import `ThemeProvider` from the UI kit.
import { CommsProvider, ThemeProvider } from '@dolbyio/comms-uikit-react';
// 2. Define a custom theme. Any values provided here will be merged with the default theme.
const theme = {
grey: {
100: 'cyan', // This will change basic Text elements and the borders around certain UI elements to cyan
},
};
// 3. Pass the custom theme object into the ThemeProvider's `theme` property.
function App() {
return (
<ThemeProvider theme={theme}>
<CommsProvider token={token} refreshToken={refreshToken}>
<div className="App" style={{ height: 400 }}>
...
</div>
</CommsProvider>
</ThemeProvider>
);
}The Dolby.io Communications UIKit for React and its repository are licensed under the MIT License. Before using the package @dolbyio/comms-uikit-react, please review and accept the Dolby Software License Agreement.
Third-party licenses can be found here.
© Dolby, 2022