云端录制
  • 产品简介
    • 概述
    • 发布日志
    • 计费说明
  • 快速开始
    • 实现云端录制
  • 基础功能
  • 服务端 API v2
  • 常见问题

开始录制

更新时间:2022-06-10 16:01

  1. 本 API 为最新服务端 API v2 接口,支持全球就近接入、统一的鉴权方式、统一的参数风格和公共错误码。后续相关功能的新增都会在此更新。
  2. 旧版 API 接口仅供 2021-09-10 前接入的旧用户维护使用。旧版接口文档请参考 旧版服务端 API

1 描述

调用本接口开始云端录制。

当开发者成功调用 StartRecord 接口后,云端录制服务会根据设置的录制参数录制房间内的音视频流和白板。

每个录制任务时间最长为 24 小时。超过 24 小时,录制任务将自动停止录制。

2 接口原型

  • 请求方法:POST
  • 请求地址:https://cloudrecord-api.zego.im/?Action=StartRecord
  • 传输协议:HTTPS
  • 调用频率限制:50 次/秒(测试环境:20 次/秒)

3 请求参数

以下请求参数列表仅列出了接口请求参数,公共参数列表请参考 调用方式 - 公共请求参数

参数 类型 是否必选 描述
RoomId
String
待录制的房间 ID。
RecordInputParams
Object
录制任务输入参数。
详见 RecordInputParams 成员列表
RecordOutputParams
Object
录制任务输出参数。
详见 RecordOutputParams 成员列表
StorageParams
Object
录制任务的存储配置。
详见 StorageParams 成员列表
若未指定该项配置,则使用开启云端录制服务时设置的存储配置。

RecordInputParams 成员如下:

参数 类型 是否必选 描述
RecordMode
Int
录制模式。
  • 1:单流录制
  • 2:混流录制
StreamType
Int
录制媒体流类型,仅适用于音视频流,白板只会录制视频。
  • 1:仅录制音频
  • 2:仅录制视频
  • 3:录制音视频(音视频文件合并)(默认值)
  • 4:录制音视频(音频视频文件分离)
RecordStreamList
Array of Object
仅适用于单流录制模式,指定要录制的流信息列表。
详见 RecordStreamList 成员列表
若未指定该字段或该列表为空,默认录制房间中所有流。
FillBlank
Bool
流中断时是否自动补白,默认为 false,即不补白。
  • true:用户推流中断时会自动补白,中断过程中视频停留在最后一帧(默认)或显示流画面背景图,用同样的流 ID 重推,录制将恢复正常,写入同一个录制文件中。
  • false:用户推流中断时不会补白,该用户下次重推生成新的录制文件。
中断补白的时机有两种可能:
  • 房间无流时长超时导致自动停止云录制,见 MaxIdleTime 的定义。
  • 主动停止云录制。
流画面背景图的说明请参见 DefaultMixStreamBackgroundImageBackgroundImage
FillFrame
Object
关闭摄像头后(音频持续在推)填充画面的方式,仅适用于混流录制。
详见 FillFrame 成员列表
RecordMuteAudio
Int
指定是否录制静音状态下的音频帧数据,仅当单流录制、只录制音频且输出文件格式为 mp3 时生效。
  • 1:录制静音状态下的音频帧(默认值)
  • 2:不录制静音状态下的音频帧
RecordMuteAudioSplitThreshold
Int
录制文件自动分片的静音时长阈值,单位:秒。
录制过程中如果静音状态时长大于等于该阈值,则该段静音前后会生成为不同的录制文件。
仅当单流录制、只录制音频、输出文件格式为 mp3 且 RecordMuteAudio 为 2 时生效。
指定为 0 时遇静音即分片,不指定或者指定为负数时表示不分片。
HasWhiteboard
Bool
是否录制白板。
  • true:录制白板
  • false:不录制白板(默认值)
