Twilio Video's Rooms and Recording APIs allow you to record the audio and video shared in a Programmable Video Room. To turn on Recording in a 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.
1https://video.twilio.com2
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.
Recordings captured by Programmable Video products are single-track, single-media and stored in a single file format.
Recordings are represented through a REST API with the following URI scheme:
/v1/Recordings/{RecordingSid}
A Recording has the following properties:
The SID of the Account that created the Recording resource.
^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34The 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.
processingcompleteddeletedfailedThe date and time in GMT when the resource was created specified in ISO 8601 format.
The unique string that we created to identify the Recording resource.
^RT[0-9a-fA-F]{32}$Min length: 34Max length: 34The SID of the recording source. For a Room Recording, this value is a track_sid.
^[a-zA-Z]{2}[0-9a-fA-F]{32}$Min length: 34Max length: 34The recording's media type. Can be: audio or video.
audiovideodataThe duration of the recording in seconds rounded to the nearest second. Sub-second tracks have a Duration property of 1 second
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.
mkamkvThe codec used to encode the track. Can be: VP8, H264, OPUS, and PCMU.
VP8H264OPUSPCMUA list of SIDs related to the recording. Includes the room_sid and participant_sid.
The name that was given to the source track of the recording. If no name is given, the source_sid is used.
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.
The URL of the media file associated with the recording when stored externally. See External S3 Recordings for more details.
The URL called using the status_callback_method to send status information on every recording event.
The HTTP method used to call status_callback. Can be: POST or GET, defaults to POST.
GETPOSTThe URLs of related resources.
Note: The duration of media tracks is rounded to the nearest second. Thus, sub-second duration tracks have a Duration property of 1 second.
Returns a single Recording Instance resource identified by a RecordingSid.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function fetchRecording() {11const recording = await client.video.v112.recordings("RTXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")13.fetch();1415console.log(recording.accountSid);16}1718fetchRecording();
1{2"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",3"status": "processing",4"date_created": "2015-07-30T20:00:00Z",5"date_updated": "2015-07-30T21:00:00Z",6"date_deleted": "2015-07-30T22:00:00Z",7"sid": "RTXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",8"source_sid": "MTaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",9"size": 0,10"url": "https://video.twilio.com/v1/Recordings/RTaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",11"type": "audio",12"duration": 0,13"container_format": "mka",14"codec": "OPUS",15"track_name": "A name",16"offset": 10,17"status_callback": "https://mycallbackurl.com",18"status_callback_method": "POST",19"grouping_sids": {20"room_sid": "RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"21},22"media_external_location": "https://my-super-duper-bucket.s3.amazonaws.com/my/path/",23"encryption_key": "public_key",24"links": {25"media": "https://video.twilio.com/v1/Recordings/RTaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Media"26}27}
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.
1// NOTE: This example uses the next generation Twilio helper library - for more2// information on how to download and install this version, visit3// https://www.twilio.com/docs/libraries/node4const Twilio = require("twilio");56// To set up environmental variables, see http://twil.io/secure7const apiKeySid = process.env.TWILIO_API_KEY;8const apiKeySecret = process.env.TWILIO_API_KEY_SECRET;9const accountSid = process.env.TWILIO_ACCOUNT_SID;10const client = new Twilio(apiKeySid, apiKeySecret, { accountSid: accountSid });1112const recordingSid = "RTXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";13const uri = `https://video.twilio.com/v1/Recordings/${recordingSid}/Media`;14client.request({ method: "GET", uri: uri }).then(response => {15const mediaLocation = response.data.redirect_to;16request.get(mediaLocation, (err, res, media) => {17console.log(media);18});19});
1{2"redirect_to": "https://com-twilio-us1-video-recording.s3.amazonaws.com/RTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"3}
Not supported.
Deletes the recording media file.
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.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function deleteRecording() {11await client.video.v112.recordings("RTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")13.remove();14}1516deleteRecording();
To delete a large set of Video Recordings, you can use the bulk deletion capabilities available in the Twilio Console.
Recordings list is available at the following URI:
1/v1/Recordings2
Returns a list of all Track Recordings with paging data.
The following GET query string parameters allow you to limit the list returned. Note, parameters are case-sensitive.
Read only the recordings that have this status. Can be: processing, completed, or deleted.
processingcompleteddeletedfailedRead only the recordings that have this source_sid.
^[a-zA-Z]{2}[0-9a-fA-F]{32}$Min length: 34Max length: 34Read only recordings with this grouping_sid, which may include a participant_sid and/or a room_sid.
Read only recordings that started on or after this ISO 8601 date-time with time zone.
Read only recordings that started before this ISO 8601 date-time with time zone, given as YYYY-MM-DDThh:mm:ss+|-hh:mm or YYYY-MM-DDThh:mm:ssZ.
Read only recordings that have this media type. Can be either audio or video.
audiovideodataHow many resources to return in each list page. The default is 50, and the maximum is 1000.
1Maximum: 1000The page token. This is provided by the API.
This endpoint does not retrieve deleted recordings by default. To retrieve deleted recordings, use the status filter in your request.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function listRecording() {11const recordings = await client.video.v1.recordings.list({12groupingSid: ["RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"],13limit: 20,14});1516recordings.forEach((r) => console.log(r.accountSid));17}1819listRecording();
1{2"recordings": [],3"meta": {4"page": 0,5"page_size": 50,6"first_page_url": "https://video.twilio.com/v1/Recordings?Status=completed&SourceSid=source_sid&MediaType=audio&GroupingSid=RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&PageSize=50&Page=0",7"previous_page_url": null,8"url": "https://video.twilio.com/v1/Recordings?Status=completed&SourceSid=source_sid&MediaType=audio&GroupingSid=RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&PageSize=50&Page=0",9"next_page_url": null,10"key": "recordings"11}12}
This endpoint does not retrieve deleted recordings by default. To retrieve deleted recordings, use the status filter in your request.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function listRecording() {11const recordings = await client.video.v1.recordings.list({12groupingSid: ["PARTICIPANT_SID"],13limit: 20,14});1516recordings.forEach((r) => console.log(r.accountSid));17}1819listRecording();
1{2"recordings": [],3"meta": {4"page": 0,5"page_size": 50,6"first_page_url": "https://video.twilio.com/v1/Recordings?Status=completed&SourceSid=source_sid&MediaType=audio&GroupingSid=RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&PageSize=50&Page=0",7"previous_page_url": null,8"url": "https://video.twilio.com/v1/Recordings?Status=completed&SourceSid=source_sid&MediaType=audio&GroupingSid=RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&PageSize=50&Page=0",9"next_page_url": null,10"key": "recordings"11}12}
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function listRecording() {11const recordings = await client.video.v1.recordings.list({12status: "deleted",13limit: 20,14});1516recordings.forEach((r) => console.log(r.accountSid));17}1819listRecording();
1{2"recordings": [],3"meta": {4"page": 0,5"page_size": 50,6"first_page_url": "https://video.twilio.com/v1/Recordings?Status=completed&SourceSid=source_sid&MediaType=audio&GroupingSid=RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&PageSize=50&Page=0",7"previous_page_url": null,8"url": "https://video.twilio.com/v1/Recordings?Status=completed&SourceSid=source_sid&MediaType=audio&GroupingSid=RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&PageSize=50&Page=0",9"next_page_url": null,10"key": "recordings"11}12}
Not supported.
Not supported.
You can also retrieve the list of recordings for a specific room using the Rooms API endpoint.
This endpoint does not retrieve deleted recordings by default. To retrieve deleted recordings, use the status filter in your request.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function listRoomRecording() {11const recordings = await client.video.v112.rooms("RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")13.recordings.list({ limit: 20 });1415recordings.forEach((r) => console.log(r.accountSid));16}1718listRoomRecording();
1{2"recordings": [],3"meta": {4"page": 0,5"page_size": 50,6"first_page_url": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Recordings?PageSize=50&Page=0",7"previous_page_url": null,8"url": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Recordings?PageSize=50&Page=0",9"next_page_url": null,10"key": "recordings"11}12}
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function fetchRoomRecording() {11const recording = await client.video.v112.rooms("RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")13.recordings("RTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")14.fetch();1516console.log(recording.accountSid);17}1819fetchRoomRecording();
1{2"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",3"status": "processing",4"date_created": "2015-07-30T20:00:00Z",5"date_updated": "2015-07-30T21:00:00Z",6"date_deleted": "2015-07-30T22:00:00Z",7"sid": "RTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",8"source_sid": "MTaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",9"size": 0,10"type": "audio",11"duration": 0,12"container_format": "mka",13"codec": "OPUS",14"track_name": "A name",15"offset": 10,16"grouping_sids": {17"room_sid": "RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"18},19"media_external_location": "https://my-super-duper-bucket.s3.amazonaws.com/my/path/",20"encryption_key": "public_key",21"room_sid": "RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",22"url": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Recordings/RTaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",23"links": {24"media": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Recordings/RTaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Media"25}26}
1// NOTE: This example uses the next generation Twilio helper library - for more2// information on how to download and install this version, visit3// https://www.twilio.com/docs/libraries/node4const Twilio = require("twilio");56// To set up environmental variables, see http://twil.io/secure7const apiKeySid = process.env.TWILIO_API_KEY;8const apiKeySecret = process.env.TWILIO_API_KEY_SECRET;9const accountSid = process.env.TWILIO_ACCOUNT_SID;10const client = new Twilio(apiKeySid, apiKeySecret, { accountSid: accountSid });1112const roomSid = "RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";13const recordingSid = "RTXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";14const uri =15"https://video.twilio.com/v1/" +16`Rooms/${roomSid}/` +17`Recordings/${recordingSid}` +18"/Media";19client.request({ method: "GET", uri: uri }).then((response) => {20const mediaLocation = response.data.redirect_to;21request.get(mediaLocation, (err, res, media) => {22console.log(media);23});24});
1{2"redirect_to": "https://com.twilio.us1.video.recording.s3.amazonaws.com/RTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"3}
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 |
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.
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 |
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.
Firefox Mobile could find Recording gaps due to a Firefox bug when sending temporization. Twilio recommends Video participants to use other mobile browsers.