Twilio Live Overview

Twilio Live is a programmable platform that you can use to build interactive live streaming experiences. The REST API and Player SDK work in conjunction with Twilio Video Rooms to allow you to create streamable content for an unlimited audience. You can create the speaker and audience experiences, and build interactivity into your application.

How it works

The core components of a Twilio Live video application are:

• A Twilio Video Room where the stream's speakers can join the room as Participants and interact with one another
• A livestream, which is created by a Video Composer running on a MediaProcessor. The Video Composer will capture audio and video content from the Video Room, format it, and produce the livestream
• A PlayerStreamer to send the livestream content to a web or mobile application using the Player SDK
• Player SDK to receive and display the livestream from the PlayerStreamer in a web, iOS, or Android application

Demo applications

If you'd like to start exploring Twilio Live with a pre-built livestreaming application, you can deploy one of our demo applications in just a few minutes:

• Live interactive video streaming application
• Live interactive audio streaming application

Build a video live streaming application

The following overview walks through how to build a live streaming application using Twilio Video Rooms as the source of the audio and video content, and Twilio Live for streaming that content.

1. Create a Twilio Video application

To start building a live streaming application, you will first create a Twilio Video application that allows the speakers to join a Room as Participants and share their audio and/or video data. If you have not built with Twilio Video before, check out Twilio's sample Video applications or view a tutorial for building a Video room using Python and JavaScript. Twilio's blog also features many tutorials about how to build with Video.

The application should include a backend server that can create Rooms and generate Access Tokens for Participants. It should also have a frontend that uses the Twilio Video SDK (available for JavaScript, iOS, and Android) to allow Participants to join the Room and share their audio and/or video.

2. Create a PlayerStreamer

Next, in the backend server you created for the speakers' Video Room application, you should create a new PlayerStreamer using the REST API. This PlayerStreamer will receive audio and video livestream content from the Video Room and send it to the Player SDK that you'll add to the frontend audience view for your application.

You will pass the new PlayerStreamer's SID to the Video Composer that you'll create in a later step.

3. Create a livestream

A video livestream is the output of a Video Composer running on a MediaProcessor.

A Twilio Video Composer is a JavaScript application that joins a Twilio Video Room and formats each Participant's video in a responsive grid. It then sends the livestream containing the room's formatted video and audio data to a PlayerStreamer, which makes that content available to the Player SDK that you can use in the frontend of your streaming application.

The Video Composer runs on a MediaProcessor, which is a virtual machine that contains a headless Chromium browser and a media encoder.

To start streaming content, you will need to create a MediaProcessor using the REST API and specify the version of the Video Composer you would like to use.

The example below will walk through using the specific video-composer-v1 Video Composer for streaming video and audio data from a room to a frontend audience application.

Create a MediaProcessor and specify a Video Composer version

You can create a MediaProcessor and specify the Video Composer version you would like to use with the REST API.

The Extension argument should be the name and version of the Video Composer you would like to use (ex: video-composer-v1).

The value for the ExtensionContext will be the SID or unique name of the room you are streaming and an array of PlayerStreamer SIDs that the Video Composer should send the room content to; in this case, it would be the single PlayerStreamer SID created in the step above. The ExtensionContext argument should be a valid JSON object.

You can specify additional arguments such as audio bitrate and video resolution when creating a MediaProcessor with a Video Composer; learn more here about the available options.

Once you have created the MediaProcessor, the Video Composer will start. It will join the specified room as a Participant and begin sending audio and video data through the PlayerStreamer. The PlayerStreamer then makes the content available to the Player SDK in your frontend audience application.

Stop the MediaProcessor when the stream ends

When the stream ends, you should stop the MediaProcessor with a REST API command:

4. Generate PlaybackGrants for audience members

The last piece you will need to complete on the server side of your application is a route that can generate Access Tokens with PlaybackGrants for streaming to audience members. Your web or mobile application will need these Access Tokens with PlaybackGrants to connect to the Player SDK and stream content.

You can create a PlaybackGrant using the REST API and then attach them to an Access Token.

Scale your application

If you intend to have thousands of audience members join a live stream, you will want to avoid creating a new PlaybackGrant for every audience member, as your application's requests will be throttled.

You can provide audience members with the same PlaybackGrant to join the stream as long as the grant is still valid. PlaybackGrants have a maximum TTL (time to live) of 60 seconds, so you can generate a new PlaybackGrant every minute and provide that grant to any audience member that joins the stream within that grant's TTL. Learn more in Using PlaybackGrants at Scale.

5. Create the audience application

By this point, you have:

• A Twilio Video application where speakers can join a Video Room as Participants and share their video/audio data.
• A PlayerStreamer
• A Video Composer, running on a MediaProcessor, that is connected to the PlayerStreamer and the speakers' Video Room
• A route in your server that will generate Access Tokens with PlaybackGrants for audience members

The final piece is creating a frontend application where audience members can view the stream. To do this, you can use the Player SDK for JavaScript, Android, or iOS.

Your application should retrieve an Access Token with a PlaybackGrant from your server and use that Access Token to connect to the Player SDK. Then, you can start streaming the video room. For example, with the JavaScript Player SDK, you can connect to the Player SDK with a token, start streaming data, and attach the video stream onto an HTML page.

// assumes there's a div on the page called "videoDiv"
// where an HTML Video Element can be attached
const videoDiv = document.getElementById("videoDiv");

const player = await Twilio.Player.connect(token, {
  playerWasmAssetsPath: "https://your-site.com/path-to-static-assets",
});

// listen for the "ready" event to fire for the Player.
// The first time the ready event fires means the Player is ready to start.
// The ready event can fire multiple times during a Player's lifecycle, so
// you should only listen for the first ready event to start the stream playback.
var playerStarted = false;
player.on("stateChanged", (state) => {
  if (state === "ready" && playerStarted === false) {
    // start streaming data
    player.play();
    playerStarted = true;
    }
});

// attach the video data into a div on the page
videoDiv.appendChild(player.videoElement);

Clean up resources after the livestream

Additional Features

Once you have the building blocks of your application constructed, you can proceed to style it and add more functionality for the speaker and audience experiences, such as pathways for inviting stream viewers in to the main Video Room as speakers.