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.

Overview

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.

For example, if a channel has two users and you choose to record both audio and video, Agora Cloud Recording generates two M3U8 files and several TS/WebM files for each user to store the audio and video separately, as is shown in the following diagram:

After merging the files using the Audio & Video File Merging script, each user's audio and video are stored in one MP4 file.

Implementation

Get a resource ID

Before recording, call the acquire method to apply for a resource ID.

An HTTP request example of acquire

• Request URL:

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
    }
}

Start recording

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.

In individual recording mode, you can configure the following parameters in clientRequest:

An HTTP request example of start

• Request URL:

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.
• Request body:

Real-time recording

{
    "uid": "527841",
    "cname": "httpClient463224",
    "clientRequest": {
        "token": "<token if any>",
        "recordingConfig": {
            "maxIdleTime": 30,
            "streamTypes": 2,
            "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"
            ]
        }
    }
}

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.

An HTTP request example of 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": {}
}

Recorded files

In individual recording mode, the audio and video profiles of the recorded file are as follows:

• Audio profile: The sample rate is 48 kHz, and the bitrate and number of audio channels are the same as those of the original audio stream.
• Video profile: The video profile of the recorded file is the same as that of the original video stream.

The recorded files vary according to the recorded content. See the table below.

If you choose the VP8 codec when recording a Web call in individual recording mode, Agora Cloud Recording generates WebM files instead of TS files. Otherwise, Agora Cloud Recording generates TS files.

For detailed information about the naming conventions of the recorded files, see Manage Recorded Files.

Considerations

The recording effects of Web SDK 3.x and Web SDK 4.x are different after disabling the video track. See the table below for details: