You need to enable JavaScript to run this app.
导航
开始云端录制 StartRecord
最近更新时间:2024.09.29 17:13:36首次发布时间:2024.01.03 20:25:17

本文档 API 接口为最新版本接口,后续相关功能的新增都会在此更新,推荐使用最新版本接口。旧版接口文档请参考历史版本

注意

在开始录制前,你必须已经在控制台上开启录制功能,参看在控制台开启/关闭云端录制功能

在实时音视频通话场景中,你可以通过调用此接口实现云端录制功能,支持单流或合流录制模式。

你可以根据需求配置指定任务 ID、选择录制模式、自定义音视频流目标列表、设置编码参数、安排视频布局以及指定存储配置等,以满足多样化的录制需求。调用后,接口返回任务启动状态,确保录制流程顺利进行。

如果录制任务状态发生变化,你在控制台上设置的回调地址会收到每个状态变化的回调

使用说明

接口行为

录制分为单流录制和合流录制:

  • 单流录制时:你可以将每一路指定录制的流单独录制成一个音视频文件。此时,你不可以设置布局;整体画面分辨率为原始视频分辨率,并不支持修改。
  • 合流录制时:你可以将指定录制的流混合录制成一个音视频文件。录制时,你可以设置视频布局,分辨率,帧率,码率等。
    无论你使用单流录制还是合流录制,你最多只能录制 17 路流。

你需要在接口调用中配置存储空间,选择将录制结果存储在存储平台中。目前支持的存储平台包括:火山引擎视频点播 VOD、火山引擎对象存储 TOS、Amazon S3、阿里云对象存储 OSS、华为云 OBS、腾讯云 COS 和七牛云 Kodo。

录制文件生成后,不推荐调用 GetRecordTask接口获取录制生成的文件,强烈建议接入录制结束回调事件。

注意事项

请求频率:QPS 不得超过 60。

前提条件

如果你需要获取云端录制状态回调,请开通消息通知服务

请求说明

  • 请求方式:POST
  • 请求地址:https://rtc.volcengineapi.com?Action=StartRecord&Version=2023-11-01

调试

请求参数

下表仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共参数

Query

参数
类型
是否必选
示例值
描述
Action
String
StartRecord
接口名称。当前 API 的名称为 StartRecord
Version
String
2023-11-01
接口版本。当前 API 的版本为 2023-11-01

Body

参数
类型
是否必选
示例值
描述
AppId
String
661e****543cf
你的音视频应用的唯一标志,参看获取 AppId
BusinessId
String
B****23
业务标识
RoomId
String
Room1
房间的 ID,是房间的唯一标志
TaskId
String
Task1

云端录制任务 ID。你必须对每个云端录制任务设定 TaskId,且在后续进行任务更新和结束时也须使用该 TaskId。

TaskId 是任务的标识,在一个 AppIdRoomIdtaskId 是唯一的,不同 AppId 或者不同 RoomIdTaskId 可以重复,因此 AppId + RoomId + TaskId 是任务的唯一标识,可以用来标识指定 AppId 下某个房间内正在运行的任务,从而能在此任务运行中进行更新或者停止此任务。

关于 TaskId 及以上 Id 字段的命名规则符合正则表达式:[a-zA-Z0-9_@\-\.]{1,128}

若任务运行中,使用相同的 TaskId 重复调用开始接口不会导致请求失败,BaseResponse.Result 会提示 The task has been started. Please do not call the startup task interface repeatedly
RecordMode
Integer
0

录制模式。支持取值及含义如下:

  • 0 :合流录制,
  • 1 :单流录制。
默认值为 0
TargetStreams
Object
-
需要录制的音视频流。如果参数为空,默认录制房间内所有发布的音视频流,最多 17 路流。
此参数中的 stream 不得和 ExcludeStreams 中重复,若重复会报错InvalidParameter
StreamList
Object[]
-
音视频流列表,由Stream组成,可以为空。为空时,表示订阅房间内所有流。在一个 StreamList 中,Stream.Index 不能重复。
Index
Integer
0
在自定义布局中,使用 Index 对流进行标志。后续在 Layout.regions.StreamIndex 中,你需要使用 Index 指定对应流的布局设置。
UserId
String
user1
用户 ID,表示这个流所属的用户。
StreamType
Integer
0

