实现合流录制

本文介绍使用云端录制 RESTful API 进行合流录制的重点步骤。建议你同时参考云端录制 RESTful API 快速开始了解云端录制的基础流程。

功能描述

云端录制共支持三种录制模式：

• 单流录制
• 合流录制
• 页面录制

合流录制模式下，频道内所有或指定 UID 的音视频混合录制为一个音视频文件。

举例来说，当频道中有两个用户，且同时录制音视频时，合流录制生成的文件如下图所示：

录制后共生成一个 M3U8 文件和多个 TS 文件。如你在调用 start 方法时将 avFileType 设置为 ["hls","mp4"]，则还会生成 MP4 文件，包含所有用户的音视频数据。

实现方法

获取 resource ID

在开始录制前，必须调用 acquire 方法请求一个用于云端录制的 resource ID。

请求示例

• 请求 URL：

    https://api.sd-rtn.com/v1/apps/<yourappid>/cloud_recording/acquire

• Content-type 为 application/json;charset=utf-8

• Authorization 为 Basic authorization，生成方法请参考 RESTful API 认证。

• 请求包体内容：

{
    "cname": "httpClient463224",
    "uid": "527841",
    "clientRequest": {
        "resourceExpiredHour": 24,
        "scene": 0
    }
}

开始录制

在调用 start 方法时，你需要将 mode 参数设置为 mix，开启合流录制模式。该模式下，你还需要通过 recordingConfig 设置合流录制的详细信息，以及通过 storageConfig 设置第三方云存储的信息。

合流录制支持的 clientRequest 参数包括：

参数	配置内容	是否选填
token	String 类型，动态密钥。	如频道使用了 token，则为必填
recordingConfig	JSON Object，用于配置音频流订阅、转码、输出音频属性，详见录制设置。	必填
recordingFileConfig	JSON Object，录制文件设置。	选填
storageConfig	JSON Object，第三方云存储设置。	必填

请求示例

• 请求 URL：

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

• Content-type 为 application/json;charset=utf-8

• Authorization 为 Basic authorization，生成方法请参考 RESTful API 认证。

• 请求包体内容：

{
    "uid": "527841",
    "cname": "httpClient463224",
    "clientRequest": {
        "token": "<token if any>",
        "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
        },
        "storageConfig": {
            "accessKey": "xxxxxxf",
            "region": 3,
            "bucket": "xxxxx",
            "secretKey": "xxxxx",
            "vendor": 2,
            "fileNamePrefix": [
                "directory1",
                "directory2"
            ]
        }
    }
}

停止录制

录制完成后，调用 stop 方法离开频道，停止录制。录制停止后如需再次录制，必须再调用 acquire 方法请求一个新的 resource ID。

请求示例

• 请求 URL：

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

• Content-type 为 application/json;charset=utf-8

• Authorization 为 Basic authorization，生成方法请参考 RESTful API 认证。

• 请求包体内容：

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

设置订阅名单

默认情况下，云端录制会订阅频道内所有发布的音视频流。你可以使用 API 进行灵活的 UID 订阅。你可以设置音频和视频的订阅白名单或黑名单，还可以在录制过程中更新订阅名单。

在开始录制时，你可以通过 start 方法中的相关参数设置订阅的黑白名单。在录制过程中，你可以通过 update 方法中的 streamSubscribe 参数更新订阅名单。

设置音频订阅名单

选择以下参数之一设置音频订阅名单。两者不可同时设置。

subscribeAudioUids：指定要订阅的音频流，即音频订阅白名单。

unSubscribeAudioUids：指定不订阅的音频流，即音频订阅黑名单。

设置视频订阅名单

选择以下参数之一设置视频订阅名单。两者不可同时设置。

subscribeVideoUids：指定要订阅的视频流，即视频订阅白名单。

unSubscribeVideoUids：指定不订阅的视频流，即视频订阅黑名单。

示例

假设录制开始时，频道内共有 111、222、333、444 四个用户，中途又进入两个 UID 未知的用户。下表列出了几种常见的订阅方式以及推荐的参数设置。

订阅方式	推荐参数设置
订阅全部音频流和视频流	无需设置订阅相关参数。
订阅全部音频流，只订阅 111 和 222 的视频流	subscribeAudioUids: ["#allstream#"] subscribeVideoUids: ["111","222"]
订阅全部音频流，不订阅 111 和 222 的视频流	subscribeAudioUids: ["#allstream#"] unSubscribeVideoUids: ["111","222"] 云端录制会订阅全部音频流以及 333、444 和两个 UID 未知用户的视频流。
订阅全部音频流，不订阅视频流	subscribeAudioUids: ["#allstream#"] 将 streamType 设置为 0，也可达到同样的效果。
不订阅 222 的音频流，只订阅 111 的视频流	unSubscribeAudioUids: ["222"] subscribeVideoUids: ["111"] 云端录制会订阅 111、333、444 和两个 UID 未知用户的音频流，以及 111 的视频流。

