Menu

Expand
Rate this page:

Twilio Live Overview

We are no longer allowing new customers to onboard to Twilio Live. Effective November 30, 2023, Twilio Live will End of Life. We have created this Migration Guide to help you identify an alternative solution for your use case.

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

Twilio Live Overview w/ Video Composer

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:

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.

Loading Code Sample...
        
        

        Create a PlayerStreamer

        Don't forget to end the PlayerStreamer when you're finished with the livestream to avoid unnecessary usage charges. See Billing and Resource Management for more information.

        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.

        By default, a MediaProcessor's maximum duration is five minutes; after the MediaProcessor runs for its maximum duration, it will automatically terminate and end the livestream. You can increase the MediaProcessor's maximum duration when creating the MediaProcessor.

        Loading Code Sample...
              
              

              Create a MediaProcessor with a Video Composer

              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:

              Loading Code Sample...
                    
                    

                    Stop a MediaProcessor

                    It is important to stop both the PlayerStreamer and MediaProcessor resources you created when the livestream has ended to avoid unnecesary usage charges. See Billing and Resource Management for more information.

                    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.

                    Loading Code Sample...
                          
                          

                          Create an Access Token with a PlaybackGrant

                          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);

                          The code sample above references a playerWasmAssetsPath parameter in the Player SDK constructor. In order for the JavaScript version of the Player SDK to run, your application must host the following artifacts:

                          twilio-player-wasmworker-x-y-z.min.wasm and twilio-player-wasmworker-x-y-z.min.js

                          The x.y.z is the version of the SDK assets. You can find these files in the node_modules/@twilio/player-sdk/dist/build directory of the Player SDK. The URL you provide as the playerWasmAssetsPath should be the URL path to the assets.

                          If you are developing a streaming audience application with the JavaScript Player SDK, note that many browsers have autoplay policies that prohibit automatically playing sound when a page loads until a user interacts with the page, such as through a button click. You can detect when the volume is muted with the Player SDK and then prompt the user to interact with the page in order to start playing audio.

                          Clean up resources after the livestream

                          To avoid unnecessary usage charges to your Twilio account, make sure that you always end the MediaProcessor and end the PlayerStreamer resources when the livestream is finished. These resources will continue to run until you explicitly end them via the REST API, or until the MediaProcessor's maximum duration is reached. See Billing and Resource Management for more information.

                          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.

                          Rate this page:

                          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 by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

                          Thank you for your feedback!

                          Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

                          Sending your feedback...
                          🎉 Thank you for your feedback!
                          Something went wrong. Please try again.

                          Thanks for your feedback!

                          thanks-feedback-gif