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

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

Parameters

Name	In	Type	Required	Description
`Content-Type`	header	String	false	`application/json`.
`appid`	path	String	true	The 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.
body	body	JSON Object	true	acquire-request

200 Response

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

Response

status	Description	Schema
200 OK	If 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 200	If 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

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

Parameters

Name	In	Type	Required	Description
`Content-Type`	header	String	false	`application/json`.
`appid`	path	String	true	The 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.
`resourceId`	path	String	true	The resource ID obtained using the `acquire` request.
`mode`	path	String	true	One of the following recording modes: `individual`: Individual recording mode. `mix`: Composite recording mode. `web`: Web page recording mode.
body	body	JSON Object	true	start-request

200 Response

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

Response

status	Description	Schema
200	If 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 200	If the HTTP status code is not `200`, see the response status code for troubleshooting.	Response status code

Response Schema

Status Code 200

Name	Type	Required	Description
`cname`	String	false	The name of the channel to be recorded.
`uid`	String	false	The user ID used by the cloud recording service in the RTC channel to identify the recording service in the channel.
`resourceId`	String	false	The cloud recording resource ID. The resource ID is valid for five minutes, after which you need to re-request it.
`sid`	String	false	The 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

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

Parameters

Name	In	Type	Required	Description
`Content-Type`	header	String	false	`application/json`.
`appid`	path	String	true	The 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.
`resourceId`	path	String	true	The resource ID obtained using the `acquire` request.
`sid`	path	String	true	The recording ID obtained through `start`.
`mode`	path	String	true	One of the following recording modes: `individual`: Individual recording mode. `mix`: Composite recording mode. `web`: Web page recording mode.
body	body	JSON Object	true	update-request

200 Response

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

Response

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

Response Schema

Status Code 200

Name	Type	Required	Description
`cname`	String	false	The name of the channel to be recorded.
`uid`	String	false	The user ID used by the cloud recording service in the RTC channel to identify the recording service in the channel.
`resourceId`	String	false	The resource ID used by cloud recording.
`sid`	String	false	The 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

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

Parameters

Name	In	Type	Required	Description
`Content-Type`	header	String	false	`application/json`.
`appid`	path	String	true	The 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.
`resourceId`	path	String	true	The resource ID obtained using the `acquire` request.
`sid`	path	String	true	The recording ID obtained through `start`.
`mode`	path	String	true	The recording mode. Supports `mix` only, which means composite recording mode.
body	body	JSON Object	true	updateLayout-request

200 Response

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

Response

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

Response Schema

Status Code 200

Name	Type	Required	Description
`cname`	String	false	The name of the channel to be recorded.
`uid`	String	false	The user ID used by the cloud recording service in the RTC channel to identify the recording service in the channel.
`resourceId`	String	false	The resource ID used by cloud recording.
`sid`	String	false	The 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

Name	In	Type	Required	Description
`Content-Type`	header	String	false	`application/json`.
`appid`	path	String	true	The 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.
`resourceId`	path	String	true	The resource ID obtained using the `acquire` request.
`sid`	path	String	true	The recording ID obtained through `start`.
`mode`	path	String	true	One of the following recording modes: `individual`: Individual recording mode. `mix`: Composite recording mode. `web`: Web page recording mode.

200 Response

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

Response

status	Description	Schema
200	If the returned HTTP status code is `200`, the request is successful.	query-response
Not 200	If 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

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

Parameters

Name	In	Type	Required	Description
`Content-Type`	header	String	false	`application/json`.
`appid`	path	String	true	The 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.
`resourceId`	path	String	true	The resource ID obtained using the `acquire` request.
`sid`	path	String	true	The recording ID obtained through `start`.
`mode`	path	String	true	One of the following recording modes: `individual`: Individual recording mode. `mix`: Composite recording mode. `web`: Web page recording mode.
body	body	JSON Object	true	stop-request

200 Response

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

Response

status	Description	Schema
200	If the returned HTTP status code is `200`, the request is successful.	stop-response
Not 200	If 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.

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

Response

status	Description	Schema
200	If 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

