Cloud recording and live streaming

Get the default recording configuration

POST /server/v1/mcu/record-config Authentication: required (see Overview) Query the app’s current default recording configuration (layout, watermark, and user name label position). No request parameters; the configuration is per app and determined by the app identity from authentication. When a task is started without layout_data, this configuration is used—put your standard watermark, labels, and layout strategy here, so you don’t have to pass them every time you start a task. Request parameters None Response parameters

string

App ID

string

Layout type: auto, full, grids_2, grids_4, …

integer

Watermark type: 0 default, 1 none, 2 single row, 3 multiple rows

string

Label position in each view, a letter or combination: L left, R right, T top, B bottom; empty disables labels

integer

Configuration creation time, Unix timestamp in seconds Example: 1718194666

integer

Configuration last-modified time, Unix timestamp in seconds Example: 1718194705

Response example:

{
  "code": 0,
  "data": {
    "app_id": "",
    "created_at": 1718194666,
    "layout": "",
    "updated_at": 1718194705,
    "watermark_type": 0,
    "window_tag_type": ""
  }
}

Update the default recording configuration

POST /server/v1/mcu/save-record-config Authentication: required (see Overview) Update the app’s default recording configuration. All three fields are optional; pass only what you want to change. Changes affect only new tasks started afterward; in-progress tasks are not affected. Request parameters

string

Layout type: auto (automatic), full (full screen), right_4 (small views on the right), top_4 (small views on top), br_7 (bottom L-shape), tl_7 (top L-shape), tb_8 (side-by-side), plus equal grids grids_N (N is 2, 3, 4, 5, 6, 8, 9, 12, 16, 20, 25) Example: auto

integer

Watermark type: 0 default, 1 none, 2 single row, 3 multiple rows Example: 1

string

Position of the user name label on each view, a letter or combination: L left, R right, T top, B bottom (such as LB for bottom left); empty means no label (max length 2) Example: L

Request example:

{
  "layout": "auto",
  "watermark_type": 1,
  "window_tag_type": "L"
}

Response parameters data is null Response example:

{
  "code": 0,
  "data": null
}

List recording tasks

POST /server/v1/mcu/list-task Authentication: required (see Overview) List recording tasks with pagination. One recording = one task, and a task may have multiple recording files (it rolls over to a new segment when the segment duration is exceeded, and resuming after an interruption also starts a new segment). This endpoint returns only the tasks themselves. To get playable files, use “Get recording task details” (which inlines all files and URLs) or “List recording files”. Use task_status to tell in-progress tasks from ended ones; record_count is the number of files produced. Request parameters

string

Channel; empty means no filter (up to 64 bytes; letters, digits, underscores (_), and hyphens (-) only) Example: fire

string

External meeting number; empty means no filter (max length 50) Example: 818595664

integer

Task status; omit for no filter: 0 pending, 1 in progress, 2 stopping, 3 ended abnormally, 4 ended normally Example: 4

string

Recording title, fuzzy match; empty means no filter (max length 100) Example: Weekly sync

string

Tag, fuzzy match; empty means no filter (max length 50) Example: R&D

integer

Start time, Unix timestamp in seconds, filtered by task creation time; 0 means no limit Example: 1718194666

integer

End time, Unix timestamp in seconds; 0 means no limit Example: 1718799878

integer

Page number, starting from 1 Example: 1

integer

Page size Example: 10

Request example:

{
  "begin_at": 1718194666,
  "channel": "fire",
  "end_at": 1718799878,
  "page": 1,
  "per-page": 10,
  "room_no": "818595664",
  "tag": "R&D",
  "task_status": 4,
  "title": "Weekly sync"
}

Response parameters

string

Task ID

string

Task initiator ID

string

Task initiator name

string

Channel

string

Channel title

string

External meeting number

integer

Task type: 1 video recording, 2 stream mixing, 4 audio recording, 8 live stream; combine as bit flags

integer

0 pending, 1 in progress, 2 stopping, 3 ended abnormally, 4 ended normally

string

Error description

