调用 StartPushPublicStream 接口，将 RTC 房间内的一路或多路（最多17路）音视频流发布为一个 WTN 流，供房间外的用户订阅。支持单流转封装或多流合流转码两种模式。

使用说明

监听回调：如果媒体流状态发生变化，你在控制台设置的回调地址，接收每个状态变化的回调。回调结果说明，参见 PushPublicStream。

你还可以通过客户端发布 WTN 流，详见 WTN 流的发布和订阅。

注意事项

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

请求说明

请求方式：POST

请求地址：https://rtc.volcengineapi.com?Action=StartPushPublicStream&Version=2023-11-01

调试

API Explorer

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

去调试

请求参数

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

Query

Action String 必选示例值：StartPushPublicStream

接口名称。当前 API 的名称为 StartPushPublicStream。

Version String 必选示例值：2023-11-01

接口版本。当前 API 的版本为 2023-11-01。

Body

AppId String 必选示例值：66****3cf

实时音视频应用的 AppId。可在控制台获取。

BusinessId String 可选示例值：Bus****ss1

业务标识 ID，用于区分不同业务。可在控制台获取。

PublicStreamId String 必选示例值：PublicStream1

自定义 WTN 流 ID，用于标识。命名规则符合正则表达式：[a-zA-Z0-9_@\-\.]{1,64}。

TranscodeMode Integer 可选示例值：0

WTN 流处理模式。支持取值及含义如下：

0（默认值）：转码。对多路流进行编码合流处理。

1：转封装。直接将单路流封装为 WTN 流，需满足以下要求：

TargetStreams 只能指定一路流，且该路流的 UserId 必须为房间内真实用户 ID。

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[] 可选示例值：-

不需要包含在公共流中的音视频流，即黑名单。参数默认为空。黑名单中的流不得超过 17 路。此参数中的 stream 不应和 TargetStreams 中重复。

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。

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，0表示自适应码率。

VideoCodec Integer 可选示例值：0

视频编码协议。支持取值及含义如下：

0：H.264。

5：VP8。如果选择 VP8 格式，请先联系火山技术支持配置。

默认值为0。

Layout Object 可选示例值：-

公共流包含多路媒体流时的布局参数。

LayoutMode Integer 必选示例值：0

布局模式。支持取值及含义如下：

0：自适应布局

1：垂直布局

2：自定义布局

3 ：并排布局

默认值为 0。

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。如果背景图片的宽高和整体屏幕的宽高不一致，背景图片会缩放到铺满屏幕。

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

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，失败时为空。

请求示例

返回示例

错误码

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