This article contains detailed help for the Cloud Recording RESTful APIs.
Before proceeding, we recommend you take a quick look at the key features of Cloud Recording.
resource ID
s by using two different uid
s to call acquire
twice, one for individual or composite recording and the other for web page recording. Please note that both sessions are charged.The RESTful APIs only support HTTPS. Before using the Agora RESTful API, you need to pass the basic HTTP authentication.
All requests are sent to the host: api.agora.io
.
Use the RESTful APIs in the following steps:
acquire
method to request a resource ID for cloud recording.start
method within five minutes after getting the resource ID to start the recording.stop
method to stop the recording.During the recording, you can call the query
method to check the recording status.
Before starting a cloud recording, you need to call acquire
to get a resource ID.
Each resource ID can only be used for one recording session.
The request frequency limit is 10 requests per second for each App ID. Contact support@agora.io if you want to raise the limit.
If this method call succeeds, you get a resource ID (resourceId
) from the HTTP response body. The resource ID is valid for five minutes, so you need to start recording with this resource ID with it before it expires.
The following parameter is required in the URL.
Parameter | Type | Description |
---|---|---|
appid |
String | Your App ID。
|
The following parameters are required in the request body.
Parameter | Type | Description |
---|---|---|
cname |
String |
|
uid |
String | A string that contains the user ID of the recording client, for example "527841" . The UID needs to meet the following requirements: |
clientRequest |
JSON | A specific client request that includes the following parameters:
|
acquire
https://api.agora.io/v1/apps/<yourappid>/cloud_recording/acquire
.Content-type
is application/json;charset=utf-8
.Authorization
is the basic authentication, see RESTful API authentication for details.{
"cname": "httpClient463224",
"uid": "527841",
"clientRequest":{
"resourceExpiredHour": 24
}
}
acquire
"Code": 200,
"Body":
{
"resourceId": "JyvK8nXHuV1BE64GDkAaBGEscvtHW7v8BrQoRPCHxmeVxwY22-x-kv4GdPcjZeMzoCBUCOr9q-k6wBWMC7SaAkZ_4nO3JLqYwM1bL1n6wKnnD9EC9waxJboci9KUz2WZ4YJrmcJmA7xWkzs_L3AnNwdtcI1kr_u1cWFmi9BWAWAlNd7S7gfoGuH0tGi6CNaOomvr7-ILjPXdCYwgty1hwT6tbAuaW1eqR0kOYTO0Z1SobpBxu1czSFh1GbzGvTZG"
}
code
: Number. Status code.resourceId
: String. The resource ID for cloud recording. The resource ID is valid for five minutes.After getting a resource ID, call start
to begin cloud recording. The Cloud Recording service does the following after you call start
:
recordingConfig
.storageConfig
.The HTTP method and endpoint of start
:
The request frequency limit is 10 requests per second for each App ID. Contact support@agora.io if you need to raise the limit.
The following parameters are required in the URL.
Parameter | Type | Description |
---|---|---|
appid |
String | Your App ID. |
resourceid |
String | The resource ID requested by the acquire method. |
mode |
String | One of the following three recording modes:
|
The following parameters are required in the request body.
Parameter | Type | Description |
---|---|---|
cname |
String |
|
uid |
String | A string containing the UID of the recording client. Must be the same uid used in the acquire method. |
clientRequest |
JSON | A specific client request that requires the following parameters: token : String. The dynamic key used for the channel to record. Ensure that you set this parameter if App Certificate is enabled for your application. See Set up Authentication.recordingConfig : JSON. Configurations for subscribing to media streams.recordingFileConfig : JSON. Configurations for the recorded files.snapshotConfig : JSON. Video screenshot configurations.storageConfig : JSON. Third-party cloud storage configurations.extensionServiceConfig : JSON. Configurations for third-party extension services. Currently supports ApsaraVideo for VoD and web page recording. |
recordingConfig
is a JSON object for configuring how the Cloud Recording service subscribes to the media streams in the channel. recordingConfig
has the following fields:
channelType
: Number. The channel profile. Agora Cloud Recording must use the same channel profile as the Agora RTC SDK. Otherwise, issues may occur.0
: (Default) Communication profile. 1
: Live broadcast profile.streamTypes
: (Optional) Number. The type of the media stream to subscribe to:0
: Subscribes to audio streams only.1
: Subscribes to video streams only.2
: (Default) Subscribes to both audio and video streams.decryptionMode
: (Optional) Number. The decryption mode that is the same as the encryption mode set by the Agora Native/Web SDK. When the channel is encrypted, Agora Cloud Recording uses decryptionMode
to enable the built-in decryption function. secret
: (Optional) String. The decryption password when decryption mode is enabled. audioProfile
: (Optional) Number. The profile of the output audio stream, including the sample rate, bitrate, encoding mode, and the number of channels. You cannot set this parameter in individual recording mode.0
: (Default) Sample rate of 48 kHz, music encoding, mono, and a bitrate of up to 48 Kbps.1
: Sample rate of 48 kHz, music encoding, mono, and a bitrate of up to 128 Kbps.2
: Sample rate of 48 kHz, music encoding, stereo, and a bitrate of up to 192 Kbps.videoStreamType
: (Optional) Number. The type of the video stream to subscribe to.0
: (Default) Subscribes to the high-quality stream.1
: Subscribes to the low-quality stream.maxIdleTime
: (Optional) Number. Agora Cloud Recording automatically stops recording and leaves the channel when there is no user in the recording channel after a time period (30 seconds by default) set by this parameter. The value range is from 5 to 2,592,000 (30 days). Once the recording stops, the recording service generates new recorded files if you call start
for the second time.maxIdleTime
), the recording service automatically stops and leaves the channel.transcodingConfig
: (Optional) JSON. The video transcoding configuration. You cannot set this parameter in individual recording mode. If you set this parameter, ensure that you set width
, height
, fps
, and bitrate
. Refer to Set the Video Profile for detailed information about setting transcodingConfig
.
width
: (Mandatory) Number. The width of the mixed video (pixels). The default value is 360. width
should not exceed 1920, and width
*height
should not exceed 1920 * 1080; otherwise, an error occurs.height
: (Mandatory) Number. The height of the mixed video (pixels). The default value is 640. height
should not exceed 1920, and width
*height
should not exceed 1920 * 1080; otherwise, an error occurs.fps
: (Mandatory) Number. The video frame rate (fps). The default value is 15.bitrate
: (Mandatory) Number. The video bitrate (Kbps). The default value is 500.maxResolutionUid
: (Optional) String. When mixedVideoLayout
is set as 2
(vertical layout), you can specify the UID of the large video window by this parameter.backgroundColor
: (Optional) String. The background color of the canvas (the display window or screen) in RGB hex value. The string starts with a "#". The default value is "#000000"
, the black color.mixedVideoLayout
: (Optional) Number. The video mixing layout. 0, 1, and 2 are the predefined layouts. If you set this parameter as 3, you need to set the layout by the layoutConfig
parameter.0
: (Default) Floating layout. The first user in the channel occupies the full canvas. The other users occupy the small regions on top of the canvas, starting from the bottom left corner. The small regions are arranged in the order of the users joining the channel. This layout supports one full-size region and up to four rows of small regions on top with four regions per row, comprising 17 users.1
: Best fit layout. This is a grid layout. The number of columns and rows and the grid size vary depending on the number of users in the channel. This layout supports up to 17 users.2
: Vertical layout. One large region is displayed on the left edge of the canvas, and several smaller regions are displayed along the right edge of the canvas. The space on the right supports up to 2 columns of small regions with 8 regions per column. This layout supports up to 17 users.3
: Customized layout. Set the layoutConfig
parameter to customize the layout.layoutConfig
: (Optional) JSONArray. An array of the configuration of each user's region. Supports 17 users at most. Each user's region configuration is a JSON object with the following parameters:uid
: (Optional) String. The string contains the UID of the user displaying the video in the region. If this parameter is not specified, the configurations apply in the order of the users joining the channel.x_axis
: (Mandatory) Float. The relative horizontal position of the top-left corner of the region. The value is between 0.0 (leftmost) and 1.0 (rightmost), and is accurate to six decimal places.y_axis
: (Mandatory) Float. The relative vertical position of the top-left corner of the region. The value is between 0.0 (top) and 1.0 (bottom), and is accurate to six decimal places.width
: (Mandatory) Float. The relative width of the region. The value is between 0.0 and 1.0, and is accurate to six decimal places.height
: (Mandatory) Float. The relative height of the region. The value is between 0.0 and 1.0, and is accurate to six decimal places.alpha
: (Optional) Float. The transparency of the image. The value is between 0.0 (transparent) and 1.0 (opaque), and is accurate to six decimal places. The default value is 1.0.render_mode
: (Optional) Number. The video display mode:0
: (Default) Cropped mode. Uniformly scales the video until it fills the visible boundaries (cropped). One dimension of the video may have clipped contents.1
: Fit mode. Uniformly scales the video until one of its dimension fits the boundary (zoomed to fit). Areas that are not filled due to the disparity in the aspect ratio will be filled with black.subscribeAudioUids
: (Optional) JSONArray. An array of the user IDs (UIDs) of the users whose audio you want to subscribe. If you want to subscribe to all UIDs, you do not need to set this parameter. The length of the array should not exceed 32 UIDs. Agora recommends that you do not set the array as empty. Once you set the parameter, do not set streamTypes
in recordingConfig
as 1
. See Set up subscription lists for details.
unSubscribeAudioUids
: (Optional) JSONArray. An array of the user IDs (UIDs) of the users whose audio you do not want to subscribe. Once you set this parameter, the recording service subscribes to the audio of all UIDs except the specified ones. The length of the array should not exceed 32 UIDs. Agora recommends that you do not set the array as empty. Once you set the parameter, do not set streamTypes
in recordingConfig
as 1
. See Set up subscription lists for details.
subscribeVideoUids
: (Optional) JSONArray. An array of the user IDs (UIDs) of the users whose video you want to subscribe. If you want to subscribe to all UIDs, you do not need to set this parameter. The length of the array should not exceed 32 UIDs. Agora recommends that you do not set the array as empty. Once you set the parameter, do not set streamTypes
in recordingConfig
as 0
. See Set up subscription lists for details.
unSubscribeVideoUids
: (Optional) JSONArray. An array of the user IDs (UIDs) of the users whose video you do not want to subscribe. Once you set this parameter, the recording service subscribes to the video of all UIDs except the specified ones. The length of the array should not exceed 32 UIDs. Agora recommends that you do not set the array as empty. Once you set the parameter, do not set streamTypes
in recordingConfig
as 0
. See Set up subscription lists for details.
subscribeUidGroup
: (Optional) Number. The estimated maximum number of subscribed users. You must set this parameter in individual mode. For example, if subscribeVideoUids
is ["100","101","102"]
and subscribeAudioUids
is ["101","102","103"]
, the number of subscribed users is 4.
0
: 1 to 2 UIDs1
: 3 to 7 UIDs2
: 8 to 12 UIDs3
: 13 to 17 UIDsrecordingFileConfig
is a JSON Object for configuring recorded files. You cannot set both recordingFileConfig
and snapshotConfig
at the same time, otherwise an error will occur. recordingFileConfig
includes the following fields:
avFileType
: (Optional) JSONArray. An array of strings. Sets the format of the recorded files. "hls"
: (Default) M3U8 and TS files."mp4"
: MP4 files. This value is for web page recording (web
) only and must be set together with "hls
"; otherwise, the recording service returns error code 2
. When the length of the recorded file reaches two hours, or when the size of the file exceeds 2 GB, the recording service automatically creates another MP4 file.snapshotConfig
is a JSON object for configuring how Cloud Recording takes screenshots. Pay attention to the following parameters, as incorrect settings result in errors or failure to capture screenshots.
mode
must be individual
.recordingFileConfig
and snapshotConfig
at the same time.streamTypes
must be 1
or 2
.subscribeAudioUid
, you must also set subscribeVideoUids
.snapshotConfig
includes the following fields:
captureInterval
: (Optional) Integer. The time interval (in seconds) between two successive screenshots. captureInterval
should be within the range [5, 3600]. The default value is 10
.fileType
: JSONArray. File format of the screenshots. fileType
can only take ["jpg"]
, setting screenshots to the JPG format.storageConfig
is a JSON object that configures the third-party cloud storage with the following fields.
vendor
: Number. The third-party cloud storage vendor.
0
: Qiniu Cloud1
: Amazon S32
: Alibaba Cloud3
: Tencent Cloud4
: Kingsoft Cloudregion
: Number. The regional information specified by the third-party cloud storage:
When the third-party cloud storage is Qiniu Cloud (vendor
= 0):
0
: East China1
: North China 2
: South China3
: North America 4
: Southeast Asia When the third-party cloud storage is Amazon S3 (vendor
= 1):
0
: US_EAST_1 1
: US_EAST_2 2
: US_WEST_1 3
: US_WEST_2 4
: EU_WEST_1 5
: EU_WEST_2 6
: EU_WEST_3 7
: EU_CENTRAL_1 8
: AP_SOUTHEAST_1 9
: AP_SOUTHEAST_2 10
: AP_NORTHEAST_1 11
: AP_NORTHEAST_2 12
: SA_EAST_1 13
: CA_CENTRAL_1 14
: AP_SOUTH_1 15
: CN_NORTH_1 16
: CN_NORTHWEST_117
: US_GOV_WEST_1 When the third-party cloud storage is Alibaba Cloud (vendor
= 2):
0
: CN_Hangzhou 1
: CN_Shanghai 2
: CN_Qingdao 3
: CN_Beijing4
: CN_Zhangjiakou 5
: CN_Huhehaote 6
: CN_Shenzhen 7
: CN_Hongkong 8
: US_West_1 9
: US_East_1 10
: AP_Southeast_1 11
: AP_Southeast_2 12
: AP_Southeast_3 13
: AP_Southeast_5 14
: AP_Northeast_1 15
: AP_South_1 16
: EU_Central_1 17
: EU_West_1 18
: EU_East_1When the third-party cloud storage is Tencent Cloud (vendor
= 3):
0
:AP_Beijing_11
:AP_Beijing2
:AP_Shanghai3
:AP_Guangzhou4
:AP_Chengdu 5
:AP_Chongqing 6
:AP_Shenzhen_FSI 7
:AP_Shanghai_FSI 8
:AP_Beijing_FSI 9
:AP_Hongkong 10
:AP_Singapore 11
:AP_Mumbai 12
:AP_Seoul 13
:AP_Bangkok 14
:AP_Tokyo 15
:NA_Siliconvalley 16
:NA_Ashburn 17
:NA_Toronto 18
:EU_Frankfurt 19
:EU_MoscowWhen the third-party cloud storage is Kingsoft Cloud (vendor
= 4):
0
:CN_Hangzhou1
:CN_Shanghai2
:CN_Qingdao3
:CN_Beijing4
:CN_Guangzhou5
:CN_Hongkong6
:JR_Beijing7
:JR_Shanghai8
:NA_Russia_19
:NA_Singapore_1bucket
: String. The bucket of the third-party cloud storage.
accessKey
: String. The access key of the third-party cloud storage. Agora suggests that you use a write-only access key.
secretKey
: String. The secret key of the third-party cloud storage.
fileNamePrefix
: (Optional) JSONArray. An array of strings. Sets the path of the recorded files in the third-party cloud storage. For example, if fileNamePrefix
= ["directory1","directory2"]
, Agora Cloud Recording will add the prefix "directory1/directory2/
" before the name of the recorded file, that 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 supported characters are as follows:
extensionServiceConfig
is a JSON Object for extension service configurations. Extension services are a collection of applications that process the media streams generated from the Agora RTC SDK. One example extension service is VoD service.
extensionServiceConfig
has the following fields:
errorHandlePolicy
: (Optional) String. 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.
apiVersion
: (Optional) String. The version of the Cloud Recording RESTful API. The default value is "v1"
.
extensionServices
: JSONArray. An array of the configuration for each extension service.
ApsaraVideo for VoD
When using ApsaraVideo for VoD,extensionServicesextensionServices
includes the following fields:
serviceName
: String. The name of the extension service. To use ApsaraVideo for VoD, set it as "aliyun_vod_service"
.errorHandlePolicy
: (Optional) String. Error handling policy. You can only set it to the default value, "error_abort"
, which means that if an error occurs to the current extension service, other extension services also stop.serviceParam
: JSON. Configurations for an extension service. To use ApsaraVideo for VoD, configure as follows:accessKey
: String. Corresponds to the AccessKeyId
in the AccessKey of Alibaba Cloud. For details, see Alibaba Cloud's documentation.secretKey
: String. Corresponds to the AccessKeySecret
in the AccessKey of Alibaba Cloud. For details, see Alibaba Cloud's documentation.regionId
: String. The service region. For details, see Alibaba Cloud's documentation.apiData
: JSON. Configurations for ApsaraVideo for VoD.videoData
: JSON. Video configurations. See Alibaba Cloud's documentation for details about the following parameters:title
: String. The title of the video.description
: (Optional) String. The description of the video.coverUrl
: (Optional) String. The URL of the custom video thumbnail.cateId
: (Optional) String. The ID of the video category.tags
: (Optional) String. The tags of the video.templateGroupId
: (Optional) String. The ID of the transcoding template group.userData
: (Optional) String. The custom configurations.storageLocation
: (Optional) String. The bucket.workflowId
: (Optional) String. The ID of the workflow.Web page recording
When using web page recording, extensionServices
includes the following fields:
serviceName
: String. The name of the extension service. To use web page recording, set it as "web_recorder_service
".errorHandlePolicy
: (Optional) String. Error handling policy. Currently you can only set it to the default value, "error_abort"
, which means that if an error occurs to the current extension service, other extension services also stop.serviceParam
: JSON. Configurations for an extension service. To use web page recording, configure as follows:url
:String. Sets the address of the web page to record.videoBitrate
:(Optional) Number. Sets the bitrate of the video (Kbps). The value range is [50,8000]. The default value of videoBitrate
varies according to the resolution of the output video:videoFps: (Optional)
Number. Sets the frame rate of the video (fps). The value range is [5,60]. The default value is 15.audioProfile
:Number. Sets the sample rate, encoding mode, number of audio channels, and bitrate.0
: (Default) Sample rate of 48 kHz, music encoding, mono, and a bitrate of up to 48 Kbps.1
: Sample rate of 48 kHz, music encoding, mono, and a bitrate of up to 128 Kbps.2
: Sample rate of 48 kHz, music encoding, stereo, and a bitrate of up to 192 Kbps.videoWidth
:Number. Sets the width of the video (pixels). The value range is [480,1280]. The product of videoWidth
and videoHeight
should not exceed 921,600 (1280 × 720).videoHeight
:Number. Sets the height of the video (pixels). The value range is [480,1280]. The product of videoWidth
and videoHeight
should not exceed 921,600 (1280 × 720).maxRecordingHour
:Number. Sets the maximum recording length (hours). If the limit is exceeded, the recording stops automatically. The value range is [1,720]. The default value is 3. We recommend that you set a value smaller than the value of resourceExpiredHour
specified in the acquire
method.start
https://api.agora.io/v1/apps/<yourappid>/cloud_recording/resourceid/<resourceid>/mode/<mode>/start
Content-type
is application/json;charset=utf-8
.
Authorization
is basic HTTP authentication, see RESTful API authentication for details.
The request body
{
"uid": "527841",
"cname": "httpClient463224",
"clientRequest": {
"token": "<token if any>",
"recordingConfig": {
"maxIdleTime": 30,
"streamTypes": 2,
"channelType": 0,
"transcodingConfig": {
"height": 640,
"width": 360,
"bitrate": 500,
"fps": 15,
"mixedVideoLayout": 1,
"backgroundColor": "#FF0000"
},
"subscribeVideoUids": ["123","456"],
"subscribeAudioUids": ["123","456"],
"subscribeUidGroup": 0
},
"recordingFileConfig": {
"avFileType": ["hls"]
},
"storageConfig": {
"accessKey": "xxxxxxf",
"region": 3,
"bucket": "xxxxx",
"secretKey": "xxxxx",
"vendor": 2,
"fileNamePrefix": ["directory1","directory2"]
}
}
}
{
"uid": "527841",
"cname": "httpClient463224",
"clientRequest": {
"token": "<token if any>",
"recordingConfig": {
"maxIdleTime": 30,
"streamTypes": 2,
"channelType": 0,
"subscribeUidGroup": 0
},
"extensionServiceConfig": {
"extensionServices": [{
"serviceName": "aliyun_vod_service",
"serviceParam": {
"secretKey": "xxxxxx",
"accessKey": "xxxxxx",
"regionId": "cn-shanghai",
"apiData": {
"videoData": {
"title": "My Video",
"description": "This is my first video",
"coverUrl": "http://xxxxx"
}
}
}
}]
}
}
}
{
"uid": "527841",
"cname": "httpClient463224",
"clientRequest": {
"token": "<token if any>",
"recordingConfig": {
"maxIdleTime": 30,
"streamTypes": 2,
"channelType": 0,
"subscribeUidGroup": 0
},
"snapshotConfig": {
"captureInterval": 5,
"fileType": ["jpg"]
},
"storageConfig": {
"accessKey": "xxxxxxf",
"region": 3,
"bucket": "xxxxx",
"secretKey": "xxxxx",
"vendor": 2,
"fileNamePrefix": ["directory1","directory2"]
}
}
}
{
"cname":"httpClient463224",
"uid":"527841",
"clientRequest":{
"token": "<token if any>",
"extensionServiceConfig": {
"errorHandlePolicy": "error_abort",
"extensionServices":[{
"serviceName":"web_recorder_service",
"errorHandlePolicy": "error_abort",
"serviceParam": {
"url": "https://xxxxx",
"audioProfile":0,
"videoWidth":1280,
"videoHeight":720,
"maxRecordingHour":72
}
}]
},
"recordingFileConfig":{
"avFileType":[
"hls",
"mp4"
]
},
"storageConfig":{
"vendor":2,
"region":3,
"bucket":"xxxxx",
"accessKey":"xxxxx",
"secretKey":"xxxxx",
"fileNamePrefix":[
"directory1",
"directory2"
]
}
}
}
start
"Code": 200,
"Body":
{
"sid": "38f8e3cfdc474cd56fc1ceba380d7e1a",
"resourceId": "JyvK8nXHuV1BE64GDkAaBGEscvtHW7v8BrQoRPCHxmeVxwY22-x-kv4GdPcjZeMzoCBUCOr9q-k6wBWMC7SaAkZ_4nO3JLqYwM1bL1n6wKnnD9EC9waxJboci9KUz2WZ4YJrmcJmA7xWkzs_L3AnNwdtcI1kr_u1cWFmi9BWAWAlNd7S7gfoGuH0tGi6CNaOomvr7-ILjPXdCYwgty1hwT6tbAuaW1eqR0kOYTO0Z1SobpBxu1czSFh1GbzGvTZG"
}
code
: Number. Status code.
resourceId
: String. The resource ID for cloud recording. The resource ID is valid for five minutes.
sid
: String. The recording ID. The unique identification of the current recording.
During a cloud recording, you can call this method to update the subscription lists multiple times. This method call overrides the existing subscription configuration.
The request frequency limit is 10 requests per second for each App ID. Contact support@agora.io if you want to raise the limit.
The following parameters are required in the URL:
Parameter | Type | Description |
---|---|---|
appid |
String | The App ID in the channel to be recorded. |
resourceid |
String | The resource ID requested by acquire . |
sid |
String | The recording ID created by start . |
mode |
String | The recording mode. Supports individual mode (individual ) and composite mode (mix ). Composite mode is the default. |
The following parameters are required in the request body:
Parameter | Type | Description |
---|---|---|
cname |
String | The name of the channel to be recorded. |
uid |
String | A string that contains the UID of the recording client. Must be the same UID used in the acquire method. |
clientRequest |
JSON | A specific client request which includes the streamSubscribe parameter. Use streamSubscribe to update the subscription list. |
streamSubscribe
requires the following parameters:
streamTypes
in recordingConfig
as 1
(video only).subscribeAudioUids
: (Optional) JSONArray. An array of the user IDs (UIDs) of the users whose audio you want to subscribe. The length of the array should not exceed 32 UIDs, and the array should not be empty. See Set up subscription lists for details.unsubscribeAudioUids
: (Optional) JSONArray. An array of the user IDs (UIDs) of the users whose audio you do not want to subscribe. Once you set this parameter, the recording service subscribes to the audio of all UIDs except the specified ones. The length of the array should not exceed 32 UIDs, and the array should not be empty. See Set up subscription lists for details.streamTypes
in recordingConfig
as 0
(audio only).subscribeVideoUids
: (Optional) JSONArray. An array of the user IDs (UIDs) of the users whose video you want to subscribe. The length of the array should not exceed 32 UIDs, and the array should not be empty. See Set up subscription lists for details.unsubscribeVideoUids
: (Optional) JSONArray. An array of the user IDs (UIDs) of the users whose video you do not want to subscribe. Once you set this parameter, the recording service subscribes to the video of all UIDs except the specified ones. The length of the array should not exceed 32 UIDs, and the array should not be empty. See Set up subscription lists for details.update
The request URL is:
https://api.agora.io/v1/apps/<appid>/cloud_recording/resourceid/<resourceid>/sid/<sid>/mode/<mode>/update
Content-type
is application/json;charset=utf-8
.
Authorization
is the basic authorization. See RESTful API authentication for details.
The request body:
{
"uid": "527841",
"cname": "httpClient463224",
"clientRequest": {
"streamSubscribe": {
"audioUidList": {
"subscribeAudioUids": ["#allstream#"]
},
"videoUidList": {
"unSubscribeVideoUids": ["444", "555", "666"]
}
}
}
}
update
"Code": 200,
"Body":
{
"sid": "38f8e3cfdc474cd56fc1ceba380d7e1a",
"resourceId": "JyvK8nXHuV1BE64GDkAaBGEscvtHW7v8BrQoRPCHxmeVxwY22-x-kv4GdPcjZeMzoCBUCOr9q-k6wBWMC7SaAkZ_4nO3JLqYwM1bL1n6wKnnD9EC9waxJboci9KUz2WZ4YJrmcJmA7xWkzs_L3AnNwdtcI1kr_u1cWFmi9BWAWAlNd7S7gfoGuH0tGi6CNaOomvr7-ILjPXdCYwgty1hwT6tbAuaW1eqR0kOYTO0Z1SobpBxu1czSFh1GbzGvTZG"
}
code
: Number. Status code.resourceId
: String. The resource ID for cloud recording.sid
: String. The recording ID. The unique identification of the current recording.During a recording, you can call this method to update the video mixing layout multiple times.
This method call overrides the existing layout configurations. For example, if you set the backgroundColor
parameter as "#FF0000"
(red) when starting a recording and call this method to update the layout without setting the backgroundColor
parameter, the background color changes back to black (the default value).
The request frequency limit is 10 requests per second for each App ID. Contact support@agora.io if you want to raise the limit.
The following parameters are required in the URL.
Parameter | Type | Description |
---|---|---|
appid |
String | The App ID used in the channel to be recorded. |
resourceid |
String | The resource ID requested by the acquire method. |
sid |
String | The recording ID created by the start method. |
mode |
String | The recording mode. Supports composite mode (mix ) only. |
The following parameters are required in the request body.
Parameter | Type | Description |
---|---|---|
cname |
String | The name of the channel to be recorded. |
uid |
String | A string that contains the UID of the recording client. Must be the same uid used in the acquire method. |
clientRequest |
JSON | A specific client request. See the following list for details. |
clientRequest
requires the following parameters:
maxResolutionUid
: (Optional) String. When the layoutType
parameter is set as 2
(vertical layout), you can specify the UID of the large video window by this parameter.mixedVideoLayout
: (Optional) Number. The video mixing layout. 0, 1, and 2 are the predefined layouts. If you set this parameter as 3, you need to set the layout by the layoutConfig
parameter.0
: (Default) Floating layout. The first user in the channel occupies the full canvas. The other users occupy the small regions on top of the canvas, starting from the bottom left corner. The small regions are arranged in the order of the users joining the channel. This layout supports one full-size region and up to four rows of small regions on top with four regions per row, comprising 17 users.1
: Best fit layout. This is a grid layout. The number of columns and rows and the grid size vary depending on the number of users in the channel. This layout supports up to 17 users.2
: Vertical layout. One large region is displayed on the left edge of the canvas, and several smaller regions are displayed along the right edge of the canvas. The space on the right supports up to 2 columns of small regions with 8 regions per column. This layout supports up to 17 users.3
: Customized layout. Set the layoutConfig
parameter to customize the layout.backgroundColor
: (Optional) String. The background color of the canvas (the display window or screen) in RGB hex value. The string starts with a "#". The default value is "#000000"
, the black color.layoutConfig
: (Optional) JSONArray. An array of the configuration of each user's region. Supports 17 users at most. Each user's region configuration is a JSON object with the following parameters:uid
: (Optional) String. The string contains the UID of the user displaying the video in the region. If this parameter is not specified, the configurations apply in the order of the users joining the channel.x_axis
: (Mandatory) Float. The relative horizontal position of the top-left corner of the region. The value is between 0.0 (leftmost) and 1.0 (rightmost). x_axis
can also be an integer 0 or 1.y_axis
: (Mandatory) Float. The relative vertical position of the top-left corner of the region. The value is between 0.0 (top) and 1.0 (bottom). y_axis
can also be an integer 0 or 1.width
: (Mandatory) Float. The relative width of the region. The value is between 0.0 and 1.0. width
can also be an integer 0 or 1.height
: (Mandatory) Float. The relative height of the region. The value is between 0.0 and 1.0. height
can also be an integer 0 or 1.alpha
: (Optional) Float. The transparency of the image. The value is between 0.0 (transparent) and 1.0 (opaque). The default value is 1.0.render_mode
: (Optional) Number. The video display mode:0
: (Default) Cropped mode. Uniformly scales the video until it fills the visible boundaries (cropped). One dimension of the video may have clipped contents.1
: Fit mode. Uniformly scales the video until one of its dimension fits the boundary (zoomed to fit). Areas that are not filled due to the disparity in the aspect ratio will be filled with black.updateLayout
The request URL is:
https://api.agora.io/v1/apps/<appid>/cloud_recording/resourceid/<resourceid>/sid/<sid>/mode/<mode>/updateLayout
Content-type
is application/json;charset=utf-8
.
Authorization
is the basic authorization, see RESTful API authentication for details.
The request body:
{
"uid": "527841",
"cname": "httpClient463224",
"clientRequest": {
"mixedVideoLayout": 3,
"backgroundColor": "#FF0000",
"layoutConfig": [
{
"uid": "1",
"x_axis": 0.1,
"y_axis": 0.1,
"width": 0.1,
"height": 0.1,
"alpha": 1.0,
"render_mode": 1
},
{
"uid": "2",
"x_axis": 0.2,
"y_axis": 0.2,
"width": 0.1,
"height": 0.1,
"alpha": 1.0,
"render_mode": 1
}
]
}
}
updateLayout
"Code": 200,
"Body":
{
"sid": "38f8e3cfdc474cd56fc1ceba380d7e1a",
"resourceId": "JyvK8nXHuV1BE64GDkAaBGEscvtHW7v8BrQoRPCHxmeVxwY22-x-kv4GdPcjZeMzoCBUCOr9q-k6wBWMC7SaAkZ_4nO3JLqYwM1bL1n6wKnnD9EC9waxJboci9KUz2WZ4YJrmcJmA7xWkzs_L3AnNwdtcI1kr_u1cWFmi9BWAWAlNd7S7gfoGuH0tGi6CNaOomvr7-ILjPXdCYwgty1hwT6tbAuaW1eqR0kOYTO0Z1SobpBxu1czSFh1GbzGvTZG"
}
code
: Number. Status code.resourceId
: String. The resource ID for cloud recording. The resource ID is valid for five minutes.sid
: String. The recording ID. The unique identification of the current recording.After you start a recording, you can call query
to check its status.
query
works only with an ongoing recording session. If you call query
after a recording ends or after it starts with error, you get a 404 (Not Found) error.The request frequency limit is 10 requests per second for each App ID. Contact support@agora.io if you need to raise the limit.
The following parameters are required in the URL.
Parameter | Type | Description |
---|---|---|
appid |
String | Your App ID. |
resourceid |
String | The resource ID requested by the acquire method. |
sid |
String | The recording ID created by the start method. |
mode |
String | The recording mode. Supports individual mode (individual ), composite mode (mix ), and web page recording mode (Web ). |
query
https://api.agora.io/v1/apps/<yourappid>/cloud_recording/resourceid/<resourceid>/sid/<sid>/mode/<mode>/query
Content-type
is application/json;charset=utf-8
.Authorization
is the basic authentication, see RESTful API authentication for details.query
"Code": 200,
"Body":
{
"resourceId":"JyvK8nXHuV1BE64GDkAaBGEscvtHW7v8BrQoRPCHxmeVxwY22-x-kv4GdPcjZeMzoCBUCOr9q-k6wBWMC7SaAkZ_4nO3JLqYwM1bL1n6wKnnD9EC9waxJboci9KUz2WZ4YJrmcJmA7xWkzs_L3AnNwdtcI1kr_u1cWFmi9BWAWAlNd7S7gfoGuH0tGi6CNaOomvr7-ILjPXdCYwgty1hwT6tbAuaW1eqR0kOYTO0Z1SobpBxu1czSFh1GbzGvTZG",
"sid":"38f8e3cfdc474cd56fc1ceba380d7e1a",
"serverResponse":{
"fileListMode": "json",
"fileList": [
{
"filename": "xxx.m3u8",
"trackType": "audio_and_video",
"uid": "123",
"mixedAllUser": true,
"isPlayable": true,
"sliceStartTime": 1562724971626
},
{
"filename": "xxx.m3u8",
"trackType": "audio_and_video",
"uid": "456",
"mixedAllUser": true,
"isPlayable": true,
"sliceStartTime": 1562724971626
}
],
"status": "5",
"sliceStartTime": 1562724971626
}
}
code
: Number. Status code.
resourceId
: String. The resource ID for cloud recording. The resource ID is valid for five minutes.
sid
: String. The recording ID. The unique identification of the current recording.
serverResponse
: JSON. The details about the recording status.
serverResponse
vary according to your configurations in start
. For example, if you configure snapshotConfig
or extensionServiceConfig
in start
, then query
does not return fileListMode
.fileListMode
: String. The data type of fileList
.
"string"
: fileList
is a string. In composite mode, fileListMode
is "string"
."json"
: fileList
is a JSONArray. In individual mode, fileListMode
is "json"
.fileList
: When fileListMode
is "string"
, fileList
is a string that represents the filename of the M3U8 file. When fileListMode
is "json"
, fileList
is a JSONArray that contains the details of each recorded file. The query
method does not return this field if you have set snapshotConfig
.
filename
: String. The name of the M3U8 file.trackType
: String. The type of the recorded file."audio"
: Audio file."video"
: Video file (no audio)."audio_and_video"
: Video file (with audio).uid
: String. User ID. The user whose audio or video is recorded in the file.mixedAllUser
: Boolean. Whether the audio and video of all users are combined into a single file.true
: All users are recorded in a single file.false
: Each user is recorded separately.isPlayable
: Boolean. Whether the file can be played online.true
: The file can be played online.false
: The file cannot be played online.sliceStartTime
: Number. The Unix time (ms) when the recording starts.status
: Number. The status of the cloud service.
0
: The cloud service has not started.1
: The initialization is complete.2
: The cloud service is starting.3
: The cloud service is partially ready.4
: The cloud service is ready.5
: The cloud service is in progress.6
: The cloud service receives the request to stop.7
: The cloud service stops.8
: The cloud service exits.20
: The cloud service exits abnormally.sliceStartTime
: Number. The time when the recording starts. Unix timestamp (ms).
extensionServiceState
: JSONArray. An array of the detailed status information of each extension service.
ApsaraVideo for VoD
serviceName
: String. The name of the extension service. aliyun_vod_service
means ApsaraVideo for VoD.payload
: JSON. The status of the extension service.state
: String. The status of uploading media content to the extension service."inProgress"
: The recorded files are being uploaded to the extension service."idle"
: No user is sending streams in the channel. Nothing is being uploaded.videoInfo
: JSONArray. An array of the M3U8 files and their corresponding video IDs. ApsaraVideo for VoD generates a video ID for each M3U8 file uploaded.fileName
: String. The name of the M3U8 file.videoId
: String. The corresponding video ID of the M3U8 file.Web page recording
serviceName
: String . The name of the extension service. "web_recorder_service"
means web page recording.payload
: JSON. The status of the extension service.state
: String. The status of uploading subscribed content to the extension service."init"
: The service is initializing."inProgress"
: The service has initialized and is working."exit"
: The service exits.fileList
: JSONArray. An array that contains details of each recorded file.fileName
: String. The name of the M3U8 file or MP4 file.sliceStartTime
: Number. The Unix timestamp (ms) when the recording starts.:subServiceStatus
: JSON. The status of the cloud recording submodules. The recording service does not return this field in web page recording mode.
recordingService
: String. The status of the video subscription submodule. For details, see Service status. When a recording finishes, call stop
to leave the channel and stop recording. To use Agora Cloud Recording again, you need to call the acquire
method for a new resource ID.
- The request frequency limit is 10 requests per second for each App ID. Contact support@agora.io if you need to raise the limit.
- By default, Agora Cloud Recording automatically leaves the channel and stops recording if there are ever no users in the channel for more than 30 seconds.
The following parameters are required in the URL.
Parameter | Type | Description |
---|---|---|
appid |
String | Your App ID. |
resourceid |
String | The resource ID requested by the acquire method. |
sid |
String | The recording ID created by the start method. |
mode |
String | The recording mode. Supports individual mode (individual ), composite mode (mix ), and web page mode (Web ). |
The following parameters are required in the request body.
Parameter | Type | Description |
---|---|---|
cname |
String |
|
uid |
String | A string that contains the UID of the recording client. Must be the same uid used in the acquire method. |
clientRequest |
JSON | A specific client request that is empty for this method. |
stop
The request URL is:
https://api.agora.io/v1/apps/<yourappid>/cloud_recording/resourceid/<resourceid>/sid/<sid>/mode/<mode>/stop
Content-type
is application/json;charset=utf-8
.
Authorization
is the basic authentication, see RESTful API authentication for details.
The request body:
{
"cname": "httpClient463224",
"uid": "527841",
"clientRequest":{
}
}
stop
"Code": 200,
"Body":
{
"resourceId":"JyvK8nXHuV1BE64GDkAaBGEscvtHW7v8BrQoRPCHxmeVxwY22-x-kv4GdPcjZeMzoCBUCOr9q-k6wBWMC7SaAkZ_4nO3JLqYwM1bL1n6wKnnD9EC9waxJboci9KUz2WZ4YJrmcJmA7xWkzs_L3AnNwdtcI1kr_u1cWFmi9BWAWAlNd7S7gfoGuH0tGi6CNaOomvr7-ILjPXdCYwgty1hwT6tbAuaW1eqR0kOYTO0Z1SobpBxu1czSFh1GbzGvTZG",
"sid":"38f8e3cfdc474cd56fc1ceba380d7e1a",
"serverResponse":{
"fileListMode": "json",
"fileList": [
{
"filename": "xxx.m3u8",
"trackType": "audio_and_video",
"uid": "123",
"mixedAllUser": true,
"isPlayable": true,
"sliceStartTime": 1562724971626
},
{
"filename": "xxx.m3u8",
"trackType": "audio_and_video",
"uid": "456",
"mixedAllUser": true,
"isPlayable": true,
"sliceStartTime": 1562724971626
}
],
"uploadingStatus": "uploaded"
}
}
code
: Number. Status code.
resourceId
: String. The resource ID for cloud recording. The resource ID is valid for five minutes.
sid
: String. The recording ID. The unique identification of the current recording.
serverResponse
: JSON. The details about the recording status. The child elements in serverResponse
vary according to your configurations in start
. For example, if you configure snapshotConfig
or extensionServiceConfig
in start
, then stop
does not return fileListMode
.
fileListMode
: String. The data type of fileList
.
"string"
: fileList
is a string. In composite mode, fileListMode
is "string"
."json"
: fileList
is a JSONArray. In individual mode, fileListMode
is "json"
.fileList
: When fileListMode
is "string"
, fileList
is a string that represents the filename of the M3U8 file. When fileListMode
is "json"
, fileList
is a JSONArray that contains the details of each recorded file.
filename
: String. The name of the M3U8 file.trackType
: String. The type of the recorded file."audio"
: Audio file."video"
: Video file (no audio)."audio_and_video"
: Video file (with audio).uid
: String. User ID. The user whose audio or video is recorded in the file.mixedAllUser
: Boolean. Whether the audio and video of all users are combined into a single file.true
: All users are recorded in a single file.false
: Each user is recorded separately.isPlayable
: Boolean. Whether the file can be played online.true
: The file can be played online.false
: The file cannot be played online.sliceStartTime
: Number. The Unix time (ms) when the recording starts. uploadingStatus
: String. The upload status.
"uploaded"
: All the recorded files are uploaded to the third-party cloud storage."backuped"
: Some of the recorded files fail to upload to the third-party cloud storage and upload to Agora Cloud Backup instead. Agora Cloud Backup automatically uploads these files to your cloud storage. "unknown"
: Unknown status.extensionServiceState
: JSONArray. An array of the detailed status information of each service.
Uploading service
serviceName
: String. The name of the service. "upload_service"
means the uploading service.payload
: JSON. The status of the service.uploadingStatus
: String. The uploading status."uploaded"
: All the recorded files are uploaded to the third-party cloud storage."backuped"
: All the recorded files are uploaded, but at least one TS file is uploaded to Agora Cloud Backup. Agora Cloud Backup will automatically upload these files to your cloud storage later."unknown"
: Unknown status.Web page recording
serviceName
: String. The name of the service. "web_recorder_service"
means web page recording.payload
: JSON. The status of the extension service.state
: String. The status of uploading subscribed content to the extension service."init"
: The service is initializing.``"inProgress"
: The service has initialized and is working."exit"
: The service exits.fileList
: JSONArray. An array that contains detailed information of each recorded file.fileName
: String. The name of the M3U8 file or MP4 file.sliceStartTime
: Number. The Unix timestamp (ms) when the recording starts.Code | Description |
---|---|
200 | The request is successful. |
201 | The request has been fulfilled, resulting in the creation of a new resource. |
206 | No user in the channel sent a stream during the recording process, or some of the recorded files are uploaded to the Agora Cloud Backup instead of the third-party cloud storage. |
400 | The server cannot process the request due to malformed request syntax, or the cloud recording service is not enabled. |
401 | Unauthorized (incorrect Customer ID/Customer Secret). |
404 | The requested resource could not be found. |
500 | Internal server error. |
504 | The server was acting as a gateway or proxy and did not receive a timely response from the upstream server. |
State | Description |
---|---|
"serviceIdle" | The submodule is idle. |
"serviceStarted" | The submodule has started. |
"serviceReady" | The submodule is ready. |
"serviceInProgress" | The submodule is running. |
"serviceCompleted" | All subscribed contents have been uploaded to the extension service. |
"servicePartialCompleted" | Part of the subscribed contents have been uploaded to the extension service. |
"serviceValidationFailed" | The validation of the extension service failed. For example, apiData is incorrect. |
"serviceAbnormal" | The submodule is in an abnormal status. |
This section lists the common errors you may encounter when using the Agora Cloud Recording RESTful APIs. If you encounter other errors, contact support@agora.io.
2
: Invalid parameter. Possible reasons:
7
: The recording is already running. Do not repeat the start
request with the same resource ID.
8
: Errors in the HTTP request header fields. Possible reasons:
Content-type
field is application/json;charset=utf-8
.cloud_recording
is missing in the request URL.49
: Caused by repeated stop
requests with the same resource ID and recording ID (sid).
53
: The recording is already running. This error occurs when you use the same parameters to call acquire
again and use the new resource ID in the start
request. To start multiple recording instances, use a different UID for each instance.
62
: If you receive this error when calling acquire
, the cloud recording service is not enabled. See Enable Cloud Recording for details.
65
: Usually caused by network jitter. Retry with the same resource ID. Agora recommends that you use a backoff strategy, for example, retry after 3 and 6 seconds successively.
432
: The parameter in the request is incorrect. Either the parameter is invalid, or the App ID, channel name, or UID does not match the resource ID.
433
: The resource ID has expired. You need to start recording within five minutes after getting a resource ID. Call acquire to get a new resource ID.
435
: No recorded files created. There is nothing to record because no user is sending any stream in the channel.
501
: The recording service is exiting. This error might occur when you call query after stop.
1001
: Fails to parse the resource ID. Call acquire to get a new resource ID.
1003
: The App ID or recording ID (sid) does not match the resource ID. Ensure that the App ID or recording ID matches the resource ID in each recording session.
1013
: The channel name is invalid. The string length must be less than 64 bytes. Supported character scopes are:
1028
: Invalid parameters in the request body of the updateLayout
method.
"invalid appid"
: The App ID you entered is invalid. If the error persists after you verify the App ID, contact support@agora.io.
"no Route matched with those values"
: A possible reason for this message is that you entered an incorrect HTTP method in your request, such as using GET when it should have been POST. Another possible reason is that you sent your request to a wrong URL.
"Invalid authentication credentials"
: The following list contains possible reasons for this message. If the error persists after you correct the following issues, contact support@agora.io:
Basic
is missing in the Authorization
field.Content-type
field. The correct value is application/json;charset=utf-8
.