Menu

Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Rest API: Recordings

Overview

Twilio Video’s Group Rooms and Recording APIs enable 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.

https://video.twilio.com

Contents

Recording instance resource

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}

Resource properties

A Recording has the following properties:

account_sid
sid<AC> Not PII

The unique SID identifier of the Twilio Account.

codec
enum:codec Not PII

The codec used to encode the track. Currently supported codecs include: VP8, H264, OPUS, and PCMU.

container_format
enum:format Not PII

The file format for this Recording. Video Room recordings are captured in Matroska container format, so this will be set to mka for audio files and mkv for video files.

date_created
date_time<iso8601> Not PII

Date conforming to UTC ISO 8601 Timestamp. Matches the time the media recording began writing.

duration
integer? Not PII

Duration of the Recording in seconds rounded to the nearest second. Thus, sub-second duration tracks have a Duration property of 1 second

grouping_sids
object Not PII

A list of Sids related to this Recording. Includes the RoomSid and ParticipantSid.

offset
long Not PII

The time in milliseconds elapsed between an arbitrary point in time, and the moment this track recording started. This information is used to synchronize tracks from recovered rooms.

sid
sid<RT> Not PII

RTxx...xx A system-generated 34-character string that uniquely identifies this Recording.

size
long Not PII

Size of the recorded track, in bytes.

source_sid
sid Not PII

Identifies the source of the Recording. For Room Recording, this field stores the TrackSid.

status
enum:status Not PII

The status of the Recording. Possible values are 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 for historical purposes.

track_name

The name that was given to the source track of this recording. If no name is given, the SourceSid is used.

type
enum:type Not PII

Indicates the media type for this recording. Can be either audio or video.

url
url Not PII

The absolute URL for this resource.

Note: The duration of media tracks is rounded to the nearest second. Thus, sub-second duration tracks have a Duration property of 1 second.

HTTP GET

Returns a single Recording Instance resource identified by a RecordingSid.

Example: Retrieve a Recording

Loading Code Sample...
      
      
      
      

      HTTP GET to the /Media subresource

      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
      VP8 video/webm
      OPUS audio/webm
      PCMU audio/x-matroska
      H264 video/x-matroska

      The URL returned will only be available for 60 minutes, but a different expiration can be specified via the Ttl request param. If the composition is not yet available, a 404 is returned. If the recording is not available (for example, if its status is processing or deleted), 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 maximum expiration time is 7 days (604800) (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.

      Example: Retrieve a Recording's Media

      Loading Code Sample...
          
          
          
          

          HTTP POST

          Not supported.

          HTTP DELETE

          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.

          Example: Delete a Recording

          Loading Code Sample...
              
              
              
              

              Recordings List Resource

              Recordings list is available at the following URI:

               /v1/Recordings
              

              HTTP GET

              Returns a list of all Track Recordings with paging data.

              HTTP GET: List filters

              The following GET query string parameters allow you to limit the list returned. Note, parameters are case-sensitive.

              DateCreatedAfter
              Optional
              get date_time<iso8601> Not PII

              Only show Recordings that started on or after this ISO8601 date-time, given as YYYY-MM-DDThh:mm:ss-hh:mm.

              DateCreatedBefore
              Optional
              get date_time<iso8601> Not PII

              Only show Recordings that started before this this ISO8601 date-time, given as YYYY-MM-DDThh:mm:ss-hh:mm.

              GroupingSid
              Optional
              get sid[] Not PII

              Only show Recordings that have this GroupingSid, which may include a ParticipantSid and/or a RoomSid.

              SourceSid
              Optional
              get sid Not PII

              Only show the Recordings with the given source Sid (you can use this to filter Recordings by TrackSid for Video Room Recordings.

              Status
              Optional
              get enum:status Not PII

              Only show Recordings with the given status.

              Note: deleted Recordings are not returned by default. For retrieving the deleted Recordings list you must explicitly specify Status=deleted.

              Example: Get all Recordings for a given Room

              Loading Code Sample...
                  
                  
                  
                  
                  Loading Code Sample...
                      
                      
                      
                      
                      Loading Code Sample...
                          
                          
                          
                          

                          HTTP POST

                          Not supported.

                          HTTP DELETE

                          Not supported.

                          Using the Rooms API to find Recordings

                          To make it easier for customers to find the Recordings from a certain Room, we provide the following affordances for list filtering via the Rooms API:

                          Example: Get all recordings from a given Room using the Rooms API

                          Loading Code Sample...
                              
                              
                              
                              
                              Loading Code Sample...
                                  
                                  
                                  
                                  
                                  Loading Code Sample...
                                      
                                      
                                      
                                      

                                      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 browsing the Twilio tag on Stack Overflow.

                                      Loading Code Sample...