实现单流录制

本文介绍使用云端录制 RESTful API 进行单流录制的重点步骤。建议你同时参考云端录制 RESTful API 快速开始了解云端录制的基础流程。
文中的单流录制均指单流转码录制，如需使用单流音频不转码录制，请参考单流音频不转码录制文档。

功能描述

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

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

单流录制模式下，分别录制频道中每个 UID 的音频流和视频流。Agora 推荐你在开始录制时选择单流录制的标准模式，录制结束后每个 UID 均获得能够直接播放的音视频文件。设置方式详见开始录制。

举例来说，当频道中有两个用户 uid1 和 uid2，且同时录制音视频时，单流录制标准模式生成的文件如下图所示：

实现方法

获取 resource ID

在开始录制前，必须调用 acquire 方法请求一个用于云端录制的 resource ID。如果要使用延时转码，需要将 scene 设置为 2。

请求示例

• 请求 URL：

  https://api.agora.io/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 参数设置为 individual，开启单流录制模式。该模式下，你还需要通过 recordingConfig 设置单流录制的详细信息，以及通过 storageConfig 设置第三方云存储的信息。
Agora 推荐你在开始录制时选择标准模式，即 recordingConfig 中的 streamMode 设置为 standard，以获得能够直接播放的音视频文件。

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

请求示例

• 请求 URL：

  https://api.agora.io/v1/apps/<yourappid>/cloud_recording/resourceid/<resourceid>/mode/individual/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,
            "streamMode": "standard",
            "channelType": 0,
            "videoStreamType": 0,
            "subscribeVideoUids": [
                "123",
                "456"
            ],
            "subscribeAudioUids": [
                "123",
                "456"
            ],
            "subscribeUidGroup": 0
        },
        "storageConfig": {
            "accessKey": "xxxxxxf",
            "region": 3,
            "bucket": "xxxxx",
            "secretKey": "xxxxx",
            "vendor": 2,
            "fileNamePrefix": [
                "directory1",
                "directory2"
            ]
        }
    }
}

延时转码

设置该场景后，录制服务会在录制后 24 小时内对录制文件进行转码生成 MP4 文件，并将 MP4 文件上传至你指定的第三方云存储（不支持七牛云）。

{
    "uid": "527841",
    "cname": "httpClient463224",
    "clientRequest": {
        "token": "<token if any>",
        "appsCollection": {
            "combinationPolicy": "postpone_transcoding"
        },
        "recordingConfig": {
            "maxIdleTime": 30,
            "streamTypes": 2,
            "channelType": 0,
            "videoStreamType": 1,
            "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.agora.io/v1/apps/<yourappid>/cloud_recording/resourceid/<resourceid>/sid/<sid>/mode/individual/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 未知的用户。下表列出了几种常见的订阅方式以及推荐的参数设置。

录制生成文件

单流录制模式下录制文件的音视频编码配置如下：

• 音频编码配置：采样率固定为 48 kHz，声道数和码率与原始音频流一致。
• 视频编码配置：与原始视频流一致。

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

你可以直接播放 M3U8 或 MPD 音视频文件。

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

开发注意事项

• 你可以使用通配符 ["#allstream#"] 指定频道内所有 UID。
• 如果 recordingConfig 中的 streamTypes 为 0（只订阅音频），则不可设置视频订阅名单； 如果 recordingConfig 中的 streamTypes 为 1（只订阅视频），则不可设置音频订阅名单。
• 使用标准模式录制（streamMode 为 standard），如果录制过程中将 Native 端切换到 Web 端（或反之），录制结束后你会获得 M3U8 格式和 MPD 格式的两个音视频索引文件，无法连贯播放整个录制过程。
• 当订阅的 UID 超过 17 人时，云端录制会按 UID 加入频道的时间顺序，订阅前 17 个 UID 的视频。当某个订阅的 UID 离开频道，云端录制会自动订阅第 18 个加入频道的 UID，以此类推。
• 禁用视频轨道之后，录制效果详见下表：

  发流端类型	禁用视频轨道的方法	录制效果
  Native	调用 muteLocalVideoStream 或 disableVideo 方法	不继续生成视频切片文件，在本切片内用户画面显示最后一帧。
  Web SDK 3.x	调用 muteVideo 方法	持续生成视频切片文件，用户画面为黑屏。
  Web SDK 4.x	调用 setEnabled 方法	不继续生成视频切片文件，在本切片内用户画面显示最后一帧。