You need to enable JavaScript to run this app.
导航
实时音视频
  • 文档首页
    • /
  • 实时音视频

开始合流转推 StartPushMixedStreamToCDN

最近更新时间：2024.04.15 17:35:12

首次发布时间：2024.01.03 20:25:17

我的收藏

本文档 API 接口为最新版本接口，后续相关功能的新增都会在此更新，推荐使用最新版本接口。旧版接口文档请参考历史版本。

对于一个音视频通话，你可以将其中的多路音视频流合为一路，并将合并得到的音视频流通过 RTMP 协议推送到指定的推流地址（通常是 CDN 地址）。

你可以使用 StartPushMixedStreamToCDN 这个 OpenAPI 实现这一功能。

同一 TaskId 不能同时开启合流转推和单流转推任务。

使用说明

接口行为

你可以调用 StartPushMixedStreamToCDN 接口，将指定音视频房间内的指定音视频流，按照指定的布局合为一路，并推送至指定的地址。

在一个房间内，自定义布局下你最多只能将 30 路流合为一路流，其他布局下你最多只能将 17 路流合为一路流。若超出最大合流数限制，会返回 InvalidParameter 错误。

前置条件

在使用合流转推功能前，你必须已经在控制台上开启转推直播服务。

调用接口

关于调用接口的请求结构、公共参数、签名算法和返回结构，参看调用方法。

注意事项

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

请求说明

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

调试

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

请求参数

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

Query

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

Body

参数
类型
是否必选
示例值
描述
AppId
String
是
Your_AppId
你的音视频应用的唯一标志
BusinessId
String
否
Your_BusinessId
业务标识
RoomId
String
是
Your_RoomId
房间的 ID，是房间的唯一标志
TaskId
String
是
Your_TaskId

合流转推任务 ID。你必须对每个合流转推任务设定 TaskId，且在后续进行任务更新和结束时也须使用该 TaskId。

TaskId 是任务的标识，在一个 AppId 的 RoomId 下 taskId 是唯一的，不同 AppId 或者不同 RoomId 下 TaskId 可以重复，因此 AppId + RoomId + TaskId 是任务的唯一标识，可以用来标识指定 AppId 下某个房间内正在运行的任务，从而能在此任务运行中进行更新或者停止此任务。

关于 TaskId 及以上 Id 字段的命名规则符合正则表达式：[a-zA-Z0-9_@\-\.]{1,128}

若任务运行中，使用相同的 TaskId 重复调用开始接口不会导致请求失败，BaseResponse.Result 会提示 The task has been started. Please do not call the startup task interface repeatedly。
TargetStreams
Object
否
-
你可以通过本参数设定需要转推的音视频流。如果参数为空，默认对房间内所有人进行转推。自定布局下最多 30 路音视频流，其他布局下最多 17 路音视频流。此参数中的 stream 不得和 ExcludeStreams 中重复。
StreamList
Object[]
否
-
音视频流列表，由Stream组成，可以为空。为空时，表示订阅房间内所有流。在一个 StreamList 中，Stream.Index 不能重复。
Index
Integer
否
0
在自定义布局中，使用 Index 对流进行标志。后续在 Layout.regions.StreamIndex 中，你需要使用 Index 指定对应流的布局设置。
UserId
String
是
Your_UserId
用户Id，表示这个流所属的用户。
StreamType
Integer
否
0

流的类型，取值：

  • 0：普通音视频流，
  • 1：屏幕流。
    默认值为0。
ExcludeStreams
Object
否
-
你可以通过本参数设定不需要转推的音视频流，即转推流的黑名单。参数默认为空。黑名单中的流自定布局下最多 30 路音视频流，其他布局下最多 17 路音视频流。不支持将屏幕流添加到黑名单中。此参数中的 stream 不得和 TargetStreams 中重复。
StreamList
Object[]
否
-
音视频流列表，由Stream组成，可以为空。为空时，表示订阅房间内所有流。在一个 StreamList 中，Stream.Index 不能重复。
Index
Integer
否
0
在自定义布局中，使用 Index 对流进行标志。后续在 Layout.regions.StreamIndex 中，你需要使用 Index 指定对应流的布局设置。
UserId
String
是
Your_UserId
用户Id，表示这个流所属的用户。
StreamType
Integer
否
0

流的类型，取值：

  • 0：普通音视频流，
  • 1：屏幕流。
    默认值为0。
