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 UIDs 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 one M3U8 file and several TS files in total, as shown in the following diagram:

After merging the files using the Audio & Video File Merging script, the two users' audio and video are stored together 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": "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": 1, 
            "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"]
       }
   }
}

Recorded files

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

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

Considerations

• If a Web user never publishes local video, or unpublishes video during a recording session, the recording service fills the video of that user with the color of the canvas; if the user disables local video, the video turns black.
• If a Native user stops sending video streams during a recording session, the video of that user shows the last frame; if the user leaves the channel, the recording service fills the video of that user with the color of the canvas.