Individual Recording

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.

Agora recommends that you use the standard mode when you start individual recording, and get audio and video files that can be played directly for each user IDs after the recording stops. For details, see Start recording.

For example, if a channel has two users and you choose to record both audio and video, the files generated for standard mode of individual recording is shown in the following diagram:

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.

Agora recommends that you use the standard mode when you start recording, that is, set the streamMode field in the recordingConfig parameter to standard to generate combined audio and video files that can be played directly.

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 for standard mode

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

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:

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.

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

Considerations

• Use standard mode to record (set streamMode to standard), if you switch the native side to the web side (or vice versa) during the recording process, two combined audio and video index files in M3U8 format and MPD format are generated after recording, and the whole recording process cannot be played continuously.
• 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:

  Publisher	Ways to disable the video track	Recording effects
  Web SDK 3.x	Call muteVideo method	Generates video slices for this user that is simply a black screen.
  Web SDK 4.x	Call setEnabled method	Displays the last frame on the user screen in this slice and does not continue to generate video slices.