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

更新公共流 UpdatePublicStreamParam

最近更新时间2024.02.21 20:12:25

首次发布时间2022.05.20 20:23:14

如果你已使用 StartPushPublicStream 发布了一路公共流,你可以调用 UpdatePublicStreamParam 来更新任务的部分参数。

使用说明

接口行为

你可以调用 UpdatePublicStreamParam 接口,覆盖此前在 StartPushPublicStreamUpdatePublicStreamParam 中设定的参数。

Control.MaxIdleTimeControl.DataMsgVideoConfig.VideoCodec 无法通过该接口进行更新。

如果你在调用 UpdatePublicStreamParam 时,没有传入对应的参数值,那么,这部分参数将被更新为参数的默认值。

调用接口

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

注意事项

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

请求说明

  • 请求方式:POST
  • 请求地址:https://rtc.volcengineapi.com?Action=UpdatePublicStreamParam&Version=2020-12-01

请求参数

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

Query

参数类型是否必选示例值描述
ActionStringUpdatePublicStreamParam接口名称。当前 API 的名称为 UpdatePublicStreamParam
VersionString2020-12-01接口版本。当前 API 的版本为 2020-12-01

Body

参数类型是否必选示例值描述
AppIdStringYour_AppId你的音视频应用的唯一标志
BusinessIdString Your_BusinessId业务标识
PublicStreamIdStringYour_PublicStreamId公共流 ID。

TranscodeMode

Integer

0

公共流处理模式。
0:转码。
1:转封装。
TranscodeMode=1 时,

  • TargetStreams 只能指定一路流,且该路流的 UserId不能为空,需为对应房间用户的 UserId
  • ExcludeStreams 必须为空。
  • Encode.VideoConfig 设置不生效。
  • Layout 设置不生效。
TargetStreamsArray of PublicStream-为公共流指定单路或多路媒体流及对应参数,Stream 数组。最高支持 17 路。
ExcludeStreamsArray of PublicStream-你可以通过本参数排除掉需要包含在公共流中的音视频流,即黑名单。参数默认为空。黑名单中的流不得超过 17 路。此参数中的 stream 不应和 TargetStreams 中重复。
LayoutObject of PublicLayout-房间内多路流合为一路时的布局参数
EncodeObject of PublicEncode-媒体编码参数
ControlObject of PublicControl-控制选项。

PublicStream

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

UserId

String

Your_UserId

媒体流的发布方的用户 ID。
UserId 为空时,表示订阅房间内所有流。
UserId 需全局唯一。不同房间内的 UserId 不能重复。

StreamType

Integer

0

流类型。默认值为 0

  • 0:媒体设备采集到的音视频
  • 1:屏幕流

Index

Integer

1

当选择自定义布局模式时,此字段必填。标记同一路公共流中不同的媒体流。
在同一个 TargetStreams 中,Stream.Index 是唯一的。

RoomIdStringYour_RoomId发布公共流的用户所在的房间 ID

MediaType

String

0

流的媒体类型。默认值为 0

  • 0:音视频
  • 1:纯音频
  • 2:纯视频

PublicLayout

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

LayoutMode

Integer

0

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

VerticalLayoutObject of VerticalLayout垂直布局参数
CustomLayoutObject of PublicCustomLayout自定义布局参数

PublicEncode

参数类型是否必选示例值描述
VideoConfigObject of VideoConfig视频编码配置

PublicControl

参数类型是否必选示例值描述
MaxIdleTimeInteger180任务的空闲超时时间,超过此时间后,任务自动终止。单位为秒。取值范围为 [10, 86400],默认值为 180。只在调用 StartPushPublicStream 时有效。

DataMsg

String

-

插入公共流的自定义信息,可用于随流信息同步,长度不超过 4 kB。
数据会添加到当前视频帧开始的连续 30 个视频帧中。
只在调用 UpdatePublicStreamParam 时有效。

UserCaptureStatsMode

Boolean

false

是否开启房间用户采集状态回调,仅在纯音频时触发。开启后会通过 onPublicStreamDataMessageReceived 回调。

  • true:开启房间用户采集状态回调。
  • false:不开启房间用户采集状态回调。
    默认值为false

VolumeIndicationMode

Boolean

false

是否开启音量指示模式。

  • true:开启音量提示。
  • false:不开启音量提示。
    默认值为false

StreamPublishStatsMode

Boolean

false

是否开启房间用户发布状态回调,仅在纯音频时触发。开启后会通过 onPublicStreamDataMessageReceived 回调。

  • true:开启房间用户发布状态回调。
  • false:不开启房间用户发布状态回调。
    默认值为false
UserCaptureStatsIntervalInteger2000房间用户采集状态回调间隔,仅在纯音频时触发。单位为毫秒,默认值为 2000,取值范围为 [1000,2147483647]。 值不合法时自动调整为默认值。
VolumeIndicationIntervalInteger2000音量指示的回调间隔。单位为毫秒,最小值为 100,默认值为 2000。 值不合法时自动调整为默认值。
VideoConfig.FrameRate 大于 10 fps 时,回调间隔才能达到 100ms。
StreamPublishStatsIntervalInteger2000房间用户发布状态回调间隔,仅在纯音频时触发。单位为毫秒,默认值为 2000,取值范围为 [1000,2147483647]。 值不合法时自动调整为默认值。

VerticalLayout

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

MainStream

Object of PublicStream

指定在大窗口中显示的流及相关信息
1. 如果在 TargetStreams 中指定了某用户的音频和视频,但在MainStream 只指定该用户的音频,则公共流中只包含该用户的音频,大窗口的区域置空。
2. 如果在 TargetStreams 中指定了某用户的视频,但在MainStream只指定该用户的音频,则公共流中不包含该用户的音频和视频,大窗口的区域置空。
3. 如果 MainStream 中指定的用户不存在,大窗口的区域置空。

