Twilio Video Quickstart for JavaScript

Before you can run the quickstart app, you need to install Node.js and gather your Twilio account credentials.

Install Node.js on your local machine. The quickstart app uses Node.js to run a local web server.

API keys represent credentials that allow your application to access the Twilio API.

1. Create an API key in the API keys & tokens section of the Twilio Console.
2. Save the API key SID and secret in a secure place. The secret is only shown once when you create the key.

Learn more about API Keys.

Get your Account SID from the Twilio Console dashboard home page.

Follow these steps to download the quickstart app and set up your Twilio credentials:

1. Clone the Twilio Video JavaScript quickstart app repository to your local machine. For example:

   Copy code block

     git clone https://github.com/twilio/video-quickstart-js.git

   (information)

   Customizing the quickstart app?

   To use the quickstart app as a starting point for your own application, you can fork the twilio/video-quickstart-js repository to your GitHub account, then clone your fork.

2. Change to the video-quickstart-js directory:

   Copy code block

   cd video-quickstart-js

3. Create a .env file from the template:

   Copy code block

   cp .env.template .env

4. Edit the new .env file. Replace the placeholders with your credentials from the Prerequisites section:

   Copy code block

   1
   TWILIO_ACCOUNT_SID=ACxxxxxxxxxx
   2
   TWILIO_API_KEY=SKxxxxxxxxxx
   3
   TWILIO_API_SECRET=xxxxxxxxxx

5. Install the dependencies:

   Copy code block

   npm install

After configuring the app, you can run it locally and test joining a Video Room:

1. Run the application:

   Copy code block

   npm start

2. Open your web browser to http://localhost:3000.

3. When prompted, test and choose your microphone and camera.

   (information)

   Info

   Desktop browsers save your choices. On mobile browsers, you're prompted to test and choose your microphone and camera every time you load the application to make sure they're not reserved by another application.

4. Enter a Room name and your user name, then click Join Room. You should see your own camera feed and name displayed.

To test the multi-Participant functionality, you can open another browser tab and enter the same Room name to join the Room and see and hear yourself on both tabs.

The quickstart app's quickstart/src/joinroom.js file demonstrates how to use the Video SDK APIs to build a multi-participant video session. You can incorporate this code into your application and build your user interface around it.

The Twilio Video API includes the following resources:

• Room: The real-time audio, data, video and screen-share session. It's the basic building block for a Programmable Video application.
• Participants: The client applications that are connected to a Room and sharing audio, data, and video media with one another.
• Tracks: The audio, data, and video media streams that are shared within a Room.
• LocalTracks: The audio, data, and video captured from the local client's media sources (for example, microphone and camera).
• RemoteTracks: The audio, data, and video tracks from other participants connected to the Room.

The following sections describe the key parts of the quickstart app code that use the Twilio Video JavaScript SDK to connect to a Room, set up local media, work with remote Participants, and participate in a Room.

The joinroom.js file makes a single call to the Video SDK's connect() API to create a new Room or to join an existing Room.

1
async function joinRoom(token, connectOptions) {
2
  …
3
  // Join to the Room with the given AccessToken and ConnectOptions.
4
  const room = await connect(token, connectOptions);
5
  …
6
}

The function accepts two parameters:

• token is required and is the Access Token obtained from the back-end server (not described in this quickstart).
• connectOptions are optional and can include name, audio, video, and other properties.

The quickstart app registers event listeners for all Participant lifecycle events immediately after it connects.

1
// Handle the LocalParticipant's media.
2
participantConnected(room.localParticipant, room);
3

4
// Subscribe to RemoteParticipants already in the Room.
5
room.participants.forEach(participant => {
6
  participantConnected(participant, room);
7
});
8

9
// Subscribe to RemoteParticipants joining later.
10
room.on('participantConnected', participant => {
11
  participantConnected(participant, room);
12
});
13

14
// Handle a disconnected RemoteParticipant.
15
room.on('participantDisconnected', participant => {
16
  participantDisconnected(participant, room);
17
});

