更新公共流 UpdatePublicStreamParam--实时音视频-火山引擎

文档中心

实时音视频

公共流

更新公共流 UpdatePublicStreamParam

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

使用说明

接口行为

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

Control.MaxIdleTime 和 VideoConfig.VideoCodec 无法通过该接口进行更新。

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

注意事项

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

请求说明

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

调试

API Explorer

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

去调试

请求参数

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

Query

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

Body

参数	类型	是否必选	示例值	描述
AppId	String	是	`You****pId`	你的音视频应用的唯一标志
BusinessId	String	否	`Your_****nessId`	业务标识
PublicStreamId	String	是	`Your_PublicStreamId`	公共流 ID。
TranscodeMode	Integer	否	`0`	公共流处理模式。 `0`：转码。 `1`：转封装。当 `TranscodeMode`=`1` 时， `TargetStreams` 只能指定一路流，且该路流的 `UserId`不能为空，需为对应房间用户的 `UserId`。 `ExcludeStreams` 必须为空。 `Encode.VideoConfig` 设置不生效。 `Layout` 设置不生效。
TargetStreams	Object[]	是	`-`	为公共流指定单路或多路媒体流及对应参数，Stream 数组。最高支持 17 路。
UserId	String	否	`Your_UserId`	媒体流的发布方的用户 ID。 UserId 为空时，表示订阅房间内所有流。 UserId 需全局唯一。不同房间内的 UserId 不能重复。
StreamType	Integer	否	`0`	流类型。默认值为 `0`。 `0`：媒体设备采集到的音视频 `1`：屏幕流
Index	Integer	否	`1`	当选择自定义布局模式时，此字段必填。标记同一路公共流中不同的媒体流。在同一个 `TargetStreams` 中，`Stream.Index` 是唯一的。
RoomId	String	是	`Your_RoomId`	发布公共流的用户所在的房间 ID
MediaType	Integer	否		流的媒体类型。默认值为 `0` 。 `0`：音视频 `1`：纯音频 `2`：纯视频
ExcludeStreams	Object[]	否	`-`	你可以通过本参数排除掉不需要包含在公共流中的音视频流，即黑名单。参数默认为空。黑名单中的流不得超过 17 路。此参数中的 `stream` 不应和 `TargetStreams` 中重复。
UserId	String	否	`Your_UserId`	媒体流的发布方的用户 ID。 UserId 为空时，表示订阅房间内所有流。 UserId 需全局唯一。不同房间内的 UserId 不能重复。
StreamType	Integer	否	`0`	流类型。默认值为 `0`。 `0`：媒体设备采集到的音视频 `1`：屏幕流
Index	Integer	否	`1`	当选择自定义布局模式时，此字段必填。标记同一路公共流中不同的媒体流。在同一个 `TargetStreams` 中，`Stream.Index` 是唯一的。
RoomId	String	是	`Your_RoomId`	发布公共流的用户所在的房间 ID
MediaType	Integer	否		流的媒体类型。默认值为 `0` 。 `0`：音视频 `1`：纯音频 `2`：纯视频
Layout	Object	否	`-`	房间内多路流合为一路时的布局参数
LayoutMode	Integer	是	`0`	布局模式。默认值为 `0`，值的范围为 `{0, 1, 2, 3}`。 `0` 为自适应布局模式。参看自适应布局。 `1` 为垂直布局模式。参看垂直布局。 `2` 为自定义布局模式。 `3` 为并排布局模式。参看并排布局
VerticalLayout	Object	否		垂直布局参数
MainStream	Object	否		指定在大窗口中显示的流及相关信息 1. 如果在 TargetStreams 中指定了某用户的音频和视频，但在MainStream 只指定该用户的音频，则公共流中只包含该用户的音频，大窗口的区域置空。 2. 如果在 TargetStreams 中指定了某用户的视频，但在MainStream只指定该用户的音频，则公共流中不包含该用户的音频和视频，大窗口的区域置空。 3. 如果 MainStream 中指定的用户不存在，大窗口的区域置空。
UserId	String	否	`Your_UserId`	媒体流的发布方的用户 ID。 UserId 为空时，表示订阅房间内所有流。 UserId 需全局唯一。不同房间内的 UserId 不能重复。
StreamType	Integer	否	`0`	流类型。默认值为 `0`。 `0`：媒体设备采集到的音视频 `1`：屏幕流
Index	Integer	否	`1`	当选择自定义布局模式时，此字段必填。标记同一路公共流中不同的媒体流。在同一个 `TargetStreams` 中，`Stream.Index` 是唯一的。
RoomId	String	是	`Your_RoomId`	发布公共流的用户所在的房间 ID
MediaType	Integer	否		流的媒体类型。默认值为 `0` 。 `0`：音视频 `1`：纯音频 `2`：纯视频
CustomLayout	Object	否		自定义布局参数
Regions	Object[]	是		自定义布局下，多路视频配置
StreamIndex	Integer	是	`1`	流标识。 StreamIndex 即 Stream.Index，用来指定布局设置将被应用到哪路流。
LocationX	Float	否	`0`	视频流对应区域左上角的横坐标相对整体画面的比例，取值的范围为 `[0.0, 1.0)`，默认值为 `0`。
LocationY	Float	否	`0`	视频流对应区域左上角的纵坐标相对整体画面的比例，取值的范围为 `[0.0, 1.0)`，默认值为 `0`。
WidthProportion	Float	是	`0.5`	视频流对应区域宽度相对整体画面的比例，取值的范围为 `(0.0, 1.0]`。
HeightProportion	Float	是	`0.5`	视频流对应区域高度相对整体画面的比例，取值的范围为 `(0.0, 1.0]`。
ZOrder	Integer	否		当画面有重叠时，使用此参数设置指定画面的图层顺序，取值范围为 `[0, 100]`：`0` 表示该区域图像位于最下层，`100` 表示该区域图像位于最上层, 默认值为 `0`。
Alpha	Float	否	`1.0`	画面的透明度，取值范围为 `(0.0, 1.0]`。`0.0` 表示完全透明，`1.0` 表示完全不透明，默认值为 `1.0`。
RenderMode	Integer	否	`0`	画面的渲染模式，值的范围为 `{0, 1, 2，3}`, 默认值为 `0`：- `0` 表示按照指定的宽高直接缩放。如果原始画面宽高比与指定的宽高比不同，就会导致画面变形 `1` 表示按照显示区域的长宽比裁减视频，然后等比拉伸或缩小视频，占满显示区域。 `2` 表示按照原始画面的宽高比缩放视频，在显示区域居中显示。如果原始画面宽高比与指定的宽高比不同，就会导致画面有空缺，空缺区域为填充的背景色值。值不合法时，自动调整为默认值。 `3` 表示按照指定的宽高直接缩放。如果原始画面宽高比与指定的宽高比不同，就会导致画面变形目前 `0` 和 `3` 均为按照指定的宽高直接缩放，但我们推荐你使用 `3` 以便与客户端实现相同逻辑。
AlternateImage	String	否	`https://xx.com/img/1.png`	占位图片的 url
SourceCrop	Object	否	`-`	源流剪切功能。公共流功能下， `SourceCrop` 对 `AlternateImage` 不生效。注意如果你填写了 `LocationX`、`LocationY`、`WidthProportion`和`HeightProportion` 中的一个或多个参数，`SourceCrop` 下的其他参数也必须填写。
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`。值不合法时，自动调整为默认值。
FrameInterpolationMode	Integer	否	`0`	选择补帧模式。默认值为`0`，可以取`0`和`1`。`0`为补最后一帧，`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`。如果背景图片的宽高和整体屏幕的宽高不一致，背景图片会缩放到铺满屏幕。如果你设置了背景图片，背景图片会覆盖背景色。
Encode	Object	否	`-`	媒体编码参数
VideoConfig	Object	否		视频编码配置
Width	Integer	否	`640`	输出画面的宽度。默认值为 640，范围为 `[16, 1920]`，必须是偶数。
Height	Integer	否	`480`	输出画面的高度，默认值为 480。范围为 `[16, 1920]`，必须是偶数。
FrameRate	Integer	否	`15`	输出视频帧率。默认为 15，取值范围为 [1,60]。单位 fps
Bitrate	Integer	否	`256`	最高输出视频码率。取值范围 `[0,10000]`，单位为 Kbps，默认值`0`，为`0`时表示自适应码率。
VideoCodec	Integer	否	`0`	视频编码协议。可取值为 `0` 或 `5`，默认值为 `0`。 `0`：`H.264`。 `5`：`VP8`。如果选择 `VP8` 格式，请先联系火山技术支持配置。
Control	Object	否	`-`	控制选项。
MaxIdleTime	Integer	否	`180`	任务的空闲超时时间，超过此时间后，任务自动终止。单位为秒。取值范围为 `[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`。
UserCaptureStatsInterval	Integer	否	`2000`	房间用户采集状态回调间隔，仅在纯音频时生效。单位为毫秒，默认值为 `2000`，取值范围为 `[1000,2147483647]`。值不合法时自动调整为默认值。
VolumeIndicationInterval	Integer	否	`2000`	音量指示的回调间隔。单位为毫秒，最小值为 `100`，默认值为 `2000`。值不合法时自动调整为默认值。 VideoConfig.FrameRate 大于 10 fps 时，回调间隔才能达到 100ms。
StreamPublishStatsInterval	Integer	否	`2000`	房间用户发布状态回调间隔，仅在纯音频时生效。单位为毫秒，默认值为 `2000`，取值范围为 `[1000,2147483647]`。值不合法时自动调整为默认值。

返回参数

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

请求示例

POST https://rtc.volcengineapi.com?Action=UpdatePublicStreamParam&Version=2020-12-01
{
    "AppId": "You****pId",
    "BusinessId": "Your_****nessId",
    "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_****estId",
        "Action": "UpdatePublicStreamParam",
        "Version": "2020-12-01",
        "Service": "rtc",
        "Region": "cn-north-1"
    }
}

错误码

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

最近更新时间：2025.07.03 20:05:44

这个页面对您有帮助吗？

有用

无用

实时音视频

使用说明 #

接口行为 #

注意事项 #

请求说明 #

调试 #

请求参数 #

Query #

Body #

返回参数 #

请求示例 #

返回示例 #

错误码 #