This page is for reference only. We are no longer onboarding new customers to Programmable Video. Existing customers can continue to use the product until December 5, 2024.
We recommend migrating your application to the API provided by our preferred video partner, Zoom. We've prepared this migration guide to assist you in minimizing any service disruption.
Overview
Twilio Video's Group Rooms and Recording APIs allow you to record the audio and video shared in a Programmable Video Room. To turn on Recording in a Group Room, set the RecordParticipantsOnConnect property to true when creating the Room. Check the Rooms REST API documentation for additional information.
All Recording resources are located beneath the following Base URL.
_10
https://video.twilio.com
(warning)
Warning
Legal implications of call recording
If you choose to record voice or video calls, you need to comply with certain laws and regulations, including those regarding obtaining consent to record (such as California's Invasion of Privacy Act and similar laws in other jurisdictions). Additional information on the legal implications of call recording can be found in the "Legal Considerations with Recording Voice and Video Communications" Help Center article.
Notice: Twilio recommends that you consult with your legal counsel to make sure that you are complying with all applicable laws in connection with communications you record or store using Twilio.
The status of the recording. Can be: processing, completed, or deleted. processing indicates the recording is still being captured; completed indicates the recording has been captured and is now available for download. deleted means the recording media has been deleted from the system, but its metadata is still available.
The file format for the recording. Can be: mka or mkv. Video Room recordings are captured in Matroska container format, mka is for audio files and mkv for video files.
The time in milliseconds elapsed between an arbitrary point in time, common to all group rooms, and the moment when the source room of this track started. This information provides a synchronization mechanism for recordings belonging to the same room.
Retrieves the media file associated to a given Recording Instance resource
identified by a RecordingSid.
When you make a request to this URL, Twilio will generate a temporary URL for accessing this binary data, and issue an HTTP 302 redirect response to your request. The Recording will be returned in the format as described in the metadata, with the Content-Type header set according to the codec used to record the media.
Codec
Content-Type value
PCMU
audio/x-matroska
H264
video/x-matroska
The URL returned will be available by default for 600 seconds, but this can be configured to a value between 1 and 3600 seconds via the Ttl request param. If the recording is not yet available, a 404 is returned. If the recording is not available (for example, if its status is processing or deleted, or if the track was muted for the duration of the recording), an HTTP 404 response is returned.
The HTTP GET request accepts the following parameters
Name
Description
ContentDisposition
Optional. Sets the Content-Disposition header of the redirect_to URL. Possible values are attachment or inline. Default value attachment%3B%20filename%3D%22RTxxx.mk{a|v} (not PII)
Ttl
Optional. Duration in seconds for which the redirect_to URL can be used to retrieve the media file. The default Ttl is 600 seconds. The minimum supported Ttl value is 1 second and the maximum supported value is 3600 seconds. (not PII)
The Content-Disposition header can be set in this request. By default, the value of this header is attachment%3B%20filename%3D%22RTxxx.mk{a|v}.
NOTE: You can play these recordings in media players that support the Matroska file format, like the VLC player. You can also use other programs like Chrome, ffplay or ffplayer to play these recordings. However, these files are optimized for compactness and they are not player-friendly. Hence, you may experience different types of problems when playing these files. For generating player-friendly media files, compose your Recordings using Twilio's Recordings Composition API.
Example: Retrieve a Recording's Media
Retrieve the actual recording Media
Node.js
Python
C#
Java
PHP
Ruby
curl
_19
// NOTE: This example uses the next generation Twilio helper library - for more
_19
// information on how to download and install this version, visit
_19
// https://www.twilio.com/docs/libraries/node
_19
const Twilio = require("twilio");
_19
_19
// To set up environmental variables, see http://twil.io/secure
The metadata for the Recording is preserved for a period of 30 days, and its Status is set to deleted. After this period, the metadata will not be available. By default, Recordings with deleted status are not returned when retrieving the Recordings list. To retrieve deleted Recordings, use the Status=deleted filter.
Note that the 30-day period starts after the Status is set to deleted. After this period expires, the metadata will not be available.
Example: Delete a Recording
Delete a Recording
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl
_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
The size of a video Recording (.mkv) will vary based on resolution, bit rate and duration. The following table shows files size for a single participant with video captured at common resolutions and bitrates:
Capture Size
1 Hr
8 Hrs
24 Hrs
720 @ 1,500 kbps
0.7 GB
5.4 GB
16.2 GB
480 @ 700 kbps
0.3 GB
2.5 GB
7.6 GB
180 @ 200 kbps
0.1 GB
0.7 GB
2.2 GB
(warning)
Warning
The above table is for heuristic estimation and reference only. There are a lot of other factors influence the actual video file size such as compression ratio, variable bitrate, color depth.
Audio track Recording
The size of an audio Recording (.mka) will vary based on bit rate and duration. The following table shows files size for a single participant with audio captured at common bit rates:
Capture Size
1 Hr
8 Hrs
24 Hrs
16 kbps
7.2 MB
57.6 MB
172.8 MB
32 kbps
14.4 MB
115.2 MB
345.6 MB
40 kbps
18 MB
144 MB
432 MB
(warning)
Warning
Note that the file size reported by our REST API may vary slightly from that shown due to file allocation methods and/or possible differences in the amount of header information.
Known limitations
Recording files are generated with a format optimized for reliability and compactness. This format is not player friendly. Hence, many media players may not render Recordings media files appropriately. For generating player-friendly media files, compose your Recordings using
Twilio's Recordings Composition API
.
Participants of Group Rooms on the browser
Firefox Mobile
could find Recording gaps due to a Firefox bug when sending temporization. Twilio recommends Video participants to use other mobile browsers.