integer

Recording start time, Unix timestamp in seconds; 0 means the underlying task hasn’t started running yet Example: 1718194666

integer

Recording end time, Unix timestamp in seconds; 0 means not ended Example: 1718216393

integer

Number of recording files. A recording that exceeds the segment duration (1 hour by default) or is resumed after an interruption produces additional files

integer

Total duration of all recording files (seconds) Example: 21727

integer

Total bytes of all recording files

string

Recording tags, comma-separated

array<object>

List of recording files, returned only by task details; null in the list endpoint

Show Element fields

string

Recording file ID, used to get the playback URL

string

ID of the recording task it belongs to

string

Channel

integer

Segment sequence number, starting from 1; sort by it to get the playback order

integer

Recording size (bytes)

integer

Segment duration (seconds) Example: 3600

integer

Segment start time, Unix timestamp in seconds, used to align with your own timeline Example: 1718194666

integer

Segment end time, Unix timestamp in seconds Example: 1718198266

integer

Offset from the task start (milliseconds); use this for the progress bar in multi-segment continuous playback Example: 7200000

integer

Segment reason: 0 unknown, 1 split by duration, 2 resumed after interruption (gap from the previous segment), 3 end of task

integer

Video width Example: 1280

integer

Video height Example: 720

integer

Frame rate Example: 15

string

Video codec Example: h264

integer

Bitrate (bps)

boolean

Whether the upload is complete. false means it is still recording or uploading, and no playback URL is available

string

Presigned playback URL, valid for 2 hours; returned only by task details, empty in the list endpoint

integer

Record creation time, Unix timestamp in seconds

integer

Task creation time, Unix timestamp in seconds Example: 1718194666

integer

Task last-modified time, Unix timestamp in seconds Example: 1718194705

Response example:

{
  "_meta": {
    "currentPage": 1,
    "pageCount": 5,
    "perPage": 20,
    "totalCount": 100
  },
  "code": 0,
  "data": [
    {
      "began_at": 1718194666,
      "channel": "",
      "created_at": 1718194666,
      "ended_at": 1718216393,
      "err_desc": "",
      "op_name": "",
      "op_uid": "",
      "record_count": 0,
      "records": [
        {
          "addr": "",
          "began_at": 1718194666,
          "bitrate": 0,
          "channel": "",
          "codec": "h264",
          "created_at": 0,
          "duration": 3600,
          "ended_at": 1718198266,
          "fps": 15,
          "height": 720,
          "is_done": false,
          "offset_ms": 7200000,
          "reason": 0,
          "record_id": "",
          "seq": 0,
          "task_id": "",
          "vod_size": 0,
          "width": 1280
        }
      ],
      "room_no": "",
      "tags": "",
      "task_id": "",
      "task_status": 0,
      "task_type": 0,
      "title": "",
      "total_duration": 21727,
      "total_size": 0,
      "updated_at": 1718194705
    }
  ]
}

Get recording task details

POST /server/v1/mcu/detail Authentication: required (see Overview) Query the details of a recording task: task type, status, start and end times, total duration, and all recording files from this recording (the records array, with each file’s playback URL, duration, start and end times, and segment sequence number). One recording produces multiple files: it rolls over to a new segment when the segment duration (1 hour by default) is exceeded, and if recording is interrupted and then resumed, that also starts a new segment. To play the entire recording, play the files in records in seq order. With task_id it queries by task; with only channel it returns the channel’s most recent recording. Use task_status to see how far the task has progressed (0 pending, 1 in progress, 2 stopping, 3 ended abnormally, 4 ended normally). Request parameters

string

Task ID Example: sxjgwy

string

Channel (required when TaskId is not set) Example: fire

boolean

Whether to return internal network playback URLs, for purely internal deployments or dedicated-line access; public network URLs are returned by default

Request example:

{
  "channel": "fire",
  "is_lan": false,
  "task_id": "sxjgwy"
}

Response parameters

string

Task ID

string

Task initiator ID

string

Task initiator name

string

Channel

string

Channel title

