Rate this page:

Video Composer

A Video Composer is a Media Extension that composes a Programmable Video Room's participants' videos in an adaptive grid layout.

The Video Composer joins a Twilio Video Room as a participant. It formats the other participants' videos in an adaptive grid format with their identities written as an overlay on the HTML Video elements. It then sends the Room's video and audio content to a PlayerStreamer.

The Video Composer will display up to nine videos in the grid layout. If there are more than nine participants in the Room, the Video Composer will render the videos for the last nine active speakers. The Video Composer will highlight the currently active speaker's video with a green border.

If the Video Room that this Video Composer is connected to ends (if its status is set to COMPLETED or it ends from a failure), the MediaProcessor will continue running. The Video Composer will disconnect from the Video Room if it is the only participant in the room for five minutes.

You will need to explicitly end the MediaProcessor when you are finished with the livestream; see Billing and Resource Management for more information.

Get Started

To use a Video Composer in a Twilio Live application, specify the Video Composer extension name and extension context parameters when creating a MediaProcessor.

Extension Names

Below are the available Video Composer extension names:

Name Description
video-composer-v1 The latest stable Video Composer extension.

Extension Context

The snippet below describes the Video Composer extension context parameters. The MediaProcessor uses these extension context parameters to create and start the Video Composer application. For example, the room parameter tells the Video Composer which Video Room to connect to, and the outputs parameter specifies where the composed video stream should be sent.

  // Room Parameters (required)
  "room": {
      // The Programmable Video Room unique name or SID (required)
      "name": "RM123"

  // Identity that the Extension uses when joining the Room (optional, video-composer-v1 by default)
  "identity": "video-composer-v1",

  // An array of media destinations represented as PlayerStreamer SIDs (required)
  "outputs": ["VJXXX"],

  // Audio bitrate in Kbps (optional, defaults to 128)
  "audioBitrate": 128,

    // Resolution (optional, defaults to "1280x720")
  "resolution": "1280x720"
Name Description
room A required object that results in the Video Composer being injected with all the required parameters to connect to a Programmable Video Room. The room object should contain the unique name or SID for the Programmable Video Room you would like to stream. See Video Room creation for more information about how the Video Composer joins the Room.
identity The identity associated with the Video Composer. Defaults to the extension name and major version (eg. video-composer-v1)
outputs An array of media destinations represented as PlayerStreamer SIDs.
audioBitrate The audio bitrate in Kbps. Can be either 128 or 192. Defaults to 128.
resolution The dimensions of the rendered content in pixels expressed as columns (width) and rows (height). The string format is {width}x{height}. Options are: "640x480", "852x480", "1024x768", "1280x720". Defaults to "1280x720".

Extension Environment

The snippet below describes the Video Composer extension environment parameters. Extension environment parameters are injected as environment variables into the Video Composer JavaScript application, and used to configure specific behaviors in the application.

  // Prevents participant identities from being displayed in the Video Composer (optional, false by default)
  "hideParticipantIdentities": true
Name Description
hideParticipantIdentities An optional parameter that, when true, will hide all participant identities in the Video Composer. Defaults to false.

Video Room creation

If Client-side Room Creation is enabled for your account and a Video Room with the specified unique name or SID does not already exist, the Video Composer will create one with this value in the unique name field and then join that Video Room. You can configure Client-side Room Creation in the Twilio Console.

Client-side Room Creation is enabled for accounts by default.

If Client-side Room Creation is disabled and you provide a Video Room name or SID that does not exist, the Video Composer will still start but will not create or connect to a Video Room.

Note that the Video Composer only tries to connect to a Video Room once. If the Video Room does not exist and Client-side Room Creation is disabled, the Video Composer will not connect to a Video Room. It will also not connect if a Video Room with the same unique name or SID is eventually created after the Video Composer has started.

Creating a MediaProcessor with a Video Composer

The snippet below demonstrates an example curl request for creating a MediaProcessor with a Video Composer Media Extension:

curl -X POST '' \
  -d 'Extension="video-composer-v1"' \
  -d 'ExtensionContext={"room": {"name": "RM123"}, "outputs": ["VJXXX"]}'
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 Community Forums or browsing the Twilio tag on Stack Overflow.


        Thank you for your feedback!

        We are always striving to improve our documentation quality, and your feedback is valuable to us. Please select the reason(s) for your feedback or provide additional information about how we can improve:

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

        Thanks for your feedback!

        Refer us and get $10 in 3 simple steps!

        Step 1

        Get link

        Get a free personal referral link here

        Step 2

        Give $10

        Your user signs up and upgrade using link

        Step 3

        Get $10

        1,250 free SMSes
        OR 1,000 free voice mins
        OR 12,000 chats
        OR more