更新合流布局

在录制过程中，可以随时调用 updateLayout 方法更新合流布局的设置。如何设置合流布局样式，详见设置合流布局。

每次调用该方法都会覆盖原来的布局设置，例如在开始录制时设置了 backgroundColor 为 "#FF0000"（红色），调用该方法更新合流布局时如果不设置 backgroundColor 参数，背景色会变为默认值黑色。

请求示例

• 请求 URL：

    https://api.sd-rtn.com/v1/apps/<appid>/cloud_recording/resourceid/<resourceid>/sid/<sid>/mode/<mode>/updateLayout

• Content-type 为 application/json;charset=utf-8

• Authorization 为 Basic authorization，生成方法请参考 RESTful API 认证。

• 请求包体内容：

{
    "uid": "527841",
    "cname": "httpClient463224",
    "clientRequest": {
        "mixedVideoLayout": 3,
        "backgroundColor": "#FF0000",
        "layoutConfig": [
            {
                "uid": "1",
                "x_axis": 0.1,
                "y_axis": 0.1,
                "width": 0.1,
                "height": 0.1,
                "alpha": 1,
                "render_mode": 1
            },
            {
                "uid": "2",
                "x_axis": 0.2,
                "y_axis": 0.2,
                "width": 0.1,
                "height": 0.1,
                "alpha": 1,
                "render_mode": 1
            }
        ]
    }
}

响应示例

{
  "sid": "38f8e3cfdc474cd56fc1ceba380d7e1a",
  "resourceId": "JyvK8nXHuV1BE64GDkAaBGEscvtHW7v8BrQoRPCHxmeVxwY22-x-kv4GdPcjZeMzoCBUCOr9q-k6wBWMC7SaAkZ_4nO3JLqYwM1bL1n6wKnnD9EC9waxJboci9KUz2WZ4YJrmcJmA7xWkzs_L3AnNwdtcI1kr_u1cWFmi9BWAWAlNd7S7gfoGuH0tGi6CNaOomvr7-ILjPXdCYwgty1hwT6tbAuaW1eqR0kOYTO0Z1SobpBxu1czSFh1GbzGvTZG"
}

录制生成文件

根据录制内容的不同，录制生成的文件如下表所示：

录制内容	参数设置	录制生成文件
仅录制音频	streamTypes 设为 0	生成一个 M3U8 文件和多个 TS 文件，TS 文件内仅存储该频道的音频数据。如果将 avFileType 设置为 ["hls","mp4"]，则还会生成一个或多个 MP4 文件，包含所有用户的音频数据。
仅录制视频	streamTypes 设为 1	生成一个 M3U8 文件和多个 TS 文件，TS 文件内仅存储该频道的视频数据。如果将 avFileType 设置为 ["hls","mp4"]，则还会生成一个或多个 MP4 文件，包含所有用户的视频数据。
同时录制音视频	（默认设置）streamTypes 设为 2	生成一个 M3U8 文件和多个 TS 文件，TS 文件内存储该频道的音视频数据。如果将 avFileType 设置为 ["hls","mp4"]，则还会生成一个或多个 MP4 文件，包含所有用户的音视频数据。

录制文件的命名规则详见管理录制文件。

开发注意事项

Web 端用户和 Native 端用户在用户中途停止发流或退出频道后的显示策略有所不同，详见下表：

发流端类型	取消发布本地视频（unpublish）	禁用视频轨道（muteVideo/setEnabled）	退出频道
Native 端	3.5 秒内显示视频画面的最后一帧。 3.5 秒后显示预先设置的用户背景图或画布背景图，详见背景图设置；如果未设置背景图，则显示视频画面最后一帧。	3.5 秒内显示视频画面的最后一帧。 3.5 秒后显示预先设置的用户背景图或画布背景图，详见背景图设置；如果未设置背景图，则显示视频画面最后一帧。	画布背景色（backgroundColor）
Web 端	Web SDK 3.x 及以前，显示为画布背景图（backgroundImage）或画布背景色（backgroundColor），详见背景图设置。	Web SDK 3.x 及以前，显示为黑屏。	画布背景色（backgroundColor）
	Web SDK 4.x 及以后， 3.5 秒内显示为视频画面最后一帧。 3.5 秒后显示预先设置的用户背景图或画布背景图，详见背景图设置；如果未设置背景图，则显示视频画面最后一帧。	Web SDK 4.x 及以后， 3.5 秒内显示为视频画面最后一帧。 3.5 秒后显示预先设置的用户背景图或画布背景图，详见背景图设置；如果未设置背景图，则显示视频画面最后一帧。	画布背景色（backgroundColor）