公共流指的是用户不需要进房，也可以订阅和接收的音视频流。在音视频通话中，用户通常需要进入房间才能订阅和接收媒体流。你可以使用 StartPushPublicStream 这个 OpenAPI 实现这一功能。
你还可以通过客户端发布公共流，详见公共流的发布和订阅。

使用说明

接口行为

你可以调用 StartPushPublicStream 接口，将指定音视频房间内的单路或多路音视频流，使用指定的布局方式，进行发布。

在一路公共流中，最多只能包含 17 路流。

调用接口

关于调用接口的服务地址、通信协议、字符编码和签名机制，参看调用 OpenAPI。

注意事项

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

请求说明

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

请求参数

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

Query

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

Body

参数	类型	是否必选	示例值	描述
AppId	String	是	`Your_AppId`	你的音视频应用的唯一标志
BusinessId	String	否	`Your_BussinessId`	你创建的业务标识
PublicStreamId	String	是	`Your_PublicStreamId`	公共流 ID。你必须对每路公共流，设定 PublicStreamId 时命名规则符合正则表达式：`[a-zA-Z0-9_@\-\.]{1,128}`
TranscodeMode	Integer	否	`0`	公共流处理模式。 `0`：转码。 `1`：转封装。当 `TranscodeMode`=`1` 时， `TargetStreams` 只能指定一路流，且该路流的 `UserId`不能为空，需为对应房间用户的 `UserId`。 `ExcludeStreams` 必须为空。 `Encode.VideoConfig` 设置不生效。 `Layout` 设置不生效。
TargetStreams	Array of PublicStream	是	`-`	为公共流指定单路或多路媒体流及对应参数，Stream 数组。最高支持 17 路。
ExcludeStreams	Array of PublicStream	否	`-`	你可以通过本参数排除掉不需要包含在公共流中的音视频流，即黑名单。参数默认为空。黑名单中的流不得超过 17 路。此参数中的 `stream` 不应和 `TargetStreams` 中重复。
Encode	Object of PublicEncode	否	`-`	媒体编码参数
Layout	Object of PublicLayout	否	`-`	公共流包含多路媒体流时的布局参数。
Control	Object of PublicControl	否	`-`	控制选项。

PublicStream

参数	类型	是否必选	示例值	描述
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	String	否	`0`	流的媒体类型。默认值为 `0` 。 `0`：音视频 `1`：纯音频 `2`：纯视频

PublicEncode

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

PublicLayout

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

参数	类型	是否必选	示例值	描述
LayoutMode	Integer	是	`0`	布局模式。默认值为 `0`，值的范围为 `{0, 1, 2, 3}`。 `0` 为自适应布局模式。参看自适应布局。 `1` 为垂直布局模式。参看垂直布局。 `2` 为自定义布局模式。 `3` 为并排布局模式。参看并排布局
VerticalLayout	Object of VerticalLayout	否		垂直布局参数
CustomLayout	Object of PublicCustomLayout	否		自定义布局参数

LayoutMode

Integer

是

0

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

0 为自适应布局模式。参看自适应布局。
1 为垂直布局模式。参看垂直布局。
2 为自定义布局模式。
3 为并排布局模式。参看并排布局

VerticalLayout Object of VerticalLayout 否垂直布局参数

CustomLayout Object of PublicCustomLayout 否自定义布局参数

PublicControl

参数	类型	是否必选	示例值	描述
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]`。

VideoConfig

参数	类型	是否必选	示例值	描述
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` 格式，请先联系火山技术支持配置。

VerticalLayout

参数	类型	是否必选	示例值	描述
MainStream	Object of PublicStream	否		指定在大窗口中显示的流及相关信息 1. 如果在 TargetStreams 中指定了某用户的音频和视频，但在MainStream 只指定该用户的音频，则公共流中只包含该用户的音频，大窗口的区域置空。 2. 如果在 TargetStreams 中指定了某用户的视频，但在MainStream只指定该用户的音频，则公共流中不包含该用户的音频和视频，大窗口的区域置空。 3. 如果 MainStream 中指定的用户不存在，大窗口的区域置空。

PublicCustomLayout

参数	类型	是否必选	示例值	描述
Regions	Array of PublicCustomRegion	是		自定义布局下，多路视频配置
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`。如果背景图片的宽高和整体屏幕的宽高不一致，背景图片会缩放到铺满屏幕。如果你设置了背景图片，背景图片会覆盖背景色。

PublicCustomRegion

参数	类型	是否必选	示例值	描述
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	Float	否	`0`	当画面有重叠时，使用此参数设置指定画面的图层顺序，取值范围为 `[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 of SourceCrop	否		源流剪切功能。公共流功能下， `SourceCrop` 对 `AlternateImage` 不生效。注意如果你填写了 `LocationX`、`LocationY`、`WidthProportion`和`HeightProportion` 中的一个或多个参数，`SourceCrop` 下的其他参数也必须填写。

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`。

返回参数

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

请求示例

POST https://rtc.volcengineapi.com?Action=StartPushPublicStream&Version=2023-11-01

{
    "AppId": "Your_AppId",
    "PublicStreamId": "Your_PublicStreamId",
    "TargetStreams": [
        {
            "Index": 1,
            "RoomId": "Your_RoomId",
            "UserId": "a",
            "MediaType": 0,
            "StreamType": 0
        },
        {
            "Index": 2,
            "RoomId": "Your_RoomId",
            "UserId": "b",
            "MediaType": 0,
            "StreamType": 0
        },
        {
            "Index": 3,
            "RoomId": "Your_RoomId",
            "UserId": "c",
            "MediaType": 0,
            "StreamType": 0
        },
        {
            "Index": 4,
            "RoomId": "Your_RoomId",
            "UserId": "d",
            "MediaType": 0,
            "StreamType": 0
        }
    ],
    "Control": {
        "MaxIdleTime": 180
    },
    "Encode": {
        "VideoConfig": {
            "Width": 414,
            "Height": 736,
            "FrameRate": 30
        }
    },
    "Layout": {
        "LayoutMode": 2,
        "CustomLayout": {
            "Regions": [
                {
                    "StreamIndex": 1,
                    "WidthProportion": 0.503,
                    "HeightProportion": 0.335,
                    "LocationX": 0,
                    "LocationY": 0,
                    "RenderMode": 1
                },
                {
                    "StreamIndex": 2,
                    "WidthProportion": 0.503,
                    "HeightProportion": 0.335,
                    "LocationX": 0,
                    "LocationY": 0.33333334,
                    "RenderMode": 1
                },
                {
                    "StreamIndex": 3,
                    "WidthProportion": 0.503,
                    "HeightProportion": 0.335,
                    "LocationX": 0,
                    "LocationY": 0.66666667,
                    "RenderMode": 1
                },
                {
                    "StreamIndex": 4,
                    "WidthProportion": 0.503,
                    "HeightProportion": 0.335,
                    "LocationX": 0.5,
                    "LocationY": 0,
                    "RenderMode": 1
                }
            ]
        }
    }
}
json

返回示例

{
    "Result": "ok",
    "ResponseMetadata": {
        "RequestId": "Your_RequestId",
        "Action": "StartPushPublicStream",
        "Version": "2023-11-01",
        "Service": "rtc",
        "Region": "cn-north-1"
    }
}
json

错误码

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