string

External meeting number

integer

Task type: 1 video recording, 2 stream mixing, 4 audio recording, 8 live stream; combine as bit flags

integer

0 pending, 1 in progress, 2 stopping, 3 ended abnormally, 4 ended normally

string

Error description

integer

Recording start time, Unix timestamp in seconds; 0 means the underlying task hasn’t started running yet Example: 1718194666

integer

Recording end time, Unix timestamp in seconds; 0 means not ended Example: 1718216393

integer

Number of recording files. A recording that exceeds the segment duration (1 hour by default) or is resumed after an interruption produces additional files

integer

Total duration of all recording files (seconds) Example: 21727

integer

Total bytes of all recording files

string

Recording tags, comma-separated

array<object>

List of recording files, returned only by task details; null in the list endpoint

Show Element fields

string

Recording file ID, used to get the playback URL

string

ID of the recording task it belongs to

string

Channel

integer

Segment sequence number, starting from 1; sort by it to get the playback order

integer

Recording size (bytes)

integer

Segment duration (seconds) Example: 3600

integer

Segment start time, Unix timestamp in seconds, used to align with your own timeline Example: 1718194666

integer

Segment end time, Unix timestamp in seconds Example: 1718198266

integer

Offset from the task start (milliseconds); use this for the progress bar in multi-segment continuous playback Example: 7200000

integer

Segment reason: 0 unknown, 1 split by duration, 2 resumed after interruption (gap from the previous segment), 3 end of task

integer

Video width Example: 1280

integer

Video height Example: 720

integer

Frame rate Example: 15

string

Video codec Example: h264

integer

Bitrate (bps)

boolean

Whether the upload is complete. false means it is still recording or uploading, and no playback URL is available

string

Presigned playback URL, valid for 2 hours; returned only by task details, empty in the list endpoint

integer

Record creation time, Unix timestamp in seconds

integer

Task creation time, Unix timestamp in seconds Example: 1718194666

integer

Task last-modified time, Unix timestamp in seconds Example: 1718194705

Response example:

{
  "code": 0,
  "data": {
    "began_at": 1718194666,
    "channel": "",
    "created_at": 1718194666,
    "ended_at": 1718216393,
    "err_desc": "",
    "op_name": "",
    "op_uid": "",
    "record_count": 0,
    "records": [
      {
        "addr": "",
        "began_at": 1718194666,
        "bitrate": 0,
        "channel": "",
        "codec": "h264",
        "created_at": 0,
        "duration": 3600,
        "ended_at": 1718198266,
        "fps": 15,
        "height": 720,
        "is_done": false,
        "offset_ms": 7200000,
        "reason": 0,
        "record_id": "",
        "seq": 0,
        "task_id": "",
        "vod_size": 0,
        "width": 1280
      }
    ],
    "room_no": "",
    "tags": "",
    "task_id": "",
    "task_status": 0,
    "task_type": 0,
    "title": "",
    "total_duration": 21727,
    "total_size": 0,
    "updated_at": 1718194705
  }
}

List recording files

POST /server/v1/mcu/list-record Authentication: required (see Overview) List recording files with pagination; each item is one file (segment) produced by a recording. Ascending seq is the playback order; offset_ms is the offset from the task start, used for the progress bar in multi-segment continuous playback. reason=2 means there is a time gap between this segment and the previous one (recording was interrupted and resumed); watch for it in continuous playback. After getting the list, use “Batch get recording file playback URLs” to fetch this page’s URLs in one go, which is much faster than fetching them one by one. Request parameters

string

Recording task ID; pass it to view only the files of one recording; empty means no filter Example: sxjgwy

string

Channel; empty means no filter (up to 64 bytes; letters, digits, underscores (_), and hyphens (-) only) Example: fire

integer

Page number, starting from 1 Example: 1

integer

Page size Example: 10

Request example:

{
  "channel": "fire",
  "page": 1,
  "per-page": 10,
  "task_id": "sxjgwy"
}

Response parameters

string

Recording file ID, used to get the playback URL

