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

开始云端录制 StartRecord

最近更新时间2024.04.15 17:35:12

首次发布时间2024.01.03 20:25:17

本文档 API 接口为最新版本接口,后续相关功能的新增都会在此更新,推荐使用最新版本接口。旧版接口文档请参考历史版本
对于一个音视频通话,你可以使用 StartRecord 这个 OpenAPI 录制音视频文件。录制生成的内容会存储在指定的存储平台,用于视频回放、内容审核等。

使用说明

接口行为

调用 StartRecord 指定 RTC 根据您的参数配置进行云端录制。在接口调用时,您可以根据业务需求配置录制模式、布局模式、音视频文件参数以及存储平台等信息。

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

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

若任务运行中,使用相同的 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 中重复。
StreamList
Object[]
-
音视频流列表,由Stream组成,可以为空。为空时,表示订阅房间内所有流。在一个 StreamList 中,Stream.Index 不能重复。
Index
Integer
0
在自定义布局中,使用 Index 对流进行标志。后续在 Layout.regions.StreamIndex 中,你需要使用 Index 指定对应流的布局设置。
UserId
String
Your_UserId
用户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
Your_UserId
用户Id,表示这个流所属的用户。
StreamType
Integer
0

流的类型,取值:

  • 0:普通音视频流,
  • 1:屏幕流。
    默认值为0
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,单位为 FPS,取值范围为 [1,60]
VideoBitrate
Integer
-
输出视频码率。取值范围 [0,10000],单位为 Kbps,默认值为 0
0 表示自适应码率,会自动根据 VideoFps , VideoWidth 以及VideoHeight 计算出合理的码率。
自适应码率模式下,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 :采用 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,值的范围为:

MainVideoStream
Object
在垂直布局模式下生效,指定主画面流的属性。垂直布局时,此参数必填。
Index
Integer
0
在自定义布局中,使用 Index 对流进行标志。后续在 Layout.regions.StreamIndex 中,你需要使用 Index 指定对应流的布局设置。
UserId
String
Your_UserId
用户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
整体屏幕(画布)的背景色,格式为 #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

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]0 表示该区域图像位于最下层,100 表示该区域图像位于最上层, 默认值为 0
Alpha
Float
1
画面的透明度,取值范围为 (0.0, 1.0]0.0 表示完全透明,1.0 表示完全不透明,默认值为 1.0
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
AlternateImage
String
-

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

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

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

  • 0:音视频
  • 1:纯音频
  • 2:纯视频
默认值为 0

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

画面的渲染模式。

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

流的类型,用于全局控制订阅的流的类型。默认值为0

  • 0:音视频,
  • 1:纯音频,
    暂不支持纯视频。
FrameInterpolationMode
Integer
0

补帧模式。默认值为0

  • 0:补最后一帧,
  • 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.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 或第三方存储平台上默认不可以重复。
如果你设置了 Pattern,需自行保证最终文件名的唯一性,否则在 TOS 或第三方存储平台上同名文件将被覆盖; 你也可以给对应 bucket 开启版本控制,允许文件名重复,防止被覆盖的情况发生。

Prefix
String[]

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

Prefix 为指定录制文件名的前缀,在 TOS 以及支持 S3 的第三方存储平台上,可以实现指定文件夹的功能。如:Prefix = ["directory1","directory2"],将在录制文件名前加上前缀 "directory1/directory2/"。
前缀长度最大值为 128 个字符。Prefix中不得出现斜杠、下划线、括号等符号字符。
仅支持大小写字母、数字。
Pattern
String
{TaskId}{RoomId}{UserId}{Type}{StartTime}{Duration}{Random}
自定义录制文件名模式,具体参看自定义录制文件名
StorageConfig
Object
-

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

支持:

Type
Integer
0

存储平台类型

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

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

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

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

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

Region
Integer
/

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

默认值为0
ServiceId
String
Your_ServiceId

服务 ID。

  • 你可以在 veImageX 控制台 服务管理页面,通过创建好的图片服务中获取服务 ID。
    你也可以通过 OpenAPI 的方式获取服务 ID,具体请参考获取所有服务信息

返回参数

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

请求示例

POST https://rtc.volcengineapi.com?Action=StartRecord&Version=2023-11-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": "2023-11-01",
    "Service": "rtc",
    "Region": "cn-north-1"
  }
}

错误码

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