Name	Type	Required	Description
`data`	Object	false	Unnecessary to know.
» `service`	Object	false	Unnecessary to know.
»» `hosts`	Array[object]	false	Unnecessary to know.
»»» `primaryIP`	String	false	The IP address of the Agora message notification server.

Schemas

acquire-request

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

Name	Type	Required	Description
`token`	String	false	A 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.
`storageConfig`	storageConfig	true	Configuration for third-party cloud storage.
`recordingConfig`	recordingConfig	false	Configuration for recorded audio and video streams. Note: You only need to set this field in individual recording and composite recording modes.
`recordingFileConfig`	recordingFileConfig	false	Configuration 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.
`snapshotConfig`	snapshotConfig	false	Configurations 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`.
`extensionServiceConfig`	extensionServiceConfig	false	Configurations for extended services. Note: Only need to set in web page recording mode.
`appsCollection`	appsCollection	false	Application configurations Note: This setting is only required when in individual recording mode and when postponed transcoding or audio mixing is enabled.
`transcodeOptions`	transcodeOptions	false	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.

Name	Type	Required	Description
`vendor`	Number	true	Third-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
`region`	Number	true	The 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.
`bucket`	String	true	Third-party cloud storage bucket. The bucket name needs to comply with the naming rules of the corresponding third-party cloud storage service.
`accessKey`	String	true	Access 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.
`secretKey`	String	true	(Required) The secret key of the third-party cloud storage.
`stsToken`	String	false	A 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.
`stsExpiration`	Number	false	The `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`
`fileNamePrefix`	Array[string]	false	The 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
`extensionParams`	extensionParams	false	Third-party cloud storage services will encrypt and tag the uploaded recording files according to this field.

Name	Type	Required	Description
`sse`	String	true	The 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.
`tag`	String	true	Tag 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.

Name	Type	Required	Description
`channelType`	Number	true	The 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.
`decryptionMode`	Number	false	The 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.
`secret`	String	false	Keys related to encryption and decryption. Only needs to be set when `decryptionMode` is not `0`.
`salt`	String	false	Salt related to encryption and decryption. Base64 encoding, 32-bit bytes. Only need to set when `decryptionMode` is `7` or `8`.
`maxIdleTime`	Number	false	Maximum 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.
`streamTypes`	Number	false	Subscribed 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.
`videoStreamType`	Number	false	Sets 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.
`subscribeAudioUids`	Array[string]	false	Specify 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.
`unsubscribeAudioUids`	Array[string]	false	Specify 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.
`subscribeVideoUids`	Array[string]	false	Specify 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.
`unsubscribeVideoUids`	Array[string]	false	Specify 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.
`subscribeUidGroup`	Number	false	Estimated 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.
`streamMode`	String	false	Output 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.
`audioProfile`	Number	false	Set 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.
`transcodingConfig`	transcodingConfig	false	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.

Name	Type	Required	Description
`width`	Number	false	The width of the video (pixels). `width` × `height` cannot exceed 1920 × 1080. The default value is 360.
`height`	Number	false	The height of the video (pixels). `width` × `height` cannot exceed 1920 × 1080. The default value is 640.
`fps`	Number	false	The frame rate of the video (fps). The default value is 15.
`bitrate`	Number	false	The bitrate of the video (Kbps). The default value is 500.
`maxResolutionUid`	String	false	Only 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 (2³²-1), and cannot be set to 0.
`mixedVideoLayout`	Number	false	Composite 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.
`backgroundColor`	String	false	The 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.
`backgroundImage`	String	false	The 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.
`defaultUserBackgroundImage`	String	false	The 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.
`layoutConfig`	Array[object]	false	layoutConfig
`backgroundConfig`	backgroundConfig	false	Configurations of user's background image.

Name	Type	Required	Description
`captureInterval`	Number	false	The cycle for regular screenshots in the cloud recording. The unit is seconds. The value range is [5,3600]. The default value is 10.
`fileType`	Array[string]	true	The file format of screenshots. Currently only `["jpg"]` is supported, which generates screenshot files in JPG format.

Name	Type	Required	Description
`errorHandlePolicy`	String	false	Error 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.
`extensionServices`	Array[object]	true	See the following.
» `serviceName`	String	true	Name 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.
» `errorHandlePolicy`	String	false	Error 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.
» `serviceParam`	serviceParam	true	Specific configurations for extension services.

Name	Type	Required	Description
`url`	String	true	The address of the page to be recorded.
`audioProfile`	Number	true	Sampling 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.
`videoWidth`	Number	true	The 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?.
`videoHeight`	Number	true	The 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.
`maxRecordingHour`	Number	true	The 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.
`videoBitrate`	Number	false	The 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.
`videoFps`	Number	false	The frame rate of the output video (fps). The value range is [5,60]. The default value is 15.
`mobile`	Boolean	false	Whether 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.
`maxVideoDuration`	Number	false	Maximum 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.
`onhold`	Boolean	false	Whether 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.
`readyTimeout`	Number	false	Set 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.

Name	Type	Required	Description
`outputs`	Array[object]	true	See the following.
» `rtmpUrl`	String	true	The CDN address to which you push the stream.

Name	Type	Required	Description
`transConfig`	Object	true	See the following.
» `transMode`	String	true	Mode: - `"postponeTranscoding"`: Postponed transcoding. - `"audioMix"`: Postponed audio mixing.
`container`	Object	false	See the following.
» `format`	String	false	The 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.
`audio`	Object	false	Audio properties of the file. Note: This setting is only required in individual recording mode with postponed audio mixing turned on.
» `sampleRate`	String	false	Audio sampling rate (Hz) supports the following values: - `"48000"`: (Default) 48 kHz. - `"32000"`: 32 kHz. - `"16000"`: 16 kHz.
» `bitrate`	String	false	Audio bit rate (Kbps) supports a customized value and the default value is `"48000"`.
» `channels`	String	false	The number of audio channels supports the following values: - `"1"`: Mono. - `"2"`: (Default) Stereo.

Name	Type	Required	Description
`streamSubscribe`	streamSubscribe	false	Update subscription lists. Note: You only need to set this field in individual recording and composite recording modes.
`webRecordingConfig`	webRecordingConfig	false	Used to update the web page recording configurations. Note: Only need to set in web page recording mode.
`rtmpPublishConfig`	rtmpPublishConfig	false	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.
`storageConfig`	storageConfig	true	Configuration for third-party cloud storage.

Name	Type	Required	Description
`audioUidList`	audioUidList	false	The audio subscription list. Note: This field is only applicable when the streamTypes field is set to audio, or both audio and video.
`videoUidList`	videoUidList	false	The video subscription list. Note: This field only applies when the streamTypes field is set to video, or both audio and video.

Name	Type	Required	Description
`status`	Number	false	Current 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.
`extensionServiceState`	Array[object]	false	extensionServiceState

Name	Type	Required	Description
`payload`	Object	false	payload
`serviceName`	String	false	Name 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.

Name	Type	Required	Description
`fileList`	Array[object]	false	See the following.
» `filename`	String	false	The file names of the M3U8 and MP4 files generated during recording.
» `sliceStartTime`	Number	false	The recording start time of the file, the Unix timestamp, in seconds.
`onhold`	Boolean	false	Whether the page recording is in pause state: - `true`: In pause state. - `false`: The page recording is running.
`state`	String	false	The 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.

Name	Type	Required	Description
`fileName`	String	false	The file names of the M3U8 and MP4 files generated during recording.
`trackType`	String	false	The recording file type. - `"audio"`: Audio-only files. - `"video"`: Video-only files. - `"audio_and_video"`: audio and video files
`uid`	String	false	User UID, indicating which user's audio or video stream is being recorded. In composite recording mode, the `uid` is `"0"`.
`mixedAllUser`	Boolean	false	Whether the users were recorded separately. - `true`: All users are recorded in a single file. - `false`: Each user is recorded separately.
`isPlayable`	Boolean	false	Whether or not can be played online. - `true`: The file can be played online. - `false`: The file cannot be played online.
`sliceStartTime`	Number	false	The recording start time of the file, the Unix timestamp, in seconds.

Name	Type	Required	Description
`fileListMode`	String	false	Data 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"`.
`fileList`	fileList-string or fileList-json	false	fileList-string or fileList-json
`uploadingStatus`	String	false	Current 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.

You are viewing Agora Docs forBetaproducts and features. Switch to Docs