Cloud recording

Feature overview

Cloud recording captures audio and video streams in ARTC channels through API-based tasks. Key features:

Versatile recording modes: Record each user individually (individual recording) or combine multiple users into one file (composite recording).
Flexible subscription: Record specific users or stream types (camera or screen sharing) within a channel.
Customizable output: Custom composite layouts, background images, and output formats (MP4, MP3, HLS).
Reliable cloud storage: Automatically uploads recordings to OSS or ApsaraVideo VOD.

Before you begin

Activate required services: Activate ARTC. Based on your storage method:
- Store to OSS: Activate OSS and create a bucket. Storage fees apply. Storage fees.
  
  Note
  Grant service permissions: ARTC requires write access to your OSS bucket, granted automatically on activation. If revoked, click Grant Cloud Resource Access Authorization to restore it.
- Store to VOD: Activate ApsaraVideo VOD and manage your storage bucket. Storage fees apply. Basic service billing.
Important
- Region consistency: The storage bucket and API endpoint must be in the same region.
- Recording file generation: After recording ends, files are saved to the bucket specified in your API request.
Understand billing:
- Cloud recording is enabled by default with no separate activation required.
- Cloud recording is a paid feature. Cloud Recording Fees.

Key concepts

Recording modes

Choose a recording mode based on your use case.

Individual recording

Records each user's audio and video into a separate file. Ideal for individual analysis or post-processing.
- By default, recording parameters match the original stream.
- If a stream is interrupted, the system fills with silence, a black screen, or the last frame to maintain continuity.
Composite recording

Mixes audio and video from multiple users into a single file. Suitable for multi-person scenarios such as meetings and online education.
- Customize output video resolution, bitrate, and frame rate.
- Custom video layouts (up to 17 panes) and canvas background images.
- If a user's stream is interrupted, their pane shows a preset background image or black screen.

Recording task lifecycle

Note

A task automatically stops after running for 72 hours (maximum lifecycle), regardless of status.
A stopped task triggers a stop callback. Use it to confirm the task ended and query recorded files.
If a task remains idle longer than MaxIdleTime, it stops automatically. Valid range: 10–14,400 seconds (4 hours). Default: 300 seconds.
- In composite mode, a task is idle when all subscribed streams stop publishing.
- In individual mode, each stream is tracked independently. A stream stops recording after its own MaxIdleTime elapses. The task stops only after all subscribed streams time out.

File generation and storage

Recording file formats

Audio-only: Supports MP3 and AAC formats.
Audio and video: Supports MP4 and HLS formats.

Note

An HLS file is always generated, even if not specified in the request.
Each additional file format incurs separate charges.

File naming rules

Recordings are stored under a TaskId directory in your specified OSS or ApsaraVideo VOD path. Customize filenames with preset variables.

Filename variables:

Parameter	Description
`AppId`	The application ID.
`ChannelId`	The channel ID.
`UserId`	The user ID. Valid only for individual recording.
`RecordMode`	The recording mode. 0: individual, 1: composite.
`StreamType`	The stream type. A: audio, V: video, AV: audio and video.
`SourceType`	The video source. C: camera, S: screen sharing.
`StartTime`	The UTC start time of the recording, in milliseconds.
`Sequence`	The index number of the HLS slice.

Default filenames:

Individual recording:
- HLS format: {AppId}_{ChannelId}_{UserId}_{StartTime}_{Sequence}
- Other formats: {AppId}_{ChannelId}_{UserId}_{StartTime}
Composite recording:
- HLS format: {AppId}_{ChannelId}_{StartTime}_{Sequence}
- Other formats: {AppId}_{ChannelId}_{StartTime}

Note

If you subscribe to different StreamType or SourceType values for the same UserId, {SourceType} is appended after {UserId} in the default filename.
When a file is named filename, the final path is TaskId/filename.M3U8. The TaskId, generated when the task starts, is automatically prepended to the storage path.

File slicing strategy

File slicing splits a recording into multiple files. Set the maximum slice duration with MaxFileDuration: 180–7,200 seconds (default: 7,200 seconds / 2 hours).

Procedure

The cloud recording workflow is fully API-driven. The following steps cover core operations with parameter examples.

Step 1: Start a recording task

Call the Start an ARTC cloud recording task API. Configure subscription, recording, and storage parameters in the request.

Key parameters:

Specify the recording mode: Choose individual (RecordMode: 0) or composite (RecordMode: 1).
Define subscription targets: In SubscribeParams, list the UserId and StreamType values to record.
Set the output format: In RecordParams, set audio-only (StreamType: 1) or audio-and-video (StreamType: 0).
Configure storage: In StorageParams, specify OSS or ApsaraVideo VOD and provide the bucket and endpoint.

Example scenarios

Individual audio-only recording

