You need to enable JavaScript to run this app.
导航
实时音视频
  • 文档首页
    • /实时音视频/服务端 OpenAPI 参考/历史版本/公共流/2020-12-01/发布公共流 StartPushPublicStream
发布公共流 StartPushPublicStream
最近更新时间：2024.08.02 11:10:45首次发布时间：2022.05.20 20:23:14
我的收藏

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

使用说明

接口行为

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

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

注意事项

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

请求说明

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

调试

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

请求参数

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

Query

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

Body

参数
类型
是否必选
示例值
描述
AppId
String
是
You****pId
你的音视频应用的唯一标志
BusinessId
String
否
Your_B****nessId
你创建的业务标识
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
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：纯视频
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 格式，请先联系火山技术支持配置。
Layout
Object
否
-
公共流包含多路媒体流时的布局参数。
LayoutMode
Integer
是
0

布局模式。默认值为 0，值的范围为 {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。如果背景图片的宽高和整体屏幕的宽高不一致，背景图片会缩放到铺满屏幕。

如果你设置了背景图片，背景图片会覆盖背景色。
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=StartPushPublicStream&Version=2020-12-01
{
    "AppId": "You****pId",
    "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
                }
            ]
        }
    }
}

返回示例

{
    "Result": "ok",
    "ResponseMetadata": {
        "RequestId": "Your_****estId",
        "Action": "StartPushPublicStream",
        "Version": "2020-12-01",
        "Service": "rtc",
        "Region": "cn-north-1"
    }
}

错误码

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