tencent cloud

Feedback

On-Cloud Recording

Last updated: 2022-05-23 16:30:57

    In applications such as online education, live showroom, video conferencing, online medical consultation, and remote banking, it is often necessary to record entire video calls or live streaming sessions for purposes including content moderation, archiving, and playback. The on-cloud recording feature of TRTC can help meet these demands.

    Overview

    The on-cloud recording feature of TRTC allows you to record an audio/video stream in real time using a RESTful API. It is flexible, light, and easy-to-use, saving you the trouble of deploying servers and recording modules.

    • Recording mode: Single-stream recording records the audio and video of each user in a room separately, while mixed-stream recording records all audios and videos in a room into one result.
    • Stream subscription: You can determine whose streams you receive or do not receive using an allowlist/blocklist.
    • Transcoding parameters: In the mixed-stream recording mode, you can determine the output video quality by specifying transcoding parameters.
    • Stream-mixing parameters: For mixed-stream recording, we offer multiple auto-arranged layout templates. You can also customize a layout template.
    • File storage: Currently, you can save recording files only in COS or VOD of Tencent Cloud.
      (We plan to add support for storage and video-on-demand services of third-party cloud vendors in the future. To save files to third-party platforms, you will need to provide your cloud service account and the storage parameters.)
    • Callback notification: By configuring a callback domain in the console, you can receive notifications about on-cloud recording events via your callback server.

    Single-stream recording

    Single-stream recording

    The diagram above shows the workflow of single-stream recording. In room 1234, anchor 1 and anchor 2 are publishing streams. If you subscribe to their streams and enable single-stream recording, the TRTC backend will record the audio and video data of anchor 1 and anchor 2 separately. The recording results will include:

    1. An M3U8 index file of anchor 1’s video
    2. Multiple TS segment files of anchor 1’s video
    3. An M3U8 index file of anchor 1’s audio
    4. Multiple TS segment files of anchor 1’s audio
    5. An M3U8 index file of anchor 2’s video
    6. Multiple TS segment files of anchor 2’s video
    7. An M3U8 index file of anchor 2’s audio
    8. Multiple TS segment files of anchor 2’s audio

    The backend will then upload the files to the cloud storage server you specify. You need to download the files and merge/transcode them. We offer a script for merging audio and video streams.

    Mixed-stream recording

    Mixed-stream recording

    The above shows the workflow of mixed-stream recording. In room 1234, anchor 1 and anchor 2 are publishing streams. If you subscribe to their streams and enable mixed-stream recording, the TRTC backend will mix the streams of anchor 1 and anchor 2 according to the layout template you specify and then record them into one result, which will include:

    1. An M3U8 index file of the mixed video
    2. Multiple TS segment files of the mixed video

    The backend will then upload the files to the cloud storage server you specify. You need to download the files and merge/transcode them. We offer a script for merging audio and video streams.

    Note:

    • The rate limit for the recording API is 20 queries per second.
    • The timeout period for a query is 6 seconds.
    • We allow up to 100 ongoing recording tasks at the same time. If you need to record more, please submit a ticket.
    • In the single-stream recording mode, you can record up to 25 streams in a room at the same time.

    Directions

    1. Start recording

    Call the RESTful API CreateCloudRecording from your server to start on-cloud recording. Pay attention to the following parameters:

    TaskId

    This parameter uniquely identifies a recording task. Note it as you will need to provide it for other actions on the same task later.

    RecordMode

    • Single-stream recording separately records the audios and videos of individual anchors whose streams you receive before uploading the results (including M3U8 and TS segment files) to the cloud.
    • Mixed-stream recording records all the audios and videos of anchors whose streams you receive into one result (including M3U8 and TS segment files) before uploading it to the cloud.

    SubscribeStreamUserIds

    By default, on-cloud recording records all the streams (max 25) you receive in a room. You can use this parameter to specify whose streams you want to record and can change its value during recording.

    StorageParams

    You can use this parameter to specify the cloud storage/video-on-demand service you want to save recording files to. Make sure you use a valid value and that the cloud storage/video-on-demand service you use is available. Below are the naming conventions of recording files:

    Naming of recording files
    • M3U8 file in the single-stream recording mode:
      <prefix>/<taskid>/<sdkappid>_<roomid>__UserId_s_<userid>__UserId_e_<mediaid>_<type>.m3u8

    • TS segment file in the single-stream recording mode:
      <prefix>/<taskid>/<sdkappid>_<roomid>__UserId_s_<userid>__UserId_e_<mediaid>_<type>_<utc>.ts

    • MP4 file in the single-stream recording mode:
      <prefix>/<taskid>/<sdkappid>_<roomid>__UserId_s_<userid>__UserId_e_<mediaid>_<index>.mp4

    • M3U8 file in the mixed-stream recording mode:
      <prefix>/<taskid>/<sdkappid>_<roomid>.m3u8

    • TS segment file in the mixed-stream recording mode:
      <prefix>/<taskid>/<sdkappid>_<roomid>_<utc>.ts

    • MP4 file in the mixed-stream recording mode:
      <prefix>/<taskid>/<sdkappid>_<roomid>_<index>.mp4

    • Naming of recovered files
      The on-cloud recording feature has a high availability scheme that can recover recording files if the server fails. To prevent the recovered files from replacing the original files, we add a prefix ha&lt;1/2/3> to the names of recovered files. The numbers indicate the times (max 3) the high availability scheme is used.

    • M3U8 file in the single-stream recording mode:
      <prefix>/<taskid>/ha&lt;1/2/3>_<sdkappid>_<roomid>__UserId_s_<userid>__UserId_e_<mediaid>_<type>.m3u8

    • TS segment file in the single-stream recording mode:
      <prefix>/<taskid>/ha&lt;1/2/3>_<sdkappid>_<roomid>__UserId_s_<userid>__UserId_e_<mediaid>_<type>_<utc>.ts

    • M3U8 file in the mixed-stream recording mode:
      <prefix>/<taskid>/ha&lt;1/2/3>_<sdkappid>_<roomid>.m3u8

    • TS segment file in the mixed-stream recording mode:
      <prefix>/<taskid>/ha&lt;1/2/3>_<sdkappid>_<roomid>_<utc>.ts

    Field description

    <prefix>: filename prefix, which is not used if not specified
    <taskid>: task ID, which is unique and is returned by the start recording API
    <sdkappid>: application ID
    <roomid>: room ID
    <userid>: Base64-encoded ID of a user whose stream is recorded
    <mediaid>: indicates whether the primary stream (main) or substream (aux) is recorded
    <type>: the type of stream that is recorded (audio or video)
    <utc>: recording start time (UTC+0) (year, month, day, hour, minute, second, millisecond)
    <index>: index of a segment, which starts from 1. This field is used only if the size of an MP4 file reaches 2 GB or its length reaches 24 hours and needs to be segmented.
    ha&lt;1/2/3>: prefix for a file recovered by the high availability scheme. For example, if the scheme is used for the first time, the recovered file is named <prefix>/<taskid>/ha1_<sdkappid>_<roomid>.m3u8.

    Note:

    If <roomid> is a string, it will be encoded into Base64. In the result, "/" is replaced with "-" and "=" is replaced with "."
    <userid> is encoded into Base64. In the result, "/" is replaced with "-" and "=" is replaced with "."

    Recording start time

    Recording starts when you start receiving data from an anchor. Recording start time is the Unix time on the server when recording starts.
    You can query the start time of a recording task in three ways:

    • Using the DescribeCloudRecording API. BeginTimeStamp in the response parameters indicates the recording start time (ms).

    Below is a response of the DescribeCloudRecording API, in which BeginTimeStamp is 1622186279144.

    {
    "Response": {
      "Status": "xx",
      "StorageFileList": [
        {
          "TrackType": "xx",
          "BeginTimeStamp": 1622186279144,
          "UserId": "xx",
          "FileName": "xx"
        }
      ],
      "RequestId": "xx",
      "TaskId": "xx"
    }
    }
    
    • Viewing the M3U8 file (the #EXT-X-TRTC-START-REC-TIME directive)

    According to the M3U8 file below, the Unix time (ms) when recording started was 1622425551884.

    #EXTM3U
    #EXT-X-VERSION:3
    #EXT-X-ALLOW-CACHE:NO
    #EXT-X-MEDIA-SEQUENCE:0
    #EXT-X-TARGETDURATION:70
    #EXT-X-TRTC-START-REC-TIME:1622425551884
    #EXT-X-TRTC-VIDEO-METADATA:WIDTH:1920 HEIGHT:1080
    #EXTINF:12.074
    1400123456_12345__UserId_s_MTY4NjExOQ..__UserId_e_main_video_20330531094551825.ts
    #EXTINF:11.901
    1400123456_12345__UserId_s_MTY4NjExOQ..__UserId_e_main_video_20330531094603825.ts
    #EXTINF:12.076
    1400123456_12345__UserId_s_MTY4NjExOQ..__UserId_e_main_video_20330531094615764.ts
    #EXT-X-ENDLIST
    
    • Via a recording callback

    If you have registered recording callbacks, you will receive a callback for the generation of recording files (event type 307), in which BeginTimeStamp indicates the recording start time.
    According to the callback below, the Unix time (ms) when recording started was 1622186279144.

    {
          "EventGroupId": 3,
          "EventType":    307,
          "CallbackTs":   1622186289148,
          "EventInfo":    {
                  "RoomId":       "xx",
                  "EventTs":      "1622186289",
                  "UserId":       "xx",
                  "TaskId":       "xx",
                  "Payload":      {
                          "FileName":     "xx.m3u8",
                          "UserId":       "xx",
                          "TrackType":    "audio",
                          "BeginTimeStamp":       1622186279144
                  }
          }
    }
    

    MixWatermark

    TRTC allows you to watermark videos during mixed-stream recording. You can add up to 25 marks to a video in your desired positions.

    Field Description
    Top Vertical offset of the watermark from the top-left corner of the video
    Left Horizontal offset of the watermark from the top-left of the video
    Width Watermark width
    Height Watermark height
    url URL of the watermark file

    MixLayoutMode

    TRTC supports the grid layout (default), floating layout, screen sharing layout, and custom layout.

    Grid layout

    The videos of anchors are scaled and positioned automatically according to the total number of anchors in a room. Each video has the same size. Up to 25 videos can be displayed.

    • When there is only one video:
      The video is scaled to fill the canvas.

    • When there are two videos:
      The width of each video is half of the canvas width.
      The height of each video is the same as the canvas height.

    • When there are three or four videos:
      The canvas is split evenly into four windows and each video is displayed in one window.

    • When the number of videos is between four and nine:
      The canvas is split evenly into nine windows and each video is displayed in one window.

    • When the number of videos is between 10 and 16:
      The canvas is split evenly into 16 windows and each video is displayed in one window.

    • When there are more than 16 videos:
      The canvas is split evenly into 25 windows and each video is displayed in one window.

      As shown below:

    Grid 1
    Grid 2
    Grid 3
    Grid 4
    Grid 5
    Grid 6

    Floating layout

    By default, the video of the first anchor (you can also specify an anchor) who enters the room is scaled to fill the screen. When other anchors enter the room, their videos appear smaller and are superimposed over the large video from left to right starting from the bottom of the canvas according to their room entry sequence. If the total number of videos is 17 or less, there will be four windows in each row (4 × 4); if it is greater than 17, there will be five windows in each row (5 × 5). Up to 25 videos can be displayed. A user who publishes only audio will still be displayed in one window.

    • When there are 17 or fewer videos:

       The width and height of each video are 23.5% of the canvas width and height.
       The horizontal space and vertical space between two neighboring videos are 1.2% of the canvas width and height.
       The right/left and top/bottom margin are 1.2% of the canvas width and height.
      
    • When there are more than 17 videos:

       The width and height of each video are 18.8% of the canvas width and height.
       The horizontal space and vertical space between two neighboring videos are 1% of the canvas width and height.
       The right/left and top/bottom margin are 1% of the canvas width and height.
      

      As shown below:
      Floating 1
      Floating 2

    Screen sharing layout

    The video of a specified anchor occupies a larger part of the canvas on the left side (if you do not specify an anchor, the left window will display the canvas background). The videos of other anchors are smaller and are positioned on the right side. If the total number of videos is 17 or less, the small videos are positioned from top to bottom in up to two columns on the right side, with eight videos per column at most. If there are more than 17 videos, the additional videos are positioned at the bottom of the canvas from left to right. Up to 24 videos can be displayed. A user who publishes only audio will still is displayed in one window.

    • When there are five or fewer videos:
      The size of each small video on the right is 1/5 the canvas width and 1/4 the canvas height.
      The width of the large video on the left is 4/5 the canvas width, and its height is the same as the canvas height.

    • When the number of videos is between 5 and 7:
      The size of each small video on the right are 1/7 the canvas width and 1/6 the canvas height.
      The width of the large video on the left is 6/7 the canvas width, and its height is the same as the canvas height.

    • When there are eight or nine videos:
      The size of each small video on the right is 1/9 the canvas width and 1/8 the canvas height.
      The width of the large video on the left is 8/9 the canvas width, and its height is the same as the canvas height.

    • When the number of videos is between 10 and 17:
      The size of each small video on the right side is 1/10 the canvas width and 1/8 the canvas height.
      The width of the large video on the left side is 4/5 the canvas width, and its height is the same as the canvas height.

    • When there are more than 17 videos:
      The size of each small video on the right and bottom is 1/10 the canvas width and 1/8 the canvas height.
      The width of the large video on the left is 4/5 the canvas width, and its height is 7/8 the canvas height.

    As shown below:
    Screen sharing 1
    Screen sharing 2
    Screen sharing 3
    Screen sharing 4
    Screen sharing 4

    Custom layout

    You can also use MixLayoutList to customize a layout for anchor videos.

    2. Query the recording task

    You can use the DescribeCloudRecording API to query the status of an ongoing recording task. If the queried task has already ended, an error will be returned.
    The file list (StorageFile) that is returned will include all the M3U8 files of the recording as well as the Unix time when recording started. If the task queried is a recording to VOD task, the StorageFile returned will be empty.

    3. Modify recording parameters

    You can use the ModifyCloudRecording API to modify recording parameters, including SubscribeStreamUserIds and MixLayoutParams (valid only for mixed-stream recording). Note that to modify parameters, you need to respecify all the parameters, including MixLayoutParams and SubscribeStreamUserIds, and not just the one you want to modify. As a result, we recommend you note all the values before modifying a parameter, or you will need to calculate them again.

    4. Stop recording

    You can call the DeleteCloudRecording API to stop recording. A recording task will also end automatically if there are no anchors in a room for longer than the specified time period (MaxIdleTime). We recommend that you call the API to stop recording when you no longer need the service.

    Advanced Features

    Recording in MP4 format

    To record in MP4 format, set OutputFormat to hls+mp4 when calling the CreateCloudRecording API. TRTC will still record in HLS format, but once recording ends, it will download the HLS file from its COS bucket, convert it into MP4 format, and upload the MP4 file to the COS bucket.
    Please note that COS download access is required for the above to work.
    An MP4 file will be segmented if one of the following conditions is met.

    1. The recording lasts for 24 hours or longer.
    2. The MP4 file is 2 GB or larger.

      The figure below shows the workflow of recording in MP4 format.

      Record in MP4 format

    Recording to VOD

    To record to VOD, specify the CloudVod parameter in StorageParams when calling the CreateCloudRecording API. After recording ends, the backend will save the file in MP4 format to VOD using the method you specify and send you a playback URL via a callback. In the single-stream recording mode, there will be a playback URL for each anchor whose stream is recorded; in the mixed-stream recording mode, there will be only one playback URL. When you record to VOD, pay attention to the following:

    1. CloudVod and CloudStorage are mutually exclusive. If you specify both, the recording task will fail to start.
    2. If you use DescribeCloudRecording to query a recording to VOD task, the StorageFile returned will be empty.

      The figure below shows the workflow of recording to VOD, in which "cloud storage" refers to the internal storage of the recording backend. You don’t need to specify a COS bucket for it.

      Record to VOD

    Script for merging single-stream recording files

    We offer a script for merging single-stream audio and video files into MP4 files.

    Note:

    If two segment files are more than 15 seconds apart, during which no audio or video data is recorded (if the substream is disabled, its data will be ignored), the two segments will be considered to belong to different sections, one being the ending segment of the previous section, and the other the starting segment of the next section.

    • Section-based merge (-m 0)
      In this mode, the recording files of each user (UserId) are merged by section. An MP4 file is generated for each section.
    • User-based merge (-m 1)
      In this mode, the recording files of each user (UserId) are merged into one MP4 file. You can use the -s option to specify whether to fill in the blanks between sections.

    Environment requirements

    Python 3

    • Centos: sudo yum install python3
    • Ubuntu: sudo apt-get install python3

    Python 3 dependency

    -sortedcontainers:pip3 install sortedcontainers

    Directions

    1. Run the merge script: python3 TRTC_Merge.py [option]
    2. An MP4 file will be generated in the directory of the recording files.
      E.g.: python3 TRTC_Merge.py -f /xxx/file -m 0

    Below is a list of the options:

    Option Description
    -f Directory of the recording files. If there are multiple users (UserId), their recording files will be merged separately.
    -m 0: section-based marge (default). In this mode, the recording files of each user (UserId) are merged by section. Multiple MP4 files may be generated for each user.
    1: user-based merge. In this mode, the recording files of each user (UserId) are merged into one MP4 file.
    -s Indicates whether to delete the blanks between sections in the user-based merge mode, in which case the files generated will be shorter than the recording duration.
    -a 0: primary stream merge (default). The audio of a user (UserId) is merged with the user’s primary stream, not the substream.
    1: automatic merge. If a user (UserId) has a primary stream, the user’s audio is merged with the primary stream; if not, it is merged with the substream.
    2: substream merge. The audio of a user (UserId) is merged with the user’s substream, not the primary stream.
    -p Frame rate (fps) of the output video, which is 15 by default. Value range: 5-120. If you enter a value smaller than 5, 5 will be used; if you enter a value greater than 120, 120 will be used.
    -r Resolution of the output video. For example, -r 640 360 indicates that the resolution of the output video is 640 × 360.

    File Naming

    • Audio-video file: UserId_timestamp_av.mp4
    • Audio-only file: UserId_timestamp.m4a
    Note:

    UserId is the Base64-encoded ID of a user whose stream is recorded. For details, see the naming of recording files. timestamp is the starting time of the first TS segment of a section.

    Callback APIs

    You can register callbacks by providing an HTTP/HTTPS gateway to receive callbacks. When an on-cloud recording event occurs, the system will send a callback notification to your callback server.

    Callback format

    Callbacks are sent to your server in the form of HTTP/HTTPS POST requests, which consist of the following parts:
    Character encoding: UTF-8
    Request: The request body is in JSON format.
    Response: HTTP STATUS CODE = 200. The server ignores the content of the response packet. For protocol-friendliness, we recommend adding JSON: {"code":0}`` to the response.

    Field description

    The header of a callback contains the following fields.

    Field Description
    Content-Type application/json
    Sign Signature value
    SdkAppId SDK application ID

    The body of a callback contains the following fields.

    Field Type Description
    EventGroupId Number Event group ID, which is 3 for on-cloud recording
    EventType Number Event type
    CallbackTs Number Unix time (ms) when the callback was sent to your server
    EventInfo JSON Object Event information

    Event types

    Field Type Description
    EVENT_TYPE_CLOUD_RECORDING_RECORDER_START 301 On-cloud recording - The recording module was started.
    EVENT_TYPE_CLOUD_RECORDING_RECORDER_STOP 302 On-cloud recording - The recording module was stopped.
    EVENT_TYPE_CLOUD_RECORDING_UPLOAD_START 303 On-cloud recording - The upload module was started.
    EVENT_TYPE_CLOUD_RECORDING_FILE_INFO 304 On-cloud recording - The first M3U8 file was generated and uploaded successfully.
    EVENT_TYPE_CLOUD_RECORDING_UPLOAD_STOP 305 On-cloud recording - The upload finished.
    EVENT_TYPE_CLOUD_RECORDING_FAILOVER 306 On-cloud recording - The recording task was migrated.
    EVENT_TYPE_CLOUD_RECORDING_FILE_SLICE 307 On-cloud recording - The first TS segment was available and an M3U8 file was generated.
    EVENT_TYPE_CLOUD_RECORDING_UPLOAD_ERROR 308 On-cloud recording - The upload module encountered an error.
    EVENT_TYPE_CLOUD_RECORDING_DOWNLOAD_IMAGE_ERROR 309 On-cloud recording - An error occurred during the download of the image decoding file.
    EVENT_TYPE_CLOUD_RECORDING_MP4_STOP 310 On-cloud recording - The task of recording in MP4 format ended and the name of the MP4 file generated was returned.
    EVENT_TYPE_CLOUD_RECORDING_VOD_COMMIT 311 On-cloud recording - Upload was completed for the recording to VOD task.
    EVENT_TYPE_CLOUD_RECORDING_VOD_STOP 312 On-cloud recording - The recording to VOD task ended.

    Event information

    Field Type Description
    RoomId String/Number Room ID (same type as Room ID on the client)
    EventTs Number Unix timestamp (s) when the event occurred
    UserId String User ID of the recording robot
    TaskId String Recording ID, which uniquely identifies a recording task
    Payload JsonObject The content of this field varies with event type.

    If the event type is 301 (EVENT_TYPE_CLOUD_RECORDING_RECORDER_START):

    Field Type Description
    Status Number 0: The recording module was started successfully. 1: The recording module failed to be started.
    {
          "EventGroupId": 3,
          "EventType":    301,
          "CallbackTs":   1622186275913,
          "EventInfo":    {
                  "RoomId":       "xx",
                  "EventTs":      "1622186275",
                  "UserId":       "xx",
                  "TaskId":       "xx",
                  "Payload":      {
                          "Status":       0
                  }
          }
    }
    

    If the event type is 302 (EVENT_TYPE_CLOUD_RECORDING_RECORDER_STOP):

    Field Type Description
    LeaveCode Number 0: The recording module ended the recording normally.
    1: The recording robot was removed from the room.
    2: The room was closed.
    3: The server removed the recording robot from the room.
    4: The server closed the room.
    99: There were no anchors in the room except the recording robot, which quit after the specified time period elapsed.
    100: The recording robot quit after timeout.
    101: The recording robot was removed due to repeat entry by the same user.
    {
          "EventGroupId": 3,
          "EventType":    302,
          "CallbackTs":   1622186354806,
          "EventInfo":    {
                  "RoomId":       "xx",
                  "EventTs":      "1622186354",
                  "UserId":       "xx",
                  "TaskId":       "xx",
                  "Payload":      {
                          "LeaveCode":    0
                  }
          }
    }
    

    If the event type is 303 (EVENT_TYPE_CLOUD_RECORDING_UPLOAD_START):

    Field Type Description
    Status Number 0: The upload module was started successfully.
    1: The upload module failed to be started.
    {
          "EventGroupId": 3,
          "EventType":    303,
          "CallbackTs":   1622191965320,
          "EventInfo":    {
                  "RoomId":       "20015",
                  "EventTs":      1622191965,
                  "UserId":       "xx",
                  "TaskId":       "xx",
                  "Payload":      {
                          "Status":       0
                  }
          }
    }
    

    If the event type is 304 (EVENT_TYPE_CLOUD_RECORDING_FILE_INFO):

    Field Type Description
    FileList String Name of the M3U8 file generated
    {
          "EventGroupId": 3,
          "EventType":    304,
          "CallbackTs":   1622191965350,
          "EventInfo":    {
                  "RoomId":       "20015",
                  "EventTs":      1622191965,
                  "UserId":       "xx",
                  "TaskId":       "xx",
                  "Payload":      {
                          "FileList":     "xx.m3u8"
                  }
          }
    }
    

    If the event type is 305 (EVENT_TYPE_CLOUD_RECORDING_UPLOAD_STOP):

    Field Type Description
    Status Number 0: The recording task ended and all the files were uploaded to the specified third-party cloud storage service.
    1: The recording task ended, but at least one file on the server or in backup storage failed to be uploaded.
    2: The files that failed to be uploaded earlier were uploaded to the specified third-party cloud storage service.
    {
          "EventGroupId": 3,
          "EventType":    305,
          "CallbackTs":   1622191989674,
          "EventInfo":    {
                  "RoomId":       "20015",
                  "EventTs":      1622191989,
                  "UserId":       "xx",
                  "TaskId":       "xx",
                  "Payload":      {
                          "Status":       0
                  }
          }
    }
    

    If the event type is 306 (EVENT_TYPE_CLOUD_RECORDING_FAILOVER):

    Field Type Description
    Status Number 0: The migration was completed.
    {
          "EventGroupId": 3,
          "EventType":    306,
          "CallbackTs":   1622191989674,
          "EventInfo":    {
                  "RoomId":       "20015",
                  "EventTs":      1622191989,
                  "UserId":       "xx",
                  "TaskId":       "xx",
                  "Payload":      {
                          "Status":       0
                  }
          }
    }
    

    If the event type is 307 (EVENT_TYPE_CLOUD_RECORDING_FILE_SLICE):

    Field Type Description
    FileName String Name of the M3U8 file generated
    UserId String ID of the user whose stream was recorded in the file
    TrackType String Valid values: audio/video/audio_video
    BeginTimeStamp Number Unix timestamp on the server when recording started
    {
         "EventGroupId": 3,
         "EventType":    307,
         "CallbackTs":   1622186289148,
         "EventInfo":    {
                 "RoomId":       "xx",
                 "EventTs":      "1622186289",
                 "UserId":       "xx",
                 "TaskId":       "xx",
                 "Payload":      {
                         "FileName":     "xx.m3u8",
                         "UserId":       "xx",
                         "TrackType":    "audio",
                         "BeginTimeStamp":       1622186279144
                 }
         }
    }
    

    If the event type is 308 (EVENT_TYPE_CLOUD_RECORDING_UPLOAD_ERROR):

    Field Type Description
    Code String Error code returned by the third-party cloud storage service
    Message String Error message returned by the third-party cloud storage service
    {
    "Code": "InvalidParameter",
    "Message": "AccessKey invalid"
    }
    {
         "EventGroupId": 3,
         "EventType":    308,
         "CallbackTs":   1622191989674,
         "EventInfo":    {
                 "RoomId":       "20015",
                 "EventTs":      1622191989,
                 "UserId":       "xx",
                 "TaskId":       "xx",
                 "Payload":      {
                         "Code":       "xx",
                         "Message":    "xx"
                 }
         }
    }
    

    If the event type is 309 (EVENT_TYPE_CLOUD_RECORDING_DOWNLOAD_IMAGE_ERROR):

    Field Type Description
    Url String The URL from which the file failed to be downloaded
    {
         "EventGroupId": 3,
         "EventType":    309,
         "CallbackTs":   1622191989674,
         "EventInfo":    {
                 "RoomId":       "20015",
                 "EventTs":      1622191989,
                 "UserId":       "xx",
                 "TaskId":       "xx",
                 "Payload":      {
                         "Url":       "http://xx",
                 }
         }
    }
    

    If the event type is 310 (EVENT_TYPE_CLOUD_RECORDING_MP4_STOP):

    Field Type Description
    Status Number 0: The task ended and all the files were uploaded to the specified third-party cloud storage service.
    1: The task ended, but at least one file on the server or in backup storage failed to be uploaded.
    2: The task stopped due to an error, for example, failure to download HLS files from COS.
    FileList String Name of the MP4 file generated
    {
         "EventGroupId": 3,
         "EventType":    310,
         "CallbackTs":   1622191989674,
         "EventInfo":    {
                 "RoomId":       "20015",
                 "EventTs":      1622191989,
                 "UserId":       "xx",
                 "TaskId":       "xx",
                 "Payload":      {
                         "Status":       0,
                         "FileList": ["xxxx1.mp4", "xxxx2.mp4"]
                 }
         }
    }
    

    If the event type is 311 (EVENT_TYPE_CLOUD_RECORDING_VOD_COMMIT):

    Field Type Description
    Status Number 0: The recording file was successfully uploaded to VOD.
    1: The recording file failed to be uploaded.
    2: An error occurred.
    UserId String ID of the user whose stream is recorded. In the mixed-stream recording mode, this field is empty.
    TrackType String Valid values: audio/video/audio_video
    MediaId String Valid values: main/aux
    FileId String Unique ID of the recording file in VOD
    VideoUrl String Playback URL of the recording file in VOD
    CacheFile String Name of the MP4 file converted from the recording file (before it was uploaded to VOD)
    Errmsg String Error message when Status is not 0

    Callback for successful upload:

    {
          "EventGroupId": 3,
          "EventType":    311,
          "CallbackTs":   1622191965320,
          "EventInfo":    {
                  "RoomId":       "20015",
                  "EventTs":      1622191965,
                  "UserId":       "xx",
                  "TaskId":       "xx",
                  "Payload":      {
                          "Status":       0,
                          "TencentVod":   {
                              "UserId":       "xx",
                              "TrackType":    "audio_video",
                              "MediaId":      "main",
                              "FileId":       "xxxx",
                              "VideoUrl":     "http://xxxx"
                          }
                  }
          }
    }
    

    Callback for failed upload:

    {
          "EventGroupId": 3,
          "EventType":    311,
          "CallbackTs":   1622191965320,
          "EventInfo":    {
                  "RoomId":       "20015",
                  "EventTs":      1622191965,
                  "UserId":       "xx",
                  "TaskId":       "xx",
                  "Payload":      {
                          "Status":       1,
                          "Errmsg":       "xxx",
                          "TencentVod":   {
                              "UserId":       "123",
                              "TrackType":    "audio_video",
                              "CacheFile":    "xxx.mp4"
                          }
                  }
          }
    }
    

    If the event type is 312 (EVENT_TYPE_CLOUD_RECORDING_VOD_STOP):

    Field Type Description
    Status Number 0: The task ended after upload was completed.
    1: The task ended due to an error.
    {
         "EventGroupId": 3,
         "EventType":    312,
         "CallbackTs":   1622191965320,
         "EventInfo":    {
                 "RoomId":       "20015",
                 "EventTs":      1622191965,
                 "UserId":       "xx",
                 "TaskId":       "xx",
                 "Payload":      {
                         "Status":       0
                 }
         }
    }
    

    Best Practices

    To ensure the high availability of the recording service, we recommend the following practices when you use the RESTful APIs:

    1. Pay attention to the HTTP response after you call CreateCloudRecording. If your request fails, fix the problem according to the status code and try again.

      The status code consists of two parts, for example InvalidParameter.SdkAppId.

      • InternalError.xxxxx indicates that a server error occurred. You can retry until the request succeeds and TaskId is returned. We recommend you use the exponential backup algorithm for retry. For example, you can wait for three seconds for the first retry, six seconds for the second, 12 seconds for the third, and so on.
      • InValidParameter.xxxxx indicates that a parameter value entered was invalid. Please check the parameter.
      • FailedOperation.RestrictedConcurrency indicates that you reached the maximum number (100 by default) of ongoing recording tasks allowed. To raise the limit, please contact technical support.
    2. The UserId and UserSig you pass in when calling CreateCloudRecording are for the recording robot. Please make sure that they are different from those of other users in the room. In addition, the room users join from the TRTC client must be of the same type as the room you specify when calling the API. For example, if the room created in the TRTC SDK is a string, the room specified for on-cloud recording must also be a string.

    3. You can obtain the information of a recording file in the following ways.

      • Call DescribeCloudRecording 15 seconds after a CreateCloudRecording request succeeds. If the status returned is idle, it indicates that no audio or video data is available for recording. Please check whether there are anchors publishing data in the room.
      • After a CreateCloudRecording request succeeds, if there are anchors publishing data in the room, you can splice the name of the recording file according to the naming conventions.
      • If you have registered on-cloud recording callbacks, the information of recording files will be sent to your server via callbacks.
      • You can specify a COS bucket to save recording files when calling the CreateCloudRecording API, so after a recording task ends, you can find the recording file in the COS bucket.
    4. Make sure the validity period of the recording user’s UserSig is set longer than the duration of the recording task. This is to avoid cases where the high availability scheme fails to resume a recording task after an internet disconnection because the UserSig is already expired.

    Contact Us

    Contact our sales team or business advisors to help your business.

    Technical Support

    Open a ticket if you're looking for further assistance. Our Ticket is 7x24 avaliable.

    7x24 Phone Support