流的类型。支持取值及含义如下:

  • 0:普通音视频流,
  • 1:屏幕流。
默认值为0
ExcludeStreams
Object
-
音视频流录制黑名单,即不需要录制的音视频流。
黑名单仅支持配置普通音视频流,且最多可配置 17 路。此参数中的 stream 不得和 TargetStreams 中重复。
默认值为空。
StreamList
Object[]
-
音视频流列表,由Stream组成,可以为空。为空时,表示订阅房间内所有流。在一个 StreamList 中,Stream.Index 不能重复。
Index
Integer
0
在自定义布局中,使用 Index 对流进行标志。后续在 Layout.regions.StreamIndex 中,你需要使用 Index 指定对应流的布局设置。
UserId
String
user1
用户 ID,表示这个流所属的用户。
StreamType
Integer
0

流的类型。支持取值及含义如下:

  • 0:普通音视频流,
  • 1:屏幕流。
默认值为0
Encode
Object
-

音视频编码参数。

  • 单流录制时,你仅可以设置 VideoFpsVideoBitrate
  • 合流录制时,你仅可以设置 VideoWidthVideoHeightVideoFps,和 VideoBitrate
VideoWidth
Integer
640
画面宽度。取值范围为 [2, 1920],必须是偶数,单位为像素,默认值为 640。该参数在垂直布局和并排布局下生效,自定义布局下请使用 canvas.Width 设置画面宽度。
VideoHeight
Integer
480
画面高度,取值范围为 [2, 1920],必须是偶数,单位为像素,默认值为 480。该参数在垂直布局和并排布局下生效,自定义布局下请使用 canvas.Height 设置画面宽度。
VideoFps
Integer
15
视频帧率。取值范围为 [1,60],单位为 FPS,默认值为 15
VideoBitrate
Integer
0
视频码率。取值范围为 [0,10000],单位为 Kbps,默认值为 0
0 表示自适应码率,会自动根据 VideoFps , VideoWidth 以及VideoHeight 计算出合理的码率。
自适应码率模式下,RTC 默认不会设置超高码率。如果订阅屏幕流,建议自行设置高码率。不同场景下设置码率等视频发布参数,请参考设置视频发布参数
VideoCodec
Integer
0

视频编码协议。支持取值及含义如下:

  • 0H.264
  • 1ByteVC1
默认值为 0
VideoGop
Integer
4
输出视频 GOP。取值范围为 [1,5],单位为秒,默认值为 4
AudioCodec
Integer
0
音频编码协议。仅支持取 0,表示 AAC 编码协议。
AudioProfile
Integer
0

音频配置文件类型。支持取值及含义如下:

  • 0 :采用 LC 规格;
  • 1: 采用 HE-AAC v1 规格;
  • 2: 采用 HE-AAC v2 规格。此时,只支持输出流音频声道数为双声道。
默认值为 0
AudioBitrate
Integer
64

音频码率。取值范围为 [32,192],单位为 Kbps,默认值为 64

AudioProfile=0时:
若输入参数取值范围为 [32,192],编码码率等于输入码率。

AudioProfile=1时:

  • 若输入参数取值范围为 [32,128],编码码率等于输入码率。
  • 若输入参数取值范围为 [128,192],编码码率固定为128

AudioProfile=2时:

  • 若输入参数取值范围为 [32,64],编码码率等于输入码率。
  • 若输入参数取值范围为 [64,192],编码码率固定为64
AudioSampleRate
Integer
48000
音频采样率。可取值为:32000,4410048000,单位为 Hz,默认值为 48000
AudioChannels
Integer
2