Scenario: In channel myRoom, there are three users: userA, userB, and userC. Record the audio streams of userA and userB individually, without recording userC. Also, generate both M3U8 and MP3 files.

Recording results: The recorded files are stored in the specified Object Storage Service (OSS) bucket, my-bucket. Files in M3U8 format are stored in the hls/{taskId} path, and files in MP3 format are stored in the mp3/{taskId} path.

Parameter example:

{
  "AppId": "my-app-id", // The AppId used for streaming
  "ChannelId": "myRoom", // The channel to record
  "SubscribeParams": {
    "SubscribeUserIdList": [
      {
        "UserId": "userA", // The user to be recorded
        "StreamType": 1 // Subscribe to audio-only stream
      },
      {
        "UserId": "userB", // The user to be recorded
        "StreamType": 1 // Subscribe to audio-only stream
      }
    ]
  },
  "RecordParams": {
    "RecordMode": 0, // Specify individual recording mode
    "StreamType": 1, // Specify audio-only output format
    "MaxFileDuration": 180 // Set the file slice duration to 180 seconds (3 minutes)
  },
  "StorageParams": {
    "StorageType": 1, // Specify storing to OSS
    "FileInfo": [ // Generate M3U8 and MP3 files, storing them under "hls" and "mp3" paths respectively
      {
        "Format": "HLS",
        "FilePathPrefix": [
          "hls"
        ]
      },
      {
        "Format": "MP3",
        "FilePathPrefix": [
          "mp3"
        ]
      }
    ],
    "OSSParams": {
      "OSSEndpoint": "oss-cn-shanghai.aliyuncs.com",
      "OSSBucket": "my-bucket"
    }
  },
  "NotifyUrl": "http://mytest/callback", // Optional: The URL to receive callback messages
  "NotifyAuthKey": "12345678abcdefghikj" // Optional: The authentication key for callback messages
}

Individual audio and video recording

Scenario: In channel myRoom, there are three users: userA, userB, and userC. Record the audio and video streams of userA and userB individually, without recording userC. Also, generate both M3U8 and MP4 files.

Recording results: The files are saved to the specified OSS bucket, my-bucket. M3U8 files are stored in the hls/{taskId} path, and MP4 files are stored in the mp4/{taskId} path.

Parameter example:

{
  "AppId": "my-app-id", // The AppId used for streaming
  "ChannelId": "myRoom", // The channel specified for streaming
  "SubscribeParams": {
    "SubscribeUserIdList": [
      {
        "UserId": "userA", // The user to be recorded
        "StreamType": 0 // Subscribe to audio and video stream
      },
      {
        "UserId": "userB", // The user to be recorded
        "StreamType": 0 // Subscribe to audio and video stream
      }
    ]
  },
  "RecordParams": {
    "RecordMode": 0, // Specify individual recording mode
    "StreamType": 0, // Specify audio and video output format
    "MaxFileDuration": 180 // Set the file slice duration to 180 seconds (3 minutes)
  },
  "StorageParams": {
    "StorageType": 1, // Specify storing to OSS
    "FileInfo": [ // Generate M3U8 and MP4 files, storing them under "hls" and "mp4" paths respectively
      {
        "Format": "HLS",
        "FilePathPrefix": [
          "hls"
        ]
      },
      {
        "Format": "MP4",
        "FilePathPrefix": [
          "mp4"
        ]
      }
    ],
    "OSSParams": {
      "OSSEndpoint": "oss-cn-shanghai.aliyuncs.com",
      "OSSBucket": "my-bucket"
    }
  },
  "NotifyUrl": "http://mytest/callback", // Optional: The URL to receive callback messages
  "NotifyAuthKey": "12345678abcdefghikj" // Optional: The authentication key for callback messages
}

Composite audio-only recording

Scenario: In channel myRoom, there are three users: userA, userB, and userC. Record the conversation between userA and userB as a single composite stream, without recording userC. Also, generate both M3U8 and MP3 files.

Recording results: The files are saved to the specified OSS bucket, my-bucket. M3U8 files are stored in the hls/{taskId} path, and MP3 files are stored in the mp3/{taskId} path.

Parameter example:

{
  "AppId": "my-app-id", // The AppId used for streaming
  "ChannelId": "myRoom", // The channel specified for streaming
  "SubscribeParams": {
    "SubscribeUserIdList": [
      {
        "UserId": "userA", // The user to be recorded
        "StreamType": 1 // Subscribe to audio-only stream
      },
      {
        "UserId": "userB", // The user to be recorded
        "StreamType": 1 // Subscribe to audio-only stream
      }
    ]
  },
  "RecordParams": {
    "RecordMode": 1, // Specify composite recording mode
    "StreamType": 1, // Specify audio-only output format
    "MaxFileDuration": 180 // Set the file slice duration to 180 seconds (3 minutes)
  },
  "StorageParams": {
    "StorageType": 1, // Specify storing to OSS
    "FileInfo": [ // Generate M3U8 and MP3 files, storing them under "hls" and "mp3" paths respectively
      {
        "Format": "HLS",
        "FilePathPrefix": [
          "hls"
        ]
      },
      {
        "Format": "MP3",
        "FilePathPrefix": [
          "mp3"
        ]
      }
    ],
    "OSSParams": {
      "OSSEndpoint": "oss-cn-shanghai.aliyuncs.com",
      "OSSBucket": "my-bucket"
    }
  },
  "MixTranscodeParams": {
    "AudioBitrate": 128, // Audio bitrate
    "AudioChannels": 2, // Number of audio channels
    "AudioSampleRate": 44100 // Sample rate
  },
  "NotifyUrl": "http://mytest/callback", // Optional: The URL to receive callback messages
  "NotifyAuthKey": "12345678abcdefghikj" // Optional: The authentication key for callback messages
}

Composite audio and video recording

Scenario: In channel myRoom, there are three users: userA, userB, and userC. Record the audio and camera streams of userA and userB, and only the audio stream of userC. Also, generate both M3U8 and MP4 files.

The resulting video arranges the panes for userA and userB as follows:

Recording results: The files are stored in the specified OSS my-bucket. M3U8 files are stored in the hls/{taskId} path, and MP4 files are stored in the mp4/{taskId} path.

Parameter example:

{
  "AppId": "my-app-id", // The AppId used for streaming
  "ChannelId": "myRoom", // The channel specified for streaming
  "SubscribeParams": {
    "SubscribeUserIdList": [
      {
        "UserId": "userA", // The user to be recorded
        "StreamType": 0, // Subscribe to audio and video stream
        "SourceType": 0 // Subscribe to camera stream
      },
      {
        "UserId": "userB", // The user to be recorded
        "StreamType": 0, // Subscribe to audio and video stream
        "SourceType": 0 // Subscribe to camera stream
      },
      {
        "UserId": "userC", // The user to be recorded
        "StreamType": 1 // Subscribe to audio-only stream
      }
    ]
  },
  "RecordParams": {
    "RecordMode": 1, // Specify composite recording mode
    "StreamType": 0, // Specify audio and video output format
    "MaxFileDuration": 180 // Set the file slice duration to 180 seconds (3 minutes)
  },
  "StorageParams": {
    "StorageType": 1, // Specify storing to OSS
    "FileInfo": [ // Generate M3U8 and MP4 files, storing them under "hls" and "mp4" paths respectively
      {
        "Format": "HLS",
        "FilePathPrefix": [
          "hls"
        ]
      },
      {
        "Format": "MP4",
        "FilePathPrefix": [
          "mp4"
        ]
      }
    ],
    "OSSParams": {
      "OSSEndpoint": "oss-cn-shanghai.aliyuncs.com",
      "OSSBucket": "my-bucket"
    }
  },
  "MixTranscodeParams": {
    "AudioBitrate": 128,
    "AudioChannels": 2,
    "AudioSampleRate": 44100,
    "VideoCodec": "H.264",
    "VideoBitrate": 500,
    "VideoFramerate": 30,
    "VideoGop": 30,
    "VideoHeight": 480, // Height of the final video
    "VideoWidth": 640 // Width of the final video
  },
  "MixLayoutParams": {
    "UserPanes": [
      {
        "userId": "userA",
        "sourceType": 0,
        "height": "1", // Occupies the full height of the canvas
        "width": "0.5", // Occupies half the width of the canvas
        // Positions the pane at the canvas's top-left corner
        "x": "0",
        "y": "0"
      },
      {
        "userId": "userB",
        "sourceType": 0,
        "height": "1", // Occupies the full height of the canvas
        "width": "0.5", // Occupies half the width of the canvas
        // Positions the pane starting at the canvas's horizontal midpoint
        "x": "0.5",
        "y": "0"
      }
    ]
  },
  "NotifyUrl": "http://mytest/callback", // Optional: The URL to receive callback messages
  "NotifyAuthKey": "12345678abcdefghikj" // Optional: The authentication key for callback messages
}

Step 2 (Optional): Update a recording task

Call the Update an ARTC cloud recording task API to change recording parameters while a task is running.

Note

Individual mode: Only subscription can be updated.
Composite mode: Both subscription and layout can be updated.

Step 3: Stop a recording task

To end the recording, call the Stop an ARTC cloud recording task API.

Note

The system processes and uploads final recording files after this call. The task is complete only after you receive the stop callback. Do not delete or modify storage resources before receiving it.

Step 4: Query tasks and files

Call the Query ARTC cloud recording files and task status API to check task status and recorded files.

Note

Only existing tasks can be queried. The API returns an error for nonexistent tasks.
Recording file information is available for tasks that started successfully and ran for less than 72 hours. The API returns an error after 72 hours.