对于一个音视频通话,你可以使用云端录制功能,录制音视频文件。
你可以使用 StartRecord
这个 OpenAPI 实现这一功能。
你可以调用 StartRecord
接口,指示 RTC 按照你设定的配置进行录制。设置包括:单流/合流,布局模板,音视频文件参数等。
录制分为单流录制和合流录制:
GetRecordTask
接口获取录制生成的文件,强烈建议接入录制结束回调事件。关于调用接口的请求结构、公共参数、签名算法和返回结构,参看调用方法。
请求频率:QPS 不得超过 60。
下表仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共参数。
参数 | 类型 | 是否必选 | 示例值 | 描述 |
---|---|---|---|---|
Action | String | 是 | StartRecord | 接口名称。当前 API 的名称为 StartRecord 。 |
Version | String | 是 | 2022-06-01 | 接口版本。当前 API 的版本为 2022-06-01 。 |
参数 | 类型 | 是否必选 | 示例值 | 描述 |
---|---|---|---|---|
AppId | String | 是 | Your_AppId | 你的音视频应用的唯一标志 |
BusinessId | String | 否 | Your_BusinessId | 业务标识 |
RoomId | String | 是 | Your_RoomId | 房间的 ID,是房间的唯一标志 |
TaskId | String | 是 | Your_TaskId | 云端录制任务 ID。你必须对每个云端录制任务设定 TaskId,且在后续进行任务更新和结束时也须使用该 TaskId。
[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 | 流的类型,值可以取 0 或1 ,默认值为0 。0 表示普通音视频流,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 | 流的类型,值可以取 0 或1 ,默认值为0 。0 表示普通音视频流,1 表示屏幕流。 |
Encode | Object | 否 | - | 音视频编码参数。
|
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 ,可以取 0 或 1 。取 0 时使用 H.264 ,取 1 时使用 ByteVC1 编码器。 |
VideoGop | Integer | 否 | 4 | 输出视频 GOP。默认为 4 ,取值范围为 [1,5] ,单位为秒。值不合法时,自动调整为默认值。 |
AudioCodec | Integer | 否 | 0 | 音频编码协议。默认值为 0 ,此时使用 aac 编码协议。目前只支持 aac。值不合法时,自动调整为默认值。 |
AudioProfile | Integer | 否 | 0 | 音频配置文件类型,在使用 aac 编码时生效。取值范围为
|
AudioBitrate | Integer | 否 | - | 音频码率。取值范围为 当
当
|
AudioSampleRate | Integer | 否 | 48000 | 音频采样率。默认值 48000 ,取值为 [32000,44100,48000] ,单位是 Hz。值不合法时,自动调整为默认值。 |
AudioChannels | Integer | 否 | 2 | 音频声道数。
|
Layout | Object | 否 | - | 布局参数。仅在合流模式下支持设置布局参数。 |
LayoutMode | Integer | 否 | 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[] | 否 | - | 在自定义布局模式下,你可以使用
|
Alpha | Float | 否 | 1 | 画面的透明度,取值范围为 (0.0, 1.0] 。0.0 表示完全透明,1.0 表示完全不透明,默认值为 1.0 。值不合法时,自动调整为默认值。 |
ZOrder | Integer | 否 | 0 | 当多个流的画面有重叠时,使用此参数设置指定画面的图层顺序。取值范围为 [0, 100] :0 表示该区域图像位于最下层,100 表示该区域图像位于最上层, 默认值为 0 。值不合法时,自动调整为默认值。 |
LocationX | Float | 否 | 0 | 视频流对应区域左上角的横坐标相对整体画面的比例,取值的范围为 1920 , 视频流对应区域左上角的横坐标相对整体画面的比例为 0.33 ,那么该画布左上角的横坐标为 634 (1920*0.33=633.6,四舍五入取整)。 |
LocationY | Float | 否 | 0 | 视频流对应区域左上角的横坐标相对整体画面的比例,取值的范围为 [0.0, Canvas.Height) 。默认值为 0 。若传入该参数,服务端会对该参数进行校验,若不合法会返回错误码 InvalidParameter 。 |
MediaType | Integer | 否 | 0 | 该路流参与混流的媒体类型。
0 。值不合法时,自动调整为默认值。假如该路流为音视频流, MediaType 设为1 ,则只混入音频内容。 |
RenderMode | Integer | 否 | 0 | 画面的渲染模式,值的范围为
|
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 个字符串。
|
WidthProportion | Float | 是 | 0.5 | 视频流对应区域宽度相对整体画面的比例,取值的范围为 (0.0, 1.0] 。 |
HeightProportion | Float | 是 | 0.5 | 视频流对应区域高度相对整体画面的比例,取值的范围为 (0.0, 1.0] 。 |
AlternateImageFillMode | Integer | 否 | 0 | 画面的渲染模式。
0 。值不合法时,自动调整为默认值。 |
MainVideoStream | Object | 否 | - | 在垂直布局模式下生效,指定主画面流的属性。垂直布局时,此参数必填。 |
Index | Integer | 否 | 0 | 在自定义布局中,使用 Index 对流进行标志。后续在 Layout.regions.StreamIndex 中,你需要使用 Index 指定对应流的布局设置。 |
UserId | String | 是 | Your_UserId | 用户Id,表示这个流所属的用户。 |
StreamType | Integer | 否 | 0 | 流的类型,值可以取 0 或1 ,默认值为0 。0 表示普通音视频流,1 表示屏幕流。 |
Control | Object | 否 | - | 配置选项 |
MediaType | Integer | 否 | 0 | 流的类型,用于全局控制订阅的流的类型。默认值为 0 ,可以取0 和1 。0 表示音视频,1 表示纯音频,暂不支持纯视频。值不合法时,自动调整为默认值。 |
FrameInterpolationMode | Integer | 否 | 0 | 选择补帧模式。默认值为 自动布局模式下,没有补帧的逻辑。 补帧是指在音视频录制或合流转推时,视频的帧率通常是固定的。但是,因为网络波动或其他原因,实际帧率可能无法达到预设的帧率。此时,需要补帧以保持视频流畅。补最后一帧意味着补充的视频帧和中断前的最后一帧相同,此时看到的画面可能会有短暂静止;补黑帧意味着补充的视频帧是全黑的。 使用占位图、补帧和上一帧的关系: 你可以在
|
MaxIdleTime | Integer | 否 | 180 | 任务的空闲超时时间,超过此时间后,任务自动终止。单位为秒。取值范围为 [10, 86400] , 默认值为 180 。 |
MaxRecordTime | Integer | 否 | 0 | (仅对录制有效)最大录制时长,单位为秒。默认值为 0 。0 表示不限制录制时长。 |
FileFormatConfig | Object | 否 | - | 录制文件的格式设置 |
FileFormat | String[] | 否 | ["HLS"] | 存储文件格式。可取值为: MP4 、HLS 、FLV 、MP3 、 AAC 、M4A 。可同时选择多个存储文件格式,最终生成所选存储格式对应的多个文件。MP3 、AAC 和M4A 仅在编码纯音频时有效。 |
FileNameConfig | Object | 否 | - | 录制文件的命名设置。 录制文件的名称由
|
Prefix | String[] | 否 | ["directory1","directory2"] | 制定录制文件名的前缀,对
|
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,例如:
|
Region | Integer | 否 | 0 | 不同存储平台支持的 Region 不同,具体参看 Region对照表 默认值为0 。 |
Bucket | String | 是 | Your_Bucket | 存储桶的名称。 |
VodConfig | Object | 否 | - | 当 Type = 1 时,需正确设置 VodConfig 的值,否则请求会报错 |
AccountId | String | 是 | Your_AccountId | 火山引擎平台账号 ID,例如:
|
Region | Integer | 否 | 0 | 不同存储平台支持的 Region 不同,具体参看 Region对照表 默认值为 0 。 |
Space | String | 是 | Your_Space | 点播空间名称。 |
CustomConfig | Object | 否 | - | 当 Type = 2 时,需正确设置 CustomConfig 的值,否则请求会报错 |
Vendor | Integer | 否 | 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,例如:
|
Region | Integer | 否 | 0 | 不同存储平台支持的 Region 不同,具体参看 Region对照表 默认值为 0 。 |
ServiceId | String | 是 | Your_ServiceId |
本接口无特有的返回参数。公共返回参数请见返回结构。
其中返回值 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": { "AccountId": "Your_AccountId", "Region": "Your_Region", "Bucket": "Your_Bucket" } } }
{ "Result": "ok", "ResponseMetadata": { "RequestId": "Your_RequestId", "Action": "StartRecord", "Version": "2022-06-01", "Service": "rtc", "Region": "cn-north-1" } }
您可访问公共错误码,获取更多错误码信息。