You need to enable JavaScript to run this app.
导航

开始云端录制 StartRecord

最近更新时间2024.03.20 14:50:10

首次发布时间2022.06.09 14:21:49

对于一个音视频通话,你可以使用云端录制功能,录制音视频文件。
你可以使用 StartRecord 这个 OpenAPI 实现这一功能。

使用说明

接口行为

你可以调用 StartRecord 接口,指示 RTC 按照你设定的配置进行录制。设置包括:单流/合流,布局模板,音视频文件参数等。

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

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

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

    你也可以在控制台配置存储空间和文件格式,效果与调用 OpenAPI 一致。
    如果你已开通录制开始的消息通知功能,在开始云端录制时,你能够收到相关回调通知。关于消息通知服务,参看开通消息通知服务
    录制文件生成后,不推荐调用 GetRecordTask接口获取录制生成的文件,强烈建议接入录制结束回调事件。
    在开始录制前,你必须已经在控制台上开启录制功能,参看在控制台开启/关闭云端录制功能

调用接口

关于调用接口的请求结构、公共参数、签名算法和返回结构,参看调用方法

注意事项

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

请求说明

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

请求参数

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

Query

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

Body

参数
类型
是否必选
示例值
描述
AppId
String
Your_AppId
你的音视频应用的唯一标志
BusinessId
String
Your_BusinessId
业务标识
RoomId
String
Your_RoomId
房间的 ID,是房间的唯一标志
TaskId
String
Your_TaskId

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

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

关于 TaskId 及以上 Id 字段的命名规则符合正则表达式:[a-zA-Z0-9_@\-\.]{1,128}
RecordMode
Integer
使用此参数设定录制模式:单流/合流录制。0 表示合流录制,1 表示单流录制。默认值为 0
TargetStreams
Object
-
你可以通过本参数设定需要录制的音视频流。如果参数为空,默认录制对房间内所有发布的音视频流进行录制。无论合流还是单流录制,最多 17 路流。此参数中的 stream 不得和 ExcludeStreams 中重复。
StreamList
Object[]
Stream组成的列表,可以为空。为空时,表示订阅房间内所有流。在一个 StreamList 中,Stream.Index 不能重复。
Index
Integer
0
在自定义布局中,使用 Index 对流进行标志。后续在 Layout.regions.StreamIndex 中,你需要使用 Index 指定对应流的布局设置。
UserId
String
Your_UserId
用户Id,表示这个流所属的用户。
StreamType
Integer
0
流的类型,值可以取01,默认值为00表示普通音视频流,1表示屏幕流。
ExcludeStreams
Object
-
你可以通过本参数设定 需要录制的音视频流,即录制流的黑名单。参数默认为空。黑名单中的流不得超过 17 路。不支持将屏幕流添加到黑名单中。此参数中的 stream 不得和 TargetStreams 中重复。
StreamList
Object[]
Stream组成的列表,可以为空。为空时,表示订阅房间内所有流。在一个 StreamList 中,Stream.Index 不能重复。
Index
Integer
0
在自定义布局中,使用 Index 对流进行标志。后续在 Layout.regions.StreamIndex 中,你需要使用 Index 指定对应流的布局设置。
UserId
String
Your_UserId
用户Id,表示这个流所属的用户。
StreamType
Integer
0
流的类型,值可以取01,默认值为00表示普通音视频流,1表示屏幕流。
Encode
Object
-

音视频编码参数。

  • 单流录制时,你仅可以设置 VideoFpsVideoBitrate
  • 合流录制时,你仅可以设置 VideoWidthVideoHeightVideoFps,和 VideoBitrate
