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

查询合流转推任务状态 GetPushMixedStreamToCDNTask

最近更新时间：2024.03.20 14:50:10

首次发布时间：2023.03.30 09:38:17

我的收藏

你可以使用此接口查询指定合流转推任务的相关信息。

使用说明

接口行为

你可以调用GetPushMixedStreamToCDNTask接口，指定你所属的AppId，查询指定 RoomId 下的合流转推任务。
你可以查询由客户端或服务端发起的合流转推任务，但返回的参数结构均为服务端的参数结构。
不支持查询端云一体场景下客户端合流转推任务。
通过此接口仅能查询距今 72 小时内开始的合流转推任务。
在查询前，你必须已经在控制台上开通转推直播服务。

调用接口

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

注意事项

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

请求说明

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

请求参数

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

Query

参数名称
数据类型
是否必选
示例值
描述
Action
String
是
GetPushMixedStreamToCDNTask
接口名称。当前 API 的名称为 GetPushMixedStreamToCDNTask。
Version
String
是
2020-12-01
接口版本。当前 API 的版本为 2020-12-01。
AppId
String
是
Your_AppId
你的音视频应用的唯一标志
RoomId
String
是
Your_RoomId
房间的 ID，是房间的唯一标志
TaskId
String
否
Your_TaskId

要查询的转推直播任务 ID。通过服务端发起时，该值为调用 OpenAPI 时传入的 TaskId。通过客户端 SDK 发起时，TaskId 是按照 userId@@taskId 格式拼接而成的字符串；当传入的 taskId 为空时，这里的 TaskId 为 userId。

TaskId 和 UserId 均为非必填参数，但是你需要至少填一个参数以保证可以正常发起请求。
UserId
String
否
Your_UserId

客户端发起转推任务的用户 ID。

你在客户端发起多个任务，当使用该接口进行查询时：

  • 查询第一个任务时，UserId 可以传入发起转推任务的用户 UserId，TaskId 传入空字符串；或直接将该用户的 UserId 传入 TaskId。
  • 查询第二个以上任务时，UserId 和 TaskId 为发起转推任务的用户 UserId 和 TaskId。

返回参数

下表仅列出本接口特有的返回参数，公共返回参数请参见返回结构。

参数
类型
示例值
描述
PushMixedStreamToCDNTask
Object
-
合流转推任务信息
StartTime
Long
1677237518000
任务开始时间戳，Unix 时间，单位为毫秒
EndTime
Long
1677239022000
任务结束时间戳，Unix 时间，单位为毫秒。0 表示任务未结束
Status
Long
3

任务状态。

  • 0：未知异常状态
  • 1：未开始
  • 2： 运行中
  • 3： 已结束
  • 4： 任务运行失败
StopReason
String
StopByAPI

任务停止的原因

  • 返回为空：表示任务未结束
  • UnknownStopReason：未知停止原因
  • StopByAPI：用户主动调用 服务端 OpenAPI 停止
  • StartTaskFailed：任务启动失败
  • IdleTimeOut：任务超过最大空闲时间
  • UserDisconnect：客户端用户主动退房/调用停止转推接口
PushStreamState
Integer
6

推流状态

  • 0：运行中，未获取到任务状态，建议稍后重新查询
  • 1：未开始推流
  • 2：首次连接 CDN 服务
  • 3：正在重连 CDN 服务
  • 4：连接 CDN 服务成功，正在尝试推流。
  • 5：连接 CDN 服务成功，推流成功
  • 6：已停止推流。