本参数为 true 时 Whiteboard 参数必选。
Whiteboard
Array of Object
白板参数,HasWhiteboard 为 true 时必选。
详见 Whiteboard 成员列表
MaxIdleTime
Int
房间内没有任何流、白板之后多长时间自动停止云录制,单位:秒。默认值为 30 秒,该值需大于等于 5,且小于等于 86400(24 小时)。
注意:该参数仅当房间内无流、无白板时生效。
MaxRecordTime
Int
录制任务最大时长,录制持续时间达到该值自动结束。单位:秒。默认值 86400 秒(24 小时),该值需大于等于 300,且小于等于 86400(24 小时)。
MixConfig
Object
混流参数,RecordMode 为 2 时必选。
详见 MixConfig 成员列表
  1. FillBlankMaxIdleTime 作用对象不同:
  • FillBlank:作用于流本身,只要录制任务还在进行,FillBlank设置为 true 后,若流处于中断状态,则会继续以补白的方式录制,此时该流仍然为中断状态,不影响房间内有无流的判断。
  • MaxIdleTime:作用于整个录制任务状态,当房间内无流时长超过 MaxIdleTime 时,则会中止整个录制任务。
  1. 混流录制模式下,若 StreamType 为 1,表示仅录制音频,此时无法录制白板。

RecordStreamList 成员如下:

参数 类型 是否必选 描述
StreamId
String
待录制的流 ID。

FillFrame 成员如下:

参数 类型 是否必选 描述
FrameFillMode
Int
画面填充模式。
  • 1:填充最后一帧(默认值)
  • 2:填充指定颜色
  • 3:不填充帧
FrameFillColor
Int
FrameFillMode 设置为 2 时有效,用于指定填充颜色,默认为黑色。前三个字节为 RGB 颜色值,第四个字节固定为 0,即 0xRRGGBB00。

FrameFillMode 相关:

  • 小程序端仅支持填充最后一帧,不支持填充指定颜色或不填充帧。
  • web 端仅支持填充黑色,不支持填充最后一帧或填充其它颜色或不填充帧。

Whiteboard 成员如下:

参数 类型 是否必选 描述
HorizontalRatio
Int
原始白板的宽高比(宽)。
VerticalRatio
Int
原始白板的宽高比(高)。
Width
Int
单流录制白板输出视频的分辨率宽,默认值为 1280。
Height
Int
单流录制白板输出视频的分辨率高,默认值为 720。
WhiteboardId
String
录制白板的 ID。
  • 如果希望开始录制后立刻录制白板,必须指定白板 ID。
  • 如果希望开始录制后先不录制白板,可不携带该参数,待需要录制白板时调用 更新白板 接口指定白板 ID。
IsPPTAnimation
Bool
是否录制动态 PPT,默认为 false。
  • true:录制动态 PPT,支持录制 PPT 中的动画效果、视频。
  • false:不录制动态 PPT,PPT 中的动画效果、视频不会被录制下来。
PPTAnimationFps
Int
录制动态 PPT 的帧率,默认值为 15,有效范围 [1,30]。

录制动态 PPT 功能需单独收费,需开通请先联系 ZEGO 商务人员。若未开通,直接设置 IsPPTAnimationPPTAnimationFps 参数属于无效设置。

MixConfig 成员如下:

参数 类型 是否必选 描述
MixMode
Int
布局方式。
  • 1:自定义布局,必须指定 MixInputList
  • 2:(默认)平分布局
  • 3:水平布局
  • 4:垂直布局
  • 5:悬浮布局