音频声道数。支持取值及含义如下:

  • 1:单声道。
  • 2:双声道。
默认值为 2
Layout
Object
-
布局参数。仅在合流模式(即 RecordMode=0)时下支持设置布局参数。
LayoutMode
Integer
0

布局模式。支持取值及含义如下:

默认值为0
MainVideoStream
Object
-
在垂直布局模式下生效,指定主画面流的属性。垂直布局时,此参数必填。
Index
Integer
0
在自定义布局中,使用 Index 对流进行标志。后续在 Layout.regions.StreamIndex 中,你需要使用 Index 指定对应流的布局设置。
UserId
String
user1
用户 ID,表示这个流所属的用户。
StreamType
Integer
0

流的类型。支持取值及含义如下:

  • 0:普通音视频流,
  • 1:屏幕流。
默认值为0
CustomLayout
Object
-
使用自定义布局模式时,使用此参数进行具体设置。
Canvas
Object
-
整体屏幕(画布)的宽高以及背景色。
Width
Integer
640
整体屏幕(画布)的宽度,取值范围为 [2, 1920],必须是偶数,单位为像素,默认值为 640
Height
Integer
480
整体屏幕(画布)的高度,取值范围为 [2, 1920],必须是偶数,单位为像素,默认值为 480
Background
String
#000000
整体屏幕(画布)的背景色, 范围为 #000000 ~ #ffffff (大小写均可),格式为 #RGB(16进制),默认值为 #000000(黑色)。
BackgroundImage
String
-
背景图片的 URL。长度最大为 1024 byte。可以传入的图片的格式包括:JPG, JPEG, PNG
如果背景图片的宽高和整体屏幕的宽高不一致,背景图片会缩放到铺满屏幕。
如果你设置了背景图片,背景图片会覆盖背景色。
Regions
Object[]
-

在自定义布局模式下,你可以使用 Regions 对每一路视频流进行画面布局设置。其中,每个 Region 对一路视频流进行画面布局设置。

自定义布局模式下,对于 StreamList 中的每个 StreamRegions 中都需要给出对应的布局信息,否则会返回请求不合法的错误。即 Regions.Region.StreamIndex 要与 TargetStreams.StreamList.Stream.Index 的值一一对应,否则自定义布局设置失败,返回 InvalidParameter 错误码。

当传入的必填参数值不合法时,返回错误码 InvalidParameter

StreamIndex
Integer
0
流的标识。这个标志应和 TargetStreams.StreamList.Stream.Index 对应。
LocationX
Integer
0

视频流对应区域左上角的横坐标相对整体画面左上角原点的横向位移,取值的范围为 [0.0, Canvas.Width)。默认值为 0。若传入该参数,服务端会对该参数进行校验,若不合法会返回错误码 InvalidParameter

视频流对应区域左上角的实际坐标是通过画面尺寸和相对位置比例相乘,并四舍五入取整得到的。假如,画布尺寸为1920, 视频流对应区域左上角的横坐标相对整体画面的比例为 0.33,那么该画布左上角的横坐标为 634(1920*0.33=633.6,四舍五入取整)。
LocationY
Integer
0
视频流对应区域左上角的横坐标相对整体画面左上角原点的纵向位移,取值的范围为 [0.0, Canvas.Height)。默认值为 0。若传入该参数,服务端会对该参数进行校验,若不合法会返回错误码 InvalidParameter
Width
Integer
640
视频流对应区域宽度的像素绝对值,取值的范围为 (0.0, Canvas.Width]
Height
Integer
480
视频流对应区域高度的像素绝对值,取值的范围为 (0.0, Canvas.Height]
ZOrder
Integer
0
当多个流的画面有重叠时,使用此参数设置指定画面的图层顺序。取值范围为 [0, 100],默认值为 00 表示该区域图像位于最下层,100 表示该区域图像位于最上层。
Alpha
Float
1
画面的透明度,取值范围为 (0.0, 1.0],默认值为 1.00.0 表示完全透明,1.0 表示完全不透明。
RenderMode
Integer
0