仅当Status=2 时，PushStreamState 有实际意义；当Status=3 时，PushStreamState=6; status 为其他值时，PushStreamState 均为0。
TargetStreams
Object
-
转推任务包含的音视频流
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。0表示普通音视频流，1表示屏幕流。
ExcludeStreams
Object
-
转推任务排除的音视频流
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。0表示普通音视频流，1表示屏幕流。
PushURL
String
rtmp://xxxxxx
推流 CDN 地址。仅支持 RTMP 协议。
Encode
Object
输出的音视频编码参数。
VideoWidth
Integer
640
输出画面的宽度。默认值为640，范围为 [2, 1920]，必须是偶数。值不合法时，自动调整为默认值。自定义布局下此参数不生效，整体画面宽度以 canvas 中的 Width 为主。
VideoHeight
Integer
480
输出画面的高度，范围为[2, 1920]，必须是偶数，默认值为480。值不合法时，自动调整为默认值。自定义布局下此参数不生效，整体画面高度以 canvas 中的 Height 为主。
VideoFps
Integer
15
输出视频帧率。默认为 15，取值范围为 [1,60]。值不合法时，自动调整为默认值。
VideoBitrate
Integer
-
输出视频码率。取值范围 [1,10000]，单位为 Kbps，默认值为自适应。值不合法时，自动调整为默认值。
自适应码率模式下，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, 1, 2}。- 0 :采用 LC 规格；

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

音频码率。取值范围为 [32,192],单位为 Kbps，默认值为 64，值不合法时，自动调整为默认值。
当AudioProfile=0时：
若输入参数取值范围为 [32,192]，编码码率等于输入码率。

当AudioProfile=1且 AudioChannels = 1 时：

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

