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.

Overview

Agora Cloud Recording supports three recording modes:

• Individual recording
• Composite recording
• Web page recording

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.

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": "httpClient463224",
    "uid": "527841",
    "clientRequest": {
        "resourceExpiredHour": 24,
        "scene": 0
    }
}

Start recording

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:

An HTTP request example of start

• Request URL:

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

{
    "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"
            ]
        }
    }
}

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/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": {}
}

Recorded files

The content of the recorded files varies according to the setting of streamTypes. See the table below:

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

Considerations

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.