string

ID of the recording task it belongs to

string

Channel

integer

Segment sequence number, starting from 1; sort by it to get the playback order

integer

Recording size (bytes)

integer

Segment duration (seconds) Example: 3600

integer

Segment start time, Unix timestamp in seconds, used to align with your own timeline Example: 1718194666

integer

Segment end time, Unix timestamp in seconds Example: 1718198266

integer

Offset from the task start (milliseconds); use this for the progress bar in multi-segment continuous playback Example: 7200000

integer

Segment reason: 0 unknown, 1 split by duration, 2 resumed after interruption (gap from the previous segment), 3 end of task

integer

Video width Example: 1280

integer

Video height Example: 720

integer

Frame rate Example: 15

string

Video codec Example: h264

integer

Bitrate (bps)

boolean

Whether the upload is complete. false means it is still recording or uploading, and no playback URL is available

string

Presigned playback URL, valid for 2 hours; returned only by task details, empty in the list endpoint

integer

Record creation time, Unix timestamp in seconds

Response example:

{
  "_meta": {
    "currentPage": 1,
    "pageCount": 5,
    "perPage": 20,
    "totalCount": 100
  },
  "code": 0,
  "data": [
    {
      "addr": "",
      "began_at": 1718194666,
      "bitrate": 0,
      "channel": "",
      "codec": "h264",
      "created_at": 0,
      "duration": 3600,
      "ended_at": 1718198266,
      "fps": 15,
      "height": 720,
      "is_done": false,
      "offset_ms": 7200000,
      "reason": 0,
      "record_id": "",
      "seq": 0,
      "task_id": "",
      "vod_size": 0,
      "width": 1280
    }
  ]
}

Get a recording file’s playback URL

POST /server/v1/mcu/vod-url Authentication: required (see Overview) Get the playback URL of a single recording file. The file must have finished uploading; no URL is available while it is recording or uploading. The URL expires (2 hours). Don’t cache it long term or store it in your database; get a new one before each playback. Request parameters

string

required

Recording file ID, taken from the task details or the recording file list Example: rc3p9w

boolean

Whether to return internal network URLs, for purely internal deployments or dedicated-line access; public network URLs are returned by default

Request example:

{
  "is_lan": false,
  "record_id": "rc3p9w"
}

Response parameters

string

Recording file ID

string

Presigned playback URL, valid for 2 hours

integer

Recording size (bytes)

integer

Segment duration (seconds)

integer

Segment start time, Unix timestamp in seconds

integer

Offset from the task start (milliseconds)

Response example:

{
  "code": 0,
  "data": {
    "addr": "",
    "began_at": 0,
    "duration": 0,
    "offset_ms": 0,
    "record_id": "",
    "size": 0
  }
}

Batch get recording file playback URLs

POST /server/v1/mcu/vod-url/batch Authentication: required (see Overview) Get playback URLs for recording files in bulk, up to 50 at a time; suited to fetching everything at once for continuous playback of an entire recording. If issuing a URL fails for a single file (for example, it has been cleaned up), that item’s addr is empty; other items are not affected. Request parameters

array<string>

required

List of recording file IDs, up to 50 per request (max length 50) Example: ["rc3p9w","rc3p9x"]

boolean

Whether to return internal network URLs, for purely internal deployments or dedicated-line access; public network URLs are returned by default

Request example:

{
  "is_lan": false,
  "record_ids": [
    "rc3p9w",
    "rc3p9x"
  ]
}

Response parameters

string

Recording file ID

string

Presigned playback URL, valid for 2 hours

integer

Recording size (bytes)

integer

Segment duration (seconds)

integer

Segment start time, Unix timestamp in seconds

integer

Offset from the task start (milliseconds)

Response example:

{
  "code": 0,
  "data": [
    {
      "addr": "",
      "began_at": 0,
      "duration": 0,
      "offset_ms": 0,
      "record_id": "",
      "size": 0
    }
  ]
}

Delete a recording task

