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

更新云端录制 UpdateRecord

最近更新时间2024.01.12 16:39:43

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

如果你已启用云端录制,并进行了自定义布局的合流录制,你可以更新录制的配置参数。你可以使用 UpdateRecord 这个 OpenAPI 实现这一功能。
关于如何启用云端录制,参看开始云端录制 StartRecord

使用说明

接口行为

你可以调用 UpdateRecord 接口,覆盖此前在 StartRecordUpdateRecord 中设定的以下参数:

  • TargetStreams
  • Layout.CustomLayout.Canvas.BackgroundLayout.CustomLayout.Canvas.BackgroundImage
  • Layout.CustomLayout.Regions
    在开始录制前,你必须已经启用云端录制,并启用了合流录制。参看开始云端录制 StartRecord

    并且,仅在启动云端录制的配置中 RecordMode=0Layout.LayoutMode=2 时,才可以调用此接口,即只有合流录制的自定义布局模式下,才可以更新任务参数。

调用接口

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

注意事项

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

请求说明

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

请求参数

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

Query

参数类型是否必选示例值描述
ActionStringUpdateRecord接口名称。当前 API 的名称为 UpdateRecord
VersionString2022-06-01接口版本。当前 API 的版本为 2022-06-01

Body

参数类型是否必选示例值描述
AppIdStringYour_AppId你的音视频应用的唯一标志
BusinessIdStringYour_BusinessId业务标识
RoomIdStringYour_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}

TargetStreamsObject of Streams-你可以通过本参数设定需要录制的音视频流。单流录制模式下,如果参数为空,默认录制对房间内所有人进行单流录制。最多17人。
LayoutObject of Layout布局参数。

Streams

参数类型是否必选示例值描述
StreamListArray of StreamStream组成的列表,可以为空。为空时,表示订阅房间内所有流。在一个 StreamList 中,Stream.Index 不能重复。

Layout

参数类型是否必选示例值描述

LayoutMode

Integer

0

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

CustomLayoutObject of CustomLayout使用自定义布局模式时,使用此参数进行具体设置。
MainVideoStreamObject of Stream在垂直布局模式下生效,指定主画面流的属性。如果此参数为空,则主画面为随机的一路流。

Stream

参数类型是否必选示例值描述
IndexInteger0在自定义布局中,使用 Index 对流进行标志。后续在 Layout.regions.StreamIndex 中,你需要使用 Index 指定对应流的布局设置。
UserIdStringYour_UserId用户Id,表示这个流所属的用户。
StreamTypeInteger0流的类型,值可以取01,默认值为00表示普通音视频流,1表示屏幕流。

CustomLayout

参数类型是否必选示例值描述
CanvasObject of Canvas整体屏幕(画布)的宽高以及背景色。

Regions

Array of Region

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

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

Canvas

参数类型是否必选示例值描述
WidthInteger640整体屏幕(画布)的宽度,单位为像素,范围为 [2, 1920],必须是偶数。默认值为 640。值不合法时,自动调整为默认值。
HeightInteger480整体屏幕(画布)的高度,单位为像素,范围为 [2, 1920],必须是偶数。默认值为 480。值不合法时,自动调整为默认值。
BackgroundString#000000整体屏幕(画布)的背景色,格式为 #RGB(16进制),默认值为 #000000(黑色), 范围为 #000000 ~ #ffffff (大小写均可)。值不合法时,自动调整为默认值。

BackgroundImage

String

背景图片的 URL。长度最大为 1024 byte。可以传入的图片的格式包括:JPG, JPEG, PNG。如果背景图片的宽高和整体屏幕的宽高不一致,背景图片会缩放到铺满屏幕。
如果你设置了背景图片,背景图片会覆盖背景色。

Region

参数类型是否必选示例值描述
AlphaFloat1画面的透明度,取值范围为 (0.0, 1.0]0.0 表示完全透明,1.0 表示完全不透明,默认值为 1.0。值不合法时,自动调整为默认值。
ZOrderInteger0当多个流的画面有重叠时,使用此参数设置指定画面的图层顺序。取值范围为 [0, 100]0 表示该区域图像位于最下层,100 表示该区域图像位于最上层, 默认值为 0。值不合法时,自动调整为默认值。