当AudioProfile=1且 AudioChannels = 2 时：

  • 若输入参数取值范围为 [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，值的范围为 {0, 1, 2, 3}。

MainVideoStream
Object
-
在垂直布局模式下生效，指定主画面流的属性。垂直布局时，MainVideoStream 和 MainVideoStreamIndex 必须填写其中一个。
Index
Integer
0
在自定义布局中，使用 Index 对流进行标志。后续在 Layout.regions.StreamIndex 中，你需要使用 Index 指定对应流的布局设置。
UserId
String
Your_UserId
用户Id，表示这个流所属的用户。
StreamType
Integer
0
流的类型，值可以取0或1，默认值为0。0表示普通音视频流，1表示屏幕流。
MainVideoStreamIndex
Integer
-
在垂直布局模式下生效，指定主画面流的属性。如果此参数为空，则主画面为随机的一路流。该参数已废弃，当前版本 MainVideoStreamIndex 依然可用，但我们强烈建议你使用 MainVideoStream 参数。如果你同时指定了 MainVideoStream 和 MainVideoStreamIndex 的值，此时只有 MainVideoStream 生效。
CustomLayout
Object
-
使用自定义布局模式时，使用此参数进行具体设置。
Canvas
Object
-
整体屏幕（画布）的宽高以及背景色。
Width
Integer
640
整体屏幕（画布）的宽度，单位为像素，范围为 [2, 1920]，必须是偶数。默认值为 640。值不合法时，自动调整为默认值。
Height
Integer
480
整体屏幕（画布）的高度，单位为像素，范围为 [2, 1920]，必须是偶数。默认值为 480。值不合法时，自动调整为默认值。
Background
String
#000000
整体屏幕（画布）的背景色，用十六进制颜色码（HEX）表示。例如，#FFFFFF 表示纯白，#000000 表示纯黑。默认值为 #000000。值不合法时，自动调整为默认值。
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
Float
0

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

视频流对应区域左上角的实际坐标是通过画面尺寸和相对位置比例相乘，并四舍五入取整得到的。假如，画布尺寸为1920, 视频流对应区域左上角的横坐标相对整体画面的比例为 0.33，那么该画布左上角的横坐标为 634（1920*0.33=633.6，四舍五入取整）。
LocationY
Float
0
视频流对应区域左上角的横坐标相对整体画面左上角原点的纵向位移，取值的范围为 [0.0, Canvas.Height)。默认值为 0。若传入该参数，服务端会对该参数进行校验，若不合法会返回错误码 InvalidParameter。
WidthProportion
Float
0.5
视频流对应区域宽度相对整体画面的比例，取值的范围为 (0.0, 1.0]。
HeightProportion
Float
0.5
视频流对应区域高度相对整体画面的比例，取值的范围为 (0.0, 1.0]。
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
-
源流剪切功能，可以在源视频帧渲染之前进行裁剪，即预处理一次再渲染。转推直播和云端录制下， SourceCrop 对 AlternateImage 也生效。
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 表示不限制录制时长。
VolumeIndicationInterval
Integer
2
(仅对转推直播有效）用户说话音量的回调间隔，单位为秒，取值范围为[1,∞]，默认值为 2。
VolumeIndicationMode
Boolean
false
(仅对转推直播有效）是否开启音量指示模式。默认值为 false。

若 VolumeIndicationMode = true 的同时设置 MediaType = 1，该流推向 CDN 地址时，服务端会补黑帧。
TalkVolume
Integer
30
(仅对转推直播有效）有效说话音量大小。取值范围为[0,255]，默认值为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[]
[1, 0, 0]
前方朝向
Right
Float[]
[0, -1, 0]
右边朝向
Forward
Float[]
[0, 0, 1]
头顶朝向
PushStreamMode
Integer
0

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

  • 0：房间内有用户推 RTC 流时即触发 CDN 推流。
  • 1：调用接口发起推流任务后，无论房间内是否有用户推 RTC 流,均可触发 CDN 推流。
    值不合法时，自动调整为默认值。

    任务超时逻辑不变，依然是无用户推流即判定为超时。

请求示例

GET https://rtc.volcengineapi.com?Action=GetPushMixedStreamToCDNTask&Version=2020-12-01&AppId=Your_AppId&RoomId=Your_RoomId&TaskId=Your_TaskId&UserId=Your_UserId

返回示例

{
    "Result": {
        "PushMixedStreamToCDNTask": {
            "StartTime": 1677237518000,
            "EndTime": 1677239022000,
            "Status": 3,
            "StopReason": "StopByAPI",
            "PushStreamState": "6",
            "TargetStreams": {
                "StreamList": [
                    {
                        "Index": 1,
                        "UserId": "user1",
                        "StreamType": 0
                    }
                ]
            },
            "ExcludeStreams": {
                "StreamList": [
                    {
                        "Index": 3,
                        "UserId": "user3",
                        "StreamType": 1
                    }
                ]
            },
            "PushURL": "rtmp://xxxxxx",
            "Layout": {
                "LayoutMode": 2,
                "CustomLayout": {
                    "Canvas": {
                        "Width": 1280,
                        "Height": 720,
                        "Background": "#303342",
                        "BackgroundImage": "http://xxxxxx"
                    },
                    "Regions": [
                        {
                            "StreamIndex": 1,
                            "LocationX": 0,
                            "LocationY": 0.2,
                            "WidthProportion": 0.5,
                            "HeightProportion": 0.4,
                            "ZOrder": 0,
                            "Alpha": 1,
                            "CornerRadius": 0,
                            "RenderMode": 0,
                            "SourceCrop": {
                                "LocationX": 0.5,
                                "LocationY": 0.5,
                                "WidthProportion": 0.4,
                                "HeightProportion": 0.4
                            },
                            "AlternateImage": "http://xxxxx",
                            "SpatialPosition": [
                                1,
                                1,
                                1
                            ]
                        }
                    ]
                }
            },
            "Encode": {
                "VideoCodec": 0,
                "VideoBitrate": 1600,
                "VideoWidth": 1280,
                "VideoHeight": 720,
                "VideoFps": 15,
                "VideoGop": 4,
                "AudioCodec": 0,
                "AudioProfile": 0,
                "AudioBitrate": 128,
                "AudioSampleRate": 48000,
                "AudioChannels": 2
            },
            "Control": {
                "MediaType": 0,
                "FrameInterpolationMode": 0,
                "MaxIdleTime": 180,
                "VolumeIndicationInterval": 2,
                "VolumeIndicationMode": false,
                "TalkVolume": 0,
                "SpatialConfig": {
                    "AudienceSpatialPosition": [
                        0,
                        0,
                        0
                    ]
                },
                "PushStreamMode": 0
            }
        }
    },
    "ResponseMetadata": {
        "RequestId": "Your_RequestId",
        "Action": "GetPushMixedStreamToCDNTask",
        "Version": "2020-12-01",
        "Service": "rtc",
        "Region": "cn-north-1"
    }
}

错误码

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