> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stmlink.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 云录制与直播接入指南

> 整场云端录制、合流、录音与直播的完整玩法：任务类型怎么组合、画面怎么排、产物怎么取

本页讲云录制与直播的整体玩法。单个接口的参数与返回结构见[云录制与直播](/zh/rtc/server-api/mcu)。

<Note>本页讲的是**整场**录制：整个频道混成一路，产出一个文件。如果你要的是**按说话人分轨、按一次讲话切段**的录音，那是另一套接口，见[语音录制](/zh/rtc/server-api/talkrec)，两者的差异见下文对照表。</Note>

## 一个任务，四种能力

`task_type` 是**按位组合**的，四个独立能力各占一位，想同时要哪几个就相加：

| 值 | 能力  | 产物       | 怎么取                                         |
| - | --- | -------- | ------------------------------------------- |
| 1 | 录像  | 录像文件     | [获取录像播放地址](/zh/rtc/server-api/mcu#获取录像播放地址) |
| 2 | 合流  | 把多路流混成一路 | 旁路推流，给不支持多流的下游用                             |
| 4 | 录音  | 纯音频文件    | 同录像                                         |
| 8 | 直播流 | 直播拉流地址   | [获取直播拉流地址](/zh/rtc/server-api/mcu#获取直播拉流地址) |

所以 `3` = 录像+合流，`9` = 录像+直播，`15` = 四种全开。

<Warning>不要把 `3` 理解成"混合模式"这一种独立类型。历史文档曾把值域写成「1录像 2合流 3混合」，那是错的 —— 既漏了录音与直播流，也误导了组合语义。</Warning>

### 「录音」和「语音录制」不是一回事

本页的 `task_type=4` 录音是 **MCU 合流录音**：整个频道混成一路音频，一次任务一个文件。

如果你要的是**按人分轨、按一次讲话切段**（对讲留痕、按人计时、逐句转写），用
[语音录制](/zh/rtc/server-api/talkrec)，那是另一套接口：

|      | MCU 录音（`task_type=4`） | 语音录制（talkrec）           |
| ---- | --------------------- | ----------------------- |
| 产物   | 整场一个混音文件              | 一次讲话一段，每段独立文件           |
| 分轨   | 不分，所有人混在一起            | 按说话人分轨，带 `uid` / `name` |
| 何时能取 | 任务停止且转码完成后            | 每段闭合就可取，边录边有            |
| 适合   | 归档整场音频                | 对讲、留痕、逐句处理              |

两者可以同时开，互不影响。

## 录像和直播的关键区别

|         | 录像             | 直播             |
| ------- | -------------- | -------------- |
| 何时能取到地址 | 任务**停止且转码完成**后 | 任务**进行中**就能取   |
| 用途      | 事后回放、归档        | 把画面分发给不参与互动的观众 |
| 地址有效期   | 有，每次播放前重新获取    | 有              |

这个差异决定了调用时序：直播是"开播即可分发"，录像是"结束后才有产物"。

## 画面怎么排

`layout_data.layout` 决定画面布局。`auto` 会按在线人数自动选宫格，**绝大多数场景够用**；需要固定画面时才指定具体布局：

| 取值                  | 说明                                                 |
| ------------------- | -------------------------------------------------- |
| `auto`              | 自动，按在线人数选宫格                                        |
| `full`              | 全屏单画面                                              |
| `grids_N`           | 等分宫格，N 取 2、3、4、5、6、8、9、12、16、20、25（`grids_3` 是品字形） |
| `right_4` / `top_4` | 主画面 + 右侧 / 顶部小窗                                    |
| `br_7` / `tl_7`     | 下 L 型 / 上 L 型                                      |
| `tb_8`              | 左右布局                                               |

注意 `grids_N` 的 N **不连续**（没有 7、10、11），传不支持的值会报错。

不传 `layout_data` 时用应用的[默认录制配置](/zh/rtc/server-api/mcu#获取默认录制配置)——把统一的水印、标签、布局策略配在那里，就不用每次启动任务都重复传。

## 指定谁出现在哪个格子

`layout_data.div_list` 用来把特定用户钉到特定格子，不指定就按加入顺序自动填充。

* `cells[].idx` 是格子序号，顺序等同 HTML 表格里 `<td>` 的排列（从左到右、从上到下）
* `uids` **留空**表示「剩余在线用户轮流出现在这些格子里」（大轮询）；**填多个**则是这几个人在这些格子里轮询（小轮询）
* `polling_dur` 是轮询间隔秒数，`0` 表示不轮询
* `cells[].bind_share` 为 `true` 时该格子优先绑定频道内的共享屏幕流

一个典型用法是"主讲人固定在大格子、其余人轮播小格子"：给大格子的 `cells` 填主讲人 `uid`，给小格子的 `cells` 留空 `uids` 并设 `polling_dur`。

## 无人时的行为

`layout_data.nobody_text` 决定频道里没人时怎么办：

* **留空** → 暂停录制（推荐，避免录出大段黑屏）
* **填了文本** → 继续录制并显示该文本

## 水印与成员名标签

* `watermark.type`：`0` 默认、`1` 无、`2` 单排、`3` 多排。`watermark.text` 留空时用任务的 `title` 作为水印内容
* 成员名标签的位置用字母组合表示：`L` 左、`R` 右、`T` 上、`B` 下，可组合（`LB` = 左下）。**留空表示不显示标签**

## 完整时序

```
1. 可选：配好应用的默认录制配置        POST /server/v1/mcu/save-record-config
2. 频道里有人后，启动任务              POST /server/v1/mcu/start        → task_id
   ├─ task_type 带 8 → 立即可取直播地址 POST /server/v1/mcu/live-url
   └─ 需要临时改布局 → 用同样参数重新调 start（同一频道同一类型是更新而非新建）
3. 结束                                POST /server/v1/mcu/stop
4. 转码完成后取回放                    POST /server/v1/mcu/vod-url
5. 归档整理                            POST /server/v1/mcu/update-record
```

频道销毁时进行中的任务会**自动停止**，不必先手动调 stop。

## 计费提示

录制、录音、直播都是持续产生费用的服务端能力。启动后若忘记停止，会一直跑到频道销毁为止——所以业务侧最好在会议结束流程里显式调 stop，不要只依赖频道销毁。