POST /server/v1/mcu/del-task Authentication: required (see Overview) Delete a recording task together with all its recording files. After deletion it no longer appears in the list or details. If you pass only channel without task_id, all tasks with video recording in that channel are deleted together. To delete one specific recording, pass task_id. Request parameters

string

Task ID Example: sxjgwy

string

Channel (required when TaskId is not set) Example: fire

boolean

Whether to return internal network playback URLs, for purely internal deployments or dedicated-line access; public network URLs are returned by default

Request example:

{
  "channel": "fire",
  "is_lan": false,
  "task_id": "sxjgwy"
}

Response parameters data is null Response example:

{
  "code": 0,
  "data": null
}

Delete a recording file

POST /server/v1/mcu/del-record Authentication: required (see Overview) Delete a single recording file; other files from the same recording are not affected. Request parameters

string

required

Recording file ID Example: rc3p9w

Request example:

{
  "record_id": "rc3p9w"
}

Response parameters data is null Response example:

{
  "code": 0,
  "data": null
}

Start a recording or live streaming task

POST /server/v1/mcu/start Authentication: required (see Overview) Start a server-side recording, stream mixing, or live streaming task. A channel has only one in-progress task per type: calling again doesn’t create a new task but updates the existing one with the parameters passed in. Request parameters

integer

required

Task type as bit flags: 1 video recording, 2 stream mixing, 4 audio recording, 8 live stream; for example, 3 means video recording + stream mixing, 9 means video recording + live stream Example: 9

string

Task initiator ID Example: 1001

string

Task initiator name (max length 100) Example: Alice

string

required

Channel (up to 64 bytes; letters, digits, underscores (_), and hyphens (-) only) Example: fire

string

required

Channel title. Becomes the recording title and is also the default watermark content (when watermark.text is empty) Example: Weekly project sync 2024-06-12

string

External meeting number. A meeting number from your own business, used only for lookup; not validated on the RTC side (max length 50) Example: 818595664

string

Recording tags, comma-separated (note: in “Update a recording task’s title and tags”, tags is an array) Example: Weekly sync,R&D

object

Layout data. If omitted, the app’s default recording configuration is used (see “Get the default recording configuration”)

Show Fields

string

required

object

Watermark

Show Fields

integer

Type: 0 default, 1 none, 2 single row, 3 multiple rows Example: 1

string

Custom text; empty means automatic (channel title)

integer

Font size; 0 means the default value

string

Font color; empty means the default value

string

Outline color; empty means the default value

integer

Outline width; 0 means the default value

string

Text shown when no one is in the channel; empty means recording stops when no one is in the channel

object

Default name label

Show Fields

string

Type, a letter or combination: L left, R right, T top, B bottom Example: L

string

Custom text; empty means automatic (display name)

integer

Font size; 0 means default

string

Font color; empty means default

string

Background color; empty means default

integer

Rotation interval (seconds); 0 disables rotation

array<object>

List of logical blocks

Show Element fields

array<object>

List of grid cells; empty means the remaining cells share the users here

array<string>

List of user IDs; empty means rotating through all remaining online users, multiple means rotating among these users

object

User name table, corresponding to McuDiv.Uids (optional)

Request example:

{
  "channel": "fire",
  "layout_data": {
    "div_list": [
      {
        "cells": [
          {
            "bind_share": false,
            "idx": 0,
            "tag": {
              "bg_color": "",
              "color": "",
              "size": 0,
              "text": "",
              "type": "L"
            }
          }
        ],
        "uids": [
          ""
        ]
      }
    ],
    "layout": "auto",
    "names": {},
    "nobody_text": "",
    "polling_dur": 0,
    "tag": {
      "bg_color": "",
      "color": "",
      "size": 0,
      "text": "",
      "type": "L"
    },
    "watermark": {
      "color": "",
      "ol_color": "",
      "ol_width": 0,
      "size": 0,
      "text": "",
      "type": 1
    }
  },
  "op_name": "Alice",
  "op_uid": "1001",
  "room_no": "818595664",
  "tags": "Weekly sync,R&D",
  "task_type": 9,
  "title": "Weekly project sync 2024-06-12"
}