MixInputList
Array of Object
自定义布局参数。
详见 MixInputList 成员列表
MixOutputStreamId
String
指定混流输出的流 ID,将作为 OutputFileRule 中的一部分。
MixOutputVideoConfig
Object
输出视频参数;StreamType 为 2、3、4 时,此参数必选。
详见 MixOutputVideoConfig 成员列表
MixOutputAudioConfig
Object
输出音频参数。
详见 MixOutputAudioConfig 成员列表
MixOutputBackgroundColor
Int
录制背景颜色,默认为黑色。前三个字节为 RGB 颜色值,第四个字节固定为 0,即 0xRRGGBB00。
MixOutputBackgroundImage
String
视频画布背景图的 URL 地址。
  • 建议背景图的分辨率与输出视频分辨率一致,如两者分辨率不一致,背景图会被拉伸或压缩以填满整个画面。
  • 背景图格式支持 JPG 和 PNG,大小不能超过 5MB,如背景图下载失败,则设置不生效。
  • URL 支持 HTTP 和 HTTPS 协议。
MixMaxResolutionStreamId
String
MixMode 设为 3、4、5 时,用于指定显示大画面的流 ID。
MixOutputWatermarkImage
String
水印图片的 URL 地址。
  • 建议背景图的分辨率与输出视频分辨率一致,如两者分辨率不一致,水印图片会被拉伸或压缩以填满整个画面。
  • 水印图格式支持 PNG,背景必须透明,否则会遮挡录制画面;大小不能超过 5MB,如水印图下载失败,则设置不生效。
  • URL 支持 HTTP 和 HTTPS 协议。
MixOutputWatermarkImageConfig
Object
水印布局配置。
详见 MixOutputWatermarkImageConfig 成员列表
DefaultMixStreamBackgroundImage
String
流画面默认背景图的 URL 地址,当 FillBlank 为 true 时,指定流不存在或者流中断时会显示该背景图。
  • 自定义布局时,若对指定流 ID 设置了 BackgroundImage,则优先显示 BackgroundImage。
  • 建议背景图的大小和设置的流的画面大小一致,若两者不一致,背景图会被拉伸或压缩以填满整个画面。
  • 背景图格式支持 JPG 和 PNG,大小不能超过 5MB,如背景图下载失败,则设置不生效。
  • URL 支持 HTTP 和 HTTPS 协议。

MixInputList 成员如下:

参数 类型 是否必选 描述
StreamId
String
指定在该画面显示的 streamID,如果未指定,会按照流加入房间的时间顺序进行匹配。
ViewType
Int
该画面显示内容的类型。
  • 1:音视频(默认值)
  • 2:白板
类型 2 仅在开启白板录制时有效,仅支持将一个画面设置为白板,超过两个及以上会返回错误。
Top
Int
画布上该画面左上角的 y 轴坐标,取值范围 [0, 1920],不能超过 Bottom 的值和画布的高。
Left
Int
画布上该画面左上角的 x 轴坐标,取值范围 [0, 1920],不能超过 Right 的值和画布的宽。
Bottom
Int
画布上该画面右下角的 y 轴坐标,取值范围 [0, 1920],不能超过画布的高。
Right
Int
画布上该画面右下角的 x 轴坐标,取值范围 [0, 1920],不能超过画布的宽。
Layer
Int
该画面的图层优先级,当两个画面发生重叠时,数值大的显示在上方。
FillMode
Int
实际视频流宽高比与画面不一致时的处理方式。
  • 1:裁剪模式,该模式下优先保证画面被填满,原视频等比缩放填满画面后,四周超出画面的内容会被裁剪。(默认值)
  • 2:缩放模式,该模式下优先保证原视频的完整性,原视频等比缩放填满画面后,四周会补一圈黑边。
BackgroundImage
String
流画面背景图的 URL 地址,仅当指定了 StreamId 时生效。
自定义布局指定的流不存在或者流中断时会显示该背景图。
  • 建议背景图的大小和设置的流的画面大小一致,若两者不一致,背景图会被拉伸或压缩以填满整个画面。
  • 背景图格式支持 JPG 和 PNG,大小不能超过 5MB,如背景图下载失败,则设置不生效。
  • URL 支持 HTTP 和 HTTPS 协议。

MixOutputVideoConfig 成员如下:

