开始录制

描述

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

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

注意

每个录制任务时间最长为 24 小时。超过 24 小时，录制任务将自动停止录制。
ZEGO 建议您的每个录制任务都调用 StopRecord 方法停止录制，以免持续录制产生额外的费用。

接口原型

请求方法：POST
请求地址：https://cloudrecord-api.zego.im/?Action=StartRecord
传输协议：HTTPS
调用频率限制：50 次/秒

请求参数

以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表请参考调用方式中的 “公共请求参数”。

参数	类型	是否必选	描述
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 重新在房间内推流。最终，同一份录制文件会保留正常推流内容和静音帧。混流录制：中断过程中，视频将停留在最后一帧（默认）或显示流画面背景图。此外，若混流中没有音频内容了，服务端将补充静音帧，直到使用同样的流 ID 重新在房间内推流。最终，同一份录制文件会保留正常推流内容、补白画面和静音帧（如有）。如果需要使用流画面背景图作为补白，请参考 DefaultMixStreamBackgroundImage 和 BackgroundImage 参数说明。仅当进行混流录制时（即 RecordMode 取值为 2），设置流画面背景图才会生效。 false：用户推流中断时不会补白，该用户下次重推生成新的录制文件。中断补白的时机有两种可能：房间无流时长超时导致自动停止云录制，见 MaxIdleTime 的定义。主动停止云录制。
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 属性列表。

注意

FillBlank 和 MaxIdleTime 作用对象不同：
- FillBlank：作用于流本身，只要录制任务还在进行，FillBlank设置为 true 后，若流处于中断状态，则会继续以补白的方式录制，此时该流仍然为中断状态，不影响房间内有无流的判断。
- MaxIdleTime：作用于整个录制任务状态，当房间内无流时长超过 MaxIdleTime 时，则会中止整个录制任务。
混流录制模式下，若 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。
BackgroundColor	Int	否	白板背景颜色，默认为白色。前三个字节为 RGB 颜色值，第四个字节固定为 0，即 0xRRGGBB00。
IsPPTAnimation	Bool	否	是否录制动态 PPT，默认为 false。 true：录制动态 PPT，支持录制 PPT 中的动画效果、视频。 false：不录制动态 PPT，PPT 中的动画效果、视频不会被录制下来。
PPTAnimationFps	Int	否	录制动态 PPT 的帧率，默认值为 15，有效范围 [1,30]。

注意

使用录制动态 PPT 功能前，请联系 ZEGO 商务人员付费开通。否则，设置 IsPPTAnimation 和 PPTAnimationFps 参数无效。

MixConfig

参数	类型	是否必选	描述
MixMode	Int	否	布局方式。 1：自定义布局，必须指定 MixInputList 2：（默认）平分布局 3：水平布局 4：垂直布局 5：悬浮布局
MixInputList	Array of Object	否	自定义布局参数。详见 MixInputList 属性列表。
FillMode	Int	否	(适用于 `MixConfig` 中的 `MixMode` 不为 `1`，即不是自定义布局时) 实际视频流宽高比与画面不一致时的处理方式。 1：裁剪模式，该模式下优先保证画面被填满，原视频等比缩放填满画面后，四周超出画面的内容会被裁剪。（默认值） 2：缩放模式，该模式下优先保证原视频的完整性，原视频等比缩放填满画面后，四周会补一圈黑边。说明如需了解适用于自定义布局的 `FillMode`，请参考 `mixinputlist.FillMode`。
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 地址。建议水印图片的大小和设置的水印布局大小一致，若两者不一致，水印图片会被拉伸以填满水印布局的位置。水印图片格式支持 JPG 和 PNG，大小不能超过 5MB，如水印图片下载失败，则设置不生效。 URL 支持 HTTP 和 HTTPS 协议。
MixOutputWatermarkImageConfig	Object	否	水印布局配置。详见 MixOutputWatermarkImageConfig 属性列表。
DefaultMixStreamBackgroundImage	String	否	流画面默认背景图的 URL 地址，当 FillBlank 为 true 时，指定流不存在或者流中断，且录制模式为混流录制时，会显示该背景图。自定义布局时，若对指定流 ID 设置了 BackgroundImage，则优先显示 BackgroundImage。建议背景图的大小和设置的流的画面大小一致，若两者不一致，背景图会被拉伸或压缩以填满整个画面。背景图格式支持 JPG 和 PNG，大小不能超过 5MB，如背景图下载失败，则设置不生效。 URL 支持 HTTP 和 HTTPS 协议。
IsAlwaysMix	Bool	否	录制任务启动后，是否立即开始录制。默认为 false，表示房间内进行推流后，开始录制。 true：录制任务启动后，立即开始录制。 false：录制任务启动后，等房间内进行推流后，开始录制。
MixOutputWatermarkTimestampConfig	Object	否	时间水印配置。配置后，时间水印显示在视频右上角，格式为 yyyy-MM-dd HH:mm 。详见 MixOutputWatermarkTimestampConfig 属性列表。
RecordSoundWave	Bool	否	录制任务启动后，是否记录音浪信息。默认为 false。 true：录制任务启动后，每间隔1秒记录当前所有流的音浪信息。 false：录制任务启动后，不记录音浪信息。音浪信息会以 JSON 格式写入到一个独立的文件中，文件名称与录制文件名称一致，后缀为.sw，在录制任务结束后，和录制文件一起上传到指定的云存储位置。
SoundWaveType	Int	否	音浪信息类型。注意：仅当 `RecordSoundWave` 为 `true` 时，此参数生效。 0：记录流 ID 信息（默认值）。示例：`\{"time":10, "sound_wave":[{"stream_id":"s1", "volume":0}]\}` 1：记录用户 ID 信息。示例：`{"time":10, "sound_wave":[{"user_id":"u1", "volume":0}]}`
StreamConfigList	Array of Object	否	自定义流参数。详见 StreamConfigList 属性列表。
ClearInputStreamTimeout	Int	否	等待输入流的超时时间，单位为毫秒。在此期间，ZEGO 服务端等待获取输入流后才开始混流。若超时仍未收到输入流，混流将自动开始。

