SUPPORT.TWILIO.COM END OF LIFE NOTICE: This site,, is scheduled to go End of Life on February 27, 2024. All Twilio Support content has been migrated to, where you can continue to find helpful Support articles, API docs, and Twilio blog content, and escalate your issues to our Support team. We encourage you to update your bookmarks and begin using the new site today for all your Twilio Support needs.

Creating Compositions with Twilio Programmable Video

Twilio Programmable Video allows you to record a group room, resulting in separate tracks for each participant. The new Compositions API allows you to combine each of the resulting tracks into a single file. This following topics are discussed in this guide. Click a topic to skip directly to this information:

What's the difference between video recordings and Compositions?

When room recording is enabled, each participant’s tracks are recorded. This can result in separate tracks for each participant: audio and video. Video recording encryption is also available for Twilio Enterprise and Business Edition customers.

The Compositions API was created to help combine these disparate files for easier consumption. This results in a final product of all the unencrypted recordings within a video room composed into a final, single playable recording, sans data tracks. Compositions video encryption is also available for Twilio Enterprise and Business Edition customers (see the Console settings section for more details).

What file formats does Compositions support?

Compositions currently is able to output in the following file types:

  • WebM (playable in Chrome, Firefox, VLC, and other media players)
  • MP4 (playable in all major browsers, and most media players)

Additional file formats may be added in the future.

What are Composition Hooks?

Composition Hooks enable developers to automate a video room composition once all participant tracks have been published. This means users won't need to run the create composition command manually each and every time room recordings finish. In essence, it allows developers to create a workflow that results in a composed recording for every room.

For full details, see Programmable Video: Composition Hooks (Twilio Docs).

What settings are available in Console?

The Compositions Settings page in Console lets users control a number of options:

Save to an External S3 Bucket: When enabled, Twilio will stop storing your video compositions in the Twilio storage. It will be your responsibility to manage the security and lifecycle of your compositions. For more information, see Programmable Video: External S3 Compositions (Twilio Docs).

Composition Encryption: When enabled, all compositions are encrypted with a public key that you provide. These compositions can only be decrypted by you, the holder of the corresponding private key. For more information, see Programmable Video: Encrypted Compositions (Twilio Docs).

Where are Twilio Compositions videos in Console?

Composition videos can be found in the Composition Logs page in Console. Here users can view, delete, or bulk delete logs.

Compositions troubleshooting

Here you'll find troubleshooting information for common issues. If the below guidance doesn't resolve an issue you are experiencing, please submit a support request.

Output quality Issues: If your Composition displays quality issues, this typically indicates that one or more participants in the room had subpar network conditions. We recommend using the Network Quality API and Bandwidth Profile API to monitor and improve quality. We also recommend updating the Programmable Video Client-Side and Server-Side (REST API) SDKs in use on a quarterly basis, as many new features and code revolve around connectivity.

Audio/video sync issues: If your Composition suffers from any sync issues, please retry creating the composition. Whether this resolves your issues or not, please submit a support request with both the new and original video Compositions SIDs (found on the Composition Logs page in Console).

Compositions delays: A good rough estimate for compositions to process is half the time of the original recordings. Once a composition has been requested, it cannot be removed or re-enqueued. You will need to wait until the composition is completed in order to remove it. At this time, Twilio does not have an SLA or maximum time for compositions to complete. Under peak load, it is possible that compositions may be in the queue for a few hours. 

Missing tracks: If your compositions are missing a track, it's likely that the missing track was not included in the “sources” portion of your composition request.

How do I open a Compositions escalation with Twilio Support?

Please contact our Support team, and include the following information:

  • Your specific use case, such as the layout used and the sources you want to include, your expected result, and your actual result.
  • Twilio recent unique identifiers SIDs:
    • Account SID
    • Composition SID
  • The version of the Video SDKs the Participants were using.
    Note: If you are not using one of our recent SDKs we recommend upgrading and then testing again.

API documentation links

Twilio Compositions API documentation:

Specific How-To docs:

Additional option for Twilio Enterprise or Business Edition customers:

Have more questions? Submit a request
Powered by Zendesk