PushURL
String
是
rtmp://xxx/xxx
推流 CDN 地址。仅支持 RTMP 协议。
Encode
Object
否
-
音视频编码参数
VideoWidth
Integer
否
640
输出画面的宽度。默认值为640，范围为 [2, 1920]，必须是偶数。自定义布局下此参数不生效，整体画面宽度以 canvas 中的 Width 为主。
VideoHeight
Integer
否
480
输出画面的高度，范围为[2, 1920]，必须是偶数，默认值为480。自定义布局下此参数不生效，画面高度以 canvas 中的 Height 为准。
VideoFps
Integer
否
15
输出视频帧率。默认为 15，单位为 FPS，取值范围为 [1,60]。
VideoBitrate
Integer
否
-
输出视频码率。取值范围 [0,10000]，单位为 Kbps，默认值为 0。
0 表示自适应码率，会自动根据 VideoFps , VideoWidth 以及VideoHeight 计算出合理的码率。
自适应码率模式下，RTC 默认不会设置超高码率。如果订阅屏幕流，建议自行设置高码率。不同场景下设置码率等视频发布参数,请参考设置视频发布参数。
VideoCodec
Integer
否
0
视频编码协议。默认值为 0，可以取 0 或 1。取 0 时使用 H.264,取 1 时使用 ByteVC1 编码器。
VideoGop
Integer
否
4
输出视频 GOP。默认为 4，取值范围为 [1,5]，单位为秒。
AudioCodec
Integer
否
0
音频编码协议。默认值为 0，此时使用 aac 编码协议。目前只支持 aac。
AudioProfile
Integer
否
0

音频配置文件类型，在使用 aac 编码时生效。取值为：

  • 0 :采用 LC 规格；
  • 1: 采用 HE-AAC v1 规格；
  • 2: 采用 HE-AAC v2 规格。取 2 时，只支持输出流音频声道数为双声道。
    默认值为 0。
AudioBitrate
Integer
否
-

音频码率。取值范围为 [32,192],单位为 Kbps，默认值为 64。

当AudioProfile=0时：
若输入参数取值范围为 [32,192]，编码码率等于输入码率。

当AudioProfile=1时：

  • 若输入参数取值范围为 [32,128]，编码码率等于输入码率。
  • 若输入参数取值范围为 [128,192]，编码码率固定为128。

当AudioProfile=2时：

  • 若输入参数取值范围为 [32,64]，编码码率等于输入码率。
  • 若输入参数取值范围为 [64,192]，编码码率固定为64。
AudioSampleRate
Integer
否
48000
音频采样率。默认值 48000，取值为 [32000,44100,48000]，单位是 Hz。
AudioChannels
Integer
否
2

音频声道数。

  • 1：单声道。
  • 2：双声道。
    默认值为 2。
Layout
Object
否
-
房间内多路流合为一路时的布局参数
LayoutMode
Integer
否
0

布局模式。默认值为 0，值的范围为：

MainVideoStream
Object
否
在垂直布局模式下生效，指定主画面流的属性。垂直布局时，此参数必填。
Index
Integer
否
0
在自定义布局中，使用 Index 对流进行标志。后续在 Layout.regions.StreamIndex 中，你需要使用 Index 指定对应流的布局设置。
UserId
String
是
Your_UserId
用户Id，表示这个流所属的用户。
StreamType
Integer
否
0

流的类型，取值：

  • 0：普通音视频流，
  • 1：屏幕流。
    默认值为0。
CustomLayout
Object
否
-
使用自定义布局模式时，使用此参数进行具体设置。
Canvas
Object
否
整体屏幕（画布）的宽高以及背景色。
Width
Integer
否
640
整体屏幕（画布）的宽度，单位为像素，范围为 [2, 1920]，必须是偶数。默认值为 640。
Height
Integer
否
480
整体屏幕（画布）的高度，单位为像素，范围为 [2, 1920]，必须是偶数。默认值为 480。
Background
String
否
#000000
整体屏幕（画布）的背景色，格式为 #RGB(16进制)，默认值为 #000000（黑色）, 范围为 #000000 ~ #ffffff (大小写均可)。
BackgroundImage
String
否
-
背景图片的 URL。长度最大为 1024 byte。可以传入的图片的格式包括：JPG, JPEG, PNG。如果背景图片的宽高和整体屏幕的宽高不一致，背景图片会缩放到铺满屏幕。
如果你设置了背景图片，背景图片会覆盖背景色。
Regions
Object[]
否

在自定义布局模式下，你可以使用 Regions 对每一路视频流进行画面布局设置。其中，每个 Region 对一路视频流进行画面布局设置。

自定义布局模式下，对于 StreamList 中的每个 Stream，Regions 中都需要给出对应的布局信息，否则会返回请求不合法的错误。即 Regions.Region.StreamIndex 要与 TargetStreams.StreamList.Stream.Index 的值一一对应，否则自定义布局设置失败，返回 InvalidParameter 错误码。

当传入的必填参数值不合法时，返回错误码 InvalidParameter 。