VideoWidth
Integer
640
输出画面的宽度。默认值为640,范围为 [2, 1920],必须是偶数。值不合法时,自动调整为默认值。自定义布局下此参数不生效,整体画面宽度以 canvas 中的 Width 为主。
VideoHeight
Integer
480
输出画面的高度,范围为[2, 1920],必须是偶数,默认值为480。值不合法时,自动调整为默认值。自定义布局下此参数不生效,整体画面高度以 canvas 中的 Height 为主。
VideoFps
Integer
15
输出视频帧率。默认为 15,取值范围为 [1,60]。值不合法时,自动调整为默认值。
VideoBitrate
Integer
-
输出视频码率。取值范围 [1,10000],单位为 Kbps,默认值为自适应。值不合法时,自动调整为默认值。
自适应码率模式下,RTC 默认不会设置超高码率。如果订阅屏幕流,建议自行设置高码率。不同场景下设置码率等视频发布参数,请参考设置视频发布参数
VideoCodec
Integer
0
视频编码协议。默认值为 0,可以取 01。取 0 时使用 H.264,取 1 时使用 ByteVC1 编码器。
VideoGop
Integer
4
输出视频 GOP。默认为 4,取值范围为 [1,5],单位为秒。值不合法时,自动调整为默认值。
AudioCodec
Integer
0
音频编码协议。默认值为 0,此时使用 aac 编码协议。目前只支持 aac。值不合法时,自动调整为默认值。
AudioProfile
Integer
0

音频配置文件类型,在使用 aac 编码时生效。取值范围为 {0, 1, 2}

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

