Configuration Item | Description |
Recording mode | Single-stream recording: The video data of each anchor in the room will be saved as a separate file. |
Recording type | Audio and video: Both audio and video streams in the room are recorded, suitable for video calls and interactive live streaming scenarios. Audio-only: Only audio streams in the room are recorded. |
File format | Supports MP4, HLS, and AAC (in audio-only format). |
Max file duration | Specifies the segment duration of the recording file, with a range of 1-1,440 minutes. The default is 1,440 minutes. |
Timeout period for resumption | Sets the timeout period for resuming recording in seconds. When the interruption interval does not exceed the set timeout period, a single call (or live stream) will generate only one file. However, the recording file will be received only after the timeout period for resumption expires. The value range is 1 - 86,400 (default 30s) . Note: During the resumption waiting period, single-stream recording fees will be charged based on the audio duration. Please set it appropriately. |
Storage | Supports storage to Tencent Cloud Video on Demand (VOD), Tencent Cloud Object Storage (COS), and AWS S3 Storage.
VOD: Requires support for specifying the VOD application and the storage period of recording files in VOD, and binding VOD task flows.
COS & AWS: Requires completion of configuration for the corresponding bucket. Ensure you have the write permission to the bucket. |
Callback address and callback key | The latest on-cloud recording service offers detailed recording event features. You can configure a server-side URL to receive recording callback events, and can also configure a callback key to verify the security of callback events. More information available here. |
CreateCloudRecording
from your server to start on-cloud recording. Pay attention to the following parameters:ha<1/2/3>
to the names of recovered files. The numbers indicate the times (max 3) the high availability scheme is used.main
) or substream (aux
) is recorded.
<Type>: The type of stream that is recorded (audio
or video
).
<UTC>: The recording start time (UTC+0), which consists of the year, month, day, hours, minutes, seconds, and milliseconds.
<Index>: The index of a segment, which starts from 1. This field is used only if an MP4 file exceeds 2 GB or 24 hours and needs to be segmented.
ha<1/2/3>: The 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
.DescribeCloudRecording
API. The response parameter BeginTimeStamp
indicates the recording start time (ms).DescribeCloudRecording
API, in which BeginTimeStamp
is 1622186279144
.{"Response": {"Status": "xx","StorageFileList": [{"TrackType": "xx","BeginTimeStamp": 1622186279144,"UserId": "xx","FileName": "xx"}],"RequestId": "xx","TaskId": "xx"}}
#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.0741400123456_12345__UserId_s_MTY4NjExOQ..__UserId_e_main_video_20330531094551825.ts#EXTINF:11.9011400123456_12345__UserId_s_MTY4NjExOQ..__UserId_e_main_video_20330531094603825.ts#EXTINF:12.0761400123456_12345__UserId_s_MTY4NjExOQ..__UserId_e_main_video_20330531094615764.ts#EXT-X-ENDLIST
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}}}
Field | Description |
Top | The vertical offset of the watermark to the top left corner of the video. |
Left | The horizontal offset of the watermark to the top left corner of the video. |
Width | The watermark width. |
Height | The watermark height. |
url | The URL of the watermark file. |
MixLayoutList
to customize a layout for anchor videos.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.ModifyCloudRecording
API to modify recording parameters, including SubscribeStreamUserIds
and MixLayoutParams
(valid only for mixed-stream recording). Note that you need to specify all the parameters, including MixLayoutParams
and SubscribeStreamUserIds
, and not just the ones you want to modify. We recommend you note all the parameter values before a modification, or you will need to calculate them again.DeleteCloudRecording
API to stop recording. A recording task will also end automatically if there are no anchors (whether they are publishing data or not) in a room for longer than the specified time period (MaxIdleTime
). We recommend you call the API to stop recording when you no longer need the service.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 the COS bucket where it is saved, 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.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:CloudVod
and CloudStorage
are mutually exclusive. If you specify both, the recording task will fail to start.DescribeCloudRecording
to query a recording to VOD task, the StorageFile
returned will be empty.
The figure below shows the workflow of recording to VOD. "Internal cloud storage" refers to the internal storage of the recording backend.
-m 0
)
In this mode, the recording files of each user (UserId
) are merged by section. One MP4 file is generated for each section.-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.sortedcontainers: pip3 install sortedcontainers
python3 TRTC_Merge.py [option]
.
2. An MP4 file will be generated in the directory of the recording files.
Example: python3 TRTC_Merge.py -f /xxx/file -m 0Parameter | Description |
-f | The directory of the recording files to be merged. If there are multiple users ( UserId ), their recording files will be merged separately. |
-m | 0 : Section-based merge (default). In this mode, the recording files of each user (UserId ) are merged by section. Multiple 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 file. |
-s | Whether to delete the blanks between sections in the user-based merge mode. If they are deleted, 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 | The 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 | The resolution of the output video. For example, -r 640 360 indicates that the resolution of the output video is 640 x 360. |
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.JSON:
{"code":0}`` to the response.Field | Description |
Content-Type | application/json |
Sign | The signature. |
SdkAppId | The application ID. |
Field | Type | Description |
EventGroupId | Number | The event group ID, which is 3 for on-cloud recording. |
EventType | Number | The event type. |
CallbackTs | Number | The Unix timestamp (ms) when the callback was sent to your server. |
EventInfo | JSON Object | The event information. |
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 files are uploaded. |
EVENT_TYPE_CLOUD_RECORDING_FAILOVER | 306 | On-cloud recording - The recording task was migrated. |
EVENT_TYPE_CLOUD_RECORDING_FILE_SLICE | 307 | On-cloud recording - An M3U8 file was generated (the first TS segment 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 when downloading the image decoding file. |
EVENT_TYPE_CLOUD_RECORDING_MP4_STOP | 310 | On-cloud recording - An MP4 recording task is finished. The callback includes the name and other details of the MP4 file generated. |
EVENT_TYPE_CLOUD_RECORDING_VOD_COMMIT | 311 | On-cloud recording - The recording files were uploaded to VOD. |
EVENT_TYPE_CLOUD_RECORDING_VOD_STOP | 312 | On-cloud recording - A recording to VOD task is finished. |
Field | Type | Description |
RoomId | String/Number | The room ID, which must be the same data type as the room ID on the client. |
EventTs | Number | The Unix timestamp (seconds) when the event occurred. |
UserId | String | The user ID of the recording robot. |
TaskId | String | The ID of a recording task. |
Payload | JsonObject | This parameter is defined differently for different event types. |
301
(EVENT_TYPE_CLOUD_RECORDING_RECORDER_START):Field | Type | Description |
Status | Number | 0 : The recording module was started successfully. 1 : Failed to start the recording module. |
{"EventGroupId": 3,"EventType": 301,"CallbackTs": 1622186275913,"EventInfo": {"RoomId": "xx","EventTs": "1622186275","UserId": "xx","TaskId": "xx","Payload": {"Status": 0}}}
302
(EVENT_TYPE_CLOUD_RECORDING_RECORDER_STOP):Field | Type | Description |
LeaveCode | Number | 0 : An API was called to stop the recording module.1 : The recording robot was removed from the room.2 : You closed the room.3 : The server removed the recording robot from the room.4 : The server closed the room.99 : There were no anchors in the room, and the recording robot left after the specified time period elapsed.100 : The room timed out.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}}}
303
(EVENT_TYPE_CLOUD_RECORDING_UPLOAD_START):Field | Type | Description |
Status | Number | 0 : The upload module was started successfully.1 : Failed to start the upload module. |
{"EventGroupId": 3,"EventType": 303,"CallbackTs": 1622191965320,"EventInfo": {"RoomId": "20015","EventTs": 1622191965,"UserId": "xx","TaskId": "xx","Payload": {"Status": 0}}}
304
(EVENT_TYPE_CLOUD_RECORDING_FILE_INFO):Field | Type | Description |
FileList | String | The 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"}}}
305
(EVENT_TYPE_CLOUD_RECORDING_UPLOAD_STOP):Field | Type | Description |
Status | Number | 0 : The recording task is finished and all the files were uploaded to the specified cloud storage service.1 : The recording task is finished, but at least one file is still on the server or in backup storage.2 : The files on the server or in backup storage were uploaded to the specified cloud storage service. |
{"EventGroupId": 3,"EventType": 305,"CallbackTs": 1622191989674,"EventInfo": {"RoomId": "20015","EventTs": 1622191989,"UserId": "xx","TaskId": "xx","Payload": {"Status": 0}}}
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}}}
307
(EVENT_TYPE_CLOUD_RECORDING_FILE_SLICE):Field | Type | Description |
FileName | String | The name of the M3U8 file. |
UserId | String | The ID of the user whose streams were recorded. |
TrackType | String | Valid values: audio , video , audio_video . |
BeginTimeStamp | Number | The Unix timestamp (milliseconds) 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}}}
308
(EVENT_TYPE_CLOUD_RECORDING_UPLOAD_ERROR):Field | Type | Description |
Code | String | The error code returned by the cloud storage service. |
Message | String | The error message returned by the 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"}}}
309
(EVENT_TYPE_CLOUD_RECORDING_DOWNLOAD_IMAGE_ERROR):Field | Type | Description |
Url | String | The download URL. |
{"EventGroupId": 3,"EventType": 309,"CallbackTs": 1622191989674,"EventInfo": {"RoomId": "20015","EventTs": 1622191989,"UserId": "xx","TaskId": "xx","Payload": {"Url": "http://xx",}}}
310
(EVENT_TYPE_CLOUD_RECORDING_MP4_STOP):Field | Type | Description |
Status | Number | 0 : The MP4 recording task is finished and all the files were uploaded to the specified cloud storage service.1 : The MP4 recording task is finished, but at least one file is still on the server or in backup storage.2 : The MP4 recording task stopped due to an error (probably because the system failed to download the HLS files from COS). |
FileList | Array | The names of the MP4 files generated. |
FileMessage | Array | The information of the MP4 files generated. |
FileName | String | The filename. |
UserId | String | The user ID. In the mixed-stream recording mode, this field is empty. |
TrackType | String | Valid values: audio , video , audio_video . |
MediaId | String | Valid values: main , aux . |
StartTimeStamp | Number | The Unix timestamp (milliseconds) when the MP4 file started. |
EndTimeStamp | Number | The Unix timestamp (milliseconds) when the MP4 file ended. |
{"EventGroupId": 3,"EventType": 310,"CallbackTs": 1622191989674,"EventInfo": {"RoomId": "20015","EventTs": 1622191989,"UserId": "xx","TaskId": "xx","Payload": {"Status": 0,"FileList": ["xxxx1.mp4", "xxxx2.mp4"],"FileMessage": [{"FileName": "xxxx1.mp4","UserId": "xxxx","TrackType": "audio_video","MediaId": "main","StartTimeStamp": 1622186279145,"EndTimeStamp": 1622186282145},{"FileName": "xxxx2.mp4","UserId": "xxxx","TrackType": "audio_video","MediaId": "main","StartTimeStamp": 1622186279153,"EndTimeStamp": 1622186282153}]}}}
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 is still on the server or in backup storage.2 : An error occurred when uploading the recording file to VOD. |
UserId | String | The user ID. 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 | The ID of the recording file in VOD. |
VideoUrl | String | The playback URL of the recording file in VOD. |
CacheFile | String | The name of the MP4 file before it was uploaded to VOD. |
Errmsg | String | The error message. This field is not empty if status is not 0 . |
{"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"}}}}
{"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"}}}}
312
(EVENT_TYPE_CLOUD_RECORDING_VOD_STOP):Field | Type | Description |
Status | Number | 0 : The recording to VOD task ended normally.1 : The recording to VOD task ended due to an error. |
{"EventGroupId": 3,"EventType": 312,"CallbackTs": 1622191965320,"EventInfo": {"RoomId": "20015","EventTs": 1622191965,"UserId": "xx","TaskId": "xx","Payload": {"Status": 0}}}
CreateCloudRecording
. If your request fails, fix the problem according to the status code and try again.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.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 joined by users 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.DescribeCloudRecording
15 seconds after a CreateCloudRecording
request succeeds. If the task status 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.CreateCloudRecording
request succeeds, if there are anchors publishing data in the room, you can splice the names of the recording files according to the naming rules.CreateCloudRecording
API. After a recording task ends, you can find the recording files in the COS bucket you specify.UserSig
is 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 a disconnection because the UserSig
has expired.
Was this page helpful?