Individual recording
Updated
Use the Cloud Recording RESTful API to make an individual recording
This guide includes the key steps in using the Cloud Recording RESTful API to make an individual recording and generate files in specific formats. For more information, see Get started.
Agora Cloud Recording supports three recording modes:
- Individual recording
- Composite recording
- Web page recording
In individual recording mode, the audio and video of each user ID in a channel are recorded in separate files.
If you use legacy individual recording, where the mode path parameter in the request URL is individual, see Legacy individual recording. To move to the current version, see Migrate from legacy individual recording.
Prerequisites
Before you start, follow the REST quickstart to complete a full recording workflow.
Implementation
Get a resource ID
Before recording, call the acquire method to get a resource ID.
The following example requests a resource ID for the httpClient463224 channel. Replace <appid> with your App ID and <credentials> with your Base64-encoded credentials. For more information, see How to pass the basic HTTP authentication.
curl --request POST \
--url 'https://api.agora.io/v1/apps/<appid>/cloud_recording/acquire' \
--header 'Authorization: Basic <credentials>' \
--header 'Content-Type: application/json;charset=utf-8' \
--data '{
"cname": "httpClient463224",
"uid": "527841",
"clientRequest": {
"resourceExpiredHour": 24,
"scene": 0
}
}'Start recording
To enable individual recording mode, set mode to raw when calling start. Use recordingConfig to configure stream subscription, recordingFileConfig to configure the recorded file types, and storageConfig to configure your third-party cloud storage.
Set the recording mode when you start the recording. You cannot switch the mode after the recording starts.
In individual recording mode, you can configure the following parameters in clientRequest:
| Parameter | Description | Required |
|---|---|---|
token | String. The dynamic key used for the channel to record. | Required if the channel uses a token |
recordingConfig | JSON. Configures stream subscription and the profile of the output audio and video. | Required |
recordingConfig.streamTypes | Number. The type of media stream to subscribe to: 0 for audio only, 1 for video only, or 2 for audio and video. | Optional. Defaults to 2 (audio and video). |
recordingFileConfig | JSON. Configures the recorded file types in avFileType. | Required, unless you only take screenshots |
storageConfig | JSON. Configures the third-party cloud storage. | Required |
The files that the recording service generates depend on the combination of recordingConfig.streamTypes and recordingFileConfig.avFileType. The recorded files use the following standard formats, which can be played directly:
- HLS: one M3U8 file and multiple TS files.
- DASH: one MPD file and multiple WebM files.
The recording service always generates HLS or DASH files. In addition, it can generate MP3 files when you record audio only, and MP4 files when you record video only or audio and video. The following tabs show the avFileType options for each case:
avFileType | Recorded files |
|---|---|
["hls"] | One HLS file for each user ID, containing only that user's audio. |
["hls","mp3"] | Two sets of files for each user ID: one HLS file containing only that user's audio, and one MP3 file. |
["mp3"] | Not supported. |
avFileType | Recorded files |
|---|---|
["hls"] | One HLS or DASH file for each user ID, depending on the video codec of the source stream. Each slice contains only that user's video. |
["hls","mp4"] | Two sets of files for each user ID: one HLS or DASH file, depending on the video codec of the source stream, with each slice containing only that user's video; and one MP4 file. MP4 generation has known limitations. For details, see Generate MP4 files directly. |
["mp4"] | Not supported. |
avFileType | Recorded files |
|---|---|
["hls"] | One HLS or DASH file for each user ID, depending on the video codec of the source stream. Each slice contains both that user's audio and video. |
["hls","mp4"] | Two sets of files for each user ID: one HLS or DASH file, depending on the video codec of the source stream, with each slice containing both that user's audio and video; and one MP4 file. MP4 generation has known limitations. For details, see Generate MP4 files directly. |
["mp4"] | Not supported. |
For the naming conventions, field definitions, and slicing rules of the recorded files, see Manage recorded files.
The following example records the audio and video of two users and generates HLS and MP4 files. To keep the number of MP4 files to a minimum, the source stream must meet certain requirements. For details, see Generate MP4 files directly. Replace <resourceid> with the resource ID that acquire returns, and use the same cname and uid values as in the acquire request.
curl --request POST \
--url 'https://api.agora.io/v1/apps/<appid>/cloud_recording/resourceid/<resourceid>/mode/raw/start' \
--header 'Authorization: Basic <credentials>' \
--header 'Content-Type: application/json;charset=utf-8' \
--data '{
"cname": "httpClient463224",
"uid": "527841",
"clientRequest": {
"token": "<token if any>",
"recordingConfig": {
"maxIdleTime": 30,
"streamTypes": 2,
"channelType": 0,
"videoStreamType": 0,
"subscribeVideoUids": ["123", "456"],
"subscribeAudioUids": ["123", "456"],
"subscribeUidGroup": 0
},
"recordingFileConfig": {
"avFileType": ["hls", "mp4"]
},
"storageConfig": {
"vendor": 2,
"region": 3,
"bucket": "xxxxx",
"accessKey": "xxxxx",
"secretKey": "xxxxx",
"fileNamePrefix": ["directory1", "directory2"]
}
}
}'If the request succeeds, the response is similar to the following:
{
"cname": "httpClient463224",
"uid": "527841",
"resourceId": "SGXETXXX",
"sid": "04a85XXX"
}Copy the sid value. You need it to stop the recording.
Stop recording
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 following example stops the recording synchronously. Replace <resourceid> and <sid> with the values that acquire and start return.
curl --request POST \
--url 'https://api.agora.io/v1/apps/<appid>/cloud_recording/resourceid/<resourceid>/sid/<sid>/mode/raw/stop' \
--header 'Authorization: Basic <credentials>' \
--header 'Content-Type: application/json;charset=utf-8' \
--data '{
"cname": "httpClient463224",
"uid": "527841",
"clientRequest": {
"async_stop": false
}
}'If the request succeeds, the response is similar to the following:
{
"resourceId": "SGXETXXX",
"sid": "04a85XXX",
"serverResponse": {
"fileListMode": "json",
"fileList": [
{
"fileName": "xxxxxxx",
"isPlayable": true,
"mixedAllUser": false,
"sliceStartTime": 1700000000000,
"trackType": "audio_and_video",
"uid": "xxx"
}
],
"uploadingStatus": "uploaded"
},
"cname": "httpClient463224",
"uid": "527841"
}The uploadingStatus field indicates the upload status of the recorded files:
uploaded: The recorded files have been uploaded to the third-party cloud storage.stranded: Added in individual recording v2. Some recorded files have not yet been uploaded to your third-party cloud storage. The recording service keeps retrying the upload automatically until it succeeds, and the files are not lost. Treat the recording as not fully uploaded, and wait until the upload completes before you play or process files that depend on the complete recording.
Generate MP4 files directly
In individual recording mode, the recording service does not transcode video. To generate MP4 files that can be played directly, and to keep the number of MP4 files to a minimum, the source stream must meet the following conditions:
- The video codec of the source stream is H.264, H.265, or AV1. If the source stream uses VP8 or VP9, MP4 files cannot be generated.
- The resolution of the source stream stays the same.
To keep the resolution of the source stream unchanged, configure the sender as follows:
Call setVideoEncoderConfiguration and set the following parameters:
- Set
orientationModeto1(ORIENTATION_MODE_FIXED_LANDSCAPE) or2(ORIENTATION_MODE_FIXED_PORTRAIT) to fix the video in landscape or portrait mode. - Set
degradationPreferenceto3(MAINTAIN_RESOLUTION) to keep the resolution unchanged, or to100to disable dynamic resolution adjustment.
Call setOptimizationMode and set the mode to "detail". This mode prioritizes clarity: in poor network conditions, the SDK reduces the frame rate rather than the resolution.
If the source stream cannot meet these requirements and its resolution changes during the recording, the recording service generates a separate MP4 file before and after each change. For the file names, see Manage recorded files.
If you cannot guarantee a fixed resolution for the source stream and cannot accept multiple MP4 files, or if the source stream uses VP8 or VP9, use composite recording instead. Composite recording transcodes in real time during the recording to maximize MP4 file compatibility.
Considerations
If the sender disables the video track during the recording, the recording effects are as follows:
| Sender | Ways to disable the video track | Recording effects |
|---|---|---|
| Native | Call muteLocalVideoStream or disableVideo | Displays the last frame on the user screen in this slice and does not continue to generate video slices. |
| Web SDK 4.x | Call setEnabled | Displays the last frame on the user screen in this slice and does not continue to generate video slices. |
Migrate from legacy individual recording
To migrate from legacy individual recording, update how your app processes the recorded files, and make the following changes:
- In the request URLs of
start,update,query, andstop, changemode/individualtomode/raw. - Remove
recordingConfig.streamMode. The current version does not supportstandard,default, ororiginal. - Remove
clientRequest.extensionServiceConfig. Requests that contain this field are rejected. - If you use notifications, identify individual recording callbacks by the
payload.serviceScenevaluertsc/raw-recordinginstead ofrtc_recordorrtc_snapshot. Otherwise, your app might ignore these callbacks. - Remove any dependency on event 33 (
uploading_progress). Individual recording does not send this event. - Handle the
strandedvalue ofuploadingStatusin thestopresponse. For details, see Stop recording.
FAQs
- How does an app crash affect cloud recording?
- How to choose the appropriate cloud storage bucket region and address cross-region upload challenges?
- Why can't I call the Cloud Recording RESTful API from a browser?
- Why are there no recorded files in the cloud storage?
- How can I get the URL of the M3U8 file?
- How does Cloud Recording handle a disconnected server or a killed process?