音频码率。取值范围为 [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
音频采样率。默认值 48000,取值为 [32000,44100,48000],单位是 Hz。值不合法时,自动调整为默认值。
AudioChannels
Integer
2

音频声道数。

  • 1:单声道
  • 2:双声道。
    默认值为 2。值不合法时,自动调整为默认值。
Layout
Object
-
布局参数。仅在合流模式下支持设置布局参数。
LayoutMode
Integer
0

布局模式。默认值为 0,值的范围为 {0, 1, 2, 3}

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

在自定义布局模式下,你可以使用 Regions 对每一路视频流进行画面布局设置。其中,每个 Region 对一路视频流进行画面布局设置。
自定义布局模式下,对于 StreamList 中的每个 StreamRegions 中都需要给出对应的布局信息,否则会返回请求不合法的错误。即 Regions.Region.StreamIndex 要与 TargetStreams.StreamList.Stream.Index 的值一一对应,否则自定义布局设置失败,返回 InvalidParameter 错误码。

当传入的必填参数值不合法时,返回错误码 InvalidParameter 。
当传入的选填参数值不合法时,自动调整为默认值。

Alpha
Float
1
画面的透明度,取值范围为 (0.0, 1.0]0.0 表示完全透明,1.0 表示完全不透明,默认值为 1.0。值不合法时,自动调整为默认值。
ZOrder
Integer
0
当多个流的画面有重叠时,使用此参数设置指定画面的图层顺序。取值范围为 [0, 100]0 表示该区域图像位于最下层,100 表示该区域图像位于最上层, 默认值为 0。值不合法时,自动调整为默认值。
LocationX
Float
0

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

视频流对应区域左上角的实际坐标是通过画面尺寸和相对位置比例相乘,并四舍五入取整得到的。假如,画布尺寸为1920, 视频流对应区域左上角的横坐标相对整体画面的比例为 0.33,那么该画布左上角的横坐标为 634(1920*0.33=633.6,四舍五入取整)。
LocationY
Float
0
视频流对应区域左上角的横坐标相对整体画面的比例,取值的范围为 [0.0, Canvas.Height)。默认值为 0。若传入该参数,服务端会对该参数进行校验,若不合法会返回错误码 InvalidParameter
MediaType
Integer
0

该路流参与混流的媒体类型。

  • 0:音视频
  • 1:纯音频
  • 2:纯视频
默认值为 0。值不合法时,自动调整为默认值。

假如该路流为音视频流,MediaType设为1,则只混入音频内容。
RenderMode
Integer
0

画面的渲染模式,值的范围为 {0, 1, 2,3}, 默认值为 0:- 0 表示按照指定的宽高直接缩放。如果原始画面宽高比与指定的宽高比不同,就会导致画面变形

  • 1 表示按照显示区域的长宽比裁减视频,然后等比拉伸或缩小视频,占满显示区域。
  • 2 表示按照原始画面的宽高比缩放视频,在显示区域居中显示。如果原始画面宽高比与指定的宽高比不同,就会导致画面有空缺,空缺区域为填充的背景色值。
  • 3 表示按照指定的宽高直接缩放。如果原始画面宽高比与指定的宽高比不同,就会导致画面变形

    值不合法时,自动调整为默认值。

    目前 03 均为按照指定的宽高直接缩放,但我们推荐你使用 3 以便与客户端实现相同逻辑。

    不同渲染模式下,效果如下:alt
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。值不合法时,自动调整为默认值。
StreamIndex
Integer
0
流的标识。这个标志应和 TargetStreams.StreamList.Stream.Index 对应。
AlternateImage
String
-

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

  • Region.StreamIndex 对应的视频流没有发布,或被暂停采集时,AlternateImage 对应的图片会填充 Region 对应的画布空间。当视频流被采集并发布时,AlternateImage 不造成任何影响。
  • 可以传入的图片的格式包括:JPG, JPEG, PNG。
  • 当图片和画布尺寸不一致时,图片根据 RenderMode 的设置,在画布中进行渲染。
WidthProportion
Float
0.5
视频流对应区域宽度相对整体画面的比例,取值的范围为 (0.0, 1.0]
HeightProportion
Float
0.5
视频流对应区域高度相对整体画面的比例,取值的范围为 (0.0, 1.0]
AlternateImageFillMode
Integer
0

画面的渲染模式。

  • 0:按照用户原始视频帧比例进行缩放
  • 1:保持图片原有比例
默认值为 0。值不合法时,自动调整为默认值。
MainVideoStream
Object
-
在垂直布局模式下生效,指定主画面流的属性。垂直布局时,此参数必填。
Index
Integer
0
在自定义布局中,使用 Index 对流进行标志。后续在 Layout.regions.StreamIndex 中,你需要使用 Index 指定对应流的布局设置。
UserId
String
Your_UserId
用户Id,表示这个流所属的用户。
StreamType
Integer
0
流的类型,值可以取01,默认值为00表示普通音视频流,1表示屏幕流。
Control
Object
-
配置选项
MediaType
Integer
0
流的类型,用于全局控制订阅的流的类型。默认值为0,可以取010表示音视频,1表示纯音频,暂不支持纯视频。值不合法时,自动调整为默认值。
FrameInterpolationMode
Integer
0

选择补帧模式。默认值为0,可以取010为补最后一帧,1为补黑帧。值不合法时会自动调整为默认值。

自动布局模式下,没有补帧的逻辑。

补帧是指在音视频录制或合流转推时,视频的帧率通常是固定的。但是,因为网络波动或其他原因,实际帧率可能无法达到预设的帧率。此时,需要补帧以保持视频流畅。补最后一帧意味着补充的视频帧和中断前的最后一帧相同,此时看到的画面可能会有短暂静止;补黑帧意味着补充的视频帧是全黑的。

使用占位图、补帧和上一帧的关系:

你可以在 Region 中传入 Alternateimage 字段设置占位图,在 Control 中传入FrameInterpolationMode 字段设置补帧模式,但占位图优先级高于补帧模式。

  • Region.StreamIndex 对应的视频流停止发布时, Region 对应的画布空间会根据设置填充占位图或补帧。但当视频流为屏幕流时,补帧模式不生效。
  • Region.StreamIndex 对应的视频流发布后停止采集或推送时, Region 对应的画布空间会填充上一帧。
  • Region.StreamIndex 对应的视频流发布时,设置的占位图或补顿模式不造成任何影响。
MaxIdleTime
Integer
180
任务的空闲超时时间,超过此时间后,任务自动终止。单位为秒。取值范围为 [10, 86400], 默认值为 180
MaxRecordTime
Integer
0
(仅对录制有效)最大录制时长,单位为秒。默认值为 00 表示不限制录制时长。
FileFormatConfig
Object
-
录制文件的格式设置
FileFormat
String[]
["HLS"]
存储文件格式。可取值为:MP4HLSFLVMP3AACM4A。可同时选择多个存储文件格式,最终生成所选存储格式对应的多个文件。

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

录制文件的命名设置。

录制文件的名称由 [StorageConfig.Type][FileNameConfig] 共同决定。

  • StorageConfig.Type配置为 0 ,即存储在 TOS 平台时,录制文件名称由FilenameConfig.Prefix + FilenameConfig.Pattern +随机数组成
  • StorageConfig.Type配置为 1 ,即存储在 火山引擎视频点播平台 平台时,录制文件名称由FilenameConfig.Pattern + 随机数组成
  • StorageConfig.Type配置为 2 ,即存储在 Amazon S3、 阿里云 OSS、华为云 OBS、腾讯云 COS 或七牛云 Kodo 第三方 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
Prefix
String[]
["directory1","directory2"]

制定录制文件名的前缀,对TosConfigCustomConfig生效。

Prefix 为指定录制文件名的前缀,是一个由多个字符串组成的数组,在 TOS 以及支持 S3 的第三方存储平台上,可以实现指定文件夹的功能。如:Prefix = ["directory1","directory2"],将在录制文件名前加上前缀 "directory1/directory2/"。
前缀长度(包括斜杠)不得超过 128 个字符。Prefix中不得出现斜杠、下划线、括号等符号字符。
仅支持以下字符:

  • 26 个小写英文字母 a-z
  • 26 个大写英文字母 A-Z
  • 10 个数字 0-9
Pattern
String
-
自定义录制文件名模式,具体参看自定义录制文件名
StorageConfig
Object
-
录制文件的存储平台。

目前支持:火山引擎视频点播 VOD 、火山引擎对象存储 TOS、Amazon S3、阿里云对象存储 OSS、华为云 OBS、腾讯云 COS 和七牛云 Kodo。
Type
Integer
0

存储平台类型

TosConfig
Object
-
当 Type = 0 时,需正确设置 TosConfig 的值,否则请求会报错
AccountId
String
Your_AccountId

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

  • 火山引擎平台账号 ID 查看路径:控制台->账号管理->账号信息
    alt

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

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

Region
Integer
0

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

默认值为0
Bucket
String
Your_Bucket
存储桶的名称。
VodConfig
Object
-
当 Type = 1 时,需正确设置 VodConfig 的值,否则请求会报错
AccountId
String
Your_AccountId

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

  • 火山引擎平台账号 ID 查看路径:控制台->账号管理->账号信息
    alt

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

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

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

默认值为0
Space
String
Your_Space
点播空间名称。
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
Your_Bucket
存储桶的名称。
AccessKey
String
Your_AccessKey
第三方存储平台账号的密钥。需确保此账号对存储桶有写权限。不建议开启读权限
SecretKey
String
Your_SecretKey
第三方存储平台账号的密钥
VeImageXConfig
Object
-
当 Type = 3时,需正确设置 VeImageXConfig 的值,否则请求会报错
AccountId
String
Your_AccountId

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

  • 火山引擎平台账号 ID 查看路径:控制台->账号管理->账号信息
    alt

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

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

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

默认值为0
ServiceId
String
Your_ServiceId
服务 ID。- 你可以在 veImageX 控制台 服务管理页面,通过创建好的图片服务中获取服务 ID。

你也可以通过 OpenAPI 的方式获取服务 ID,具体请参考获取所有服务信息

返回参数

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

请求示例

POST https://rtc.volcengineapi.com?Action=StartRecord&Version=2022-06-01
{
    "AppId" : "Your_AppId",
    "BusinessId" : "Your_BusinessId",
    "RoomId" : "Your_RoomId",   
    "TaskId": "Your_TaskId",
    "RecordMode": 0,
    "FileFormatConfig": {
        "FileFormat": ["HLS", "FLV"]
    },
    "FileNameConfig": {
        "Prefix": ["directory1", "directory2"],
        "Pattern": ""
    },
    "StorageConfig": {
        "Type": 0,
        "TosConfig": {
            "UserAccountId": "Your_UserAccountId",
            "Region": "Your_Region",
            "Bucket": "Your_Bucket"
        }
    }
}

返回示例

{
    "Result": "ok",
    "ResponseMetadata": {
        "RequestId": "Your_RequestId",
        "Action": "StartRecord",
        "Version": "2022-06-01",
        "Service": "rtc",
        "Region": "cn-north-1"
        }
}

错误码

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