Response parameters

string

ID of this task, used to stop the task, query details, and get playback URLs

Response example:

{
  "code": 0,
  "data": {
    "task_id": ""
  }
}

Stop a recording or live streaming task

POST /server/v1/mcu/stop Authentication: required (see Overview) Stop an in-progress recording, stream mixing, or live streaming task. Recording files are transcoded only after the task stops; playback URLs become available after that. In-progress tasks stop automatically when the channel is destroyed, so you don’t need to stop them manually first. Request parameters

string

Task ID Example: sxjgwy

string

Channel (required when TaskId is not set) Example: fire

integer

Task type (optional). Omit to stop tasks of all types in the channel; if set, only the specified types are stopped. Values are the same as for the start endpoint Example: 1

Request example:

{
  "channel": "fire",
  "task_id": "sxjgwy",
  "task_type": 1
}

Response parameters data is null Response example:

{
  "code": 0,
  "data": null
}

Update a recording task’s title and tags

POST /server/v1/mcu/update-task Authentication: required (see Overview) Update a recording task’s title and tags for archiving and organization; the recording files themselves are not affected. Both the title and tags can be matched by search in the recording task list. Request parameters

string

required

Task ID Example: sxjgwy

string

Recording title; omit to leave unchanged (max length 100) Example: Weekly project sync (archived)

array<string>

Tags, up to 10. They are replaced as a whole, not appended—include any tags you want to keep (max length 10) Example: ["Weekly sync","R&D"]

Request example:

{
  "tags": [
    "Weekly sync",
    "R&D"
  ],
  "task_id": "sxjgwy",
  "title": "Weekly project sync (archived)"
}

Response parameters data is null Response example:

{
  "code": 0,
  "data": null
}

Get live stream playback URLs

POST /server/v1/mcu/live-url Authentication: required (see Overview) Get live stream playback URLs; returns rtmp / flv / hls URLs at once, so you can choose one for your player. Unlike recording playback, live stream URLs are available while the task is in progress—provided that task_type included the live streaming bit (8) when the task was started. The URLs expire; don’t cache them long term. Request parameters

string

Task ID Example: sxjgwy

string

Channel (required when TaskId is not set) Example: fire

boolean

Whether to return internal network playback URLs, for purely internal deployments or dedicated-line access; public network URLs are returned by default

Request example:

{
  "channel": "fire",
  "is_lan": false,
  "task_id": "sxjgwy"
}

Response parameters

string

RTMP playback URL; lowest latency, suited to players that need low latency

string

HTTP-FLV playback URL, commonly used on the Web

string

HLS (m3u8) playback URL; best compatibility, relatively higher latency

Response example:

{
  "code": 0,
  "data": {
    "flv": "",
    "hls": "",
    "rtmp": ""
  }
}

Overview

Web SDK

Android SDK

Swift SDK (iOS/macOS)

Python SDK (server-side AI)

Server API

Cloud recording and live streaming

Get the default recording configuration

Update the default recording configuration

List recording tasks

Get recording task details

List recording files

Get a recording file’s playback URL

Batch get recording file playback URLs

Delete a recording task

Delete a recording file

Start a recording or live streaming task

Stop a recording or live streaming task

Update a recording task’s title and tags

Get live stream playback URLs

​Get the default recording configuration

​Update the default recording configuration

​List recording tasks

​Get recording task details

​List recording files

​Get a recording file’s playback URL

​Batch get recording file playback URLs

​Delete a recording task

​Delete a recording file

​Start a recording or live streaming task

​Stop a recording or live streaming task

​Update a recording task’s title and tags

​Get live stream playback URLs

Get the default recording configuration

Update the default recording configuration

List recording tasks

Get recording task details

List recording files

Get a recording file’s playback URL

Batch get recording file playback URLs

Delete a recording task

Delete a recording file

Start a recording or live streaming task

Stop a recording or live streaming task

Update a recording task’s title and tags

Get live stream playback URLs