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

更新合流转推 UpdatePushMixedStreamToCDN

最近更新时间2024.02.19 11:10:11

首次发布时间2023.10.31 17:39:57

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

如果你已使用 StartPushMixedStreamToCDN 启动了一个合流转推任务,你可以调用此接口 UpdatePushMixedStreamToCDN 来更新任务的部分参数。

使用说明

接口行为

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

  • TargetStreams
  • Layout.CustomLayout.Canvas.BackgroundLayout.CustomLayout.Canvas.BackgroundImageLayout.CustomLayout.Regions
  • Encode 中,除 audioProfilevideoCodec 以外的参数。
  • Control.SpatialConfig
  • Control.SEIConfig.UserConfigExtraInfo
    通过此 OpenAPI,你无法更新除上述参数以外的参数。并且,对于上述参数,如果你在调用 OpenAPI 时,没有传入对应的值,那么,合流转推时使用的值将会被更新为默认值。

前置条件

在调用StartPushMixedStreamToCDN时,Layout.LayoutMode 必须为2。即只有自定义布局模式下,才支持调用UpdatePushMixedStreamToCDN更新任务的部分参数。

调用接口

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

注意事项

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

请求说明

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

请求参数

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

Query

参数类型是否必选示例值描述
ActionStringUpdatePushMixedStreamToCDN接口名称。当前 API 的名称为 UpdatePushMixedStreamToCDN
VersionString2023-06-01接口版本。当前 API 的版本为 2023-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转推包含的房间内的流。
LayoutObject of Layout房间内多路流合为一路时的布局参数
EncodeObject of Encode音视频编码参数
ControlObject of Control配置选项。若合流转推的音频参数设置为单声道,空间音频无效。

IsUpdatePartialParam

Boolean

False

是否更新部分参数。

  • False:否。
  • True:是。
    默认值为 False
    开启部分更新后,必须按照参数层级传入,且数组类参数需要传入该数组中所有参数。

SequenceNumber

Integer

0

更新请求序列号。填写该参数后,服务端会对请求进行校验,请确保最后一次更新请求的序列号大于前一次请求的序列号。
建议更新部分参数场景下传入此参数,以确保服务端按照最新请求进行更新。

Streams

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

Layout

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

LayoutMode

Integer

0

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

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

Encode

参数类型是否必选示例值描述
VideoWidthInteger640输出画面的宽度。默认值为640,范围为 [2, 1920],必须是偶数。值不合法时,自动调整为默认值。自定义布局下此参数不生效,整体画面宽度以 canvas 中的 Width 为主。
VideoHeightInteger480输出画面的高度,范围为[2, 1920],必须是偶数,默认值为480。值不合法时,自动调整为默认值。自定义布局下此参数不生效,整体画面高度以 canvas 中的 Height 为主。
VideoFpsInteger15输出视频帧率。默认为 15,取值范围为 [1,60]。值不合法时,自动调整为默认值。

VideoBitrate

Integer

/

输出视频码率。取值范围 [1,10000],单位为 Kbps,默认值为自适应。值不合法时,自动调整为默认值。
自适应码率模式下,RTC 默认不会设置超高码率。如果订阅屏幕流,建议自行设置高码率。不同场景下设置码率等视频发布参数,请参考设置视频发布参数

VideoCodecInteger0视频编码协议。默认值为 0,可以取 01。取 0 时使用 H.264,取 1 时使用 ByteVC1 编码器。
VideoGopInteger4输出视频 GOP。默认为 4,取值范围为 [1,5],单位为秒。值不合法时,自动调整为默认值。
AudioCodecInteger0音频编码协议。默认值为 0,此时使用 aac 编码协议。目前只支持 aac。值不合法时,自动调整为默认值。

AudioProfile

Integer

0

音频配置文件类型,在使用 aac 编码时生效。取值范围为 {0, 1, 2}

  • 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
AudioSampleRateInteger48000音频采样率。默认值 48000,取值为 [32000,44100,48000],单位是 Hz。值不合法时,自动调整为默认值。

AudioChannels

Integer

2

音频声道数。

  • 1:单声道
  • 2:双声道。
    默认值为 2。值不合法时,自动调整为默认值。

Control

