实现单流录制

更新时间

云端录制支持单流录制、合流录制和页面录制三种模式,其中单流录制模式指分别录制频道中每个用户 ID 的音频流和视频流,录制结束后每个用户 ID 会生成对应的音频文件和视频文件。

本文介绍如何使用云端录制的 RESTful API 并设置核心字段,进行单流录制并生成特定格式的文件。

信息

本文内容适用于新单流录制。旧版单流录制文档请参阅旧版实现单流录制。

从旧版单流录制迁移

从旧版单流录制迁移至 v2 时,除调整录制文件处理逻辑外,还需要更新以下配置:

  • 将 start、update、query 和 stop 请求 URL 中的 mode/individual 改为 mode/raw。
  • 删除 recordingConfig.streamMode。v2 不再支持 standard、default 和 original。
  • 删除请求中的 clientRequest.extensionServiceConfig。新单流录制(mode=raw)不支持该字段,请求中包含该字段会被接口拒绝。
  • 如果使用消息通知服务,将回调处理逻辑中对 payload.serviceScene 的判断从 rtc_record 更新为 rtsc/raw-recording,否则可能忽略新单流录制的回调。字段说明见回调事件概览。

前提条件

开始前,请参考使用 RESTful API 开始云端录制进行一次完整的录制流程体验。

实现步骤

本节介绍如何在申请录制服务器资源后,实现单流音视频录制。

开始录制

调用 start 方法开始云端录制。

请求示例

以下介绍开始单流音视频录制请求的关键配置,确保你进行正确设置以实现预期的录制效果。

  1. 在调用 start 方法时,将 mode 参数设置为 raw,开启单流录制模式。

    注意

    录制模式的设置必须在开始录制的时候完成,不支持在录制开始后切换模式。

  2. 设置 recordingConfig 和 recordingFileConfig 中的参数。不同 streamTypes 与 recordingFileConfig.avFileType 配置组合对应的录制文件生成关系如下。具体设置参见 streamTypes 参数说明。

录制内容recordingFileConfig.avFileType 设置最终输出效果
仅录制音频["hls"]每个用户 ID 生成一个 HLS 文件,仅包含该用户的音频数据。
仅录制音频["hls", "mp3"]

同时生成 2 份文件:

  • 每个用户 ID 生成一个 HLS 文件,仅包含该用户的音频数据。
  • 每个用户 ID 生成一个 MP3 文件。
仅录制音频["mp3"]不支持。
表格内容超出当前宽度,可横向滚动查看更多列。
录制内容recordingFileConfig.avFileType 设置最终输出效果
仅录制视频["hls"]每个用户 ID 生成一个 HLS 文件或 DASH 文件(取决于源流视频编码器),每个切片内仅包含该用户的视频数据。
仅录制视频["hls", "mp4"]

同时生成 2 份文件:

  1. 每个用户 ID 生成一个 HLS 文件或 DASH 文件(取决于源流视频编码器),每个切片内仅包含该用户的视频数据。
  2. 每个用户 ID 生成一个 MP4 文件。该功能有一些已知限制,详见单流直接生成 MP4。
仅录制视频["mp4"]不支持。
表格内容超出当前宽度,可横向滚动查看更多列。
录制内容recordingFileConfig.avFileType 设置最终输出效果
同时录制音视频["hls"]每个用户 ID 生成一个 HLS 文件或 DASH 文件(取决于源流视频编码器),每个切片内同时包含该用户的音频及视频数据。
同时录制音视频["hls", "mp4"]

同时生成 2 份文件:

  1. 每个用户 ID 生成一个 HLS 文件或 DASH 文件(取决于源流视频编码器),每个切片内同时包含该用户的音频及视频数据。
  2. 每个用户 ID 生成一个 MP4 文件。该功能有一些已知限制,详见单流直接生成 MP4。
同时录制音视频["mp4"]不支持。
表格内容超出当前宽度,可横向滚动查看更多列。

信息

  • HLS 文件表示一个 M3U8 文件及多个 TS 文件,属于标准 HLS 协议,可直接播放。
  • DASH 文件表示一个 MPD 文件及多个 WebM 文件,属于标准 DASH 协议,可直接播放。

如需了解录制文件的命名规则、字段含义和切片规则,请参见录制文件介绍。

  1. 参照快速开始配置 storageConfig 相关参数。

单流音视频录制的请求 Body 示例如下:

Shell
curl --location --request POST 'https://api.sd-rtn.com/v1/apps/<your_app_id>/cloud_recording/resourceid/<resourceid>/mode/raw/start' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: <http_basic_auth>' \
--data '{
  "cname": "show",
  "uid": "123",
  "clientRequest": {
    "token": "<your_token>",
    "recordingConfig": {
      "channelType": 1,
      "streamTypes": 2,
      "videoStreamType": 0,
      "maxIdleTime": 30,
      "subscribeAudioUids": [
        "123",
        "456"
      ],
      "subscribeVideoUids": [
        "123",
        "456"
      ],
      "subscribeUidGroup": 0
    },
    "recordingFileConfig": {
      "avFileType": [
        "hls",
        "mp4"
      ]
    },
    "storageConfig": {
      "vendor": 2,
      "region": 3,
      "bucket": "<your_storage_bucket_name>",
      "accessKey": "<your_storage_access_key>",
      "secretKey": "<your_storage_secret_key>",
      "fileNamePrefix": [
        "quickstart",
      ]
    },
  }
}

单流直接生成 MP4

单流录制模式下,视频不做编解码。若想直接生成可播放的 MP4 文件,且尽量减少 MP4 切片数量,需要满足以下条件:

  • 源流视频编码器必须是 H.264、H.265 或 AV1。若源流是 VP8 或 VP9,则不支持直接生成 MP4。
  • 源流分辨率保持不变。

具体设置如下:

调用 SetVideoEncodeConfiguration,将参数 orientationMode 设置为 1 或 2,固定为横屏或竖屏。

调用 SetVideoEncodeConfiguration,将参数 DEGRADATION_PREFERENCE 设置为 3 或 100,保持分辨率不变或关闭 VQC。

调用 setOptimizationMode API,将 OptimizationMode 设置为 detail,即清晰度优先,弱网情况下优先降低帧率,不降低分辨率。

若主播源流无法满足上述要求,录制过程中分辨率发生变化,变化前后将生成不同的 MP4 切片文件,具体文件名可参考录制文件组成及命名规则。

信息

如果无法保证主播源流分辨率固定,也不接受生成多段 MP4 文件,或者主播源流是 VP8/VP9 编码,则可使用合流录制,在录制过程中实时转码,以最大限度保证 MP4 文件兼容性。

响应示例

JSON
{
    "cname": "show",
    "uid": "123",
    "resourceId": "SGXETXXX",
    "sid": "04a85XXX"
}

你需要复制 sid 以备后用。

停止录制

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

请求示例

Shell
curl --location --request POST 'https://api.sd-rtn.com/v1/apps/<yourappid>/cloud_recording/resourceid/<resourceid>/sid/<sid>/mode/raw/stop' \
--header 'Content-Type: application/json' \
--data '{
  "cname": "show",
  "uid": "123",
  "clientRequest": {
    "async_stop": false
  }
}'

响应示例

JSON
{
  "resourceId": "SGXETXXX",
  "sid": "04a85XXX",
  "serverResponse": {
    "fileListMode": "json",
    "fileList": [
      {
        "fileName": "xxxxxxx",
        "isPlayable": true,
        "mixedAllUser": false,
        "sliceStartTime": xxxxxxxxxx,
        "trackType": "audio_and_video",
        "uid": "xxx"
      }
    ],
    "uploadingStatus": "uploaded"
  },
  "cname": "show",
  "uid": "123"
}

uploadingStatus 字段表示录制文件上传状态:

  • uploaded:录制文件已上传至第三方云存储。
  • stranded:v2 新增状态,表示部分录制文件尚未上传至指定的第三方云存储。录制服务会继续自动重试上传,直至上传成功;该状态不表示文件丢失。业务侧应将其视为“上传未完成”,等待文件上传完成后再进行依赖完整录制文件的播放或处理。

开发注意事项

在进行单流录制过程中,你需要关注如下注意事项:

  • 如果在录制过程中禁用视频轨道,则录制效果详见下表:

    发流端类型禁用视频轨道的方法录制效果
    Native 端调用 muteLocalVideoStream 或 disableVideo 方法不继续生成视频切片文件,在本切片内用户画面显示最后一帧。
    Web 端调用 setEnabled 方法不继续生成视频切片文件,在本切片内用户画面显示最后一帧。
    表格内容超出当前宽度,可横向滚动查看更多列。

相关文档

在单流录制过程中,你还可以参考如下文档:

API 参考

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

常见问题