MixInputList

参数	类型	是否必选	描述
StreamId	String	否	指定在该画面中录制的流的 ID。如果未指定，会按照流加入房间的时间顺序进行录制。
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]，不能超过画布的高。

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

StreamConfigList

参数	类型	是否必选	描述
StreamId	String	否	流 ID。
StreamType	Int	否	流录制类型，仅在 RecordInputParams 中的 StreamType等于 3 或 4 生效。 0: 默认类型 1 音频 2: 视频 3: 音视频

StreamConfigList 中如果StreamId为空，表示设置参数的默认值，其他没有在 StreamConfigList 中出现的流会使用参数默认值。

MixOutputWatermarkTimestampConfig

参数	类型	是否必选	描述
FontSize	Int	是	字体大小，取值范围 [12, 100]，单位 px。

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 协议。
FragmentSeconds	Int	否	分片时长，单位：秒，取值范围是 [2, 60]，默认值 15。注意：仅当 `OutputFileFormat` 为"hls"时，此参数生效。
RealtimeUploadFragment	Bool	否	是否在录制时实时上传分片。注意：仅当 `OutputFileFormat` 为 "hls"时，此参数生效。
ShortFragmentPath	Bool	否	M3U8 文件是否只保存视频分片文件（如 .ts 文件）的文件名，而非视频分片的路径。注意：仅当 `RealtimeUploadFragment` 为 "true" 时生效。

StorageParams

说明

各个属性参数的填写方法请参考 StorageParams 中的各个云存储相关的参数如何填写？

参数	类型	是否必选	描述
Vendor	Int	是	录制文件存储服务提供商，目前支持的存储服务提供商如下： 1：亚马逊 S3 2：阿里云 OSS 3：腾讯云 COS 4：七牛云 Kodo 5：阿里云 Vod 6：腾讯云 Vod 7：华为云 OBS 8：谷歌云 Cloud Storage 9：移动云 EOS 10：使用 S3 协议的存储服务提供商，需要填写 `StorageParams` 属性参数 `EndPoint`。
Region	String	否	云存储指定的地区信息。
Bucket	String	否	云存储 bucket。
AccessKeyId	String	否	云存储的 access key，建议提供只写权限的访问密钥。
AccessKeySecret	String	否	云存储的 secret key。
AlibabaCloudVodParams	Object	否	阿里云 Vod 存储信息。详见 AlibabaCloudVodParams 属性列表。
TencentCloudVodParams	Object	否	腾讯云 Vod 存储信息。详见 TencentCloudVodParams 属性列表。
EndPoint	String	否	Vendor为 10 时，填写使用 S3 协议的存储服务的地址。

注意

Vendor设置为 1、2、3、4、7、9、10 时，Region，Bucket，AccessKeyId，AccessKeySecret 必选。
Vendor 设置为 5 时，AlibabaCloudVodParams 必选。目前仅支持上传 MP4、FLV 格式文件。
Vendor 设置为 6 时，TencentCloudVodParams 必选。目前仅支持上传 MP4、FLV、JPG、MP3 格式文件。
Vendor设置为 8 时，Bucket，AccessKeyId，AccessKeySecret 必选。
Vendor设置为 10 时，Bucket，EndPoint 必选。

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。

请求示例

请求 URL

Untitled

https://cloudrecord-api.zego.im/?Action=StartRecord
&AppId=1234567890
&SignatureNonce=15215528852396
&Timestamp=1234567890
&Signature=7a2c0f11145fb760d607a07b54825013
&SignatureVersion=2.0

Copied!

请求消息体

亚马逊 S3、阿里云 OSS、腾讯云 COS、七牛云 Kodo、华为云 OBS、移动云 EOS

阿里云 Vod

S3 协议存储服务提供商

{
    "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"
    }
}

Copied!

{
    "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"
        }
    }
}

Copied!

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

Copied!

响应参数

参数	类型	描述
Code	Int64	错误码。
Message	String	错误描述。
RequestId	String	请求 ID。
Data	Object	响应对象。
└TaskId	String	云录制服务分配的任务 ID，长度固定为 16 个字节的字符串。任务 ID 是对一次录制生命周期过程的唯一标识，结束录制时会失去意义。

响应示例

Untitled

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

Copied!