参数类型是否必选示例值描述
MediaTypeInteger0流的类型,用于全局控制订阅的流的类型。默认值为0,可以取010表示音视频,1表示纯音频,暂不支持纯视频。值不合法时,自动调整为默认值。

FrameInterpolationMode

Integer

0

选择补帧模式。默认值为0,可以取010为补最后一帧,1为补黑帧。值不合法时会自动调整为默认值。
自动布局模式下,没有补帧的逻辑。
补帧是指在音视频录制或合流转推时,视频的帧率通常是固定的。但是,因为网络波动或其他原因,实际帧率可能无法达到预设的帧率。此时,需要补帧以保持视频流畅。补最后一帧意味着补充的视频帧和中断前的最后一帧相同,此时看到的画面可能会有短暂静止;补黑帧意味着补充的视频帧是全黑的。
使用占位图、补帧和上一帧的关系:
你可以在 Region 中传入 Alternateimage 字段设置占位图,在 Control 中传入FrameInterpolationMode 字段设置补帧模式,但占位图优先级高于补帧模式。

  • Region.StreamIndex 对应的视频流停止发布时, Region 对应的画布空间会根据设置填充占位图或补帧。但当视频流为屏幕流时,补帧模式不生效。
  • Region.StreamIndex 对应的视频流发布后停止采集或推送时, Region 对应的画布空间会填充上一帧。
  • Region.StreamIndex 对应的视频流发布时,设置的占位图或补顿模式不造成任何影响。
MaxIdleTimeInteger180任务的空闲超时时间,超过此时间后,任务自动终止。单位为秒。取值范围为 [10, 86400], 默认值为 180
MaxRecordTimeInteger0(仅对录制有效)最大录制时长,单位为秒。默认值为 00 表示不限制录制时长。
SpatialConfigObject of SpatialConfig空间音频配置。若合流转推的音频参数设置为单声道,空间音频无效。

PushStreamMode

Integer

0

转推直播推流模式,用于控制触发推流的时机。取值为01。默认值为0

  • 0:房间内有用户推 RTC 流时即触发 CDN 推流。
  • 1:调用接口发起推流任务后,无论房间内是否有用户推 RTC 流,均可触发 CDN 推流。
    值不合法时,自动调整为默认值。
    任务超时逻辑不变,依然是无用户推流即判定为超时。
SEIConfigObject of SEIConfig(仅对转推直播有效)SEI 相关配置。

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
当传入的选填参数值不合法时,自动调整为默认值。

SpatialConfig

