Skip to main content

Cloud Recording RESTful API

Agora Cloud Recording is a component provided by Agora to record and save voice calls, video calls, and interactive streaming. You can send HTTP requests from your business server to the Agora server to manage Cloud Recording tasks on the server side.

To monitor the status of your cloud recording, Agora provides the message notification service. After enabling this service, you receive events related to cloud recording through a webhook.

Since Agora dynamically adjusts the IP addresses of the message notification server, best practice is to regularly query the IP addresses and update the firewall whitelist configuration to continue receiving cloud recording notifications.

Base URL

https://api.sd-rtn.com

Authentication

When sending an HTTP request, use Basic HTTP authentication and fill in the Authorization field in the HTTP request header with the generated credentials. For details on generating the Authorization field, see Authenticate REST calls.

Endpoints

The RESTful API includes the following set of endpoints for managing the cloud recording functionality:

  • acquire: Request a resource ID for cloud recording.
  • start: Call this method within two seconds after getting the resource ID to start cloud recording. During recording, call query, update, and updateLayout methods as needed.
  • query: Check the status of cloud recording.
  • update: Update recording settings.
  • updateLayout: Update the video mixing layout.
  • stop: To end a recording, call stop to leave the channel and stop the recording.

acquire

Get a cloud recording resource ID.

POST /v1/apps/{appid}/cloud_recording/acquire

Before starting cloud recording, call the acquire method to get a resource ID. One resource ID can be used for only one recording session.

Note: To ensure success when starting cloud recording, proceed as follows:

  • Call acquire and start requests in pairs.
  • start cloud recording within two seconds of receiving the resource ID from each acquire request. Batch fetching of resource IDs followed by batch start requests may lead to request failure.
  • The resource ID is valid for five minutes and should be used as soon as possible.

Request body


_8
{
_8
"cname": "httpClient463224",
_8
"uid": "527841",
_8
"clientRequest": {
_8
"scene": 0,
_8
"resourceExpiredHour": 24
_8
}
_8
}

Parameters

