Getting Started

Contents

This guide provides you with an overview of the key objects you'll use in the Programmable Video API to build your video application with the Twilio Programmable Video JavaScript SDK.

Note: If you haven’t already done so, then take a look at the Twilio Video JavaScript Quickstart Application. Once you've played with the Quickstart, come back to this guide for more detail on how to add video to your own app.

If you’ve worked with WebRTC in the past, you’ll find that Programmable Video provides a simple wrapper around WebRTC’s lower-level APIs to make it easy to build rich audio and video applications. You can still access lower-level primitives, but that’s not required to get started.

Additionally, Programmable Video provides the missing pieces required to use WebRTC to build sophisticated applications: Global STUN/TURN relays, media services for large-scale group conferences and recording, and signaling infrastructure are all included.

Video API overview

Let’s start with an overview of the Programmable Video API:

  • A Room represents a real-time audio, video, and/or screen-share session, and is the basic building block for a Programmable Video application.
  • In a Peer-to-peer Room, media flows directly between participants. Supports upto 10 participants in a mesh topology.
  • In a Group Room, media is routed through Twilio's Media Servers. Supports upto 50 participants.
  • Participants represent client applications that are connected to a Room and sharing audio and/or video media with one another.
  • Tracks represent the individual audio and video media streams that are shared within a Room.
  • LocalTracks represent the audio and video captured from the local microphone and camera.
  • RemoteVideoTracks represent the audio and video tracks from other participants connected to the Room.

The following code samples illustrate common tasks that you as a developer may wish to perform related to a Room and its Participants.

Prerequisites

To start using the JavaScript Programmable Video SDK in your apps, you need to perform a few basic tasks first.

1. Get the Programmable Video JavaScript SDK

You can install the JavaScript Video library using NPM or Bower. You can also include it in your application using our CDN.

NPM
npm install --save twilio-video
Bower
bower install --save twilio-video
CDN
<script src="//media.twiliocdn.com/sdk/js/video/v1/twilio-video.min.js"></script>
Supported Browsers

The JavaScript Video library requires recent versions of Chrome and Firefox, and Safari 11 or greater.

2. Get an API Key

API Keys represent credentials to access the Twilio API. They are used for two purposes:

For the purposes of this guide, we will create our API Key from the Twilio Console.

  • Go to the API Keys section under Tools in the Twilio Console.
  • Click on “Create a New API Key”, add a friendly name and save your Key and Secret.

3. Generate an Access Token

To execute the code samples below, you can use the Testing Tools page in the Twilio Console to generate an Access Token. An Access Token is a short-lived credential used to authenticate your client-side application to Twilio.

In a production application, your back-end server will need to generate an Access Token for every user in your application. An Access Token is a short-lived credential used to authenticate your client-side application to Twilio. Visit the User Identity and Access Token guide to learn more.

Connect to a Room

Call connect() to connect to a Room from your web application. Once connected, you can send and receive audio and video streams with other Participants who are connected to the Room.

Twilio.Video.connect('$TOKEN', {name:'my-new-room'}).then(function(room) {
  console.log('Successfully joined a Room: ', room);
  room.on('participantConnected', function(participant) {
    console.log('A remote Participant connected: ', participant);
  })
}, function(error) {
    console.error('Unable to connect to Room: ' +  error.message);
});

You must pass the Access Token when connecting to a Room. You may also optionally pass the following:

  • Audio and video options, which when enabled will create and publish audio and video tracks from your local camera and microphone to the Room immediately upon connecting.
  • Local audio or video tracks, to begin sharing pre-created local media with other Participants in the Room upon connecting.
  • A room name, which allows you to dynamically specify the name of the Room you wish to join. (Note: You can also encode the Room name in the Access Token, which will allow the user to connect to only the Room specified in the token.)
  • An ICE transport policy, which allows you to force calls through TURN relay for testing purposes.
  • A log level for debugging.

The name of the Room specifies which Room you wish to join. If a Room by that name does not already exist, it will be created upon connection. If a Room by that name is already active, you'll be connected to the Room and receive notifications from any other Participants also connected to the same Room. Room names must be unique within an account.

You can also create a Room using the Rooms REST API. Look at the REST API Rooms resource docs for more details.

Example: Create a Room called DailyStandup

 curl -XPOST 'https://video.twilio.com/v1/Rooms' \
 -u '{API Key SID}:{API Secret}' \
 -d 'UniqueName=DailyStandup'

Note: If you don’t specify a Type attribute, then Twilio will create a Group room by default.

Default Room Settings

You can also set the room type from the Room Settings page in the Twilio Video Console. Twilio will use the room type set on Room Settings page, when you create a room from the client-side or the REST API.

Note: Twilio will set the Room Type as Group by default on the Room Settings page.

Once a Room is created, Twilio will fire a room-created webhook event, if the StatusCallback URL is set. You can set the StatusCallback URL on the Room Settings page, if you want create a room from the client-side. If you create a room using the REST API, then you need to provide a StatusCallback URL while creating the room.

 curl -XPOST 'https://video.twilio.com/v1/Rooms' \
 -u '{API Key SID}:{API Secret}' \
 -d 'UniqueName=DailyStandup' \
 -d 'StatusCallback=https://hooks.yoursite.com/room-events' \
 -d 'StatusCallbackMethod=POST' \
 -d 'Type=group'

