实时音视频
实时音视频
文档指南
请输入
- 文档首页
实时音视频实时音视频开发指南录制音视频通话云端录制
复制全文
下载 pdf云端录制
文档反馈
问问助手你可以将音视频通话或直播过程录制为单个或多个文件，并存储至指定的云存储平台，用于后续回放、存档、二次处理或分析。本文主要介绍如何快速使用云端录制及相关配置（如合流录制、单流录制、录制文件格式、录制文件存储等）。
支持以下两种录制模式：
- 合流录制：将多路音视频流混合成一路，生成一个音视频文件。您可以自定义最终合成视频的布局、分辨率、码率等参数。
- 单流录制：将订阅的每一路音视频流都单独录制成一个文件，不进行混合。录制文件的分辨率与原始流保持一致。
适用场景
行业 | 场景 |
在线教育 | 录制在线课程的完整过程，方便学生课后点播回顾。 |
视频会议 | 记录重要会议内容，自动生成会议纪要或作为凭证存档。 |
金融行业 | 办理视频面签、远程见证等业务时，存档备查。 |
计费说明
快速使用
时序图
步骤 1：在控制台开启云端录制
- 前往 RTC 控制台-功能配置。
- 在下拉框中选择目标 RTC 应用，并在云端录制页签，启用录制。
-
步骤 2（建议）：接收录制通知
步骤 3：发起录制任务
核心参数
- RecordMode：保持为默认值 0。
- Layout：配置视频布局（自适应、垂直、并排或自定义）。详见合流布局（CustomLayout）。
- Encode：配置音视频编码参数，如分辨率、帧率和码率。
- StorageConfig：必填。配置录制文件的存储位置，如火山引擎 VOD、TOS 或第三方存储。
请求示例
以将 Room1 房间内的所有流存储至 TOS 为例。
{
"AppId": "Your_AppId",
"RoomId": "Your_RoomId",
"TaskId": "mixed_record_001",
"RecordMode": 0,
"Layout": {}, // 默认自适应布局
"Encode": {
"VideoWidth": 1280,
"VideoHeight": 720,
"VideoFps": 15,
"VideoBitrate": 0 // 0 为自适应码率
},
"FileFormatConfig": { "FileFormat": ["MP4"] },
"StorageConfig": {
"Type": 0, // 0 代表火山引擎 TOS
"TosConfig": {
"AccountId": "Your_AccountId",
"Bucket": "your-tos-bucket-name"
}
}
}
核心参数
- RecordMode：必须设置为 1。
- TargetStreams：可选。不传默认录制房间内所有流。
- StorageConfig：必填项。配置录制文件的存储位置。
请求示例
以录制 Room1 房间内 user_A 和 user_B 两路流，并将录制文件以 MP4 格式存储 VOD 为例。
{
"AppId": "Your_AppId",
"RoomId": "Your_RoomId",
"TaskId": "single_record_002",
"RecordMode": 1, // 表示单流录制
"TargetStreams": {
"StreamList": [
{ "UserId": "user_A", "StreamType": 0 },
{ "UserId": "user_B", "StreamType": 0 }
]
},
"FileFormatConfig": { "FileFormat": ["MP4"] },
"StorageConfig": {
"Type": 1, // 1 代表火山引擎 VOD
"VodConfig": {
"AccountId": "Your_AccountId",
"Space": "your-vod-space-name"
}
}
}
如果您的业务场景只需保存纯音频录音，推荐采用单流录制模式，并将 MediaType 参数固定为 1（仅音频）。
{
"AppId": "Your_AppId",
"RoomId": "Your_RoomId",
"TaskId": "audio_only_task",
"RecordMode": 1,
"FileFormatConfig": {
"FileFormat": ["MP3"] // 设置录制格式为 MP3
},
"Control": {
"MediaType": 1 // 设置为 1 表示仅订阅音频流
}
}
步骤 4：停止录制任务
进阶使用
自动录制
你可以在控制台为指定 RTC 应用开启自动录制功能。开启后，当满足条件的用户进入房间并开始发送音视频流时，系统将自动为该用户启动一个单流录制任务。
自动录制限制
- 自动录制只支持单流录制，不支持将房间内多路流混合的合流录制。
- 自动录制生成的文件名与存储路径只能使用系统默认格式，暂不支持自定义。
- 自动录制目前仅支持对视频流（摄像头）进行录制，不支持屏幕流。如果用户仅发布屏幕流，不会触发自动录制。
- 房间解散或用户停止发送音视频，并超过最大空闲超时时间后，自动录制任务会自动结束。
使用方式
- 前往 RTC 控制台-功能配置。
- 在下拉框中选择目标 RTC 应用，并在云端录制页签，点击添加自动录制。
- 配置录制规则：
- 业务标识：你可以为不同的业务场景设置不同的业务标识（BusinessId）。
- 若设置了业务标识，则只有通过 StartRecord API 传入相同 BusinessId 的用户才会触发自动录制。
- 若不设置业务标识，则默认对房间内所有发送音视频的用户进行单流录制。
-
合流布局（CustomLayout）
合流录制提供三种预设布局模式。若预设布局不满足需求，可通过字段 CustomLayout 设置坐标自定义布局。
注意
当同一个 RTC 房间内同时存在 PC 端与移动端用户推流时，由于推流设备的分辨率差异（如横屏与竖屏），若录制布局强制设定统一宽高的画布，极易导致部分端画面显示不全或被异常拉伸裁剪。建议根据实际推流设备的类型，分别为移动端流与 PC 端流动态配置对应的宽高比例参数。
自适应布局
根据人数自动排布。若人数未满或仅有音频流，相应位置显示背景色。视频会自动裁剪以填满视窗。
- 2人：
-
- 4人：
-
- 5-9人、10-16人：
-
- 17人：
-
自适应布局会遵循以下规则：
- 具体布局会根据人数进行选择，遵循以上示意图。人数未达到布局适用的最多人数时，空缺窗口会显示背景色。
- 只发送音频的用户仍然会在整体布局上占据窗口，窗口会显示背景色。
- 如果实际视频流的宽高比与视窗的宽高比不一致，会自动对视频进行裁剪以适配窗口的大小。
垂直布局
1 个大视窗（可指定用户）+ 侧边小视窗（按加入顺序排列）。大视窗可指定 UserID，否则随机展示。
垂直布局会遵循以下规则：
- 对于大窗口：
- 如果未指定用户，大窗口会随机显示一个用户；如果指定用户未进入房间或进入房间未发布流，大窗口会显示背景色。
- 如果实际视频流的宽高比与窗口的宽高比不一致，窗口会按照显示区域的长宽比裁剪视频，并等比拉伸或缩小视频，以占满显示区域。
- 对于小窗口：
- 小视窗根据加入的顺序进行排列。如果某个用户退出房间，紧跟的后续用户会占据前序用户的窗口，并依次替补。
- 如果实际视频流的宽高比与视窗的宽高比不一致，视频会裁剪以适配视窗的大小。
- 人数未达到布局适用的最多人数时，空缺窗口会显示背景色。
- 只发送音频的用户仍然会在整体布局上占据窗口，窗口会显示背景色。
并排布局
各路画面等分平铺。
设置录制文件格式
通过配置 FileFormatConfig，您可以定义录制文件的存储格式。云端录制支持同时生成多种格式的文件。
- 支持的格式：
- 音视频格式（适用于合流录制或单流录制）：
- MP4（默认格式）：兼容性最好的音视频格式。
- HLS：适用于边录边传、即时回放场景。
- FLV：常用于流媒体存储。
- 纯音频格式：MP3、AAC、M4A。仅在编码纯音频时有效。
- 多格式生成：FileFormat 是一个数组。如果您希望同时生成视频和音频备份，可以配置为 ["MP4", "MP3"]，系统会生成两个独立的录制文件。
- 与文件名的关系：您在 FileNameConfig 中定义的 Pattern（文件名模板）不应包含后缀名。系统会根据您在此处选择的 FileFormat 自动追加正确的后缀（如 .mp3）。
请求示例：仅录制音频（MP3 格式）
{
"AppId": "Your_AppId",
"RoomId": "Your_RoomId",
"TaskId": "audio_only_task",
"FileFormatConfig": {
"FileFormat": ["MP3"] // 设置录制格式为 MP3
},
"Control": {
"MediaType": 1 // 设置为 1 表示仅订阅音频流
}
}
录制文件名称
录制文件名组成
录制文件的名称由 StorageConfig.Type、FileNameConfig 和 FileFormat 共同决定。
存储平台 | 录制文件名组成 |
TOS 平台（StorageConfig.Type = 0） | FilenameConfig.Prefix + FilenameConfig.Pattern + 随机数组成 + FileFormat |
火山点播平台（StorageConfig.Type = 1） | FilenameConfig.Pattern + 随机数组成 + FileFormat |
第三方 S3 对象存储平台（StorageConfig.Type = 2） | FilenameConfig.Prefix + FilenameConfig.Pattern +随机数组成 + FileFormat |
示例：
假设您进行如下配置：
- StorageConfig.Type：0
- FilenameConfig.Prefix：dire1/dire2/
- FilenameConfig.Pattern：{TaskId} {RoomId} _
- FileFormat：MP3
如果一个录制任务的实际变量值为：TaskId=mytask123456789、RoomId= myroom99991234、StartTime= 1645769481126、Duration= 30s、随机字符串是 c4694fa1，则最终生成的文件名称：dire1/dire2/mytask123456789_myroom99991234_1645769481126_000030_c4694fa1.mp3。
文件名前缀和模板
您可以通过 FileNameConfig自定义录制文件的存储路径（前缀 Prefix）和文件名模板（Pattern），以便于归档和检索。
- Prefix: 自定义目录前缀。
- Pattern: 文件名模板。可使用 {} 占位符来插入动态变量，例如 {RoomId}、{UserId} 等。Pattern 总长度不得超过 128 个字符，且格式中不可包含文件扩展名（如 .mp4）。
使用示例：
- 按日期自动建文件夹：您可以在 Pattern 中配置 {StartTime} 变量，例如设置 Pattern 为 {StartTime:%Y-%m-%d}/{RoomId}_{TaskId}。这样录制文件每天会自动保存在对应的日期目录下。
- 前缀检索：为了方便后续按前缀查询文件，可将目标搜索变量（如{StartTime}）放置在 Pattern 的最前端。
单流录制
- Pattern 默认格式：{TaskId}_{RoomId}_{UserId}_{Type}_{StartTime}_{Duration}_{Random}
- 可用变量：
-
- 变量描述TaskId云端录制任务 ID。RoomId房间 ID。UserId用户 ID。Type流类型，C 表示摄像头流，S 表示屏幕流。StartTime文件开始录制的 UTC 时间戳（毫秒）。Duration录制文件时长（秒），固定为 6 位字符，不足则补 0。
合流录制
- Pattern 默认格式：{TaskId}_{RoomId}_{StartTime}_{Duration}_{Random}
- 可用变量：
-
- 变量描述TaskId云端录制任务 ID。RoomId房间 ID。StartTime文件开始录制的 UTC 时间戳（毫秒）。Duration录制文件时长（秒），固定为 6 位字符，不足则补 0。
自动录制
自动录制为单流录制，其文件名格式固定为默认格式：{TaskId}_{RoomId}_{UserId}_{Type}_{StartTime}_{Duration}_{Random}。
注意
在自动录制模式下，TaskId 的值与 UserId 相同。
边录边传（HLS）
若希望在录制进行中就能开始观看回放、降低长视频录制的等待时间。可通过设置 Control.EnableSyncUpload 为 true，开启边录制边上传。
注意
此功能仅对 HLS 格式的录制文件生效。
查找或处理录制文件
若你选择在火山引擎视频点播平台存储文件，你可以查找或处理录制文件：
录制文件切片
- 时长切片：每当录制时长达到约 4 小时，系统会自动创建一个新的录制文件（切片）。多个文件按序号排列。若已配置云端录制回调，所有录制文件的信息可通过 RecordStopped.RecordFileList 回调获取。
- 断流切片（仅单流录制）：当某路流中断时：
- 中断时间小于 MaxSilenceSeconds（默认为 3600 秒），录制服务会补充相应时长的黑帧或最后一帧到当前文件中。
- 中断时间超过 MaxSilenceSeconds，录制服务会先结束当前文件，待视频流恢复后，再创建一个新的录制文件。
在线预览文件（TOS）
默认情况下，通过 URL 访问存储在对象存储（TOS）中的录制文件时，浏览器会将其作为附件直接下载。如需实现直接在线播放或预览，你可以在发起录制任务时通过 ObjectMetadata 设置文件元数据来实现。
核心参数说明：
- ObjectMetadata.AutoSetContentType: 设置为 true，系统会根据录制文件的扩展名（如 .mp4）自动设置正确的 Content-Type（如 video/mp4），这是浏览器能否正确预览的关键。
- ObjectMetadata.ContentDisposition: 设置为 inline，指示浏览器应尝试在窗口内直接展示文件。
请求示例
以下示例演示了如何开启在线预览功能。
{
"AppId": "Your_AppId",
"RoomId": "Your_RoomId",
"TaskId": "record_for_preview",
"StorageConfig": {
"Type": 0,
"TosConfig": {
"AccountId": "Your_AccountId",
"Bucket": "your-tos-bucket-name",
"ObjectMetadata": {
"AutoSetContentType": true,
"ContentDisposition": "inline",
"CacheControl": "public, max-age=3600",
"Metadata": {
"record-id": "rec_xxx_123"
}
}
}
}
}
任务控制参数
在 StartRecord 请求中，你可以通过以下参数对录制任务进行更精细的控制：
- MaxIdleTime：任务空闲超时时间（秒）。若任务启动后，在设定的时间内未订阅到任何目标流，任务将自动结束。默认为 180 秒。
- MaxRecordTime：最大录制时长（秒）。超过该时长任务将自动停止。默认为 0，表示不限制。
- MaxSilenceSeconds：（仅单流生效）任务中断容忍时间（秒）。当流中断时，如果中断时间小于此值，系统会补帧；若大于此值，则可能生成新文件。
- FrameInterpolationMode：补帧模式。当视频流中断时，选择补充最后一帧 (0) 还是黑帧 (1)。
常见问题
- 为什么自适应布局下，屏幕流录制效果不够清晰？
- 自适应布局下，服务端默认不会设置超高码率。如果订阅屏幕流，为保证清晰度，建议自行设置高码率。不同场景下设置码率等视频发布参数，请参考名词解释。
- 单流录制下，用户重新进房后前几秒录制文件为黑帧。
- 单流录制下，用户重进房间后，若前几秒只发送音频流而未发送视频流，服务端会默认补充黑帧。
- 需要技术支持排障， RequestId ** 在哪获取？**
- 当您遇到录制文件异常（如画面黑屏、无声音、录制提前停止等）需要寻求技术支持协助排障时，请务必提供本次调用 StartRecord 接口返回的 RequestId（位于 ResponseMetadata.RequestId 字段中）。该 ID 是定位录制任务推流状态与云端内部日志的唯一凭证。
最近更新时间：2026.09.28 10:08:29
这个页面对您有帮助吗？
有用
有用
无用
无用