NameInTypeRequiredDescription
Content-TypeheaderStringfalseapplication/json.
appidpathStringtrueThe App ID for your project.
  • For web page recording mode, simply enter the App ID for which the cloud recording service is enabled.
  • For individual and composite recording modes, use the same App ID as for the channel to be recorded. Ensure that the cloud recording service has been enabled for this App ID.
  • bodybodyJSON Objecttrueacquire-request

    200 Response


    _5
    {
    _5
    "cname": "string",
    _5
    "uid": "string",
    _5
    "resourceId": "string"
    _5
    }

    Response

    statusDescriptionSchema
    200 OKIf the returned HTTP status code is 200, the request is successful. If you set the startParameter object in the request body and its value is invalid, it will not affect the success of the acquire request, but you will receive an error in the subsequent start request.acquire-response
    Not 200If the HTTP status code is not 200, see the response status code for troubleshooting.Response status code

    start

    Start cloud recording.

    POST /v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/mode/{mode}/start

    After receiving a cloud recording resource ID using the acquire method, call the start method to start cloud recording.

    info

    After calling start, best practice is to check that the recording service has started successfully.

    Request body


    _38
    {
    _38
    "cname": "httpClient463224",
    _38
    "uid": "527841",
    _38
    "clientRequest": {
    _38
    "recordingConfig": {
    _38
    "channelType": 1,
    _38
    "streamTypes": 2,
    _38
    "streamMode": "default",
    _38
    "videoStreamType": 0,
    _38
    "maxIdleTime": 30,
    _38
    "subscribeAudioUids": [
    _38
    "123",
    _38
    "456"
    _38
    ],
    _38
    "subscribeVideoUids": [
    _38
    "123",
    _38
    "456"
    _38
    ],
    _38
    "subscribeUidGroup": 0
    _38
    },
    _38
    "recordingFileConfig": {
    _38
    "avFileType": [
    _38
    "hls"
    _38
    ]
    _38
    },
    _38
    "storageConfig": {
    _38
    "vendor": 2,
    _38
    "region": 3,
    _38
    "bucket": "xxxxx",
    _38
    "accessKey": "xxxxx",
    _38
    "secretKey": "xxxxx",
    _38
    "fileNamePrefix": [
    _38
    "directory1",
    _38
    "directory2"
    _38
    ]
    _38
    }
    _38
    }
    _38
    }

    Parameters

    NameInTypeRequiredDescription
    Content-TypeheaderStringfalseapplication/json.
    appidpathStringtrueThe App ID for your project.
  • For web page recording mode, simply enter the App ID for which the cloud recording service is enabled.
  • For individual and composite recording modes, use the same App ID as for the channel to be recorded. Ensure that the cloud recording service has been enabled for this App ID.
  • resourceIdpathStringtrueThe resource ID obtained using the acquire request.
    modepathStringtrueOne of the following recording modes:
  • individual: Individual recording mode.
  • mix: Composite recording mode.
  • web: Web page recording mode.
  • bodybodyJSON Objecttruestart-request

    200 Response


    _6
    {
    _6
    "cname": "string",
    _6
    "uid": "string",
    _6
    "resourceId": "string",
    _6
    "sid": "string"
    _6
    }

    Response

    statusDescriptionSchema
    200If the returned HTTP status code is 200, the request is successful. To check whether the recording service has started successfully, see the best practices to proceed.Response Schema
    Not 200If the HTTP status code is not 200, see the response status code for troubleshooting.Response status code

    Response Schema

    Status Code 200

    NameTypeRequiredDescription
    cnameStringfalseThe name of the channel to be recorded.
    uidStringfalseThe user ID used by the cloud recording service in the RTC channel to identify the recording service in the channel.
    resourceIdStringfalseThe cloud recording resource ID. The resource ID is valid for five minutes, after which you need to re-request it.
    sidStringfalseThe recording ID. After successfully starting cloud recording, you receive an sid (the recording ID). This ID uniquely identifies a recording cycle.

    update

    Update the cloud recording settings.

    POST /v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/sid/{sid}/mode/{mode}/update

    After starting the recording, call the update method to update the following recording configuration:

    • For individual and composite recordings, update the subscription list.
    • For web page recording, pause or resume the recording, or update the CDN streaming address (URL) where the web page recording is pushed to.
    info
    • The update request is only valid within a recording session. If the recording was started incorrectly, or if the recording has ended, the update call returns 404.

    • If you need to call the update method successively to update recording settings, repeat the call after receiving the previous update response to avoid unexpected results.

    Request body


    _20
    {
    _20
    "cname": "httpClient463224",
    _20
    "uid": "527841",
    _20
    "clientRequest": {
    _20
    "streamSubscribe": {
    _20
    "audioUidList": {
    _20
    "subscribeAudioUids": [
    _20
    "#allstream#"
    _20
    ]
    _20
    },
    _20
    "videoUidList": {
    _20
    "unSubscribeVideoUids": [
    _20
    "444",
    _20
    "555",
    _20
    "666"
    _20
    ]
    _20
    }
    _20
    }
    _20
    }
    _20
    }

    Parameters

    NameInTypeRequiredDescription
    Content-TypeheaderStringfalseapplication/json.
    appidpathStringtrueThe App ID for your project.
  • For web page recording mode, simply enter the App ID for which the cloud recording service is enabled.
  • For individual and composite recording modes, use the same App ID as for the channel to be recorded. Ensure that the cloud recording service has been enabled for this App ID.
  • resourceIdpathStringtrueThe resource ID obtained using the acquire request.
    sidpathStringtrueThe recording ID obtained through start.
    modepathStringtrueOne of the following recording modes:
  • individual: Individual recording mode.
  • mix: Composite recording mode.
  • web: Web page recording mode.
  • bodybodyJSON Objecttrueupdate-request

    200 Response


    _6
    {
    _6
    "cname": "string",
    _6
    "uid": "string",
    _6
    "resourceId": "string",
    _6
    "sid": "string"
    _6
    }

    Response

    statusDescriptionSchema
    200If the returned HTTP status code is 200, the request is successful.Response Schema
    Not 200If the HTTP status code is not 200, see the response status code for troubleshooting.Response status code

    Response Schema

    Status Code 200

    NameTypeRequiredDescription
    cnameStringfalseThe name of the channel to be recorded.
    uidStringfalseThe user ID used by the cloud recording service in the RTC channel to identify the recording service in the channel.
    resourceIdStringfalseThe resource ID used by cloud recording.
    sidStringfalseThe recording ID, identifying each recording cycle.

    updateLayout

    Update the mixing layout of cloud recording.

    POST /v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/sid/{sid}/mode/{mode}/updateLayout

    After starting composite recording, call this method to update the mixing layout.

    Each call to this method overrides the original layout settings. For example, if you set the backgroundColor field to "#FF0000" (red) when starting a recording and call the updateLayout method to update the mixing layout without setting the backgroundColor field again, the background color will change to black (the default value).

    info
    • The updateLayout request is only valid within a session. If the recording was started incorrectly, or if the recording has ended, the updateLayout call returns 404.

    • If you need to call the updateLayout method successively to update the recording settings, repeat the call after receiving the previous updateLayout response to avoid unexpected results.

    Request body


    _28
    {
    _28
    "cname": "httpClient463224",
    _28
    "uid": "527841",
    _28
    "clientRequest": {
    _28
    "mixedVideoLayout": 3,
    _28
    "backgroundColor": "#FF0000",
    _28
    "layoutConfig": [
    _28
    {
    _28
    "uid": "1",
    _28
    "x_axis": 0.1,
    _28
    "y_axis": 0.1,
    _28
    "width": 0.1,
    _28
    "height": 0.1,
    _28
    "alpha": 1,
    _28
    "render_mode": 1
    _28
    },
    _28
    {
    _28
    "uid": "2",
    _28
    "x_axis": 0.2,
    _28
    "y_axis": 0.2,
    _28
    "width": 0.1,
    _28
    "height": 0.1,
    _28
    "alpha": 1,
    _28
    "render_mode": 1
    _28
    }
    _28
    ]
    _28
    }
    _28
    }

    Parameters

    NameInTypeRequiredDescription
    Content-TypeheaderStringfalseapplication/json.
    appidpathStringtrueThe App ID for your project.
  • For web page recording mode, simply enter the App ID for which the cloud recording service is enabled.
  • For individual and composite recording modes, use the same App ID as for the channel to be recorded. Ensure that the cloud recording service has been enabled for this App ID.
  • resourceIdpathStringtrueThe resource ID obtained using the acquire request.
    sidpathStringtrueThe recording ID obtained through start.
    modepathStringtrueThe recording mode. Supports mix only, which means composite recording mode.
    bodybodyJSON ObjecttrueupdateLayout-request

    200 Response


    _6
    {
    _6
    "cname": "string",
    _6
    "uid": "string",
    _6
    "resourceId": "string",
    _6
    "sid": "string"
    _6
    }

    Response

    statusDescriptionSchema
    200If the returned HTTP status code is 200, the request is successful.Response Schema
    Not 200If the HTTP status code is not 200, see the response status code for troubleshooting.Response status code

    Response Schema

    Status Code 200

    NameTypeRequiredDescription
    cnameStringfalseThe name of the channel to be recorded.
    uidStringfalseThe user ID used by the cloud recording service in the RTC channel to identify the recording service in the channel.
    resourceIdStringfalseThe resource ID used by cloud recording.
    sidStringfalseThe recording ID, identifying a recording cycle.

    query

    Query the status of cloud recording.

    GET /v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/sid/{sid}/mode/{mode}/query

    After you start recording, call query to query the recording status.

    info

    The query request is only valid within a session. If the recording was started incorrectly, or if the recording has ended, the query call returns 404.

    Parameters

    NameInTypeRequiredDescription
    Content-TypeheaderStringfalseapplication/json.
    appidpathStringtrueThe App ID for your project.
  • For web page recording mode, simply enter the App ID for which the cloud recording service is enabled.
  • For individual and composite recording modes, use the same App ID as for the channel to be recorded. Ensure that the cloud recording service has been enabled for this App ID.
  • resourceIdpathStringtrueThe resource ID obtained using the acquire request.
    sidpathStringtrueThe recording ID obtained through start.
    modepathStringtrueOne of the following recording modes:
  • individual: Individual recording mode.
  • mix: Composite recording mode.
  • web: Web page recording mode.
  • 200 Response


    _24
    {
    _24
    "resourceId": "string",
    _24
    "sid": "string",
    _24
    "serverResponse": {
    _24
    "status": 0,
    _24
    "extensionServiceState": [
    _24
    {
    _24
    "payload": {
    _24
    "fileList": [
    _24
    {
    _24
    "filename": "string",
    _24
    "sliceStartTime": 0
    _24
    }
    _24
    ],
    _24
    "onhold": true,
    _24
    "state": "string"
    _24
    },
    _24
    "serviceName": "string"
    _24
    }
    _24
    ]
    _24
    },
    _24
    "cname": "string",
    _24
    "uid": "string"
    _24
    }

    Response

    statusDescriptionSchema
    200If the returned HTTP status code is 200, the request is successful.query-response
    Not 200If the HTTP status code is not 200, see the response status code for troubleshooting.Response status code

    stop

    Stop cloud recording.

    POST /v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/sid/{sid}/mode/{mode}/stop

    After starting recording, call the stop method to leave the channel and stop recording. To start recording again after the recording has stopped, call the acquire method again to request a new resource ID.

    info
    • The stop request is only valid within a session. If the recording is started incorrectly, or if the recording has ended, the stop call returns 404.

    • In non-web page recording mode, when the channel is idle (without users) for more than the predefined duration (default is 30 seconds), cloud recording automatically leaves the channel and stops recording.

    Request body


    _7
    {
    _7
    "cname": "httpClient463224",
    _7
    "uid": "527841",
    _7
    "clientRequest": {
    _7
    "async_stop": false
    _7
    }
    _7
    }

    Parameters

    NameInTypeRequiredDescription
    Content-TypeheaderStringfalseapplication/json.
    appidpathStringtrueThe App ID for your project.
  • For web page recording mode, simply enter the App ID for which the cloud recording service is enabled.
  • For individual and composite recording modes, use the same App ID as for the channel to be recorded. Ensure that the cloud recording service has been enabled for this App ID.
  • resourceIdpathStringtrueThe resource ID obtained using the acquire request.
    sidpathStringtrueThe recording ID obtained through start.
    modepathStringtrueOne of the following recording modes:
  • individual: Individual recording mode.
  • mix: Composite recording mode.
  • web: Web page recording mode.
  • bodybodyJSON Objecttruestop-request

    200 Response


    _16
    {
    _16
    "resourceId": "string",
    _16
    "sid": "string",
    _16
    "serverResponse": {
    _16
    "extensionServiceState": [
    _16
    {
    _16
    "playload": {
    _16
    "uploadingStatus": "string"
    _16
    },
    _16
    "serviceName": "string"
    _16
    }
    _16
    ]
    _16
    },
    _16
    "cname": "string",
    _16
    "uid": "string"
    _16
    }

    Response

    statusDescriptionSchema
    200If the returned HTTP status code is 200, the request is successful.stop-response
    Not 200If the HTTP status code is not 200, see the response status code for troubleshooting.Response status code

    get-ncs-ip

    Query the IP addresses of the message notification server.

    GET /v1/ncs/ip

    Query the IP address or IP address list of the message notification server.

    After you enable the message notification service, the Agora message notification service can notify your server of events that occur during a cloud recording with HTTPS requests. Agora dynamically adjusts the IP addresses of the message notification server every 24 hours. Query the IP addresses using this method. After the query, add the IP address (or IP address list) to the whitelist.

    info

    Best practice is to query the IP addresses at least once every 24 hours and automatically update the firewall configuration to avoid interruption in the reception of notifications.


    _14
    {
    _14
    "data": {
    _14
    "service": {
    _14
    "hosts": [
    _14
    {
    _14
    "primaryIP": "xxx.xxx.xxx.xxx"
    _14
    },
    _14
    {
    _14
    "primaryIP": "xxx.xxx.xxx.xxx"
    _14
    }
    _14
    ]
    _14
    }
    _14
    }
    _14
    }

    Response

    statusDescriptionSchema
    200If the returned HTTP status code is 200, the request is successful. You only need to pay attention to the PrimaryIP field in the response body, but not the response header or other fields in the response body.Response Schema

    Response Schema

    Status Code 200

    NameTypeRequiredDescription
    dataObjectfalseUnnecessary to know.
    » serviceObjectfalseUnnecessary to know.
    »» hostsArray[object]falseUnnecessary to know.
    »»» primaryIPStringfalseThe IP address of the Agora message notification server.

    Schemas

    acquire-request


    _130
    {
    _130
    "cname": "string",
    _130
    "uid": "string",
    _130
    "clientRequest": {
    _130
    "scene": 0,
    _130
    "resourceExpiredHour": 72,
    _130
    "startParameter": {
    _130
    "token": "string",
    _130
    "storageConfig": {
    _130
    "vendor": 0,
    _130
    "region": 0,
    _130
    "bucket": "string",
    _130
    "accessKey": "string",
    _130
    "secretKey": "string",
    _130
    "fileNamePrefix": [
    _130
    "string"
    _130
    ],
    _130
    "extensionParams": {
    _130
    "sse": "string",
    _130
    "tag": "string"
    _130
    }
    _130
    },
    _130
    "recordingConfig": {
    _130
    "channelType": 0,
    _130
    "decryptionMode": 0,
    _130
    "secret": "string",
    _130
    "salt": "string",
    _130
    "maxIdleTime": 30,
    _130
    "streamTypes": 2,
    _130
    "videoStreamType": 0,
    _130
    "subscribeAudioUids": [
    _130
    "string"
    _130
    ],
    _130
    "unsubscribeAudioUids": [
    _130
    "string"
    _130
    ],
    _130
    "subscribeVideoUids": [
    _130
    "string"
    _130
    ],
    _130
    "unsubscribeVideoUids": [
    _130
    "string"
    _130
    ],
    _130
    "subscribeUidGroup": 0,
    _130
    "streamMode": "default",
    _130
    "audioProfile": 0,
    _130
    "transcodingConfig": {
    _130
    "width": 360,
    _130
    "height": 640,
    _130
    "fps": 15,
    _130
    "bitrate": 500,
    _130
    "maxResolutionUid": "string",
    _130
    "mixedVideoLayout": 0,
    _130
    "backgroundColor": "#000000",
    _130
    "backgroundImage": "string",
    _130
    "defaultUserBackgroundImage": "string",
    _130
    "layoutConfig": [
    _130
    {
    _130
    "uid": "string",
    _130
    "x_axis": 1,
    _130
    "y_axis": 1,
    _130
    "width": 1,
    _130
    "height": 1,
    _130
    "alpha": 1,
    _130
    "render_mode": 0
    _130
    }
    _130
    ],
    _130
    "backgroundConfig": [
    _130
    {
    _130
    "uid": "string",
    _130
    "image_url": "string",
    _130
    "render_mode": 0
    _130
    }
    _130
    ]
    _130
    }
    _130
    },
    _130
    "recordingFileConfig": {
    _130
    "avFileType": [
    _130
    "hls"
    _130
    ]
    _130
    },
    _130
    "snapshotConfig": {
    _130
    "captureInterval": 10,
    _130
    "fileType": [
    _130
    "jpg"
    _130
    ]
    _130
    },
    _130
    "extensionServiceConfig": {
    _130
    "errorHandlePolicy": "error_abort",
    _130
    "extensionServices": [
    _130
    {
    _130
    "serviceName": "string",
    _130
    "errorHandlePolicy": "string",
    _130
    "serviceParam": {
    _130
    "url": "string",
    _130
    "audioProfile": 0,
    _130
    "videoWidth": 240,
    _130
    "videoHeight": 240,
    _130
    "maxRecordingHour": 1,
    _130
    "videoBitrate": 0,
    _130
    "videoFps": 15,
    _130
    "mobile": false,
    _130
    "maxVideoDuration": 120,
    _130
    "onhold": false,
    _130
    "readyTimeout": 0
    _130
    }
    _130
    }
    _130
    ]
    _130
    },
    _130
    "appsCollection": {
    _130
    "combinationPolicy": "default"
    _130
    },
    _130
    "transcodeOptions": {
    _130
    "transConfig": {
    _130
    "transMode": "string"
    _130
    },
    _130
    "container": {
    _130
    "format": "string"
    _130
    },
    _130
    "audio": {
    _130
    "sampleRate": "48000",
    _130
    "bitrate": "48000",
    _130
    "channels": "2"
    _130
    }
    _130
    }
    _130
    },
    _130
    "excludeResourceIds": [
    _130
    "string"
    _130
    ]
    _130
    }
    _130
    }

    Properties

    NameTypeRequiredDescription
    cnameStringtrueChannel name:
    - For individual recording and composite recording modes, this field is used to set the name of the channel to be recorded.
    - For web page recording mode, this field is used to differentiate the recording process. The string length cannot exceed 1024 bytes.
    Note: A unique recording instance can be located through appid, cname, and uid. Therefore, if you intend to record the same channel multiple times, use the same appId and cname, while differentiating them with different uids.
    uidStringtrueThe string contains the UID used by the cloud recording service within the channel to identify the recording service, for example, "527841". The string must meet the following conditions:
    - The value is in the range from 1 to (232-1), and cannot be set to 0.
    - It must not duplicate any UID within the current channel.
    - The field value within the quotation marks is an integer UID, and all users in the channel should use integer UIDs.
    clientRequestObjectfalseSee the following.
    » sceneNumberfalseUse cases for cloud recording resources:
    - 0: (default) Real-time audio and video recording.
    - 1: Web page recording.
    - 2: Individual recording mode, with postponed transcoding or audio mixing enabled.
    - Postponed transcoding: The recording service will transcode the recorded files into the MP4 format within 24 hours after the recording ends (in special cases, it may take more than 48 hours), and then upload the MP4 files to your third-party cloud storage. This scene is only applicable to the individual recording mode.
    - Postponed audio mixing: The recording service will merge and transcode the recorded files of all UIDs in the specified channel into a single MP3/M4A/AAC file within 24 hours after the recording ends (in special cases, it may take more than 48 hours), and then upload the file to your specified third-party cloud storage. This scene is only applicable to the individual audio non-transcoding recording mode.
    > - When scene is set to 2, you need to set the appsCollectionfield in the start method at the same time.
    > - In scenarios involving postponed transcoding and audio mixing, the recorded files are cached on the Agora edge servers for up to 24 hours. If your business is sensitive to information security and to ensure data compliance, please carefully consider whether to use postponed transcoding and audio mixing functions. Contact Agora technical support if you need assistance.
    » resourceExpiredHourNumberfalseThe validity period for calling the cloud recording RESTful API. Start calculating after you successfully initiate the cloud recording service and obtain the sid (Recording ID). The calculation unit is hours. The value range is [1,720]. The default value is 72.

    Note: After the timeout, you will not be able to call the query, update, updateLayout, and stop methods.
    » startParameterclient-requestfalseSetting this field can improve availability and optimize load balancing.

    Note: When populating the startParameter object, make sure the values are valid and consistent with the clientRequest object in the subsequent start request body; otherwise, the start request will receive an error response.
    » excludeResourceIdsArray[string]falseThe resourceId of another or several other recording tasks. This field is used to exclude specified recording resources so that newly initiated recording tasks can use resources from a new region, enabling cross-regional multi-stream recording. See Multi-channel task assurance.
    » regionStringfalseSpecify regions that the cloud recording service can access. By default, the cloud recording service accesses the region where the server you initiated the request is located. Once you specify the access region through region, the cloud recording service will not access servers outside the specified region. The region can be set to:
    - "CN": Mainland China
    - "AP": Asia excluding Mainland China
    - "EU": Europe
    - "NA": North America
    Note: When calling the start method, the region of the third-party cloud storage must be consistent with this field. In scenarios of postponed transcoding and audio mixing, Agora recommends not setting the region field. Otherwise, due to the data compliance risks arising from the dynamic adjustment of Agora edge servers and the caching of recording files in scenarios of postponed transcoding and audio mixing, the Agora recording service may fail to function properly.

    client-request


    _119
    {
    _119
    "token": "string",
    _119
    "storageConfig": {
    _119
    "vendor": 0,
    _119
    "region": 0,
    _119
    "bucket": "string",
    _119
    "accessKey": "string",
    _119
    "secretKey": "string",
    _119
    "fileNamePrefix": [
    _119
    "string"
    _119
    ],
    _119
    "extensionParams": {
    _119
    "sse": "string",
    _119
    "tag": "string"
    _119
    }
    _119
    },
    _119
    "recordingConfig": {
    _119
    "channelType": 0,
    _119
    "decryptionMode": 0,
    _119
    "secret": "string",
    _119
    "salt": "string",
    _119
    "maxIdleTime": 30,
    _119
    "streamTypes": 2,
    _119
    "videoStreamType": 0,
    _119
    "subscribeAudioUids": [
    _119
    "string"
    _119
    ],
    _119
    "unsubscribeAudioUids": [
    _119
    "string"
    _119
    ],
    _119
    "subscribeVideoUids": [
    _119
    "string"
    _119
    ],
    _119
    "unsubscribeVideoUids": [
    _119
    "string"
    _119
    ],
    _119
    "subscribeUidGroup": 0,
    _119
    "streamMode": "default",
    _119
    "audioProfile": 0,
    _119
    "transcodingConfig": {
    _119
    "width": 360,
    _119
    "height": 640,
    _119
    "fps": 15,
    _119
    "bitrate": 500,
    _119
    "maxResolutionUid": "string",
    _119
    "mixedVideoLayout": 0,
    _119
    "backgroundColor": "#000000",
    _119
    "backgroundImage": "string",
    _119
    "defaultUserBackgroundImage": "string",
    _119
    "layoutConfig": [
    _119
    {
    _119
    "uid": "string",
    _119
    "x_axis": 1,
    _119
    "y_axis": 1,
    _119
    "width": 1,
    _119
    "height": 1,
    _119
    "alpha": 1,
    _119
    "render_mode": 0
    _119
    }
    _119
    ],
    _119
    "backgroundConfig": [
    _119
    {
    _119
    "uid": "string",
    _119
    "image_url": "string",
    _119
    "render_mode": 0
    _119
    }
    _119
    ]
    _119
    }
    _119
    },
    _119
    "recordingFileConfig": {
    _119
    "avFileType": [
    _119
    "hls"
    _119
    ]
    _119
    },
    _119
    "snapshotConfig": {
    _119
    "captureInterval": 10,
    _119
    "fileType": [
    _119
    "jpg"
    _119
    ]
    _119
    },
    _119
    "extensionServiceConfig": {
    _119
    "errorHandlePolicy": "error_abort",
    _119
    "extensionServices": [
    _119
    {
    _119
    "serviceName": "string",
    _119
    "errorHandlePolicy": "string",
    _119
    "serviceParam": {
    _119
    "url": "string",
    _119
    "audioProfile": 0,
    _119
    "videoWidth": 240,
    _119
    "videoHeight": 240,
    _119
    "maxRecordingHour": 1,
    _119
    "videoBitrate": 0,
    _119
    "videoFps": 15,
    _119
    "mobile": false,
    _119
    "maxVideoDuration": 120,
    _119
    "onhold": false,
    _119
    "readyTimeout": 0
    _119
    }
    _119
    }
    _119
    ]
    _119
    },
    _119
    "appsCollection": {
    _119
    "combinationPolicy": "default"
    _119
    },
    _119
    "transcodeOptions": {
    _119
    "transConfig": {
    _119
    "transMode": "string"
    _119
    },
    _119
    "container": {
    _119
    "format": "string"
    _119
    },
    _119
    "audio": {
    _119
    "sampleRate": "48000",
    _119
    "bitrate": "48000",
    _119
    "channels": "2"
    _119
    }
    _119
    }
    _119
    }

    Properties

    NameTypeRequiredDescription
    tokenStringfalseA dynamic key used for authentication. If your project has enabled the App certificate, pass in the dynamic key of your project in this field. See Token Authentication for details.

    Note:
  • You only need to set the authentication token in individual recording and composite recording modes.

  • Cloud recording service does not support updating tokens currently. To ensure normal recording, ensure that the effective duration of the token is longer than your expected recording time, to avoid the token expiring and causing the recording task to exit the channel and end the recording.

  • storageConfigstorageConfigtrueConfiguration for third-party cloud storage.
    recordingConfigrecordingConfigfalseConfiguration for recorded audio and video streams.

    Note: You only need to set this field in individual recording and composite recording modes.
    recordingFileConfigrecordingFileConfigfalseConfiguration for recorded files.

    Note: This field cannot be set when only taking screenshots, but it needs to be set in all other cases. Other cases include the following:
  • Recording without transcoding, recording with transcoding, or recording and taking screenshots simultaneously in individual recording mode.

  • Composite recording.

  • In the web page recording mode, you can do page recording only, or simultaneously do the page recording and push it to the CDN.

  • snapshotConfigsnapshotConfigfalseConfigurations for screenshot capture.

    Note: Only need to set this field when using the screenshot function in individual recording mode.
    Screenshot usage instructions:
    - The screenshot function is only applicable to individual recording mode (individual).
    - You can either take screenshots in an individual recording process, or record and take screenshots at the same time. For more information, see Capture Screenshots. The scenario of simultaneous recording and screenshot capture requires setting the recordingFileConfig field.
    - If the recording service or recording upload service is abnormal, the screenshot will fail. Recording is not affected when there is a screenshot exception.
    - streamTypes must be set as 1 or 2 when capturing screenshots. If you have set subscribeAudioUid, you must also set subscribeVideoUids.
    extensionServiceConfigextensionServiceConfigfalseConfigurations for extended services.

    Note: Only need to set in web page recording mode.
    appsCollectionappsCollectionfalseApplication configurations

    Note: This setting is only required when in individual recording mode and when postponed transcoding or audio mixing is enabled.
    transcodeOptionstranscodeOptionsfalseConfigurations for the recorded files generated under postponed transcoding or audio mixing.

    Note: This setting is only required when in individual recording mode and when postponed transcoding or audio mixing is enabled.

    storageConfig


    _14
    {
    _14
    "vendor": 0,
    _14
    "region": 0,
    _14
    "bucket": "string",
    _14
    "accessKey": "string",
    _14
    "secretKey": "string",
    _14
    "fileNamePrefix": [
    _14
    "string"
    _14
    ],
    _14
    "extensionParams": {
    _14
    "sse": "string",
    _14
    "tag": "string"
    _14
    }
    _14
    }

    Configurations for third-party cloud storage.

    Properties

    NameTypeRequiredDescription
    vendorNumbertrueThird-party cloud storage platforms.
    - 1: Amazon S3
    - 2: Alibaba Cloud
    - 3: Tencent Cloud
    - 5: Microsoft Azure
    - 6: Google Cloud
    - 7: Huawei Cloud
    - 8: Baidu IntelligentCloud
    regionNumbertrueThe region information specified for the third-party cloud storage.

    Note: To ensure the success rate and real-time performance of the upload of the recording file, the region of the third-party cloud storage must be the same as the region of the application server where you initiate the request. For example: If the App server from which you initiate the request is in mainland China, and meanwhile the third-party cloud storage needs to be set to a region within mainland China. See Third-party Cloud Storage regions.
    bucketStringtrueThird-party cloud storage bucket. The bucket name needs to comply with the naming rules of the corresponding third-party cloud storage service.
    accessKeyStringtrueAccess Key for third-party cloud storage. If postponed transcoding is required, the Access Key must have read and write permissions; otherwise, it is recommended to only provide the write permission.
    secretKeyStringtrue(Required) The secret key of the third-party cloud storage.
    stsTokenStringfalseA temporary security token for third-party cloud storage. This token is issued by the cloud service provider's Security Token Service (STS) and used to grant limited access rights to third-party cloud storage resources.
    Note
    Currently supported cloud service providers include only the following: 1: Amazon S3, 2: Alibaba Cloud, 3: Tencent Cloud.
    stsExpirationNumberfalseThe stsToken expiration timestamp used to mark UNIX time, in seconds.
    Note
    • To avoid timestamp overflow, use Uint64 storage.
    • Set the longest possible validity period when applying the stsToken. The minimum validity period must be at least 4 hours. Call update to update the stsToken value before it expires.
    • If the recording task lasts for more than 1 hour, reapply the stsToken every 60 minutes and call update to update the relevant parameters in storageConfig
    fileNamePrefixArray[string]falseThe storage location of the recorded files in the third-party cloud is related to the prefix of the file name. If it is set to ["directory1","directory2"], then the prefix of the recording file name is "directory1/directory2/", that is, the recording file name is directory1/directory2/xxx.m3u8. The prefix's length, including the slashes, should not exceed 128 characters. The string itself should not contain symbols such as slash, underscore, or parenthesis. The following are the supported character set ranges:
    - 26 lowercase English letters: a-z
    - 26 uppercase English letters: A-Z
    - 10 numbers: 0-9
    extensionParamsextensionParamsfalseThird-party cloud storage services will encrypt and tag the uploaded recording files according to this field.

    extensionParams


    _4
    {
    _4
    "sse": "string",
    _4
    "tag": "string"
    _4
    }

    Third-party cloud storage services will encrypt and tag the uploaded recording files according to this field.

    Properties

    NameTypeRequiredDescription
    sseStringtrueThe encryption mode. After setting this field, the third-party cloud storage service will encrypt the uploaded recording files according to this encryption mode. This field is only applicable to Amazon S3, see the official Amazon S3 documentation.
    - kms: KMS encryption.
    - aes256: AES256 encryption.
    tagStringtrueTag content. After setting this field, the third-party cloud storage service will tag the uploaded recording files according to the content of this tag. This field is only applicable to Alibaba Cloud and Amazon S3. For details, see the Alibaba Cloud official documentation and the Amazon S3 official documentation.

    recordingConfig


    _53
    {
    _53
    "channelType": 0,
    _53
    "decryptionMode": 0,
    _53
    "secret": "string",
    _53
    "salt": "string",
    _53
    "maxIdleTime": 30,
    _53
    "streamTypes": 2,
    _53
    "videoStreamType": 0,
    _53
    "subscribeAudioUids": [
    _53
    "string"
    _53
    ],
    _53
    "unsubscribeAudioUids": [
    _53
    "string"
    _53
    ],
    _53
    "subscribeVideoUids": [
    _53
    "string"
    _53
    ],
    _53
    "unsubscribeVideoUids": [
    _53
    "string"
    _53
    ],
    _53
    "subscribeUidGroup": 0,
    _53
    "streamMode": "default",
    _53
    "audioProfile": 0,
    _53
    "transcodingConfig": {
    _53
    "width": 360,
    _53
    "height": 640,
    _53
    "fps": 15,
    _53
    "bitrate": 500,
    _53
    "maxResolutionUid": "string",
    _53
    "mixedVideoLayout": 0,
    _53
    "backgroundColor": "#000000",
    _53
    "backgroundImage": "string",
    _53
    "defaultUserBackgroundImage": "string",
    _53
    "layoutConfig": [
    _53
    {
    _53
    "uid": "string",
    _53
    "x_axis": 1,
    _53
    "y_axis": 1,
    _53
    "width": 1,
    _53
    "height": 1,
    _53
    "alpha": 1,
    _53
    "render_mode": 0
    _53
    }
    _53
    ],
    _53
    "backgroundConfig": [
    _53
    {
    _53
    "uid": "string",
    _53
    "image_url": "string",
    _53
    "render_mode": 0
    _53
    }
    _53
    ]
    _53
    }
    _53
    }

    Configurations for recorded audio and video streams.

    Note: You only need to set this field in individual recording and composite recording modes.

    Properties

    NameTypeRequiredDescription
    channelTypeNumbertrueThe channel profile.
    - 0: (Default) The communication scenario.
    - 1: Live streaming scene.
    The channel scene must be consistent with the Agora RTC SDK, otherwise it may cause issues.
    decryptionModeNumberfalseThe decryption mode. If you have set channel encryption in the SDK client, you need to set the same decryption mode for the cloud recording service.
    - 0: (Default) Not encrypted.
    - 1: AES_128_XTS encryption mode. 128-bit AES encryption, XTS mode.
    - 2: AES_128_ECB encryption mode. 128-bit AES encryption, ECB mode.
    - 3: AES_256_XTS encryption mode. 256-bit AES encryption, XTS mode.
    - 4: SM4_128_ECB encryption mode. 128-bit SM4 encryption, ECB mode.
    - 5: AES_128_GCM encryption mode. 128-bit AES encryption, GCM mode.
    - 6: AES_256_GCM encryption mode. 256-bit AES encryption, GCM mode.
    - 7: AES_128_GCM2 encryption mode. 128-bit AES encryption, GCM mode. Compared to AES_128_GCM encryption mode, AES_128_GCM2 encryption mode has higher security and requires setting a key and salt.
    - 8: AES_256_GCM2 encryption mode. 256-bit AES encryption, GCM mode. Compared to the AES_256_GCM encryption mode, the AES_256_GCM2 encryption mode is more secure and requires setting a key and salt.
    secretStringfalseKeys related to encryption and decryption. Only needs to be set when decryptionMode is not 0.
    saltStringfalseSalt related to encryption and decryption. Base64 encoding, 32-bit bytes. Only need to set when decryptionMode is 7 or 8.
    maxIdleTimeNumberfalseMaximum channel idle time. The unit is seconds. The value range is [5,259,200]. The default value is 30. The maximum value can not exceed 30 days. The recording service will automatically exit after exceeding the maximum channel idle time. After the recording service exits, if you initiate a start request again, a new recording file will be generated.

    Channel idle: There are no broadcasters in the live channel, or there are no users in the communication channel.
    streamTypesNumberfalseSubscribed media stream type.
    - 0: Subscribes to audio streams only. Suitable for smart voice review scenarios.
    - 1: Subscribes to video streams only.
    - 2: (Default) Subscribes to both audio and video streams.
    videoStreamTypeNumberfalseSets the stream type of the remote video. If you enable dual-stream mode in the SDK client, you can choose to subscribe to either the high-quality video stream or the low-quality video stream.
    - 0: High-quality video stream refers to high-resolution and high-bitrate video stream.
    - 1: Low-quality video stream refers to low-resolution and low-bitrate video stream.
    subscribeAudioUidsArray[string]falseSpecify which UIDs' audio streams to subscribe to. If you want to subscribe to the audio stream of all UIDs, no need to set this field. The array length should not exceed 32, and using an empty array is not recommended. Only one of the fields can be set: this field or unsubscribeAudioUids. For details, see Set up subscription lists.

    Note:
  • This field is only applicable when the streamTypes field is set to audio, or both audio and video.

  • If you have set up a subscription list for audio or video only, but not at the same time, then the cloud recording service will not subscribe to any video streams. If you set up a subscription list for video, but not for audio, then Agora Cloud Recording will not subscribe to any audio streams.

  • Set as ["#allstream#"] to subscribe to the audio streams of all UIDs in the channel.

  • unsubscribeAudioUidsArray[string]falseSpecify which UIDs' audio streams not to subscribe to. The cloud recording service will subscribe to the audio streams of all other UIDs except the specified ones. The array length should not exceed 32, and using an empty array is not recommended. Only one of the fields can be set: this field or subscribeAudioUids. For details, see Set up subscription lists.
    subscribeVideoUidsArray[string]falseSpecify which UID's video streams to subscribe to. If you want to subscribe to the video streams of all UIDs, no need to set this field. The array length should not exceed 32, and using an empty array is not recommended. Only one of the fields can be set: this field or unsubscribeVideoUids. For details, see Set up subscription lists.

    Note:
  • This field is only applicable when the streamTypes field is set to video, or both audio and video.

  • If you have set up a subscription list for audio or video only, but not at the same time, then the cloud recording service will not subscribe to any video streams. If you set up a subscription list for video, but not for audio, then Agora Cloud Recording will not subscribe to any audio streams.

  • Set as ["#allstream#"] to subscribe to the video streams of all UIDs in the channel.

  • unsubscribeVideoUidsArray[string]falseSpecify which UIDs' audio streams not to subscribe to. The cloud recording service will subscribe to the video streams of all UIDs except the specified ones. The array length should not exceed 32, and using an empty array is not recommended. Only one of the fields can be set: this field or subscribeVideoUids. For details, see Set up subscription lists.
    subscribeUidGroupNumberfalseEstimated peak number of subscribers.
    - 0: 1 to 2 UIDs.
    - 1:3 to 7 UIDs.
    - 2: 8 to 12 UIDs
    - 3: 13 to 17 UIDs
    - 4: 18 to 32 UIDs.
    - 5: 33 to 49 UIDs.
    Note:
    - Only need to be set in individual recordingmode, and it is required in this mode.
    - For example, if subscribeVideoUids is ["100","101","102"] and subscribeAudioUids is ["101","102","103"], the number of subscribers is 4.
    streamModeStringfalseOutput mode of media stream. See Media streaming output modes.
    - "default": Default mode. Recording with audio transcoding will separately generate an M3U8 audio index file and a video index file.
    - "standard": Standard mode. Agora recommends using this mode. Recording with audio transcoding will separately generate an M3U8 audio index file, a video index file, and a merged audio and video index file. If VP8 encoding is used on the Web client, a merged MPD audio-video index file will be generated.
    - "original": Original encoding mode. It is applicable to individual non-transcoding audio recording. This field only takes effect when subscribing to audio only (streamTypes is 0). During the recording process, the audio is not transcoded, and an M3U8 audio index file is generated.
    Note: Only need to set in individual recording mode.
    audioProfileNumberfalseSet the sampling rate, bitrate, encoding mode, and number of channels for the output audio.
    - 0: (Default) 48 kHz sampling rate, music encoding, mono audio channel, and the encoding bitrate is about 48 Kbps.
    1: 48 kHz sampling rate, music encoding, mono audio channel, and the encoding bitrate is approximately 128 Kbps.
    2: 48 kHz sampling rate, music encoding, stereo audio channel, and the encoding bitrate is approximately 192 Kbps.
    Note: Only need to set in the composite recording mode.
    transcodingConfigtranscodingConfigfalseConfigurations for transcoded video output The value can refer to Setting the Resolution of the Recorded Video Output.

    Note: Only need to set in the composite recording mode.

    transcodingConfig


    _29
    {
    _29
    "width": 360,
    _29
    "height": 640,
    _29
    "fps": 15,
    _29
    "bitrate": 500,
    _29
    "maxResolutionUid": "string",
    _29
    "mixedVideoLayout": 0,
    _29
    "backgroundColor": "#000000",
    _29
    "backgroundImage": "string",
    _29
    "defaultUserBackgroundImage": "string",
    _29
    "layoutConfig": [
    _29
    {
    _29
    "uid": "string",
    _29
    "x_axis": 1,
    _29
    "y_axis": 1,
    _29
    "width": 1,
    _29
    "height": 1,
    _29
    "alpha": 1,
    _29
    "render_mode": 0
    _29
    }
    _29
    ],
    _29
    "backgroundConfig": [
    _29
    {
    _29
    "uid": "string",
    _29
    "image_url": "string",
    _29
    "render_mode": 0
    _29
    }
    _29
    ]
    _29
    }

    Configurations for transcoded video output The value can refer to Setting the Resolution of the Recorded Video Output.

    Note: Only need to set in the composite recording mode.

    Properties

    NameTypeRequiredDescription
    widthNumberfalseThe width of the video (pixels). width × height cannot exceed 1920 × 1080. The default value is 360.
    heightNumberfalseThe height of the video (pixels). width × height cannot exceed 1920 × 1080. The default value is 640.
    fpsNumberfalseThe frame rate of the video (fps). The default value is 15.
    bitrateNumberfalseThe bitrate of the video (Kbps). The default value is 500.
    maxResolutionUidStringfalseOnly need to set it in vertical layout. Specify the user ID of the large video window. The string value should be an integer ranging from 1 to (232-1), and cannot be set to 0.
    mixedVideoLayoutNumberfalseComposite video layout:
    - 0: (Default) Floating layout. The first user to join the channel will be displayed as a large window, filling the entire canvas. The video windows of other users will be displayed as small windows, arranged horizontally from bottom to top, up to 4 rows, each with 4 windows. It supports up to a total of 17 windows of different users' videos.
    - 1: Adaptive layout. Automatically adjust the size of each user's video window according to the number of users, each user's video window size is consistent, and supports up to 17 windows.
    - 2: Vertical layout. The maxResolutionUid is specified to display the large video window on the left side of the screen, and the small video windows of other users are vertically arranged on the right side, with a maximum of two columns, 8 windows per column, supporting up to 17 windows.
    - 3: Customized layout. Set the layoutConfig field to customize the mixed layout.
    backgroundColorStringfalseThe background color of the video canvas. The RGB color table is supported, with strings formatted as a # sign and 6 hexadecimal digits. The default value is "#000000", representing the black color.
    backgroundImageStringfalseThe URL of the background image of the video canvas. The display mode of the background image is set to cropped mode.

    Cropped mode: Will prioritize to ensure that the screen is filled. The background image size is scaled in equal proportion until the entire screen is filled with the background image. If the length and width of the background image differ from the video window, the background image will be peripherally cropped to fill the window.
    defaultUserBackgroundImageStringfalseThe URL of the default user screen background image.

    After configuring this field, when any user stops sending the video streams for more than 3.5 seconds, the screen will switch to the background image; this setting will be overridden if the background image is set separately for a UID.
    layoutConfigArray[object]falselayoutConfig
    backgroundConfigbackgroundConfigfalseConfigurations of user's background image.

    layoutConfig


    _11
    [
    _11
    {
    _11
    "uid": "string",
    _11
    "x_axis": 1,
    _11
    "y_axis": 1,
    _11
    "width": 1,
    _11
    "height": 1,
    _11
    "alpha": 1,
    _11
    "render_mode": 0
    _11
    }
    _11
    ]

    The mixed video layout of users. An array of screen layout settings for each user, supporting up to 17 users.

    Note: Only need to set in custom layout.

    Properties

    NameTypeRequiredDescription
    uidStringfalseThe content of the string is the UID of the user to be displayed in the area, 32-bit unsigned integer.

    If the UID is not specified, the screen settings in layoutConfig will be matched automatically in the order that users join the channel.
    x_axisNumber(float)trueThe relative value of the horizontal coordinate of the upper-left corner of the screen, accurate to six decimal places. Layout from left to right, with 0.0 at the far left and 1.0 at the far right. This field can also be set to the integer 0 or 1. The value range is [0,1].
    y_axisNumber(float)trueThe relative value of the vertical coordinate of the upper-left corner of this screen in the screen, accurate to six decimal places. Layout from top to bottom, with 0.0 at the top and 1.0 at the bottom. This field can also be set to the integer 0 or 1. The value range is [0,1].
    widthNumber(float)trueThe relative value of the width of this screen, accurate to six decimal places. This field can also be set to the integer 0 or 1. The value range is [0,1].
    heightNumber(float)trueThe relative value of the height of this screen, accurate to six decimal places. This field can also be set to the integer 0 or 1. The value range is [0,1].
    alphaNumber(float)falseThe transparency of the user's video window. Accurate to six decimal places. 0.0 means the user's video window is transparent, and 1.0 indicates that it is completely opaque. The value range is [0,1]. The default value is 1.
    render_modeNumberfalseThe display mode of users' video windows:
    - 0: (Default) cropped mode. Prioritize to ensure the screen is filled. The video window size is proportionally scaled until it fills the screen. If the video's length and width differ from the video window, the video stream will be cropped from its edges to fit the window, under the aspect ratio set for the video window.
    - 1: Fit mode. Prioritize to ensure that all video content is displayed. The video size is scaled proportionally until one side of the video window is aligned with the screen border. If the video scale does not comply with the window size, the video will be scaled to fill the screen while maintaining its aspect ratio. This scaling may result in a black border around the edges of the video.

    backgroundConfig


    _7
    [
    _7
    {
    _7
    "uid": "string",
    _7
    "image_url": "string",
    _7
    "render_mode": 0
    _7
    }
    _7
    ]

    Configurations of user's background image.

    Properties

    NameTypeRequiredDescription
    uidStringtrueThe string content is the UID.
    image_urlStringtrueThe URL of the user's background image. After setting the background image, if the user stops sending the video stream for more than 3.5 seconds, the screen will switch to the background image.

    URL supports the HTTP and HTTPS protocols, and the image formats supported are JPG and BMP. The image size must not exceed 6 MB. The settings will only take effect after the recording service successfully downloads the image; if the download fails, the settings will not take effect. Different field settings may overlap each other. For specific rules, see Set the background color or background image.
    render_modeNumberfalseThe display mode of users' video windows:
    - 0: (Default) cropped mode. Prioritize to ensure the screen is filled. The video window size is proportionally scaled until it fills the screen. If the video's length and width differ from the video window, the video stream will be cropped from its edges to fit the window, under the aspect ratio set for the video window.
    - 1: Fit mode. Prioritize to ensure that all video content is displayed. The video size is scaled proportionally until one side of the video window is aligned with the screen border. If the video scale does not comply with the window size, the video will be scaled to fill the screen while maintaining its aspect ratio. This scaling may result in a black border around the edges of the video.

    recordingFileConfig


    _5
    {
    _5
    "avFileType": [
    _5
    "hls"
    _5
    ]
    _5
    }

    NameTypeRequiredDescription
    avFileTypeArray[string]falseType of video files generated by recording:
    - "hls": default value. M3U8 and TS files.
    - "mp4": MP4 files.
    Note:
    - In individual recording mode and not in screenshot-only case, you can use the default value.
    - In the composite recording and web page recording modes, if you need to generate MP4 files, set it to ["hls","mp4"]. Setting it as ["mp4"] will result in an error. After setting, the recording file behavior is as follows:
    - In the composite recording mode, the recording service will create a new MP4 file when the current recording duration exceeds about 2 hours or the file size roughly exceeds 2 GB.
    - Web page recording mode: The recording service will create a new MP4 file when the current file's duration exceeds maxVideoDuration.

    snapshotConfig


    _6
    {
    _6
    "captureInterval": 10,
    _6
    "fileType": [
    _6
    "jpg"
    _6
    ]
    _6
    }

    Properties

    NameTypeRequiredDescription
    captureIntervalNumberfalseThe cycle for regular screenshots in the cloud recording. The unit is seconds. The value range is [5,3600]. The default value is 10.
    fileTypeArray[string]trueThe file format of screenshots. Currently only ["jpg"] is supported, which generates screenshot files in JPG format.

    extensionServiceConfig


    _22
    {
    _22
    "errorHandlePolicy": "error_abort",
    _22
    "extensionServices": [
    _22
    {
    _22
    "serviceName": "string",
    _22
    "errorHandlePolicy": "string",
    _22
    "serviceParam": {
    _22
    "url": "string",
    _22
    "audioProfile": 0,
    _22
    "videoWidth": 240,
    _22
    "videoHeight": 240,
    _22
    "maxRecordingHour": 1,
    _22
    "videoBitrate": 0,
    _22
    "videoFps": 15,
    _22
    "mobile": false,
    _22
    "maxVideoDuration": 120,
    _22
    "onhold": false,
    _22
    "readyTimeout": 0
    _22
    }
    _22
    }
    _22
    ]
    _22
    }

    Configurations for extended services.

    Note: Only need to set in web page recording mode.

    Properties

    NameTypeRequiredDescription
    errorHandlePolicyStringfalseError handling policy. You can only set it to the default value, "error_abort", which means that once an error occurs to an extension service, all other non-extension services, such as stream subscription, also stop.
    extensionServicesArray[object]trueSee the following.
    » serviceNameStringtrueName of the extended service:
    - web_recorder_service: Represents the extended service is web page recording.
    - rtmp_publish_service: Represents the extended service is to push web page recording to the CDN.
    » errorHandlePolicyStringfalseError handling strategy within the extension service:
    - "error_abort": the default and only value during web page recording. Stop other extension services when the current extension service encounters an error.
    - "error_ignore": The only default value when you push the web page recording to the CDN. Other extension services are not affected when the current extension service encounters an error.

    If the web page recording service or the recording upload service is abnormal, pushing the stream to the CDN will fail. Therefore, errors in the web page recording service can affect the service of pushing page recording to the CDN.

    When an exception occurs during the process of pushing to the CDN, web page recording is not affected.
    » serviceParamserviceParamtrueSpecific configurations for extension services.

    serviceParam


    _13
    {
    _13
    "url": "string",
    _13
    "audioProfile": 0,
    _13
    "videoWidth": 240,
    _13
    "videoHeight": 240,
    _13
    "maxRecordingHour": 1,
    _13
    "videoBitrate": 0,
    _13
    "videoFps": 15,
    _13
    "mobile": false,
    _13
    "maxVideoDuration": 120,
    _13
    "onhold": false,
    _13
    "readyTimeout": 0
    _13
    }

    Properties

    Scenario 1

    Set the following fields for web page recording:

    NameTypeRequiredDescription
    urlStringtrueThe address of the page to be recorded.
    audioProfileNumbertrueSampling rate, bitrate, encoding mode, and number of channels for the audio output.
    0: 48 kHz sampling rate, music encoding, mono audio channel, and the encoding bitrate is approximately 48 Kbps.
    1: 48 kHz sampling rate, music encoding, mono audio channel, and the encoding bitrate is approximately 128 Kbps.
    2: 48 kHz sampling rate, music encoding, stereo audio channel, and the encoding bitrate is approximately 192 Kbps.
    videoWidthNumbertrueThe output video width (pixel). The product of videoWidth and videoHeight should be less than or equal to 1920 × 1080. For recommended values, see How can I set the page recording output resolution in mobile web page mode?.
    videoHeightNumbertrueThe height of the output video (pixel). The product of videoWidth and videoHeight should be less than or equal to 1920 × 1080. For recommended values, see How can I set the page recording output resolution in mobile web page mode.
    maxRecordingHourNumbertrueThe maximum duration of web page recording (hours). The web page recording will automatically stop after exceeding this value. The value range is [1,720].
    > The recommended value should not exceed the value you set in the acquire method for resourceExpiredHour.

    Billing related: The charge will continue until the web page recording stops, so you need to set a reasonable value according to the actual business situation or stop the page recording voluntarily.
    videoBitrateNumberfalseThe bitrate of the output video (Kbps). For different output video resolutions, the default value of videoBitrate is different:
    - Output video resolution is greater than or equal to 1280 × 720, and the default value is 2000.
    - Output video resolution is less than 1280 × 720, and the default value is 1500.
    videoFpsNumberfalseThe frame rate of the output video (fps). The value range is [5,60]. The default value is 15.
    mobileBooleanfalseWhether to enable the mobile web mode:
    - true: Enables the mode. After enabling, the recording service uses the mobile web rendering mode to record the current page.
    - false: (default) Disables the mode.
    maxVideoDurationNumberfalseMaximum length of MP4 slice file generated by web page recording, in minutes During the web page recording process, the recording service will create a new MP4 slice file when the current MP4 file duration exceeds the maxVideoDuration approximately. The value range is [30,240]. The default value is 120.
    onholdBooleanfalseWhether to pause page recording when starting a web page recording task.
    - true: Pauses the web page recording that has been started. Immediately pause the recording after starting the web page recording task. The recording service will open and render the page to be recorded, but will not generate slice files.
    - false: (Default) Starts a web page recording task and performs web page recording.
    We suggest using the onhold field according to the following process:
    1. Set onhold to true when calling the start method, which will start and pause the web page recording, and you need to determine the appropriate time to start the web page recording on your own.
    2. Call update and set onhold to false, continue with the web page recording. If you need to pause or resume the web page recording by continuously calling the update method, please make the call after receiving the response from the previous update, otherwise it may cause inconsistent results with your expectations.
    readyTimeoutNumberfalseSet the page load timeout in seconds. See Page Load Timeout Detection. The value range is [0,60]. The default value is 0.
    - Set to 0 or not set, which means the web page loading status is not detected.
    -An integer between [1,60], representing the page load timeout.

    Scenario 2

    Pushing web page recording to the CDN requires configuring the following fields.

    NameTypeRequiredDescription
    outputsArray[object]trueSee the following.
    » rtmpUrlStringtrueThe CDN address to which you push the stream.

    appsCollection


    _3
    {
    _3
    "combinationPolicy": "default"
    _3
    }

    Application configurations

    Note: This setting is only required when in individual recording mode and when postponed transcoding or audio mixing is enabled.

    Properties

    NameTypeRequiredDescription
    combinationPolicyStringfalseThe combination of cloud recording applications.
    - postpone_transcoding: Use this method if you need to postpone transcoding or audio mixing.
    - default: (Default) Use this method except for postponed transcoding and audio mixing.

    transcodeOptions


    _13
    {
    _13
    "transConfig": {
    _13
    "transMode": "string"
    _13
    },
    _13
    "container": {
    _13
    "format": "string"
    _13
    },
    _13
    "audio": {
    _13
    "sampleRate": "48000",
    _13
    "bitrate": "48000",
    _13
    "channels": "2"
    _13
    }
    _13
    }

    Configurations for the recorded files generated under postponed transcoding or audio mixing.

    Note: This setting is only required when in individual recording mode and when postponed transcoding or audio mixing is enabled.

    Properties

    NameTypeRequiredDescription
    transConfigObjecttrueSee the following.
    » transModeStringtrueMode:
    - "postponeTranscoding": Postponed transcoding.
    - "audioMix": Postponed audio mixing.
    containerObjectfalseSee the following.
    » formatStringfalseThe container format of the file, which supports the following values:
    - "mp4": the default format for the postponed transcoding. MP4 format.
    - "mp3": The default format for postponed audio mixing. MP3 format.
    - "m4a": M4A format.
    - "aac": AAC format.
    Note: Postponed transcoding can currently only be set to MP4 format.
    audioObjectfalseAudio properties of the file.

    Note: This setting is only required in individual recording mode with postponed audio mixing turned on.
    » sampleRateStringfalseAudio sampling rate (Hz) supports the following values:
    - "48000": (Default) 48 kHz.
    - "32000": 32 kHz.
    - "16000": 16 kHz.
    » bitrateStringfalseAudio bit rate (Kbps) supports a customized value and the default value is "48000".
    » channelsStringfalseThe number of audio channels supports the following values:
    - "1": Mono.
    - "2": (Default) Stereo.

    acquire-response


    _5
    {
    _5
    "cname": "string",
    _5
    "uid": "string",
    _5
    "resourceId": "string"
    _5
    }

    Properties

    NameTypeRequiredDescription
    cnameStringfalseThe name of the channel to be recorded.
    uidStringfalseThe user ID used by the cloud recording service in the RTC channel to identify the recording service in the channel.
    resourceIdStringfalseThe cloud recording resource ID. You can start a cloud recording with this resource ID. The resource ID is valid for five minutes, after which you need to re-request it.

    start-request


    _123
    {
    _123
    "cname": "string",
    _123
    "uid": "string",
    _123
    "clientRequest": {
    _123
    "token": "string",
    _123
    "storageConfig": {
    _123
    "vendor": 0,
    _123
    "region": 0,
    _123
    "bucket": "string",
    _123
    "accessKey": "string",
    _123
    "secretKey": "string",
    _123
    "fileNamePrefix": [
    _123
    "string"
    _123
    ],
    _123
    "extensionParams": {
    _123
    "sse": "string",
    _123
    "tag": "string"
    _123
    }
    _123
    },
    _123
    "recordingConfig": {
    _123
    "channelType": 0,
    _123
    "decryptionMode": 0,
    _123
    "secret": "string",
    _123
    "salt": "string",
    _123
    "maxIdleTime": 30,
    _123
    "streamTypes": 2,
    _123
    "videoStreamType": 0,
    _123
    "subscribeAudioUids": [
    _123
    "string"
    _123
    ],
    _123
    "unsubscribeAudioUids": [
    _123
    "string"
    _123
    ],
    _123
    "subscribeVideoUids": [
    _123
    "string"
    _123
    ],
    _123
    "unsubscribeVideoUids": [
    _123
    "string"
    _123
    ],
    _123
    "subscribeUidGroup": 0,
    _123
    "streamMode": "default",
    _123
    "audioProfile": 0,
    _123
    "transcodingConfig": {
    _123
    "width": 360,
    _123
    "height": 640,
    _123
    "fps": 15,
    _123
    "bitrate": 500,
    _123
    "maxResolutionUid": "string",
    _123
    "mixedVideoLayout": 0,
    _123
    "backgroundColor": "#000000",
    _123
    "backgroundImage": "string",
    _123
    "defaultUserBackgroundImage": "string",
    _123
    "layoutConfig": [
    _123
    {
    _123
    "uid": "string",
    _123
    "x_axis": 1,
    _123
    "y_axis": 1,
    _123
    "width": 1,
    _123
    "height": 1,
    _123
    "alpha": 1,
    _123
    "render_mode": 0
    _123
    }
    _123
    ],
    _123
    "backgroundConfig": [
    _123
    {
    _123
    "uid": "string",
    _123
    "image_url": "string",
    _123
    "render_mode": 0
    _123
    }
    _123
    ]
    _123
    }
    _123
    },
    _123
    "recordingFileConfig": {
    _123
    "avFileType": [
    _123
    "hls"
    _123
    ]
    _123
    },
    _123
    "snapshotConfig": {
    _123
    "captureInterval": 10,
    _123
    "fileType": [
    _123
    "jpg"
    _123
    ]
    _123
    },
    _123
    "extensionServiceConfig": {
    _123
    "errorHandlePolicy": "error_abort",
    _123
    "extensionServices": [
    _123
    {
    _123
    "serviceName": "string",
    _123
    "errorHandlePolicy": "string",
    _123
    "serviceParam": {
    _123
    "url": "string",
    _123
    "audioProfile": 0,
    _123
    "videoWidth": 240,
    _123
    "videoHeight": 240,
    _123
    "maxRecordingHour": 1,
    _123
    "videoBitrate": 0,
    _123
    "videoFps": 15,
    _123
    "mobile": false,
    _123
    "maxVideoDuration": 120,
    _123
    "onhold": false,
    _123
    "readyTimeout": 0
    _123
    }
    _123
    }
    _123
    ]
    _123
    },
    _123
    "appsCollection": {
    _123
    "combinationPolicy": "default"
    _123
    },
    _123
    "transcodeOptions": {
    _123
    "transConfig": {
    _123
    "transMode": "string"
    _123
    },
    _123
    "container": {
    _123
    "format": "string"
    _123
    },
    _123
    "audio": {
    _123
    "sampleRate": "48000",
    _123
    "bitrate": "48000",
    _123
    "channels": "2"
    _123
    }
    _123
    }
    _123
    }
    _123
    }

    Properties

    NameTypeRequiredDescription
    cnameStringtrueThe name of the channel where the recording service locates. The cname field you input in the acquire request needs to be the same.
    uidStringtrueThe string content is the UID used by the recording service in the RTC channel to identify the recording service. It needs to be the same as the uid field you input in the acquire request.
    clientRequestObjecttrueclient-request

    update-request


    _34
    {
    _34
    "cname": "string",
    _34
    "uid": "string",
    _34
    "clientRequest": {
    _34
    "streamSubscribe": {
    _34
    "audioUidList": {
    _34
    "subscribeAudioUids": [
    _34
    "string"
    _34
    ],
    _34
    "unsubscribeAudioUids": [
    _34
    "string"
    _34
    ]
    _34
    },
    _34
    "videoUidList": {
    _34
    "subscribeVideoUids": [
    _34
    "string"
    _34
    ],
    _34
    "unsunscribeVideoUids": [
    _34
    "string"
    _34
    ]
    _34
    }
    _34
    },
    _34
    "webRecordingConfig": {
    _34
    "onhold": false
    _34
    },
    _34
    "rtmpPublishConfig": {
    _34
    "outputs": [
    _34
    {
    _34
    "rtmpUrl": "string"
    _34
    }
    _34
    ]
    _34
    }
    _34
    }
    _34
    }

    Properties

    NameTypeRequiredDescription
    cnameStringtrueThe name of the channel where the recording service locates. The cname field you input in the acquire request needs to be the same.
    uidStringtrueThe string content is the UID used by the recording service in the RTC channel to identify the recording service. It needs to be the same as the uid field you input in the acquire request.
    clientRequestObjecttrueclientRequest

    clientRequest


    _30
    {
    _30
    "streamSubscribe": {
    _30
    "audioUidList": {
    _30
    "subscribeAudioUids": [
    _30
    "string"
    _30
    ],
    _30
    "unsubscribeAudioUids": [
    _30
    "string"
    _30
    ]
    _30
    },
    _30
    "videoUidList": {
    _30
    "subscribeVideoUids": [
    _30
    "string"
    _30
    ],
    _30
    "unsunscribeVideoUids": [
    _30
    "string"
    _30
    ]
    _30
    }
    _30
    },
    _30
    "webRecordingConfig": {
    _30
    "onhold": false
    _30
    },
    _30
    "rtmpPublishConfig": {
    _30
    "outputs": [
    _30
    {
    _30
    "rtmpUrl": "string"
    _30
    }
    _30
    ]
    _30
    }
    _30
    }

    Properties

    NameTypeRequiredDescription
    streamSubscribestreamSubscribefalseUpdate subscription lists.

    Note: You only need to set this field in individual recording and composite recording modes.
    webRecordingConfigwebRecordingConfigfalseUsed to update the web page recording configurations.

    Note: Only need to set in web page recording mode.
    rtmpPublishConfigrtmpPublishConfigfalseUsed to update the configurations for pushing web page recording to the CDN.

    Note: This should only be set when you push media stream to the CDN during aweb page recording.

    storageConfigstorageConfigtrueConfiguration for third-party cloud storage.

    streamSubscribe


    _18
    {
    _18
    "audioUidList": {
    _18
    "subscribeAudioUids": [
    _18
    "string"
    _18
    ],
    _18
    "unsubscribeAudioUids": [
    _18
    "string"
    _18
    ]
    _18
    },
    _18
    "videoUidList": {
    _18
    "subscribeVideoUids": [
    _18
    "string"
    _18
    ],
    _18
    "unsunscribeVideoUids": [
    _18
    "string"
    _18
    ]
    _18
    }
    _18
    }

    Update subscription lists.

    Note: You only need to set this field in individual recording and composite recording modes.

    Properties

    NameTypeRequiredDescription
    audioUidListaudioUidListfalseThe audio subscription list.

    Note: This field is only applicable when the streamTypes field is set to audio, or both audio and video.
    videoUidListvideoUidListfalseThe video subscription list.

    Note: This field only applies when the streamTypes field is set to video, or both audio and video.

    audioUidList


    _8
    {
    _8
    "subscribeAudioUids": [
    _8
    "string"
    _8
    ],
    _8
    "unsubscribeAudioUids": [
    _8
    "string"
    _8
    ]
    _8
    }

    The audio subscription list.

    Note: This field is only applicable when the streamTypes field is set to audio, or both audio and video.

    Properties

    NameTypeRequiredDescription
    subscribeAudioUidsArray[string]falseSpecify which UIDs' audio streams to subscribe to. If you want to subscribe to the audio stream of all UIDs, no need to set this field. The array length should not exceed 32, and using an empty array is not recommended. Only one of the fields can be set: this field or unsubscribeAudioUids. For details, see Set up subscription lists.

    Note:
  • This field is only applicable when the streamTypes field is set to audio, or both audio and video.

  • If you have set up a subscription list for audio or video only, but not at the same time, then the cloud recording service will not subscribe to any video streams. If you set up a subscription list for video, but not for audio, then Agora Cloud Recording will not subscribe to any audio streams.

  • Set as ["#allstream#"] to subscribe to the audio streams of all UIDs in the channel.

  • unsubscribeAudioUidsArray[string]falseSpecify which UIDs' audio streams not to subscribe to. The cloud recording service will subscribe to the audio streams of all other UIDs except the specified ones. The array length should not exceed 32, and using an empty array is not recommended. Only one of the fields can be set: this field or subscribeAudioUids. For details, see Set up subscription lists.

    videoUidList


    _8
    {
    _8
    "subscribeVideoUids": [
    _8
    "string"
    _8
    ],
    _8
    "unsunscribeVideoUids": [
    _8
    "string"
    _8
    ]
    _8
    }

    The video subscription list.

    Note: This field only applies when the streamTypes field is set to video, or both audio and video.

    Properties

    NameTypeRequiredDescription
    subscribeVideoUidsArray[string]falseSpecify which UID's video streams to subscribe to. If you want to subscribe to the video streams of all UIDs, no need to set this field. The array length should not exceed 32, and using an empty array is not recommended. Only one of the fields can be set: this field or unsubscribeVideoUids. For details, see Set up subscription lists.

    Note:
  • This field is only applicable when the streamTypes field is set to video, or both audio and video.

  • If you have set up a subscription list for audio or video only, but not at the same time, then the cloud recording service will not subscribe to any video streams. If you set up a subscription list for video, but not for audio, then Agora Cloud Recording will not subscribe to any audio streams.

  • Set as ["#allstream#"] to subscribe to the video streams of all UIDs in the channel.

  • unsubscribeVideoUidsArray[string]falseSpecify which UIDs' audio streams not to subscribe to. The cloud recording service will subscribe to the video streams of all UIDs except the specified ones. The array length should not exceed 32, and using an empty array is not recommended. Only one of the fields can be set: this field or subscribeVideoUids. For details, see Set up subscription lists.

    webRecordingConfig


    _3
    {
    _3
    "onhold": false
    _3
    }

    Used to update the web page recording configurations.

    Note: Only need to set in web page recording mode.

    Properties

    NameTypeRequiredDescription
    onholdBooleanfalseSet whether to pause the web page recording.
    - true: Pauses web page recording and generating recording files.
    - false: (Default) Continues web page recording and generates recording files.
    If you want to resume a paused web page recording, you can call the update method and set onhold to false.

    rtmpPublishConfig


    _7
    {
    _7
    "outputs": [
    _7
    {
    _7
    "rtmpUrl": "string"
    _7
    }
    _7
    ]
    _7
    }

    Used to update the configurations for pushing web page recording to the CDN.

    Note: This should only be set when you push media stream to the CDN during aweb page recording.

    Properties

    NameTypeRequiredDescription
    outputsArray[object]falseSee the following.
    » rtmpUrlStringfalseThe CDN URL where you push the stream to.

    Note:
  • URLs only support the RTMP and RTMPS protocols.

  • The maximum number of streams being pushed to the CDN is 1.

  • updateLayout-request


    _29
    {
    _29
    "cname": "string",
    _29
    "uid": "string",
    _29
    "clientRequest": {
    _29
    "maxResolutionUid": "string",
    _29
    "mixedVideoLayout": 0,
    _29
    "backgroundColor": "#000000",
    _29
    "backgroundImage": "string",
    _29
    "defaultUserBackgroundImage": "string",
    _29
    "layoutConfig": [
    _29
    {
    _29
    "uid": "string",
    _29
    "x_axis": 1,
    _29
    "y_axis": 1,
    _29
    "width": 1,
    _29
    "height": 1,
    _29
    "alpha": 1,
    _29
    "render_mode": 0
    _29
    }
    _29
    ],
    _29
    "backgroundConfig": [
    _29
    {
    _29
    "uid": "string",
    _29
    "image_url": "string",
    _29
    "render_mode": 0
    _29
    }
    _29
    ]
    _29
    }
    _29
    }

    Properties

    NameTypeRequiredDescription
    cnameStringtrueThe name of the channel where the recording service locates. The cname field you input in the acquire request needs to be the same.
    uidStringtrueThe string content is the UID used by the recording service in the RTC channel to identify the recording service. It needs to be the same as the uid field you input in the acquire request.
    clientRequestObjecttrueclientRequest-updateLayout

    clientRequest-updateLayout


    _25
    {
    _25
    "maxResolutionUid": "string",
    _25
    "mixedVideoLayout": 0,
    _25
    "backgroundColor": "#000000",
    _25
    "backgroundImage": "string",
    _25
    "defaultUserBackgroundImage": "string",
    _25
    "layoutConfig": [
    _25
    {
    _25
    "uid": "string",
    _25
    "x_axis": 1,
    _25
    "y_axis": 1,
    _25
    "width": 1,
    _25
    "height": 1,
    _25
    "alpha": 1,
    _25
    "render_mode": 0
    _25
    }
    _25
    ],
    _25
    "backgroundConfig": [
    _25
    {
    _25
    "uid": "string",
    _25
    "image_url": "string",
    _25
    "render_mode": 0
    _25
    }
    _25
    ]
    _25
    }

    Properties

    NameTypeRequiredDescription
    maxResolutionUidStringfalseOnly need to set it in vertical layout. Specify the user ID of the large video window. The string value should be an integer ranging from 1 to (232-1), and cannot be set to 0.
    mixedVideoLayoutNumberfalseComposite video layout:
    - 0: (Default) Floating layout. The first user to join the channel will be displayed as a large window, filling the entire canvas. The video windows of other users will be displayed as small windows, arranged horizontally from bottom to top, up to 4 rows, each with 4 windows. It supports up to a total of 17 windows of different users' videos.
    - 1: Adaptive layout. Automatically adjust the size of each user's video window according to the number of users, each user's video window size is consistent, and supports up to 17 windows.
    - 2: Vertical layout. The maxResolutionUid is specified to display the large video window on the left side of the screen, and the small video windows of other users are vertically arranged on the right side, with a maximum of two columns, 8 windows per column, supporting up to 17 windows.
    - 3: Customized layout. Set the layoutConfig field to customize the mixed layout.
    backgroundColorStringfalseThe background color of the video canvas. The RGB color table is supported, with strings formatted as a # sign and 6 hexadecimal digits. The default value is "#000000", representing the black color.
    backgroundImageStringfalseThe URL of the background image of the video canvas. The display mode of the background image is set to cropped mode.

    Cropped mode: Will prioritize to ensure that the screen is filled. The background image size is scaled in equal proportion until the entire screen is filled with the background image. If the length and width of the background image differ from the video window, the background image will be peripherally cropped to fill the window.
    defaultUserBackgroundImageStringfalseThe URL of the default user screen background image.

    After configuring this field, when any user stops sending the video streams for more than 3.5 seconds, the screen will switch to the background image; this setting will be overridden if the background image is set separately for a UID.
    layoutConfigArray[object]falselayoutConfig
    backgroundConfigArray[object]falsebackgroundConfig

    query-response


    _24
    {
    _24
    "resourceId": "string",
    _24
    "sid": "string",
    _24
    "serverResponse": {
    _24
    "status": 0,
    _24
    "extensionServiceState": [
    _24
    {
    _24
    "payload": {
    _24
    "fileList": [
    _24
    {
    _24
    "filename": "string",
    _24
    "sliceStartTime": 0
    _24
    }
    _24
    ],
    _24
    "onhold": true,
    _24
    "state": "string"
    _24
    },
    _24
    "serviceName": "string"
    _24
    }
    _24
    ]
    _24
    },
    _24
    "cname": "string",
    _24
    "uid": "string"
    _24
    }

    Properties

    NameTypeRequiredDescription
    resourceIdStringfalseThe resource ID used by cloud recording.
    sidStringfalseThe recording ID.
    serverResponseObjectfalseserverResponse
    cnameStringfalseThe name of the channel to be recorded.
    uidStringfalseThe user ID used by the cloud recording service in the RTC channel to identify the recording service in the channel.

    serverResponse


    _18
    {
    _18
    "status": 0,
    _18
    "extensionServiceState": [
    _18
    {
    _18
    "payload": {
    _18
    "fileList": [
    _18
    {
    _18
    "filename": "string",
    _18
    "sliceStartTime": 0
    _18
    }
    _18
    ],
    _18
    "onhold": true,
    _18
    "state": "string"
    _18
    },
    _18
    "serviceName": "string"
    _18
    }
    _18
    ]
    _18
    }

    Properties

    Scenario 1

    Fields returned in **web page recording **mode.

    NameTypeRequiredDescription
    statusNumberfalseCurrent status of the cloud service:
    - 0: Cloud service has not started.
    - 1: The cloud service initialization is complete.
    - 2: The cloud service components are starting.
    - 3: Some cloud service components are ready.
    - 4: All cloud service components are ready.
    - 5: The cloud service is in progress.
    - 6: The cloud service receives the request to stop.
    - 7: All components of the cloud service stop.
    - 8: The cloud service exits.
    - 20: The cloud service exits abnormally.
    extensionServiceStateArray[object]falseextensionServiceState

    Scenario 2

    Fields returned when in individual recording mode and video screenshot capture is turned on.

    NameTypeRequiredDescription
    statusNumberfalseCurrent status of the cloud service:
    - 0: Cloud service has not started.
    - 1: The cloud service initialization is complete.
    - 2: The cloud service components are starting.
    - 3: Some cloud service components are ready.
    - 4: All cloud service components are ready.
    - 5: The cloud service is in progress.
    - 6: The cloud service receives the request to stop.
    - 7: All components of the cloud service stop.
    - 8: The cloud service exits.
    - 20: The cloud service exits abnormally.
    sliceStartTimeNumberfalseRecording start time, the Unix timestamp, in milliseconds.

    Scenario 3

    Fields returned in scenarios other than video screenshot capturing during the individual recording and web page recording.

    NameTypeRequiredDescription
    statusNumberfalseCurrent status of the cloud service:
    - 0: Cloud service has not started.
    - 1: The cloud service initialization is complete.
    - 2: The cloud service components are starting.
    - 3: Some cloud service components are ready.
    - 4: All cloud service components are ready.
    - 5: The cloud service is in progress.
    - 6: The cloud service receives the request to stop.
    - 7: All components of the cloud service stop.
    - 8: The cloud service exits.
    - 20: The cloud service exits abnormally.
    fileListModeStringfalseData format of fileList field:
    - "string": fileList is of String type. In composite recording mode, if avFileType is set to ["hls"], fileListMode is "string".
    - "json": fileList is a JSON Array. When avFileType is set to ["hls","mp4"] in the individual or composite recording mode, fileListMode is set to "json".
    fileListfileList-string or fileList-jsonfalsefileList-string or fileList-json
    sliceStartTimeNumberfalseRecording start time, the Unix timestamp, in milliseconds.

    fileList-string

    TypeRequiredDescription
    StringfalseThe filename of the M3U8 file generated by the recording.

    extensionServiceState


    _15
    [
    _15
    {
    _15
    "payload": {
    _15
    "fileList": [
    _15
    {
    _15
    "filename": "string",
    _15
    "sliceStartTime": 0
    _15
    }
    _15
    ],
    _15
    "onhold": true,
    _15
    "state": "string"
    _15
    },
    _15
    "serviceName": "string"
    _15
    }
    _15
    ]

    Properties

    NameTypeRequiredDescription
    payloadObjectfalsepayload
    serviceNameStringfalseName of the extended service:
    - web_recorder_service: Represents the extended service is web page recording.
    - rtmp_publish_service: Represents the extended service is to push web page recording to the CDN.

    payload

    Properties

    Scenario 1

    The following fields will be returned during web page recording.

    NameTypeRequiredDescription
    fileListArray[object]falseSee the following.
    » filenameStringfalseThe file names of the M3U8 and MP4 files generated during recording.
    » sliceStartTimeNumberfalseThe recording start time of the file, the Unix timestamp, in seconds.
    onholdBooleanfalseWhether the page recording is in pause state:
    - true: In pause state.
    - false: The page recording is running.
    stateStringfalseThe status of uploading subscription content to the extension service:
    - "init": The service is initializing.
    - "inProgress": The service has started and is currently in progress.
    - "exit": Service exits.

    Scenario 2

    When pushing the web page recording to CDN, the following fields will be returned.

    NameTypeRequiredDescription
    outputsArray[object]falseSee the following.
    » rtmpUrlStringfalseThe CDN address to which you push the stream.
    » statusStringfalseThe current status of stream pushing of the web page recording:
    - "connecting": Connecting to the CDN server.
    - "publishing": The stream pushing is going on.
    - "onhold": Set whether to pause the stream pushing.
    - "disconnected": Failed to connect to the CDN server. Agora recommends that you change the CDN address to push the stream.
    stateStringfalseThe status of uploading subscription content to the extension service:
    - "init": The service is initializing.
    - "inProgress": The service has started and is currently in progress.
    - "exit": Service exits.

    fileList-json


    _10
    [
    _10
    {
    _10
    "fileName": "string",
    _10
    "trackType": "string",
    _10
    "uid": "string",
    _10
    "mixedAllUser": true,
    _10
    "isPlayable": true,
    _10
    "sliceStartTime": 0
    _10
    }
    _10
    ]

    The Array[object] type.

    Properties

    NameTypeRequiredDescription
    fileNameStringfalseThe file names of the M3U8 and MP4 files generated during recording.
    trackTypeStringfalseThe recording file type.
    - "audio": Audio-only files.
    - "video": Video-only files.
    - "audio_and_video": audio and video files
    uidStringfalseUser UID, indicating which user's audio or video stream is being recorded. In composite recording mode, the uid is "0".
    mixedAllUserBooleanfalseWhether the users were recorded separately.
    - true: All users are recorded in a single file.
    - false: Each user is recorded separately.
    isPlayableBooleanfalseWhether or not can be played online.
    - true: The file can be played online.
    - false: The file cannot be played online.
    sliceStartTimeNumberfalseThe recording start time of the file, the Unix timestamp, in seconds.

    stop-request


    _7
    {
    _7
    "cname": "string",
    _7
    "uid": "string",
    _7
    "clientRequest": {
    _7
    "async_stop": false
    _7
    }
    _7
    }

    Properties

    NameTypeRequiredDescription
    cnameStringtrueThe name of the channel where the recording service locates. The cname field you input in the acquire request needs to be the same.
    uidStringtrueThe string content is the UID used by the recording service in the RTC channel to identify the recording service. It needs to be the same as the uid field you input in the acquire request.
    clientRequestObjecttrueSee the following.
    » async_stopBooleanfalseSet the response mechanism for the stop method:
    - true: Asynchronous. Immediately receive a response after calling stop.
    - false: (Default) Synchronous. After calling stop, you need to wait for all the recorded files to be uploaded to the third-party cloud storage before receiving a response. Agora expects the upload time to be no more than 20 seconds. If the upload exceeds the time limit, you will receive an error code of 50.

    stop-response


    _16
    {
    _16
    "resourceId": "string",
    _16
    "sid": "string",
    _16
    "serverResponse": {
    _16
    "extensionServiceState": [
    _16
    {
    _16
    "playload": {
    _16
    "uploadingStatus": "string"
    _16
    },
    _16
    "serviceName": "string"
    _16
    }
    _16
    ]
    _16
    },
    _16
    "cname": "string",
    _16
    "uid": "string"
    _16
    }

    Properties

    NameTypeRequiredDescription
    resourceIdStringfalseThe resource ID used by cloud recording.
    sidStringfalseThe recording ID, identifying a recording cycle.
    serverResponseObjectfalseserverResponse
    cnameStringfalseThe name of the channel to be recorded.
    uidStringfalseThe user ID used by the cloud recording service in the RTC channel to identify the recording service in the channel.

    serverResponse-stop


    _10
    {
    _10
    "extensionServiceState": [
    _10
    {
    _10
    "playload": {
    _10
    "uploadingStatus": "string"
    _10
    },
    _10
    "serviceName": "string"
    _10
    }
    _10
    ]
    _10
    }

    Properties

    Scenario 1

    Fields returned in the web page recording scenario.

    NameTypeRequiredDescription
    extensionServiceStateArray[object]falseSee the following.
    » playloadObjectfalseplayload-stop
    » serviceNameStringfalseService type:
    - "upload_service": Upload service.
    - "web_recorder_service": Web recording service.

    Scenario 2

    Fields returned in the case of video screenshot capturing during individual recording.

    NameTypeRequiredDescription
    uploadingStatusStringfalseCurrent upload status of the recording file:
    - "uploaded": All recording files have been uploaded to the specified third-party cloud storage.
    - "backuped": All files of this recording have been uploaded, but at least one TS file has been uploaded to the Agora Backup Cloud. The Agora server will automatically continue to upload this portion of the file to the designated third-party cloud storage.
    - "unknown": Unknown status.

    Scenario 3

    Fields returned in scenarios other than video screenshot capturing during the individual recording and web page recording.

    NameTypeRequiredDescription
    fileListModeStringfalseData format of fileList field:
    - "string": fileList is of String type. In composite recording mode, if avFileType is set to ["hls"], fileListMode is "string".
    - "json": fileList is a JSON Array. When avFileType is set to ["hls","mp4"] in the individual or composite recording mode, fileListMode is set to "json".
    fileListfileList-string or fileList-jsonfalsefileList-string or fileList-json
    uploadingStatusStringfalseCurrent upload status of the recording file:
    - "uploaded": All recording files have been uploaded to the specified third-party cloud storage.
    - "backuped": All files of this recording have been uploaded, but at least one TS file has been uploaded to the Agora Backup Cloud. The Agora server will automatically continue to upload this portion of the file to the designated third-party cloud storage.
    - "unknown": Unknown status.

    playload-stop

    Properties

    Scenario 1

    Fields returned by the upload service in web page recording mode.

    NameTypeRequiredDescription
    uploadingStatusStringfalseCurrent upload status of the recording file:
    - "uploaded": All recording files have been uploaded to the specified third-party cloud storage.
    - "backuped": All files of this recording have been uploaded, but at least one TS file has been uploaded to the Agora Backup Cloud. The Agora server will automatically continue to upload this portion of the file to the designated third-party cloud storage.
    - "unknown": Unknown status.

    Scenario 2

    Fields returned by the page recording service in web page recording mode.

    NameTypeRequiredDescription
    fileListArray[object]falseSee the following.
    » filenameStringfalseThe file names of the M3U8 and MP4 files generated during recording.
    » sliceStartTimeNumberfalseThe recording start time of the file, the Unix timestamp, in seconds.
    onholdBooleanfalseWhether the page recording is in pause state:
    - true: In pause state.
    - false: The page recording is running.
    stateStringfalseThe status of uploading subscription content to the extension service:
    - "init": The service is initializing.
    - "inProgress": The service has started and is currently in progress.
    - "exit": Service exits.
    vundefined