Individual recording

Updated

Use the Cloud Recording RESTful API to make an individual recording

This guide includes the key steps in using the Cloud Recording RESTful API to make an individual recording and generate files in specific formats. For more information, see Get started.

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.

If you use legacy individual recording, where the mode path parameter in the request URL is individual, see Legacy individual recording. To move to the current version, see Migrate from legacy individual recording.

Prerequisites

Before you start, follow the REST quickstart to complete a full recording workflow.

Implementation

Get a resource ID

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

The following example requests a resource ID for the httpClient463224 channel. Replace <appid> with your App ID and <credentials> with your Base64-encoded credentials. For more information, see How to pass the basic HTTP authentication.

Example acquire request
curl --request POST \
  --url 'https://api.agora.io/v1/apps/<appid>/cloud_recording/acquire' \
  --header 'Authorization: Basic <credentials>' \
  --header 'Content-Type: application/json;charset=utf-8' \
  --data '{
    "cname": "httpClient463224",
    "uid": "527841",
    "clientRequest": {
      "resourceExpiredHour": 24,
      "scene": 0
    }
  }'

Start recording

To enable individual recording mode, set mode to raw when calling start. Use recordingConfig to configure stream subscription, recordingFileConfig to configure the recorded file types, and storageConfig to configure your third-party cloud storage.

Set the recording mode when you start the recording. You cannot switch the mode after the recording starts.

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

ParameterDescriptionRequired
tokenString. The dynamic key used for the channel to record.Required if the channel uses a token
recordingConfigJSON. Configures stream subscription and the profile of the output audio and video.Required
recordingConfig.streamTypesNumber. The type of media stream to subscribe to: 0 for audio only, 1 for video only, or 2 for audio and video.Optional. Defaults to 2 (audio and video).
recordingFileConfigJSON. Configures the recorded file types in avFileType.Required, unless you only take screenshots
storageConfigJSON. Configures the third-party cloud storage.Required

The files that the recording service generates depend on the combination of recordingConfig.streamTypes and recordingFileConfig.avFileType. The recorded files use the following standard formats, which can be played directly:

  • HLS: one M3U8 file and multiple TS files.
  • DASH: one MPD file and multiple WebM files.

The recording service always generates HLS or DASH files. In addition, it can generate MP3 files when you record audio only, and MP4 files when you record video only or audio and video. The following tabs show the avFileType options for each case:

avFileTypeRecorded files
["hls"]One HLS file for each user ID, containing only that user's audio.
["hls","mp3"]Two sets of files for each user ID: one HLS file containing only that user's audio, and one MP3 file.
["mp3"]Not supported.
avFileTypeRecorded files
["hls"]One HLS or DASH file for each user ID, depending on the video codec of the source stream. Each slice contains only that user's video.
["hls","mp4"]Two sets of files for each user ID: one HLS or DASH file, depending on the video codec of the source stream, with each slice containing only that user's video; and one MP4 file. MP4 generation has known limitations. For details, see Generate MP4 files directly.
["mp4"]Not supported.
avFileTypeRecorded files
["hls"]One HLS or DASH file for each user ID, depending on the video codec of the source stream. Each slice contains both that user's audio and video.
["hls","mp4"]Two sets of files for each user ID: one HLS or DASH file, depending on the video codec of the source stream, with each slice containing both that user's audio and video; and one MP4 file. MP4 generation has known limitations. For details, see Generate MP4 files directly.
["mp4"]Not supported.

For the naming conventions, field definitions, and slicing rules of the recorded files, see Manage recorded files.

The following example records the audio and video of two users and generates HLS and MP4 files. To keep the number of MP4 files to a minimum, the source stream must meet certain requirements. For details, see Generate MP4 files directly. Replace <resourceid> with the resource ID that acquire returns, and use the same cname and uid values as in the acquire request.

Example start request
curl --request POST \
  --url 'https://api.agora.io/v1/apps/<appid>/cloud_recording/resourceid/<resourceid>/mode/raw/start' \
  --header 'Authorization: Basic <credentials>' \
  --header 'Content-Type: application/json;charset=utf-8' \
  --data '{
    "cname": "httpClient463224",
    "uid": "527841",
    "clientRequest": {
      "token": "<token if any>",
      "recordingConfig": {
        "maxIdleTime": 30,
        "streamTypes": 2,
        "channelType": 0,
        "videoStreamType": 0,
        "subscribeVideoUids": ["123", "456"],
        "subscribeAudioUids": ["123", "456"],
        "subscribeUidGroup": 0
      },
      "recordingFileConfig": {
        "avFileType": ["hls", "mp4"]
      },
      "storageConfig": {
        "vendor": 2,
        "region": 3,
        "bucket": "xxxxx",
        "accessKey": "xxxxx",
        "secretKey": "xxxxx",
        "fileNamePrefix": ["directory1", "directory2"]
      }
    }
  }'