参数 类型 是否必选 描述
Width
Int
输出视频的分辨率宽,单位为像素。
Width 取值小于或等于 1920,且 Width 和 Height 的乘积不能超过 1920 * 1080,否则会报错。
Height
Int
输出视频的分辨率高,单位为像素。
Height 取值小于或等于 1920,且 Width 和 Height 的乘积不能超过 1920 * 1080,否则会报错。
Fps
Int
输出视频的帧率,默认 15,有效范围 [5,30]。
Bitrate
Int
输出视频的码率,单位:bps。例如要设置码率为 1.5 Mbps 时,需要设置设置此参数为 1500*1000,也就是 1500000。

MixOutputAudioConfig 成员如下:

参数 类型 是否必选 描述
Bitrate
Int
音频码率,默认值为 48000 bps。

MixOutputWatermarkImageConfig 成员如下:

参数 类型 是否必选 描述
Left
Int
画布上该水印左上角的 x 轴坐标,取值范围 [0, 1920],不能超过 Right 的值和画布的宽。
Top
Int
画布上该水印左上角的 y 轴坐标,取值范围 [0, 1920],不能超过 Bottom 的值和画布的高。
Right
Int
画布上该水印右下角的 x 轴坐标,取值范围 [0, 1920],不能超过画布的宽。
Bottom
Int
画布上该水印右下角的 y 轴坐标,取值范围 [0, 1920],不能超过画布的高。

坐标系相关说明,请参考 设置混流布局 - 自定义布局

RecordOutputParams 成员如下:

参数 类型 是否必选 描述
OutputFileFormat
String
指定录制生成文件的格式,默认为 “mp4”。目前支持 “mp4”、“flv”、“hls”、“jpg” 和 "mp3"。如果录制 “mp4” 或 “flv”,且 StreamType 设为 4,则录制生成的音频文件格式为 aac。
OutputFolder
String
录制文件在第三方云存储的输出目录,默认为根目录。
OutputFileRule
Int
录制文件命名规则,默认值为 1(暂不支持设置其它命名格式),表示命名格式为:
  • TaskId_RoomId_UserId_StreamId_Type_UTC(单流录制)
  • Taskid_RoomId_MixOutputStreamId_Type_UTC(混流录制)
  • Taskid_Roomid_whiteboard_Type_UTC(单流录制带白板)
文件名中的字段含义如下:
  • Type:文件类型,V 表示视频文件,A 表示音频文件,VA 表示音视频文件。
  • UTC:该文件开始录制时的 UTC 时间,时区为 UTC+0,由年、月、日、小时、分钟、秒和毫秒组成。
  • MixOutputStreamId:在 MixConfig 中指定。
  • whiteboard:固定,不可修改。
SnapshotInterval
Int
截图周期,单位:秒。录制文件格式为 “jpg” 时有效,取值范围是 [5, 3600],默认值 10。
CallbackUrl
String
自定义回调地址的 URL,不填写此参数时会使用服务开通时配置的回调地址。URL 支持 HTTP 和 HTTPS 协议。

StorageParams 成员如下:

各个成员参数的填写方法请参考 StorageParams 中的各个云存储相关的参数如何填写?

参数 类型 是否必选 描述
Vendor
Int
录制文件存储服务提供商,目前支持的存储服务提供商如下:
  • 1:亚马逊 S3
  • 2:阿里云 OSS
  • 3:腾讯云 COS
  • 4:七牛云 Kodo
  • 5:阿里云 Vod
  • 6:腾讯云 Vod
  • 7:华为云 OBS
