tencent cloud

PrevNext

Feedback

search by keyword

Recent Pages

Documentation
Documentation

CreateCloudRecording

Last updated: 2024-03-11 11:06:32

    1. API Description

    Domain name for API request: trtc.tencentcloudapi.com.

    API description:
    This API is used to start an on-cloud recording task. It records the audio and video streams in a room and saves them to the specified cloud storage. You can use this API to record the streams in a room separately, or you can mix the streams first and then record the mixed stream.

    You can use this API to perform the following operations:

    • Specify the anchors whose streams you want or do not want to record by using the RecordParams parameter
    • Specify the storage service you want to save recording files to by using the StorageParams parameter. Currently, you can save recording files to Tencent Cloud VOD or COS.
    • Specify transcoding settings for mixed-stream recording, including video resolution, video bitrate, frame rate, and audio quality, by using MixTranscodeParams
    • Specify the layout of different videos in mixed-stream recording mode or select an auto-arranged layout template

    Key concepts:

    • Single-stream recording: Record the audio and video of each subscribed user (UserId) in a room and save the recording files to the storage you specify.
      Mixed-stream recording: Mix the audios and videos of subscribed users (UserId) in a room, record the mixed stream, and save the recording files to the storage you specify. After a recording task ends, you can go to the VOD console (https://console.tencentcloud.com/vod/media) or COS console to view the recording files.

    A maximum of 20 requests can be initiated per second for this API.

    We recommend you to use API Explorer
    Try it
    API Explorer provides a range of capabilities, including online call, signature authentication, SDK code generation, and API quick search. It enables you to view the request, response, and auto-generated examples.

    2. Input Parameters

    The following request parameter list only provides API request parameters and some common parameters. For the complete common parameter list, see Common Request Parameters.

    Parameter Name Required Type Description
    Action Yes String Common Params. The value used for this API: CreateCloudRecording.
    Version Yes String Common Params. The value used for this API: 2019-07-22.
    Region Yes String Common Params. For more information, please see the list of regions supported by the product. This API only supports: ap-beijing, ap-guangzhou, ap-mumbai, ap-shanghai, ap-singapore.
    SdkAppId Yes Integer The SDKAppID of the TRTC room whose streams are recorded.
    RoomId Yes String The room ID of the TRTC room whose streams are recorded.
    UserId Yes String The user ID of the recording robot in the TRTC room, which cannot be identical to the user IDs of anchors in the room or other recording robots. To distinguish this user ID from others, we recommend you include the room ID in the user ID.
    UserSig Yes String The signature (similar to a login password) required for the recording robot to enter the room. Each user ID corresponds to a signature. For information on how to calculate the signature, see What is UserSig?.
    RecordParams Yes RecordParams The on-cloud recording parameters.
    StorageParams Yes StorageParams The storage information of the recording file. Currently, you can save recording files to Tencent Cloud VOD or COS.
    RoomIdType No Integer The type of the TRTC room ID, which must be the same as the ID type of the room whose streams are recorded.
    0: String
    1: 32-bit integer (default)
    MixTranscodeParams No MixTranscodeParams The stream mixing parameters, which are valid if the mixed-stream recording mode is used.
    MixLayoutParams No MixLayoutParams The layout parameters, which are valid if the mixed-stream recording mode is used.
    ResourceExpiredHour No Integer The amount of time (in hours) during which API requests can be made after recording starts. Calculation starts when a recording task is started (when the recording task ID is returned). Once the period elapses, the query, modification, and stop recording APIs can no longer be called, but the recording task will continue. The default value is 72 (three days), and the maximum and minimum values allowed are 720 (30 days) and 6 respectively. If you do not set this parameter, the query, modification, and stop recording APIs can be called within 72 hours after recording starts.
    PrivateMapKey No String The permission ticket for a TRTC room. This parameter is required if advanced permission control is enabled in the console, in which case the TRTC backend will verify users’ PrivateMapKey, which include an encrypted room ID and permission bit list. A user providing only UserSig and not PrivateMapKey will be unable to enter the room.

    3. Output Parameters

    Parameter Name Type Description
    TaskId String The task ID assigned by the recording service, which uniquely identifies a recording process and becomes invalid after a recording task ends. After a recording task starts, if you want to perform other actions on the task, you need to specify the task ID when making API requests.
    RequestId String The unique request ID, generated by the server, will be returned for every request (if the request fails to reach the server for other reasons, the request will not obtain a RequestId). RequestId is required for locating a problem.

    4. Example

    Example1 Starting an on-cloud recording task

    This example shows you how to start on-cloud recording in room 3560 under the application whose SDKAppID is 1234.

    The timeout period for recording is one minute.
    The recording mode is mixed-stream recording.
    The type of the streams recorded are audio and video.
    The streams of all anchors in the room are subscribed.
    The resolution of the recorded video is 360 x 640, the frame rate is 15 fps, and the bitrate is 500,000 bps. The default background color is used.
    The grid layout template is used.
    The recording file is saved to Tencent Cloud VOD.

    Input Example

    POST / HTTP/1.1
Host: trtc.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateCloudRecording
<Common request parameters>

{
    "StorageParams": {
        "CloudVod": {
            "TencentVod": {
                "ExpireTime": 0
            }
        }
    },
    "UserSig": "11xx111",
    "UserId": "10001",
    "RecordParams": {
        "MaxIdleTime": 60,
        "StreamType": 0,
        "RecordMode": 2
    },
    "RoomIdType": 1,
    "MixTranscodeParams": {
        "VideoParams": {
            "Width": 360,
            "BitRate": 500000,
            "Fps": 15,
            "Height": 640,
            "Gop": 10
        }
    },
    "MixLayoutParams": {
        "MixLayoutMode": 3
    },
    "SdkAppId": 1234,
    "RoomId": "3560"
}

    Output Example

    {
    "Response": {
        "TaskId": "-gCTFWtU7t7DUlo7A8IswFszO9z2O-rbERqJAoK-4pycoZXKjIAAnasdcasdOEycyX4CnzhIm4RAQ..",
        "RequestId": "71993312-6ab8-4768-9124-118e0a20c45f"
    }
}

    5. Developer Resources

    SDK

    TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call APIs.

    Command Line Interface

    6. Error Code

    The following only lists the error codes related to the API business logic. For other error codes, see Common Error Codes.

    Error Code Description
    AuthFailure CAM signature/authentication error.
    AuthFailure.UnRealNameAuthenticated Identity verification has not been completed, so this operation is not allowed.
    AuthFailure.UnauthorizedOperation CAM authentication failed.
    AuthFailure.UnsupportedOperation Unsupported operation.
    FailedOperation Operation failed.
    FailedOperation.CRUnsupportMethod Unsupported on-cloud recording method.
    FailedOperation.RestrictedConcurrency Maximum number of concurrent on-cloud recording tasks reached. Contact us to raise the limit.
    InternalError.CRInternalError On-cloud recording internal error.
    InvalidParameter.OutOfRange Parameter value is out of range.
    InvalidParameter.SdkAppId SdkAppId is incorrect.
    MissingParameter.AccessKey AccessKey parameter missing.
    MissingParameter.Bucket Bucket parameter missing.
    MissingParameter.CloudStorage CloudStorage parameter missing.
    MissingParameter.RecordMode RecordMode parameter missing.
    MissingParameter.RecordParams RecordParams parameter missing.
    MissingParameter.Region Region parameter missing.
    MissingParameter.RoomId RoomId is missing.
    MissingParameter.SdkAppId SdkAppId is missing.
    MissingParameter.SecretKey SecretKey parameter missing.
    MissingParameter.StorageParams StorageParams parameter missing.
    MissingParameter.StreamType StreamType parameter missing.
    MissingParameter.TaskId TaskId parameter missing.
    MissingParameter.UserId Missing UserId parameter.
    MissingParameter.UserSig UserSig parameter missing.
    MissingParameter.Vendor Vendor parameter missing.
    UnsupportedOperation Unsupported operation.
    Copyright © 2013-2024 Tencent Cloud. All Rights Reserved.
    Privacy PolicyLegalCookie Policy