If the request succeeds, the response is similar to the following:

Example start response
{
    "cname": "httpClient463224",
    "uid": "527841",
    "resourceId": "SGXETXXX",
    "sid": "04a85XXX"
}

Copy the sid value. You need it to stop the recording.

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.

The following example stops the recording synchronously. Replace <resourceid> and <sid> with the values that acquire and start return.

Example stop request
curl --request POST \
  --url 'https://api.agora.io/v1/apps/<appid>/cloud_recording/resourceid/<resourceid>/sid/<sid>/mode/raw/stop' \
  --header 'Authorization: Basic <credentials>' \
  --header 'Content-Type: application/json;charset=utf-8' \
  --data '{
    "cname": "httpClient463224",
    "uid": "527841",
    "clientRequest": {
      "async_stop": false
    }
  }'

If the request succeeds, the response is similar to the following:

Example stop response
{
    "resourceId": "SGXETXXX",
    "sid": "04a85XXX",
    "serverResponse": {
        "fileListMode": "json",
        "fileList": [
            {
                "fileName": "xxxxxxx",
                "isPlayable": true,
                "mixedAllUser": false,
                "sliceStartTime": 1700000000000,
                "trackType": "audio_and_video",
                "uid": "xxx"
            }
        ],
        "uploadingStatus": "uploaded"
    },
    "cname": "httpClient463224",
    "uid": "527841"
}

The uploadingStatus field indicates the upload status of the recorded files:

  • uploaded: The recorded files have been uploaded to the third-party cloud storage.
  • stranded: Added in individual recording v2. Some recorded files have not yet been uploaded to your third-party cloud storage. The recording service keeps retrying the upload automatically until it succeeds, and the files are not lost. Treat the recording as not fully uploaded, and wait until the upload completes before you play or process files that depend on the complete recording.

Generate MP4 files directly

In individual recording mode, the recording service does not transcode video. To generate MP4 files that can be played directly, and to keep the number of MP4 files to a minimum, the source stream must meet the following conditions:

  • The video codec of the source stream is H.264, H.265, or AV1. If the source stream uses VP8 or VP9, MP4 files cannot be generated.
  • The resolution of the source stream stays the same.

To keep the resolution of the source stream unchanged, configure the sender as follows:

Call setVideoEncoderConfiguration and set the following parameters:

  • Set orientationMode to 1 (ORIENTATION_MODE_FIXED_LANDSCAPE) or 2 (ORIENTATION_MODE_FIXED_PORTRAIT) to fix the video in landscape or portrait mode.
  • Set degradationPreference to 3 (MAINTAIN_RESOLUTION) to keep the resolution unchanged, or to 100 to disable dynamic resolution adjustment.

Call setOptimizationMode and set the mode to "detail". This mode prioritizes clarity: in poor network conditions, the SDK reduces the frame rate rather than the resolution.

If the source stream cannot meet these requirements and its resolution changes during the recording, the recording service generates a separate MP4 file before and after each change. For the file names, see Manage recorded files.

If you cannot guarantee a fixed resolution for the source stream and cannot accept multiple MP4 files, or if the source stream uses VP8 or VP9, use composite recording instead. Composite recording transcodes in real time during the recording to maximize MP4 file compatibility.

Considerations

If the sender disables the video track during the recording, the recording effects are as follows:

SenderWays to disable the video trackRecording effects
NativeCall muteLocalVideoStream or disableVideoDisplays the last frame on the user screen in this slice and does not continue to generate video slices.
Web SDK 4.xCall setEnabledDisplays the last frame on the user screen in this slice and does not continue to generate video slices.

Migrate from legacy individual recording

To migrate from legacy individual recording, update how your app processes the recorded files, and make the following changes:

  • In the request URLs of start, update, query, and stop, change mode/individual to mode/raw.
  • Remove recordingConfig.streamMode. The current version does not support standard, default, or original.
  • Remove clientRequest.extensionServiceConfig. Requests that contain this field are rejected.
  • If you use notifications, identify individual recording callbacks by the payload.serviceScene value rtsc/raw-recording instead of rtc_record or rtc_snapshot. Otherwise, your app might ignore these callbacks.
  • Remove any dependency on event 33 (uploading_progress). Individual recording does not send this event.
  • Handle the stranded value of uploadingStatus in the stop response. For details, see Stop recording.

FAQs

See also