实时音视频
实时音视频
文档指南
请输入
- 文档首页
实时音视频实时音视频服务端 API 参考WTN 流（原公共流）更新 WTN 流 UpdatePublicStreamParam
复制全文
下载 pdf更新 WTN 流 UpdatePublicStreamParam
文档反馈
问问助手调用 UpdatePublicStreamParam 接口，更新一个已发布的 WTN 流的参数，如调整流布局、包含的媒体流以及编码参数等。
使用说明
接口行为
- Control.MaxIdleTime和 VideoConfig.VideoCodec 无法通过该接口进行更新。
- 对于支持更新的参数，如果在调用 UpdatePublicStreamParam 时，没有传入对应的参数值，那么这些参数将被更新为参数的默认值。
注意事项
请求频率：QPS 不得超过 150。
请求说明
- 请求方式：POST
- 请求地址：https://rtc.volcengineapi.com?Action=UpdatePublicStreamParam&Version=2023-11-01
调试
API Explorer
您可以通过 API Explorer 在线发起调用，无需关注签名生成过程，快速获取调用结果。
请求参数
Query
Action String 必选 示例值：UpdatePublicStreamParam
接口名称。当前 API 的名称为 UpdatePublicStreamParam。
Version String 必选 示例值：2023-11-01
接口版本。当前 API 的版本为 2023-11-01。
Body
AppId String 必选 示例值：66****3cf
BusinessId String 可选 示例值：B****3
PublicStreamId String 必选 示例值：PublicStream1
WTN 流 ID。
TranscodeMode Integer 可选 示例值：0
WTN 流处理模式。支持取值及含义如下：
0：转码。
1：转封装。
当 TranscodeMode=1 时，
- TargetStreams 只能指定一路流，且该路流的 UserId不能为空，需为对应房间用户的 UserId。
- ExcludeStreams 必须为空。
- Encode.VideoConfig 设置不生效。
- Layout 设置不生效。
TargetStreams Object[] 必选 示例值：-
需要发布为 WTN 流的音视频流。最多支持 17 路。
UserId String 可选 示例值：user1
流对应的用户 ID，需全局唯一且不同房间不可重复。为空时，表示房间内所有流媒体流。
StreamType Integer 可选 示例值：0
流类型：
- 0：音视频流
- 1：屏幕流
默认值为 0。
Index Integer 可选 示例值：1
当选择自定义布局模式时，此字段必填。标记同一路 WTN 流中不同的媒体流。
在同一个 TargetStreams 中，Stream.Index 是唯一的。
RoomId String 必选 示例值：Room1
指定流的用户所在的房间 ID。
MediaType Integer 可选 示例值：0
流的媒体类型：
- 0：音视频
- 1：纯音频
- 2：纯视频
默认值为 0。
ExcludeStreams Object[] 可选 示例值：-
不需要发布为 WTN 流中的音视频流（黑名单）。默认为空，最多不得超过 17 路。
UserId String 可选 示例值：user1
流对应的用户 ID，需全局唯一且不同房间不可重复。为空时，表示房间内所有流媒体流。
StreamType Integer 可选 示例值：0
流类型：
- 0：音视频流
- 1：屏幕流
默认值为 0。
Index Integer 可选 示例值：1
当选择自定义布局模式时，此字段必填。标记同一路 WTN 流中不同的媒体流。
在同一个 TargetStreams 中，Stream.Index 是唯一的。
RoomId String 必选 示例值：Room1
指定流的用户所在的房间 ID。
MediaType Integer 可选 示例值：0
流的媒体类型：
- 0：音视频
- 1：纯音频
- 2：纯视频
默认值为 0。
Layout Object 可选 示例值：-
合流布局配置。
VerticalLayout Object 可选 示例值：-
垂直布局配置。
MainStream Object 可选 示例值：-
指定在大窗口中显示的流及相关信息
1. 如果在 TargetStreams 中指定了某用户的音频和视频，但在 MainStream 只指定该用户的音频，则公共流中只包含该用户的音频，大窗口的区域置空。
2. 如果在 TargetStreams 中指定了某用户的视频，但在 MainStream 只指定该用户的音频，则公共流中不包含该用户的音频和视频，大窗口的区域置空。
3. 如果 MainStream 中指定的用户不存在，大窗口的区域置空。
UserId String 可选 示例值：user1
流对应的用户 ID，需全局唯一且不同房间不可重复。为空时，表示房间内所有流媒体流。
StreamType Integer 可选 示例值：0
流类型：
- 0：音视频流
- 1：屏幕流
默认值为 0。
Index Integer 可选 示例值：1
当选择自定义布局模式时，此字段必填。标记同一路 WTN 流中不同的媒体流。
在同一个 TargetStreams 中，Stream.Index 是唯一的。
RoomId String 必选 示例值：Room1
指定流的用户所在的房间 ID。
MediaType Integer 可选 示例值：0
流的媒体类型：
- 0：音视频
- 1：纯音频
- 2：纯视频
默认值为 0。
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
当画面有重叠时，使用此参数设置指定画面的图层顺序，取值范围为 [0, 100]，默认值为 0。0 表示该区域图像位于最下层，100 表示该区域图像位于最上层。
Alpha Float 可选 示例值：1.0
画面的透明度，取值范围为 (0.0, 1.0]，默认值为 1.0。0.0 表示完全透明，1.0 表示完全不透明。
RenderMode Integer 可选 示例值：0
画面的渲染模式。支持取值及含义如下：
- 0：按照指定的宽高直接缩放。如果原始画面宽高比与指定的宽高比不同，就会导致画面变形
- 1：按照显示区域的长宽比裁减视频，然后等比拉伸或缩小视频，占满显示区域。
- 2：按照原始画面的宽高比缩放视频，在显示区域居中显示。如果原始画面宽高比与指定的宽高比不同，就会导致画面有空缺，空缺区域为填充的背景色值。
- 3：按照指定的宽高直接缩放。如果原始画面宽高比与指定的宽高比不同，就会导致画面变形。
默认值为 0。
目前 0 和 3 均为按照指定的宽高直接缩放，但我们推荐你使用 3 以便与客户端实现相同逻辑。
AlternateImage String 可选 示例值：-
占位图片的 URL。
SourceCrop Object 可选 示例值：-
源流剪切功能。公共流功能下， SourceCrop 对 AlternateImage 不生效。
注意
如果你填写了 LocationX、LocationY、WidthProportion和HeightProportion 中的一个或多个参数，SourceCrop 下的其他参数也必须填写。
LocationX Float 可选 示例值：0.1
裁剪后得到的视频帧左上角的横坐标相对裁剪前整体画面的比例，取值的范围为 [0.0, 1.0)。默认值为 0.0。
LocationY Float 可选 示例值：0.1
裁剪后得到的视频帧左上角的纵坐标相对裁剪前整体画面的比例，取值的范围为 [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：补最后一帧，
- 1：补黑帧。
默认值为0。自动布局模式下，该参数不生效。
补帧是指在音视频录制时，视频的帧率通常是固定的。但是，因为网络波动或其他原因，实际帧率可能无法达到预设的帧率。此时，需要补帧以保持视频流畅。补最后一帧意味着补充的视频帧和中断前的最后一帧相同，此时看到的画面可能会有短暂静止；补黑帧意味着补充的视频帧是全黑的。
如果同时配置Alternateimage 和FrameInterpolationMode ，优先使用 Alternateimage 参数。
- 在 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
输出视频帧率。取值范围为 [1,60]，单位为 fps，默认为 15。
Bitrate Integer 可选 示例值：256
最高输出视频码率。取值范围为 [0,10000]，单位为 Kbps，默认值为0，表示自适应码率。
VideoCodec Integer 可选 示例值：0
视频编码协议。支持取值及含义如下：
- 0（默认值）：H.264。
- 5：VP8。 如果选择 VP8 格式，请先联系火山技术支持配置。
Control Object 可选 示例值：-
高级配置。
MaxIdleTime Integer 可选 示例值：180
任务的空闲超时时间，超过此时间后，任务自动终止。取值范围为 [10, 86400]，单位为秒，默认值为 180。只在调用 StartPushPublicStream 时有效。
DataMsg String 可选 示例值：-
插入 WTN 流的自定义信息，可用于随流信息同步，长度不超过 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
房间用户采集状态回调间隔，仅在纯音频时生效。取值范围为 [1000,2147483647]，单位为毫秒，默认值为 2000。
VolumeIndicationInterval Integer 可选 示例值：2000
音量指示的回调间隔。最小值为 100，单位为毫秒，默认值为 2000。
VideoConfig.FrameRate 大于 10 fps 时，回调间隔才能达到 100ms。
StreamPublishStatsInterval Integer 可选 示例值：2000
房间用户发布状态回调间隔，仅在纯音频时生效。取值范围为 [1000,2147483647]，单位为毫秒，默认值为 2000。
返回参数
其中返回值 Result 仅在请求成功时返回 ok，失败时为空。
请求示例
POST https://rtc.volcengineapi.com?Action=UpdatePublicStreamParam&Version=2023-11-01
{
"AppId": "66****3cf",
"BusinessId": "B****3",
"TranscodeMode": 0,
"TargetStreams": [
{
"Index": 0,
"UserId": "user1_3",
"RoomId": "Room1",
"StreamType": 1,
"MediaType": 0
},
{
"Index": 1,
"UserId": "user1_3",
"RoomId": "Room1",
"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": "20230604110420",
"Action": "UpdatePublicStreamParam",
"Version": "2023-11-01",
"Service": "rtc",
"Region": "cn-north-1"
}
}
错误码
最近更新时间：2026.07.18 23:50:57
这个页面对您有帮助吗？
有用
有用
无用
无用