画面的渲染模式。支持取值及含义如下:

  • 0 :按照指定的宽高直接缩放。如果原始画面宽高比与指定的宽高比不同,就会导致画面变形
  • 1 :按照显示区域的长宽比裁减视频,然后等比拉伸或缩小视频,占满显示区域。
  • 2 :按照原始画面的宽高比缩放视频,在显示区域居中显示。如果原始画面宽高比与指定的宽高比不同,就会导致画面有空缺,空缺区域为填充的背景色值。
  • 3 :按照指定的宽高直接缩放。如果原始画面宽高比与指定的宽高比不同,就会导致画面变形。
默认值为 0
目前 03 均为按照指定的宽高直接缩放,但我们推荐你使用 3 以便与客户端实现相同逻辑。
SourceCrop
Object
-
源流剪切功能,可以在源视频帧渲染之前进行裁剪,即预处理一次再渲染。
LocationX
Float
0
裁剪后得到的视频帧左上角的横坐标相对裁剪前整体画面的比例,取值的范围为 [0.0, 1.0)。默认值为 0.0
LocationY
Float
0
裁剪后得到的视频帧左上角的纵坐标相对裁剪前整体画面的比例,取值的范围为 [0.0, 1.0)。默认值为 0.0
WidthProportion
Float
0.5
裁剪后得到的视频帧宽度相对裁剪前整体画面宽度的比例,取值范围为 (0.0, 1.0]。默认值为 1.0
HeightProportion
Float
0.5
裁剪后得到的视频帧高度相对裁剪前整体画面宽度的比例,取值范围为 (0.0, 1.0]。默认值为 1.0
AlternateImage
String
-

补位图片的 url。长度不超过 1024 个字符串。

  • Region.StreamIndex 对应的视频流没有发布,或被暂停采集时,AlternateImage 对应的图片会填充 Region 对应的画布空间。当视频流被采集并发布时,AlternateImage 不造成任何影响。
  • 可以传入的图片的格式包括:JPG, JPEG, PNG。
  • 当图片和画布尺寸不一致时,图片根据 RenderMode 的设置,在画布中进行渲染。
CornerRadius
Float
0.1
转推直播下边框圆角半径与画布宽度的比例值,取值范围为 [0,1]。默认值为 0,表示没有圆角效果。
圆角半径的像素位不能超过 Region 宽高最小值的一半,否则不会出现圆角效果。
MediaType
Integer
0

该路流参与混流的媒体类型。支持取值及含义如下:

  • 0:音视频
  • 1:纯音频
  • 2:纯视频
默认值为 0
例如该路流为音视频流,MediaType设为1,则只混入音频内容。
AlternateImageFillMode
Integer
0

画面的渲染模式。支持取值及含义如下:

  • 0:按照用户原始视频帧比例进行缩放
  • 1:保持图片原有比例
默认值为 0
Control
Object
-
高级配置选项
MediaType
Integer
0

订阅流类型。支持取值及含义如下:

  • 0:音视频;
  • 1:纯音频。
默认值为0
FrameInterpolationMode
Integer
0

补帧模式。支持取值及含义如下:

  • 0:补最后一帧,
  • 1:补黑帧。

默认值为0。自动布局模式下,该参数不生效。
补帧是指在音视频录制时,视频的帧率通常是固定的。但是,因为网络波动或其他原因,实际帧率可能无法达到预设的帧率。此时,需要补帧以保持视频流畅。补最后一帧意味着补充的视频帧和中断前的最后一帧相同,此时看到的画面可能会有短暂静止;补黑帧意味着补充的视频帧是全黑的。

如果同时配置AlternateimageFrameInterpolationMode ,优先使用 Alternateimage参数。

  • Region.StreamIndex 对应的视频流停止发布时, Region 对应的画布空间会根据设置填充占位图或补帧。但当视频流为屏幕流时,补帧模式不生效。
  • Region.StreamIndex 对应的视频流发布后停止采集或推送时, Region 对应的画布空间会填充上一帧。
  • Region.StreamIndex 对应的视频流发布时,设置的占位图或补顿模式不造成任何影响。