Region
String
云存储指定的地区信息。
Bucket
String
云存储 bucket。
AccessKeyId
String
云存储的 access key,建议提供只写权限的访问密钥。
AccessKeySecret
String
云存储的 secret key。
AlibabaCloudVodParams
Object
阿里云 Vod 存储信息。
详见 AlibabaCloudVodParams 成员列表
TencentCloudVodParams
Object
腾讯云 Vod 存储信息。
详见 TencentCloudVodParams 成员列表
  • Vendor设置为 1~4 还有 7 时,RegionBucketAccessKeyIdAccessKeySecret 必选。
  • Vendor设置为 5 时,AlibabaCloudVodParams 必选。目前仅支持上传 MP4、FLV 格式文件。
  • Vendor设置为 6 时,TencentCloudVodParams 必选。目前仅支持上传 MP4、FLV 格式文件。

AlibabaCloudVodParams 成员如下:

参数 类型 是否必选 描述
Region
String
阿里云 Vod 指定的地区信息,例如 cn-shanghai。
AccessKeyId
String
阿里云 Vod 的 access key。
AccessKeySecret
String
阿里云 Vod 的 secret key,建议提供只写权限的访问密钥。
Title
String
阿里云 Vod 视频名称。
StorageLocation
String
阿里云 Vod 提供的固定参数。

TencentCloudVodParams 成员如下:

参数 类型 是否必选 描述
SecretId
String
腾讯云 Vod 的 access key。
SecretKey
String
腾讯云 Vod 的 secret key,建议提供只写权限的访问密钥。
Region
String
腾讯云 Vod 指定的地区信息,例如 ap-shanghai。
SubAppId
Int64
腾讯云 Vod 的子应用 ID。

4 请求示例

  • 请求 URL
    https://cloudrecord-api.zego.im/?Action=StartRecord
    &AppId=1234567890
    &SignatureNonce=15215528852396
    &Timestamp=1234567890
    &Signature=7a2c0f11145fb760d607a07b54825013
    &SignatureVersion=2.0
    &IsTest=false
  • 请求消息体

以下是使用亚马逊 S3、阿里云 OSS、腾讯云 COS、七牛云 Kodo、华为云 OBS 请求消息体示例。

{
    "RoomId": "xxxx",
    "RecordInputParams": {
        "RecordMode": 1,
        "StreamType": 3,
        "MaxIdleTime": 60
    },
    "RecordOutputParams": {
        "OutputFileFormat": "mp4",
        "OutputFolder": "record/"
    },
    "StorageParams": {
        "Vendor": 2,
        "Region": "oss-xxxx",
        "Bucket": "xxxx",
        "AccessKeyId": "xxxx",
        "AccessKeySecret": "xxxx"
    }
}

以下是使用阿里云 Vod 请求消息体示例。

{
    "RoomId": "xxxx",
    "RecordInputParams": {
        "RecordMode": 1,
        "StreamType": 3,
        "MaxIdleTime": 60
    },
    "RecordOutputParams": {
        "OutputFileFormat": "mp4",
        "OutputFolder": "record/"
    },
    "StorageParams": {
        "Vendor": 5,
        "Region": "",
        "Bucket": "",
        "AccessKeyId": "",
        "AccessKeySecret": "",
        "AlibabaCloudVodParams":{
            "Region": "cn-xxxxx",
            "AccessKeyId": "xxxx",
            "AccessKeySecret": "xxxx",
            "Title": "xxxx",
            "StorageLocation": "xxxx.oss-cn-xxxx.aliyuncs.com",
            }
    }
}

5 响应参数

参数 类型 描述
Code
Int64
错误码。
Message
String
错误描述。
RequestId
String
请求 ID。
Data
Object
响应对象。
详见 Data 成员列表

Data 成员如下:

参数 类型 描述
TaskId
String
云录制服务分配的任务 ID,长度固定为 16 个字节的字符串。任务 ID 是对一次录制生命周期过程的唯一标识,结束录制时会失去意义。

6 响应示例

以下是 StartRecord 接口的响应示例。

{
    "Code": 0,
    "Message": "succeed",
    "RequestId": "abcd123",
    "Data": {
        "TaskId": "XXXXXXXXXXXX"
    }
}