LocationX

Float

0

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

LocationYFloat0视频流对应区域左上角的横坐标相对整体画面左上角原点的纵向位移,取值的范围为 [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
SourceCropObject of SourceCrop源流剪切功能,可以在源视频帧渲染之前进行裁剪,即预处理一次再渲染。
StreamIndexInteger0流的标识。这个标志应和 TargetStreams.StreamList.Stream.Index 对应。

AlternateImage

String

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

  • Region.StreamIndex 对应的视频流没有发布,或被暂停采集时,AlternateImage 对应的图片会填充 Region 对应的画布空间。当视频流被采集并发布时,AlternateImage 不造成任何影响。
  • 可以传入的图片的格式包括:JPG, JPEG, PNG。
  • 当图片和画布尺寸不一致时,图片根据 RenderMode 的设置,在画布中进行渲染。
SpatialPositionArray of Integer空间音频下,房间内指定用户所在位置的三维坐标,默认值为[0,0,0]。数组长度为3,三个值依次对应X,Y,Z,每个值的取值范围为[-100,100]
WidthProportionFloat0.5视频流对应区域宽度相对整体画面的比例,取值的范围为 (0.0, 1.0]
HeightProportionFloat0.5视频流对应区域高度相对整体画面的比例,取值的范围为 (0.0, 1.0]

AlternateImageFillMode

Integer

0

画面的渲染模式。

  • 0:按照用户原始视频帧比例进行缩放
  • 1:保持图片原有比例
    默认值为 0。值不合法时,自动调整为默认值。

SourceCrop

参数类型是否必选示例值描述
LocationXFloat0裁剪后得到的视频帧左上角的横坐标相对裁剪前整体画面的比例,取值的范围为 [0.0, 1.0)。默认值为 0.0。值不合法时,自动调整为默认值。
LocationYFloat0裁剪后得到的视频帧左上角的纵坐标相对裁剪前整体画面的比例,取值的范围为 [0.0, 1.0)。默认值为 0.0。值不合法时,自动调整为默认值。
WidthProportionFloat0.5裁剪后得到的视频帧宽度相对裁剪前整体画面宽度的比例,取值范围为 (0.0, 1.0]。默认值为 1.0。值不合法时,自动调整为默认值。
HeightProportionFloat0.5裁剪后得到的视频帧高度相对裁剪前整体画面宽度的比例,取值范围为 (0.0, 1.0]。默认值为 1.0。值不合法时,自动调整为默认值。

返回参数

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

请求示例

POST https://rtc.volcengineapi.com?Action=UpdateRecord&Version=2022-06-01

{
    "AppId": "Your_AppId",
    "BusinessId": "Your_BusinessId",
    "RoomId": "Your_RoomId",
    "TaskId": "Your_TaskId",
    "TargetStreams": {
        "StreamList": [
            {
                "Index": 0,
                "UserId": "Your_UserId_1",
                "StreamType": 1
            },
            {
                "Index": 1,
                "UserId": "Your_UserId_2"
            }
        ]
    },    
    "Layout": {
        "LayoutMode": 2,
        "CustomLayout": {
            "Canvas": {
                "Width": 860,
                "Height": 340,
                "Background": "#303342"
            },
            "Regions": [
                {
                    "StreamIndex": 0,
                    "LocationX": 0,
                    "LocationY": 0,
                    "WidthProportion": 0.5,
                    "HeightProportion": 1,
                    "ZOrder": 0,
                    "Alpha": 1,
                    "RenderMode": 0
                },
                {
                    "StreamIndex": 1,
                    "LocationX": 0.5,
                    "LocationY": 0,
                    "WidthProportion": 0.5,
                    "HeightProportion": 1,
                    "ZOrder": 1,
                    "Alpha": 1,
                    "RenderMode": 1
                }
            ]
        }
    }
}

返回示例

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

错误码

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