MaxSilenceSeconds
Integer
3600

任务最大中断时间,仅对单流录制生效。取值范围为 [60, 3600],单位为秒,默认值为 3600

  • 若任务中断时间小于该参数值,则根据设置的补帧模式进行补帧。
  • 若任务中断时间大于该参数值但小于空闲超时时间,任务恢复时会生成一个新文件。
    建议该参数取值小于 MaxIdleTime 取值。
MaxIdleTime
Integer
180
任务的空闲超时时间,超过此时间后,任务自动终止。取值范围为 [10, 86400],单位为秒,默认值为 180
MaxRecordTime
Integer
0
最大录制时长,取值为正整数,单位为秒。默认值为 00 表示不限制录制时长。
EnableSyncUpload
Boolean
false

是否开启边录制边上传功能。

  • false:关闭
  • true:开启

默认值为 false

注意

该功能仅对HLS格式存储文件生效,即:FileFormatConfig.FileFormat取值必须包含 HLS
若 HLS 格式文件名中包含Duration填充变量,开通该功能Duration的值始终为 0

FileFormatConfig
Object
-
录制文件的格式设置
FileFormat
String[]
["HLS"]
存储文件格式。支持取值包括:MP4HLSFLVMP3AACM4A。可同时选择多个存储文件格式,最终生成所选存储格式对应的多个文件。

MP3AACM4A仅在编码纯音频时有效。
FileNameConfig
Object
-

录制文件的命名设置。

录制文件的名称由 StorageConfig.TypeFileNameConfig 共同决定。

  • StorageConfig.Type配置为 0 ,即存储在 TOS 平台时,录制文件名称由FilenameConfig.Prefix + FilenameConfig.Pattern +随机数组成
  • StorageConfig.Type配置为 1 ,即存储在 火山引擎视频点播平台 平台时,录制文件名称由FilenameConfig.Pattern + 随机数组成
  • StorageConfig.Type配置为 2 ,即存储在指定第三方S3 对象存储平台时,录制文件名称由FilenameConfig.Prefix + FilenameConfig.Pattern +随机数组成。
    例如:当 StorageConfig.Type 配置为 0FilenameConfig.Prefix配置为directory1/directory2/FilenameConfig.Pattern 配置为 {TaskId}_{RoomId}_{StartTime}_{Duration}
    若此时该文件的 TaskId = mytask123456789, RoomId = myroom99991234StartTime =1645769481126Duration = 30s 且生成的随机八位字符为 c4694fa1,则生成录制文件的文件名为:directory1/directory2/mytask123456789_myroom99991234_1645769481126_000030_c4694fa1.mp4

文件名在 视频点播平台 上可以重复,但在 TOS 或第三方存储平台上默认不可以重复。

Prefix
String[]
["directory1","directory2"]
指定录制文件名的前缀,对TosConfigCustomConfig生效。
在 TOS 以及支持 S3 的第三方存储平台上,可以实现指定文件夹的功能。如:Prefix = ["directory1","directory2"],将在录制文件名前加上前缀 "directory1/directory2/"。
前缀长度最大值为 128 个字符。仅支持大小写字母、数字。
Pattern
String
{TaskId}{RoomId}{UserId}{Type}{StartTime}{Duration}{Random}
自定义录制文件名模式,具体参看自定义录制文件名
如果你设置了 Pattern,需自行保证最终文件名的唯一性,否则在 TOS 或第三方存储平台上同名文件将被覆盖; 你也可以给对应 bucket 开启版本控制,允许文件名重复,防止被覆盖的情况发生。
StorageConfig
Object
-

录制文件的存储平台配置。

支持:

Type
Integer
0

存储平台类型