The participantConnected and participantDisconnected functions are helper methods that attach and detach media and update the user interface.

Immediately after connecting, the app stores the LocalVideoTrack that connect() created for you:

1
let localVideoTrack =
2
  Array.from(room.localParticipant.videoTracks.values())[0].track;

When a Participant backgrounds the app (on mobile browsers), the app stops and unpublishes the track:

1
localVideoTrack.stop();
2
room.localParticipant.unpublishTrack(localVideoTrack);

The app creates a new track (respecting any constraints present in connectOptions.video) when the app returns to the foreground.

1
localVideoTrack = await createLocalVideoTrack(connectOptions.video);
2
await room.localParticipant.publishTrack(localVideoTrack);

The app renders the local Participant's camera the same way as any remote track. Upon connection, participantConnected immediately calls attachTrack so the local preview appears instantly:

participantConnected(room.localParticipant, room);

When a remote Participant joins the Room, the quickstart app sets up event listeners to attach newly published audio and video tracks in real time. The app updates the UI to render each Participant's media and clean up if they disconnect:

1
function participantConnected(participant, room) {
2
  // Set up the Participant's media container.
3
  setupParticipantContainer(participant, room);
4

5
  // Tracks already published.
6
  participant.tracks.forEach(publication => {
7
    trackPublished(publication, participant);
8
  });
9

10
  // Tracks that will be published later.
11
  participant.on('trackPublished', publication => {
12
    trackPublished(publication, participant);
13
  });
14
}
15

16
function trackPublished(publication, participant) {
17
  if (publication.track) {
18
    attachTrack(publication.track, participant);
19
  }
20
  publication.on('subscribed',  track => attachTrack(track, participant));
21
  publication.on('unsubscribed', track => detachTrack(track, participant));
22
}

The attachTrack function renders the audio or video into the app's page:

1
function attachTrack(track, participant) {
2
  const $media = $(`div#${participant.sid} > ${track.kind}`, $participants);
3
  $media.css('opacity', '');
4
  track.attach($media.get(0));
5

6
  if (track.kind === 'video' && participant === activeParticipant) {
7
    track.attach($activeVideo.get(0));
8
    $activeVideo.css('opacity', '');
9
  }
10
}

The quickstart app automatically mutes video when the app is backgrounded and unmutes when the app returns to the foreground:

1
// Mute (backgrounded)
2
localVideoTrack.stop();
3
room.localParticipant.unpublishTrack(localVideoTrack);
4

5
// Unmute (foregrounded)
6
localVideoTrack = await createLocalVideoTrack(connectOptions.video);
7
await room.localParticipant.publishTrack(localVideoTrack);

To disconnect from a Room, the application can call room.disconnect() in response to user actions or events.

When the user clicks the Leave Room button, the app disconnects from the Room:

1
$leave.click(function onLeave() {
2
  $leave.off('click', onLeave);
3
  $togglePip.off('click', togglePipButtonHandler);
4
  room.disconnect();
5
});

The app automatically disconnects when the Participant leaves or reloads the app page, or closes the tab:

1
window.onbeforeunload = () => { room.disconnect(); };
2
window.onpagehide     = () => { room.disconnect(); };   // iOS Safari

After the SDK emits the disconnected event, the app performs the final resource cleanup.

1
room.once('disconnected', (room, error) => {
2
  …
3
  localVideoTrack.stop();
4
  participantDisconnected(room.localParticipant, room);
5
  room.participants.forEach(participant => {
6
    participantDisconnected(participant, room);
7
  });
8
  $activeVideo.get(0).srcObject = null;
9
  window.room = null;
10
  …
11
});

Now that you've run the quickstart app and understand the basics of connecting to a Room, explore these resources to build and enhance your video application:

• Install the Twilio Video JavaScript SDK: Add the SDK to your own project
• Twilio Video React app: Explore a full-featured video application built with React
• Video app components: Understand the architecture of a complete video application