Enabling Room Recordings

Recordings can be enabled only on Group Rooms. Set Recordings to Enabled to record participants when they connect to a Group Room. Recordings can also be enabled on Group Rooms through via the Rest API at Room creation time by setting the RecordParticipantsOnConnect property to true.

curl -XPOST 'https://video.twilio.com/v1/Rooms' \
-u 'SKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_api_key_secret' \
-d 'UniqueName=DailyStandup' \
-d 'Type=group' \
-d 'RecordParticipantsOnConnect=true' \
-d 'StatusCallback=http://example.org'

Join a Room

If you'd like to join a Room you know already exists, you handle that exactly the same way as creating a room: just pass the Room name to the connect method. Once in a Room, you'll receive a participantConnectedevent for each Participant that successfully joins. Querying the participants getter will return any existing Participants who have already joined the Room.

Twilio.Video.connect('$TOKEN', {name:'existing-room'}).then(function(room) {
  console.log('Successfully joined a Room: ', room);
  room.on('participantConnected', function(participant) {
    console.log('A remote Participant connected: ', participant);
  })
}, function(error) {
    console.error('Unable to connect to Room: ' +  error.message);
});

Setup local media

You can capture local media from your device's microphone, camera or screen-share on different platforms in the following ways:

  • In a JavaScript application, call Twilio's createLocalTracks API to gain access to the user's microphone and camera. Note that some browsers, such as Google Chrome, will only let your application access local media when your site is served from localhost or over HTTPS.
const { connect, createLocalTracks } = require('twilio-video');

// Option 1
createLocalTracks({
  audio: true,
  video: { width: 640 }
}).then(localTracks => {
  return connect('$TOKEN', {
    name: 'my-room-name',
    tracks: localTracks
  });
}).then(room => {
  console.log('Connected to Room:', room.name);
});

// Option 2
connect('$TOKEN', {
  audio: true,
  name: 'my-room-name',
  video: { width: 640 }
}).then(room => {
  console.log('Connected to Room:', room.name);
});

Specify Constraints

In a JavaScript application, call Twilio's createLocalTracks API to gain access to the user's microphone and camera. Note that some browsers, such as Google Chrome, will only let your application access local media when your site is served from localhost or over HTTPS.

if (participant.getVideoTracks().size() == 0) {
  CameraCapturer cameraCapturer = new CameraCapturer(this, CameraSource.FRONT_CAMERA);
  LocalVideoTrack localVideoTrack = LocalVideoTrack.create(context, true, cameraCapturer);
}

Working with Remote Participants

Handle Connected Participants

When you join a Room, Participants may already be present. You can check for existing Participants in the connected event callback by using the participantsgetter.

// Log your Client's LocalParticipant in the Room
const localParticipant = room.localParticipant;
console.log('Connected to the Room as LocalParticipant "%s"', localParticipant.identity);

// Log any Participants already connected to the Room
room.participants.forEach(participant => {
  console.log('Participant "%s" is connected to the Room', participant.identity);
});

// Log new Participants as they connect to the Room
room.once('participantConnected', participant => {
  console.log('Participant "%s" has connected to the Room', participant.identity);
});

// Log Participants as they disconnect from the Room
room.once('participantDisconnected', participant => {
  console.log('Participant "%s" has disconnected from Room', participant.identity);
});

Handle Participant Connection Events

When Participants connect to or disconnect from a Room that you're connected to, you'll be notified via an event listener: Similar to Room Events, Twilio will fire Participant events if the StatusCallback webhook URL is set when the Room is created. These events help your application keep track of the participants who join or leave a Room.

room.on('participantConnected', function(participant) {
  console.log('Participant connected: ' + participant.identity);
});

room.on('participantDisconnected', function(participant) {
  console.log('Participant disconnected: ' + participant.identity);
});

Display a Remote Participant's Video

To see the Video Tracks being sent by remote Participants, we need to render them to the screen:

// Attach the Participant's Media to a <div> element.
room.on('participantConnected', function(participant) {
  console.log("Participant '" +  participant.identity  + "' connected");

  participant.tracks.forEach(track => {
    document.getElementById('remote-media-div').appendChild(track.attach());
  });
});

Participating in a Room

Display a Camera Preview

Sometimes you need to make sure you're looking fantastic before entering a Room. We get it. Each SDK provides a means to render a local camera preview outside the context of an active Room:

const { createLocalVideoTrack } = require('twilio-video');

createLocalVideoTrack().then(track => {
  var localMediaContainer = document.getElementById('local-media-ctr');
  localMediaContainer.appendChild(track.attach());
});

Disconnect from a Room

You can disconnect from a Room you're currently participating in. Other Participants will receive a participantDisconnected event.

room.on('disconnected', room => {
  // Detach the local media elements
  room.localParticipant.tracks.forEach(track => {
    var attachedElements = track.detach();
    attachedElements.forEach(element => element.remove());
  });
});

// To disconnect from a Room
room.disconnect();

Server-side control

The Programmable Video REST API allows you to control your video applications from your back-end server via HTTP requests. To learn more check out the Programmable Video REST API docs.

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.