默认值为 0
TosConfig
Object
-
Tos 平台设置。当 Type = 0 时,需正确设置 TosConfig 的值,否则请求会报错
AccountId
String
210****990

火山引擎平台账号 ID,例如:200000000

  • 火山引擎平台账号 ID 查看路径参看查看和管理账号信息

  • 此账号 ID 为火山引擎主账号 ID。

  • 若你调用 OpenAPI 鉴权过程中使用的 AK、SK 为子用户 AK、SK,账号 ID 也必须为火山引擎主账号 ID,不能使用子用户账号 ID。

Region
Integer
0

不同存储平台支持的 Region 不同,具体参看 Region对照表

默认值为0
Bucket
String
tos-vod-c****16fd9e8343
存储桶的名称。
VodConfig
Object
-
点播平台设置。当 Type = 1 时,需正确设置 VodConfig 的值,否则请求会报错
AccountId
String
210****933

火山引擎平台账号 ID,例如:200000000

  • 火山引擎平台账号 ID 查看路径参看查看和管理账号信息

  • 此账号 ID 为火山引擎主账号 ID。

  • 若你调用 OpenAPI 鉴权过程中使用的 AK、SK 为子用户 AK、SK,账号 ID 也必须为火山引擎主账号 ID,不能使用子用户账号 ID。

Region
Integer
0

不同存储平台支持的 Region 不同,具体参看 Region对照表

默认值为0
Space
String
Storagespace
点播空间名称。
StorageClass
Integer
1

上传到视频点播平台时, 文件的存储类型。支持取值及含义如下::

  • 1:标准存储。
  • 2:归档存储。
  • 3:低频存储。
默认值为 1
关于存储类型的详细说明,参看媒资存储存储类型
AutoSetFileExtension
Boolean
false

上传到视频点播平台时, 是否需要根据文件后缀自动设置 FileExtension。关于 FileExtension 的详细说明,参看 FileExtension

  • true:需要;
  • false:不需要。
默认值为 false
CustomConfig
Object
-
第三方存储平台设置。当 Type = 2时,需正确设置 CustomConfig 的值,否则请求会报错
Vendor
Integer
0

第三方云存储平台。支持取值及含义如下:

  • 0:Amazon S3
  • 1:阿里云 OSS
  • 2:华为云 OBS
  • 3:腾讯云 COS
  • 4:七牛云 Kodo。
默认值为 0
Region
Integer
0

不同存储平台支持的 Region 不同,具体参看 Region对照表

默认值为0
Bucket
String
tos-vod-c****16fd9e8343
存储桶的名称。
AccessKey
String
AKLTMzV****NDcyNjU
第三方存储平台账号的密钥。需确保此账号对存储桶有写权限。不建议开启读权限
SecretKey
String
TVRjMl****aadf==
第三方存储平台账号的密钥

返回参数

本接口无特有的返回参数。公共返回参数请见返回结构
其中返回值 Result 仅在请求成功时返回 ok,失败时为空。

请求示例

POST https://rtc.volcengineapi.com?Action=StartRecord&Version=2023-11-01
{
  "AppId": "661e****543cf",
  "BusinessId": "12312312****2131djad",
  "RoomId": "Room1",
  "TaskId": "Task1",
  "RecordMode": 0,
  "FileFormatConfig": {
    "FileFormat": ["HLS", "FLV"]
  },
  "FileNameConfig": {
    "Prefix": ["directory1", "directory2"],
    "Pattern": ""
  },
  "StorageConfig": {
    "Type": 0,
    "TosConfig": {
      "UserAccountId": "21****89",
      "Region": "0",
      "Bucket": "tos-vod-cn-v****d9e8343******"
    }
  }
}

返回示例

{
  "Result": "ok",
  "ResponseMetadata": {
    "RequestId": "20230****10420",
    "Action": "StartRecord",
    "Version": "2023-11-01",
    "Service": "rtc",
    "Region": "cn-north-1"
  }
}

错误码

您可访问公共错误码,获取更多错误码信息。