StreamIndex
Integer
是
0
流的标识。这个标志应和 TargetStreams.StreamList.Stream.Index 对应。
LocationX
Integer
否
0

视频流对应区域左上角的横坐标相对整体画面左上角原点的横向位移，取值的范围为 [0.0, Canvas.Width)。默认值为 0。若传入该参数，服务端会对该参数进行校验，若不合法会返回错误码 InvalidParameter。

视频流对应区域左上角的实际坐标是通过画面尺寸和相对位置比例相乘，并四舍五入取整得到的。假如，画布尺寸为1920, 视频流对应区域左上角的横坐标相对整体画面的比例为 0.33，那么该画布左上角的横坐标为 634（1920*0.33=633.6，四舍五入取整）。
LocationY
Integer
否
0
视频流对应区域左上角的横坐标相对整体画面左上角原点的纵向位移，取值的范围为 [0.0, Canvas.Height)。默认值为 0。若传入该参数，服务端会对该参数进行校验，若不合法会返回错误码 InvalidParameter。
Width
Integer
是
640
视频流对应区域宽度的像素绝对值，取值的范围为 (0.0, Canvas.Width]。
Height
Integer
是
480
视频流对应区域高度的像素绝对值，取值的范围为 (0.0, Canvas.Height]。
ZOrder
Integer
否
0
当多个流的画面有重叠时，使用此参数设置指定画面的图层顺序。取值范围为 [0, 100]：0 表示该区域图像位于最下层，100 表示该区域图像位于最上层, 默认值为 0。
Alpha
Float
否
1
画面的透明度，取值范围为 (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 以便与客户端实现相同逻辑。
    不同渲染模式下，效果如下：alt

SourceCrop
Object
否
源流剪切功能，可以在源视频帧渲染之前进行裁剪，即预处理一次再渲染。
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。
AlternateImage
String
否
-

补位图片的 url。长度不超过 1024 个字符串。

  • 在 Region.StreamIndex 对应的视频流没有发布，或被暂停采集时，AlternateImage 对应的图片会填充 Region 对应的画布空间。当视频流被采集并发布时，AlternateImage 不造成任何影响。
  • 可以传入的图片的格式包括：JPG, JPEG, PNG。
  • 当图片和画布尺寸不一致时，图片根据 RenderMode 的设置，在画布中进行渲染。
ApplySpatialAudio
Boolean
否
-

该路流对应的用户是否开启空间音频效果。

  • true：开启空间音频效果。
  • false：关闭空间音频效果。
默认值为 true
SpatialPosition
Integer[]
否
[0,0,0]
空间音频下，房间内指定用户所在位置的三维坐标，默认值为[0,0,0]。数组长度为3，三个值依次对应X,Y,Z，每个值的取值范围为[-100,100]。
CornerRadius
Float
否
0.1
转推直播下边框圆角半径与画布宽度的比例值，取值范围为 [0,1]。圆角半径的像素位不能超过 Region 宽高最小值的一半，否则不会出现圆角效果。
MediaType
Integer
否
0

该路流参与混流的媒体类型。

  • 0：音视频
  • 1：纯音频
  • 2：纯视频
默认值为 0。

假如该路流为音视频流，MediaType设为1，则只混入音频内容。
AlternateImageFillMode
Integer
否
0

画面的渲染模式。

  • 0：按照用户原始视频帧比例进行缩放
  • 1：保持图片原有比例
默认值为 0。
Control
Object
否
-
配置选项。
MediaType
Integer
否
0
流的类型，用于全局控制订阅的流的类型。默认值为0，可以取0和1。0表示音视频，1表示纯音频，暂不支持纯视频。
FrameInterpolationMode
Integer
否
0

选择补帧模式。默认值为0，可以取0和1。0为补最后一帧，1为补黑帧。

自动布局模式下，没有补帧的逻辑。

补帧是指在音视频录制或合流转推时，视频的帧率通常是固定的。但是，因为网络波动或其他原因，实际帧率可能无法达到预设的帧率。此时，需要补帧以保持视频流畅。补最后一帧意味着补充的视频帧和中断前的最后一帧相同，此时看到的画面可能会有短暂静止；补黑帧意味着补充的视频帧是全黑的。

使用占位图、补帧和上一帧的关系:

你可以在 Region 中传入 Alternateimage 字段设置占位图,在 Control 中传入FrameInterpolationMode 字段设置补帧模式,但占位图优先级高于补帧模式。

  • 在 Region.StreamIndex 对应的视频流停止发布时, Region 对应的画布空间会根据设置填充占位图或补帧。但当视频流为屏幕流时，补帧模式不生效。
  • 当 Region.StreamIndex 对应的视频流发布后停止采集或推送时, Region 对应的画布空间会填充上一帧。
  • 当 Region.StreamIndex 对应的视频流发布时,设置的占位图或补顿模式不造成任何影响。
MaxIdleTime
Integer
否
180
任务的空闲超时时间，超过此时间后，任务自动终止。单位为秒。取值范围为 [10, 86400], 默认值为 180。
MaxRecordTime
Integer
否
0
（仅对录制有效）最大录制时长，单位为秒。默认值为 0。0 表示不限制录制时长。
SpatialConfig
Object
否
空间音频配置。若合流转推的音频参数设置为单声道，空间音频无效。
EnableSpatialRender
Boolean
否
false
是否开启空间音频处理功能。
  • false：关闭。
  • true：开启
    • AudienceSpatialPosition
    Integer[]
    否
    [0,0,0]
    观众所在位置的三维坐标，默认值为[0,0,0]。数组长度为3，三个值依次对应X,Y,Z，每个值的取值范围为[-100,100]。
    AudienceSpatialOrientation
    Object
    否
    设置观众朝向。各个向量两两垂直，如果传入的值没有保证两两垂直，自动赋予默认值。默认值为：forward = [1, 0, 0], right = [0, 1, 0], up = [0, 0, 1]。
    Up
    Float[]
    否
    [0, 0, 1]
    头顶朝向
    Right
    Float[]
    否
    [0, -1, 0]
    右边朝向
    Forward
    Float[]
    否
    [1, 0, 0]
    前方朝向
    PushStreamMode
    Integer
    否
    0

    转推直播推流模式，用于控制触发推流的时机。取值为0或1。默认值为0。

    • 0：房间内有用户推 RTC 流时即触发 CDN 推流。
    • 1：调用接口发起推流任务后，无论房间内是否有用户推 RTC 流,均可触发 CDN 推流。
    任务超时逻辑不变，依然是无用户推流即判定为超时。
    SEIConfig
    Object
    否
    （仅对转推直播有效）SEI 相关配置。
    UserConfigExtraInfo
    String
    否
    -
    设置SEI数据结构中 app_data 参数的值，最大长度为 4096。此参数支持动态更新。
    PassthroughRTCSEIMessage
    Boolean
    否
    true

    是否透传 RTC 流里的 SEI 信息。

    • true：是。
    • false：否。
    默认值为 true。
    VolumeIndicationInterval
    Float
    否
    2
    用户说话音量的回调间隔，单位为秒，取值范围为[0.3,∞]，默认值为 2。仅当用户说话音量发生变化时此回调才会被触发。
    VolumeIndicationMode
    Boolean
    否
    false

    (仅对转推直播有效）是否开启音量指示模式。

    • true：是。此时非关键帧中也可能携带 SEI 信息。
    • false：否。此时只会在关键帧中携带 SEI 信息。

    默认值为 false。

    若 VolumeIndicationMode = true 的同时设置 MediaType = 1，该流推向 CDN 地址时，服务端会补黑帧。 关于音量指示模式的用法，参看 音量指示模式。
    AddVolumeValue
    Boolean
    否
    false

    SEI 中是否包含用户说话音量值。

    • false：否。
    • true：是。
    默认值为 false。
    SEIContentMode
    Integer
    否
    0

    开启音量指示模式后，非关键帧携带 SEI 包含的信息类型。

    • 0：全量信息。
    • 1：只有音量信息和时间戳。
    关于 SEI 结构，参看服务端合流转推 SEI 结构
    SEIPayLoadType
    Integer
    否
    100
    设置 SEI 的 Payload Type，对 服务端合流转推 SEI 和 RTC 透传SEI 均生效。取值为 5 或 100，默认为 100。
    SEIPayloadUUID
    String
    否
    566f6c63656e67696e65525443534549

    该字段为长度为 32 位的 16 进制字符，每个字符的范围为 a-f，A-F，0-9，不可包含 -。如果校验失败，会返回错误码 InvalidParameter。

    仅当 SEIPayLoadType=5时，该字段需要填写，SEIPayLoadType=100时，该字段内容会被忽略。

    此参数仅对 RTC 透传SEI 生效。当用户设置 SEIPayloadType = 5 时，服务端合流转推SEI 的 SEIPayloadUUID 为固定值：566f6c63656e67696e65525443534549，对应16位字符串 VolcengineRTCSEI。

    返回参数

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

    请求示例

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

{
    "AppId" : "Your_AppId",
    "BusinessId" : "Your_BusinessId",
    "RoomId" : "Your_RoomId",   
    "TaskId": "Your_TaskId",
    "PushURL": "rtmp://xxx/xxx"
}

    返回示例

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

    错误码

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