# 实现合流录制 (/zh-CN/realtime-media/cloud-recording/build/recording-modes/mix-mode/set-composite)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

云端录制支持单流录制、合流录制和页面录制三种模式。

[合流录制](/zh-CN/realtime-media/cloud-recording/reference/concepts#合流录制)模式指录制并混合频道内所有指定用户 ID 的音视频，生成一个包含所有指定用户 ID 音视频的 HLS (HTTP Live Streaming) 流媒体点播文件和可选的 MP4 格式文件。

## 前提条件 [#前提条件]

开始前，请参考[使用 RESTful API 开始云端录制](/zh-CN/realtime-media/cloud-recording/get-started/quick-start)进行一次完整的录制流程体验。

## 实现步骤 [#实现步骤]

本节介绍如何在[申请录制服务器资源](/zh-CN/realtime-media/cloud-recording/get-started/quick-start#申请录制服务器资源)后，实现合流录制。

### 开始录制 [#开始录制]

在调用 [`start`](/zh-CN/api-reference/api-ref/cloud-recording/start) 方法时，你需要将 `mode` 参数设置为 `mix`，开启合流录制模式。

:::warning[注意]
录制模式的设置必须在开始录制的时候完成，不支持在录制开始后切换模式。
:::

以下介绍设置合流录制的 `clientRequest` 关键配置，确保你进行正确设置以实现预期的录制效果。

| 字段                  | 配置内容                         |
| :-------------------- | :------------------------------- |
| `recordingConfig`     | JSON Object，用于配置音频流订阅、转码、输出音频属性。 |
| `storageConfig`       |  JSON Object，第三方云存储设置。                  |

请求示例如下：

- 请求 URL：

    ```text
    https://api.sd-rtn.com/v1/apps/<yourappid>/cloud_recording/resourceid/<resourceid>/mode/mix/start
    ```

- 请求 Body 内容：

    以下示例重点展示 `recordingConfig` 和 `storageConfig` 的配置。

    ```json
    {
      "uid": "527841",
      "cname": "httpClient463224",
      "clientRequest": {
        "token": "<token if any>",
        // [!code highlight:24]
        "recordingConfig": {
          "maxIdleTime": 30,
          "streamTypes": 2,
          "audioProfile": 1,
          "channelType": 0,
          "videoStreamType": 0,
          "transcodingConfig": {
            "height": 640,
            "width": 360,
            "bitrate": 500,
            "fps": 15,
            "mixedVideoLayout": 1,
            "backgroundColor": "#FF0000"
          },
          "subscribeVideoUids": [
            "123",
            "456"
          ],
          "subscribeAudioUids": [
            "123",
            "456"
          ],
          "subscribeUidGroup": 0
        },
        "recordingFileConfig": {
          "avFileType": [
            "hls",
            "mp4"
          ]
        },
        // [!code highlight:11]
        "storageConfig": {
          "accessKey": "xxxxxxf",
          "region": 3,
          "bucket": "xxxxx",
          "secretKey": "xxxxx",
          "vendor": 2,
          "fileNamePrefix": [
            "directory1",
            "directory2"
          ]
        }
      }
    }
    ```

### 停止录制 [#停止录制]

录制完成后，调用 [`stop`](/zh-CN/api-reference/api-ref/cloud-recording/stop) 方法离开频道，停止录制。录制停止后如需再次录制，必须再调用 `acquire` 方法请求一个新的 Resource ID。

请求示例如下：

- 请求 URL：

    ```text
    https://api.sd-rtn.com/v1/apps/<yourappid>/cloud_recording/resourceid/<resourceid>/sid/<sid>/mode/mix/stop
    ```

- 请求 Body 内容：

    ```json
    {
      "cname": "httpClient463224",
      "uid": "527841",
      "clientRequest": {}
    }
    ```

## 录制生成文件 [#录制生成文件]

录制后共生成一个 M3U8 文件和多个 TS 文件。根据 `avFileType` 字段的设置，还有可能生成一个或多个 MP4 文件。录制文件的切片和命名原则详见[录制文件介绍](/zh-CN/realtime-media/cloud-recording/build/manage-recorded-files/introduce-recorded-files)。

合流录制生成的文件如下图所示：

<DocsImage alt="合流录制生成文件" src="https://web-cdn.agora.io/doc-cms/uploads/1725865139156-合流生成文件.png" displayWidth="80%" />

## 开发注意事项 [#开发注意事项]

Native 端、Web 端及框架端用户在用户中途停止发流或退出频道后的显示策略如下：

| 取消发布本地视频 | 禁用视频轨道 | 退出频道 |
| --- | --- | --- |
| [set-composite-html-0-1-0 details](#table-slot-set-composite-html-0-1-0) | [set-composite-html-0-1-1 details](#table-slot-set-composite-html-0-1-1) | 优先显示画布背景图，如无画布背景图则显示画布背景色。如果画布背景色也未设置，则显示默认的黑色画布背景色。 |

<a id="table-slot-set-composite-html-0-1-0"></a>

**set-composite-html-0-1-0 details**

- 3.5 秒内显示视频画面的最后一帧。
- 3.5 秒后显示预设的用户背景图或画布背景图。如果未设置背景图，则显示画布背景色。如果画布背景色也未设置，则显示默认的黑色画布背景色。

<a id="table-slot-set-composite-html-0-1-1"></a>

**set-composite-html-0-1-1 details**

- 3.5 秒内显示视频画面的最后一帧。
- 3.5 秒后显示预设的用户背景图或画布背景图。如果未设置背景图，则显示画布背景色。如果画布背景色也未设置，则显示默认的黑色画布背景色。

## 参考信息 [#参考信息]

### 相关文档 [#相关文档]

在合流录制过程中，你还可以参考如下文档：

- [设置订阅名单](/zh-CN/realtime-media/cloud-recording/reference/api-reference#订阅名单设置)
- [设置合流布局](/zh-CN/realtime-media/cloud-recording/build/recording-modes/mix-mode/set-composite-layout)
- [设置输出视频属性](/zh-CN/realtime-media/cloud-recording/reference/api-reference#常用视频属性)

### API 参考 [#api-参考]

你可以参考以下方法了解字段详情：

- [`acquire`](/zh-CN/api-reference/api-ref/cloud-recording/acquire)
- [`start`](/zh-CN/api-reference/api-ref/cloud-recording/start)
- [`stop`](/zh-CN/api-reference/api-ref/cloud-recording/stop)

### 常见问题 [#常见问题]

- [应用崩溃后对云端录制有什么影响？](/zh-CN/reference/faq/integration/abnormal_exit)
- [如何选择云存储 bucket 区域及处理跨区上传问题？](/zh-CN/reference/faq/integration/bucket_region)
- [为什么无法通过浏览器调用云端录制 RESTful API？](/zh-CN/reference/faq/product/call_api_in_browser)
- [为什么第三方云储存中没有录制文件？](/zh-CN/reference/faq/integration/fail_to_upload)
- [如何获取 M3U8 文件地址？](/zh-CN/reference/faq/integration/acquire_file_directory)
- [云端录制如何处理服务器断网、进程被杀问题？](/zh-CN/reference/faq/integration/high_availability)