PublicCustomLayout

参数类型是否必选示例值描述
RegionsArray of PublicCustomRegion自定义布局下,多路视频配置

FrameInterpolationMode

Integer

0

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

  • Region.StreamIndex 对应的视频流停止发布时, Region 对应的画布空间会根据设置填充占位图或补帧。但当视频流为屏幕流时,补帧模式不生效。
  • Region.StreamIndex 对应的视频流发布后停止采集或推送时, Region 对应的画布空间会填充上一帧。
  • Region.StreamIndex 对应的视频流发布时,设置的占位图或补顿模式不造成任何影响。

BackgroundColor

String

#000000

背整体屏幕(画布)的背景色,格式为 #RGB(16进制),默认值为 #000000(黑色), 范围为 #000000 ~ #ffffff (大小写均可)。值不合法时,自动调整为默认值。

如果你设置了背景图片,背景图片会覆盖背景色。

BackgroundImage

String

http://xxxx.svg

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

如果你设置了背景图片,背景图片会覆盖背景色。

VideoConfig

参数类型是否必选示例值描述
WidthInteger640输出画面的宽度。默认值为 640,范围为 [16, **1920**],必须是偶数。
HeightInteger480输出画面的高度,默认值为 480。范围为 [16, 1920],必须是偶数。
FrameRateInteger15输出视频帧率。默认为 15,取值范围为 [1,60]。单位 fps
BitrateInteger256最高输出视频码率。取值范围 [**0,10000**],单位为 Kbps,默认值0,为0时表示自适应码率。

VideoCodec

Integer

0

视频编码协议。可取值为 0 或 5,默认值为 0

  • 0H.264
  • 5VP8。 如果选择 VP8 格式,请先联系火山技术支持配置。

PublicCustomRegion

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

StreamIndex

Integer

1

流标识。

StreamIndex 即 Stream.Index,用来指定布局设置将被应用到哪路流。

LocationXFloat0视频流对应区域左上角的横坐标相对整体画面的比例,取值的范围为 [0.0, 1.0),默认值为 0
LocationYFloat0视频流对应区域左上角的纵坐标相对整体画面的比例,取值的范围为 [0.0, 1.0),默认值为 0
WidthProportionFloat0.5视频流对应区域宽度相对整体画面的比例,取值的范围为 (0.0, 1.0]
HeightProportionFloat0.5视频流对应区域高度相对整体画面的比例,取值的范围为 (0.0, 1.0]
ZOrderFloat0当画面有重叠时,使用此参数设置指定画面的图层顺序,取值范围为 [0, 100]0 表示该区域图像位于最下层,100 表示该区域图像位于最上层, 默认值为 0
AlphaFloat1.0画面的透明度,取值范围为 (0.0, 1.0]0.0 表示完全透明,1.0 表示完全不透明,默认值为 1.0

RenderMode

Integer

0

画面的渲染模式,值的范围为 {0, 1, 2,3}, 默认值为 0:- 0 表示按照指定的宽高直接缩放。如果原始画面宽高比与指定的宽高比不同,就会导致画面变形

  • 1 表示按照显示区域的长宽比裁减视频,然后等比拉伸或缩小视频,占满显示区域。
  • 2 表示按照原始画面的宽高比缩放视频,在显示区域居中显示。如果原始画面宽高比与指定的宽高比不同,就会导致画面有空缺,空缺区域为填充的背景色值。值不合法时,自动调整为默认值。
  • 3 表示按照指定的宽高直接缩放。如果原始画面宽高比与指定的宽高比不同,就会导致画面变形

    目前 03 均为按照指定的宽高直接缩放,但我们推荐你使用 3 以便与客户端实现相同逻辑。
AlternateImageStringhttps://xx.com/img/1.png占位图片的 url

SourceCrop

Object of SourceCrop

源流剪切功能。公共流功能下, SourceCropAlternateImage 不生效。

注意

如果你填写了 LocationXLocationYWidthProportionHeightProportion 中的一个或多个参数,SourceCrop 下的其他参数也必须填写。

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=UpdatePublicStreamParam&Version=2020-12-01

{
    "AppId": "Your_AppId",
    "BusinessId": "Your_BusinessId",
    "TranscodeMode": 0,
    "TargetStreams": [
        {
            "Index": 0,
            "UserId": "Your_UserId_3",
            "RoomId": "Your_RoomId",
            "StreamType": 1,
            "MediaType": 0
        },
        {
            "Index": 1,
            "UserId": "Your_UserId_3",
            "RoomId": "Your_RoomId",
            "StreamType": 1,
            "MediaType": 0
        }
    ],
    "Encode": {
        "VideoConfig": {
            "Width": 640,
            "Height": 480,
            "FrameRate": 15,
            "Bitrate": 256
        }
    },
    "Layout": {
        "LayoutMode": 2,
        "CustomLayout": {
            "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,
                    "AlternateImage": "https://xx.com/img/1.jpg",
                    "SourceCrop": {
                        "LocationX": 500,
                        "LocationY": 0,
                        "WidthProportion": 0.5,
                        "HeightProportion": 0.5
                    }
                }
            ],
            "FrameInterpolationMode": 0,
            "BackgroundColor": "#000000",
            "BackgroundImage": "https://xx.com/img/1.jpg"
        }
    },
    "Control": {
        "DataMsg": "CamInfo"
    }
}

返回示例

{
    "Result": "ok",
    "ResponseMetadata": {
        "RequestId": "Your_RequestId",
        "Action": "UpdatePublicStreamParam",
        "Version": "2020-12-01",
        "Service": "rtc",
        "Region": "cn-north-1"
    }
}

错误码

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