参数类型是否必选示例值描述
EnableSpatialRenderBooleanfalse是否开启空间音频处理功能。
  • false:关闭。
  • true:开启
  • AudienceSpatialPositionArray of Integer[0,0,0]观众所在位置的三维坐标,默认值为[0,0,0]。数组长度为3,三个值依次对应X,Y,Z,每个值的取值范围为[-100,100]
    AudienceSpatialOrientationObject of AudienceSpatialOrientation设置观众朝向。各个向量两两垂直,如果传入的值没有保证两两垂直,自动赋予默认值。默认值为:forward = [1, 0, 0], right = [0, 1, 0], up = [0, 0, 1]

    SEIConfig

    参数类型是否必选示例值描述
    UserConfigExtraInfoString/设置SEI数据结构app_data 参数的值,最大长度为 4096。此参数支持动态更新。

    PassthroughRTCSEIMessage

    Boolean

    true

    是否透传 RTC 流里的 SEI 信息。

    • true:是。
    • false:否。
      默认值为 true
    VolumeIndicationIntervalFloat2接受 SDK 传入的用户说话音量回调的间隔,单位为秒,取值范围为[0.5,∞],默认值为 2。仅当用户说话音量发生变化时,接受用户说话音量回调才会被触发。

    VolumeIndicationMode

    Boolean

    false

    (仅对转推直播有效)是否开启音量指示模式。

    • true:是。此时非关键帧中也可能携带 SEI 信息。
    • false:否。此时只会在关键帧中携带 SEI 信息。
      默认值为 false
      VolumeIndicationMode = true 的同时设置 MediaType = 1,该流推向 CDN 地址时,服务端会补黑帧。 关于音量指示模式的用法,参看 音量指示模式

    AddVolumeValue

    Boolean

    false

    SEI 中是否包含用户说话音量值。

    • false:否。
    • true:是。
      默认值为 false。值不合法时自动调整为默认值。

    SEIContentMode

    Integer

    0

    开启音量指示模式后,非关键帧携带 SEI 包含的信息类型。

    SEIPayLoadTypeInteger100设置 SEI 的 Payload Type,对 服务端合流转推 SEI 和 RTC 透传SEI 均生效。取值为 5100,默认为 100

    SEIPayloadUUID

    String

    566f6c63656e67696e65525443534549

    该字段为长度为 32 位的 16 进制字符,每个字符的范围为 a-f,A-F,0-9,不可包含 -。如果校验失败,会返回错误码 InvalidParameter
    仅当 SEIPayLoadType=5时,该字段需要填写,SEIPayLoadType=100时,该字段内容会被忽略。
    此参数仅对 RTC 透传SEI 生效。当用户设置 SEIPayloadType = 5 时,服务端合流转推SEI 的 SEIPayloadUUID 为固定值:566f6c63656e67696e65525443534549,对应16位字符串 VolcengineRTCSEI

    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

    参数类型是否必选示例值描述
    StreamIndexInteger0流的标识。这个标志应和 TargetStreams.StreamList.Stream.Index 对应。

    LocationX

    Integer

    0

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

    LocationYInteger0视频流对应区域左上角的横坐标相对整体画面左上角原点的纵向位移,取值的范围为 [0.0, Canvas.Height)。默认值为 0。若传入该参数,服务端会对该参数进行校验,若不合法会返回错误码 InvalidParameter
    WidthInteger640视频流对应区域宽度的像素绝对值,取值的范围为 (0.0, Canvas.Width]
    HeightInteger480视频流对应区域高度的像素绝对值,取值的范围为 (0.0, Canvas.Height]
    ZOrderInteger0当多个流的画面有重叠时,使用此参数设置指定画面的图层顺序。取值范围为 [0, 100]0 表示该区域图像位于最下层,100 表示该区域图像位于最上层, 默认值为 0。值不合法时,自动调整为默认值。
    AlphaFloat1画面的透明度,取值范围为 (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
    SourceCropObject of SourceCrop源流剪切功能,可以在源视频帧渲染之前进行裁剪,即预处理一次再渲染。
    AlternateImageStringrtmp://xxx.xxx补位图片的 url。长度不超过 1024 个字符串。- 在 Region.StreamIndex 对应的视频流没有发布,或被暂停采集时,AlternateImage 对应的图片会填充 Region 对应的画布空间。当视频流被采集并发布时,AlternateImage 不造成任何影响。- 可以传入的图片的格式包括:JPG, JPEG, PNG。- 当图片和画布尺寸不一致时,图片根据 RenderMode 的设置,在画布中进行渲染。

    ApplySpatialAudio

    Boolean

    /

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

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

    MediaType

    Integer

    0

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

    • 0:音视频
    • 1:纯音频
    • 2:纯视频
      默认值为 0。值不合法时,自动调整为默认值。

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

    AlternateImageFillMode

    Integer

    0

    画面的渲染模式。

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

    AudienceSpatialOrientation

    参数类型是否必选示例值描述
    UpArray of Float[0, 0, 1]头顶朝向
    RightArray of Float[0, -1, 0]右边朝向
    ForwardArray of Float[1, 0, 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=UpdatePushMixedStreamToCDN&Version=2023-06-01
    
    {
        "AppId": "Your_AppId",
        "BusinessId": "Your_BusinessId",
        "RoomId": "Your_RoomId",
        "TaskId": "Your_TaskId",
        "TargetStreams": {
            "StreamList": [
                {
                    "Index": 0,
                    "UserId": "Your_UserId_3"
                },
                {
                    "Index": 1,
                    "UserId": "Your_UserId_4",
                    "StreamType": 1
                }
            ]
        },
        "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": "Your_RequestId",
            "Action": "UpdatePushMixedStreamToCDN",
            "Version": "2023-06-01",
            "Service": "rtc",
            "Region": "cn-north-1"
        }
    }
    

    错误码

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