Composite Recording

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

Set up the subscription list

By default, Agora Cloud Recording subscribes to all published audio and video streams in a channel. This feature enables you to create a whitelist or blacklist for audio and video subscriptions. You can also update the subscription lists during a cloud recording.
When the recording starts, set the parameters in start to create subscription lists. During the recording, set the streamSubscribe parameter in update to update the subscription lists.

Set up the subscription list for audio streams

Use either of the following parameters to set up a subscription list for audio:

• subscribeAudioUids: Specify the users whose audio streams you want to subscribe to. The setting creates a whitelist for audio subscription.
• unSubscribeAudioUids: Specify the users whose audio streams you do not want to subscribe to. The setting creates a blacklist for audio subscription.

Set up the subscription list for video streams

Use either of the following parameters to set up a subscription list for video:

• subscribeVideoUids: Specify the users whose video streams you want to subscribe to. The setting creates a whitelist for video subscription.
• unSubscribeVideoUids: Specify the users whose video streams you do not want to subscribe to. The setting creates a blacklist for video subscription.

Example

Suppose that four users, whose user IDs are 111, 222, 333, and 444, are in a channel when the recording begins, and two more users with unknown user IDs join the channel during the recording. The following lists the typical scenarios and recommended settings:

Set the video mixing layout

During a recording, you can call updateLayout method to update the video mixing layout multiple times. For details of video layout types, see Set Video Layout.

This method call overrides the existing layout configurations. For example, if you set the backgroundColor parameter as "#FF0000" (red) when starting a recording and call this method to update the layout without setting the backgroundColor parameter, the background color changes back to black (the default value).

Request example

• The request URL is:

https://api.agora.io/v1/apps/<appid>/cloud_recording/resourceid/<resourceid>/sid/<sid>/mode/<mode>/updateLayout

• Content-type is application/json;charset=utf-8.
• Authorization is the basic authorization, see RESTful API authentication for details.
• The request body:

{
    "uid": "527841",
    "cname": "httpClient463224",
    "clientRequest": {
        "mixedVideoLayout": 3,
        "backgroundColor": "#FF0000",
        "layoutConfig": [
        {
             "uid": "1",
             "x_axis": 0.1,
             "y_axis": 0.1,
             "width": 0.1,
             "height": 0.1,
             "alpha": 1.0,
             "render_mode": 1
         },
        {
             "uid": "2",
             "x_axis": 0.2,
             "y_axis": 0.2,
             "width": 0.1,
             "height": 0.1,
             "alpha": 1.0,
             "render_mode": 1
         }
         ]
     }
}

Response example

"Code": 200,
"Body":
{
    "sid": "38f8e3cfdc474cd56fc1ceba380d7e1a",
    "resourceId": "JyvK8nXHuV1BE64GDkAaBGEscvtHW7v8BrQoRPCHxmeVxwY22-x-kv4GdPcjZeMzoCBUCOr9q-k6wBWMC7SaAkZ_4nO3JLqYwM1bL1n6wKnnD9EC9waxJboci9KUz2WZ4YJrmcJmA7xWkzs_L3AnNwdtcI1kr_u1cWFmi9BWAWAlNd7S7gfoGuH0tGi6CNaOomvr7-ILjPXdCYwgty1hwT6tbAuaW1eqR0kOYTO0Z1SobpBxu1czSFh1GbzGvTZG"
}

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.