This guide includes the key steps in using the Cloud Recording RESTful API to make an individual recording. For more information, see Agora Cloud Recording RESTful API Quickstart.
Agora Cloud Recording supports three recording modes:
In individual recording mode, the audio and video of each user ID in a channel are recorded in separate files.
Agora recommends that you use the standard mode when you start individual recording, and get audio and video files that can be played directly for each user IDs after the recording stops. For details, see Start recording.
For example, if a channel has two users and you choose to record both audio and video, the files generated for standard mode of individual recording is shown in the following diagram:
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.
Request body:
{
"cname": "https://xxxxx",
"uid": "527841",
"clientRequest": {
"resourceExpiredHour": 24,
"scene": 0
}
}
To enable individual recording mode, set mode
to individual
when calling start
. Use recordingConfig
to configure individual recording, and use storageConfig
to configure your third-party cloud storage.
Agora recommends that you use the standard mode when you start recording, that is, set the streamMode
field in the recordingConfig
parameter to standard
to generate combined audio and video files that can be played directly.
In individual recording mode, you can configure the following parameters in clientRequest
:
Parameter | Description | Note |
---|---|---|
token |
String. The dynamic key used for the channel to record. | Required if the channel uses a token |
recordingConfig |
JSON. Configures stream subscription, transcoding, and the profile of the output audio and video. | Required |
recordingConfig.streamMode |
String. The output mode of the media stream in individual recording mode. | Optional. Agora recommends that you set the streamMode as standard . |
recordingFileConfig |
JSON. Configures the recorded files. | Optional |
storageConfig |
JSON. Configures the third-party cloud storage. | Required |
start
https://api.agora.io/v1/apps/<yourappid>/cloud_recording/resourceid/<resourceid>/mode/individual/start
Content-type
: application/json;charset=utf-8
Authorization
: Basic authorization. For more information, see How to pass the basic HTTP authentication.Real-time recording for standard mode
{
"uid": "527841",
"cname": "httpClient463224",
"clientRequest": {
"token": "<token if any>",
"recordingConfig": {
"maxIdleTime": 30,
"streamTypes": 2,
"streamMode": "standard",
"channelType": 0,
"videoStreamType": 0,
"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/individual/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": {}
}
In individual recording mode, the audio and video profiles of the recorded file are as follows:
The recorded files vary according to the recorded content. See the table below.
Recorded content | Settings | Recorded files |
---|---|---|
Audio only | Set streamTypes to 0 |
One M3U8 file and several TS files for each user ID. The TS files store the audio. |
Video only | Set streamTypes to 1 |
One M3U8 file and several TS/WebM files for each user ID. The TS/WebM files store the video. |
Audio and video, and standard mode | Set streamTypes to 2 and streamMode to standard 。 |
One M3U8 audio index file, one M3U8 video index file, a combined M3U8 audio and video index file, multiple TS audio slice files and multiple TS video slice files are generated per user ID. If VP8 encoding is used on the web side, a combined MPD audio and video index file and multiple WebM video slice files are generated per user ID. |
For detailed information about the naming conventions of the recorded files, see Manage Recorded Files.
streamMode
to standard
), if you switch the native side to the web side (or vice versa) during the recording process, two combined audio and video index files in M3U8 format and MPD format are generated after recording, and the whole recording process cannot be played continuously.Publisher | Ways to disable the video track | Recording effects |
---|---|---|
Web SDK 3.x | Call muteVideo method |
Generates video slices for this user that is simply a black screen. |
Web SDK 4.x | Call setEnabled method |
Displays the last frame on the user screen in this slice and does not continue to generate video slices. |