This guide includes the key steps in using the Cloud Recording RESTful API to make a composite recording. For more information, see Agora Cloud Recording RESTful API Quickstart.
Agora Cloud Recording supports three recording modes:
In composite recording mode, the audio and video of multiple user IDs in a channel are recorded in a single file.
For example, if a channel has two users, and you choose to record both audio and video, Agora Cloud Recording generates files as shown in the following diagram:
The recording service generates one M3U8 file and multiple TS files. If you set avFileType
as ["hls","mp4"]
when calling the start
method, the recording service also generates MP4 files, which include the audio and video of all users in the channel.
Before recording, call the acquire
method to apply for a resource ID.
acquire
https://api.agora.io/v1/apps/<yourappid>/cloud_recording/acquire
Content-type
: application/json;charset=utf-8
Authorization
: Basic authorization. For more information, see How to pass the basic HTTP authentication.{
"cname": "httpClient463224",
"uid": "527841",
"clientRequest": {
"resourceExpiredHour": 24,
"scene": 0
}
}
To enable composite recording mode, set mode
to mix
when calling start
. Use recordingConfig
to configure composite recording, and use storageConfig
to configure your third-party cloud storage.
In composite recording mode, you can configure the following parameters in clientRequest
:
Parameter | Description | Note |
---|---|---|
token |
The dynamic key used for the channel to record. | Required if the channel uses a token |
recordingConfig |
Configures stream subscription, transcoding, and the profile of the output audio and video. | Required |
recordingFileConfig |
Configures the recorded files. | Optional |
storageConfig |
Configures the third-party cloud storage. | Required |
start
https://api.agora.io/v1/apps/<yourappid>/cloud_recording/resourceid/<resourceid>/mode/mix/start
Content-type
: application/json;charset=utf-8
Authorization
: Basic authorization. For more information, see How to pass the basic HTTP authentication.{
"uid": "527841",
"cname": "httpClient463224",
"clientRequest": {
"token": "<token if any>",
"recordingConfig": {
"maxIdleTime": 30,
"streamTypes": 2,
"audioProfile": 1,
"channelType": 0,
"videoStreamType": 0,
"transcodingConfig": {
"height": 640,
"width": 360,
"bitrate": 500,
"fps": 15,
"mixedVideoLayout": 1,
"backgroundColor": "#FF0000"
},
"subscribeVideoUids": [
"123",
"456"
],
"subscribeAudioUids": [
"123",
"456"
],
"subscribeUidGroup": 0
},
"storageConfig": {
"accessKey": "xxxxxxf",
"region": 3,
"bucket": "xxxxx",
"secretKey": "xxxxx",
"vendor": 2,
"fileNamePrefix": [
"directory1",
"directory2"
]
}
}
}
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.
stop
The request URL is:
http://api.agora.io/v1/apps/<yourappid>/cloud_recording/resourceid/<resourceid>/sid/<sid>/mode/mix/stop
Content-type
: application/json;charset=utf-8
Authorization
: Basic authorization. For more information, see How to pass the basic HTTP authentication.
Request body:
{
"cname": "httpClient463224",
"uid": "527841",
"clientRequest": {}
}
The content of the recorded files varies according to the setting of streamTypes
. See the table below:
Recorded content | Settings | Recorded files |
---|---|---|
Audio only | Set streamTypes as 0 |
One M3U8 file, several TS files, and one or more MP4 files if you set avFileType as ["hls","mp4"] . The TS files and MP4 files store the audio. |
Video only | Set streamTypes as 1 |
One M3U8 file, several TS files, and one or more MP4 files if you set avFileType as ["hls","mp4"] . The TS files and MP4 files store the video. |
Audio and video | Set streamTypes as 2 (default) |
One M3U8 file, several TS files, and one or more MP4 files if you set avFileType as ["hls","mp4"] . The TS files and MP4 files store the audio and video. |
For detailed information about the naming conventions of the recorded files, see Manage Recorded Files.
A Web client and a Native client have different display strategies when they stop publishing streams or leave the channel. See the table below for details.
Type of the publisher | The client unpublishes the local video stream (unpublish ) |
The client disables the video track (muteVideo /setEnabled ) |
The client leaves the channel |
---|---|---|---|
Native client | Displays the background color of the canvas (backgroundColor ). |
||
Web client | For the Web SDK 3.x and earlier, the background image (backgroundImage ) or background color (backgroundColor ) of the canvas is displayed, see Set the background image. |
For the Web SDK 3.x and earlier, a black screen is displayed. | Displays the background color of the canvas (backgroundColor ). |
For the Web SDK 4.x and later, |
For the Web SDK 4.x and later, |
Displays the background color of the canvas (backgroundColor ). |