You need to enable JavaScript to run this app.
导航
实时音视频
  • 文档首页
    • /实时音视频/服务端 OpenAPI 参考/云端录制/更新云端录制 UpdateRecord
更新云端录制 UpdateRecord
最近更新时间：2024.12.18 16:27:01首次发布时间：2024.01.03 20:25:17
我的收藏

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

在实时音视频通话场景中，若需对已设定的云端录制任务进行调整，你可以通过调用此接口实现。

通过此接口，你可以灵活调整录制内容的布局和视觉效果，以满足不同场景下的录制需求。调用后，接口返回操作结果，确认任务参数的更新是否成功。

调用此接口时，需确保云端录制功能已启用且当前处于合流录制的自定义布局模式，即 RecordMode=0 且 Layout.LayoutMode=2。

使用说明

接口行为

你可以调用 UpdateRecord 接口，覆盖此前在 StartRecord 或 UpdateRecord 中设定的以下参数：

  • TargetStreams
  • Layout.CustomLayout.Canvas.Background 和 Layout.CustomLayout.Canvas.BackgroundImage
  • Layout.CustomLayout.Regions

注意事项

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

请求说明

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

调试

API Explorer
您可以通过 API Explorer 在线发起调用，无需关注签名生成过程，快速获取调用结果。
去调试

请求参数

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

Query

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

Body

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

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

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

关于 TaskId 及以上 Id 字段的命名规则符合正则表达式：[a-zA-Z0-9_@\-\.]{1,128}
TargetStreams
Object
否
-
你可以通过本参数设定需要录制的音视频流。单流录制模式下，如果参数为空，默认录制对房间内所有人进行单流录制。最多17人。
StreamList
Object[]
否
-
音视频流列表，由Stream组成，可以为空。为空时，表示订阅房间内所有流。在一个 StreamList 中，Stream.Index 不能重复。
Index
Integer
否
0
在自定义布局中，使用 Index 对流进行标志。后续在 Layout.regions.StreamIndex 中，你需要使用 Index 指定对应流的布局设置。
UserId
String
是
user1
用户 ID，表示这个流所属的用户。
StreamType
Integer
否
0

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

  • 0：普通音视频流，
  • 1：屏幕流。
默认值为0。
Layout
Object
否
-
布局参数。
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, 4096]，必须是偶数，单位为像素，默认值为 640。
Height
Integer
否
480
整体屏幕（画布）的高度，取值范围为 [2, 2160]，必须是偶数，单位为像素，默认值为 480。
Background
String
否
#000000
整体屏幕（画布）的背景色, 范围为 #000000 ~ #ffffff (大小写均可)，格式为 #RGB(16进制)，默认值为 #000000（黑色）。
BackgroundImage
String
否
-
背景图片的 URL。长度最大为 1024 byte。可以传入的图片的格式包括：JPG, JPEG, PNG。
如果背景图片的宽高和整体屏幕的宽高不一致，背景图片会缩放到铺满屏幕。
如果你设置了背景图片，背景图片会覆盖背景色。
Regions
Object[]
否
-

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

自定义布局模式下，对于 StreamList 中的每个 Stream，Regions 中都需要给出对应的布局信息，否则会返回请求不合法的错误。即 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。0 表示该区域图像位于最下层，100 表示该区域图像位于最上层。
Alpha
Float
否
1
画面的透明度，取值范围为 (0.0, 1.0]，默认值为 1.0。0.0 表示完全透明，1.0 表示完全不透明。
RenderMode
Integer
否
0

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

  • 0 ：按照指定的宽高直接缩放。如果原始画面宽高比与指定的宽高比不同，就会导致画面变形
  • 1 ：按照显示区域的长宽比裁减视频，然后等比拉伸或缩小视频，占满显示区域。
  • 2 ：按照原始画面的宽高比缩放视频，在显示区域居中显示。如果原始画面宽高比与指定的宽高比不同，就会导致画面有空缺，空缺区域为填充的背景色值。
  • 3 ：按照指定的宽高直接缩放。如果原始画面宽高比与指定的宽高比不同，就会导致画面变形。
默认值为 0。
目前 0 和 3 均为按照指定的宽高直接缩放，但我们推荐你使用 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 的设置，在画布中进行渲染。
ApplySpatialAudio
Boolean
否
-

该路流对应的用户是否开启空间音频效果。

  • true：开启空间音频效果。
  • false：关闭空间音频效果。
默认值为 true
SpatialPosition
Integer[]
否
[0,0,0]
空间音频下，房间内指定用户所在位置的三维坐标，默认值为[0,0,0]。数组长度为3，三个值依次对应X,Y,Z，每个值的取值范围为 [-100,100]。
CornerRadius
Float
否
0.1
转推直播下边框圆角半径与画布宽度的比例值，取值范围为 [0,1]。默认值为 0，表示没有圆角效果。
圆角半径的像素位不能超过 Region 宽高最小值的一半，否则不会出现圆角效果。
MediaType
Integer
否
0

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

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

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

  • 0：按照用户原始视频帧比例进行缩放
  • 1：保持图片原有比例
默认值为 0。

返回参数

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

请求示例

POST https://rtc.volcengineapi.com?Action=UpdateRecord&Version=2023-11-01
{
    "AppId": "661e****543cf",
    "BusinessId": "B****23",
    "RoomId": "Room1",
    "TaskId": "Task1",
    "TargetStreams": {
        "StreamList": [
            {
                "Index": 0,
                "UserId": "user1_1",
                "StreamType": 1
            },
            {
                "Index": 1,
                "UserId": "user1_2"
            }
        ]
    },
    "Layout": {
        "LayoutMode": 2,
        "CustomLayout": {
            "Canvas": {
                "Width": 860,
                "Height": 340,
                "Background": "#303342"
            },
            "Regions": [
                {
                    "StreamIndex": 0,
                    "LocationX": 0,
                    "LocationY": 0,
                    "Width": 430,
                    "Height": 340,
                    "ZOrder": 0,
                    "Alpha": 1,
                    "RenderMode": 0
                },
                {
                    "StreamIndex": 1,
                    "LocationX": 430,
                    "LocationY": 0,
                    "Width": 430,
                    "Height": 340,
                    "ZOrder": 1,
                    "Alpha": 1,
                    "RenderMode": 1
                }
            ]
        }
    }
}

返回示例

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

错误码

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