You need to enable JavaScript to run this app.
导航
查询合流转推任务状态 GetPushMixedStreamToCDNTask
最近更新时间:2024.06.20 16:22:25首次发布时间:2024.01.03 20:25:17

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

在实时音视频通话场景中,若需查询特定房间下合流转推任务的详细信息,你可以通过调用此接口实现。

通过指定应用标识、房间 ID 及任务 ID,你能够获取任务的当前状态和配置详情,任务的开始与结束时间、状态、停止原因、推流状态等详细信息,以及音视频流的具体配置。此接口适用于查询 72 小时内启动的合流转推任务。

你可以查询由客户端或服务端发起的合流转推任务,但返回的参数结构均为服务端的参数结构。

使用说明

前置条件

在查询前,你必须已经在控制台上开通转推直播服务。

注意事项

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

请求说明

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

调试

请求参数

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

Query

参数
类型
是否必选
示例值
描述
Action
String
GetPushMixedStreamToCDNTask
接口名称。当前 API 的名称为 GetPushMixedStreamToCDNTask
Version
String
2023-11-01
接口版本。当前 API 的版本为 2023-11-01
AppId
String
661e****543cf
你的音视频应用的唯一标志
RoomId
String
Room1
房间的 ID,是房间的唯一标志
TaskId
String
Task1

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

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

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

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

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

返回参数

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

参数
类型
示例值
描述
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
user1
用户 ID,表示这个流所属的用户。
StreamType
Integer
0

流的类型。支持取值及含义如下:

  • 0:普通音视频流,
  • 1:屏幕流。
默认值为0
ExcludeStreams
Object
-
转推任务排除的音视频流
StreamList
Object[]
-
音视频流列表,由Stream组成,可以为空。为空时,表示订阅房间内所有流。在一个 StreamList 中,Stream.Index 不能重复。
Index
Integer
0
在自定义布局中,使用 Index 对流进行标志。后续在 Layout.regions.StreamIndex 中,你需要使用 Index 指定对应流的布局设置。
UserId
String
user1
用户 ID,表示这个流所属的用户。
StreamType
Integer
0

流的类型。支持取值及含义如下:

  • 0:普通音视频流,
  • 1:屏幕流。
默认值为0
PushURL
String
rtmp://xxxxxx
推流 CDN 地址。仅支持 RTMP 协议。
Encode
Object
-
输出的音视频编码参数。
VideoWidth
Integer
640
画面宽度。取值范围为 [2, 1920],必须是偶数,单位为像素,默认值为 640。该参数在垂直布局和并排布局下生效,自定义布局下请使用 canvas.Width 设置画面宽度。
VideoHeight
Integer
480
画面高度,取值范围为 [2, 1920],必须是偶数,单位为像素,默认值为 480。该参数在垂直布局和并排布局下生效,自定义布局下请使用 canvas.Height 设置画面宽度。
VideoFps
Integer
15
视频帧率。取值范围为 [1,60],单位为 FPS,默认值为 15
VideoBitrate
Integer
0
视频码率。取值范围为 [0,10000],单位为 Kbps,默认值为 0
0 表示自适应码率,会自动根据 VideoFps , VideoWidth 以及VideoHeight 计算出合理的码率。
自适应码率模式下,RTC 默认不会设置超高码率。如果订阅屏幕流,建议自行设置高码率。不同场景下设置码率等视频发布参数,请参考设置视频发布参数
VideoCodec
Integer
0

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

  • 0H.264
  • 1ByteVC1
默认值为 0
VideoGop
Integer
4
输出视频 GOP。取值范围为 [1,5],单位为秒,默认值为 4
AudioCodec
Integer
0
音频编码协议。仅支持取 0,表示 AAC 编码协议。
AudioProfile
Integer
0

音频配置文件类型。支持取值及含义如下:

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

音频码率。取值范围为 [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
音频采样率。可取值为:32000,4410048000,单位为 Hz,默认值为 48000
AudioChannels
Integer
2

音频声道数。支持取值及含义如下:

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

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

默认值为0
MainVideoStream
Object
-
在垂直布局模式下生效,指定主画面流的属性。垂直布局时,此参数必填。
Index
Integer
0
在自定义布局中,使用 Index 对流进行标志。后续在 Layout.regions.StreamIndex 中,你需要使用 Index 指定对应流的布局设置。
UserId
String
user1
用户 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
整体屏幕(画布)的背景色, 范围为 #000000 ~ #ffffff (大小写均可),格式为 #RGB(16进制),默认值为 #000000(黑色)。
BackgroundImage
String
-
背景图片的 URL。长度最大为 1024 byte。可以传入的图片的格式包括:JPG, JPEG, PNG
如果背景图片的宽高和整体屏幕的宽高不一致,背景图片会缩放到铺满屏幕。
如果你设置了背景图片,背景图片会覆盖背景色。
Regions
Object[]
-

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

自定义布局模式下,对于 StreamList 中的每个 StreamRegions 中都需要给出对应的布局信息,否则会返回请求不合法的错误。即 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],默认值为 00 表示该区域图像位于最下层,100 表示该区域图像位于最上层。
Alpha
Float
1
画面的透明度,取值范围为 (0.0, 1.0],默认值为 1.00.0 表示完全透明,1.0 表示完全不透明。
RenderMode
Integer
0

画面的渲染模式。支持取值及含义如下:

  • 0 :按照指定的宽高直接缩放。如果原始画面宽高比与指定的宽高比不同,就会导致画面变形
  • 1 :按照显示区域的长宽比裁减视频,然后等比拉伸或缩小视频,占满显示区域。
  • 2 :按照原始画面的宽高比缩放视频,在显示区域居中显示。如果原始画面宽高比与指定的宽高比不同,就会导致画面有空缺,空缺区域为填充的背景色值。
  • 3 :按照指定的宽高直接缩放。如果原始画面宽高比与指定的宽高比不同,就会导致画面变形。
默认值为 0
目前 03 均为按照指定的宽高直接缩放,但我们推荐你使用 3 以便与客户端实现相同逻辑。
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]。默认值为 0,表示没有圆角效果。
圆角半径的像素位不能超过 Region 宽高最小值的一半,否则不会出现圆角效果。
MediaType
Integer
0

该路流参与混流的媒体类型。支持取值及含义如下:

  • 0:音视频
  • 1:纯音频
  • 2:纯视频
默认值为 0
例如该路流为音视频流,MediaType设为1,则只混入音频内容。
AlternateImageFillMode
Integer
0

画面的渲染模式。支持取值及含义如下:

  • 0:按照用户原始视频帧比例进行缩放
  • 1:保持图片原有比例
默认值为 0
Control
Object
-
MediaType
Integer
0

流的类型,用于全局控制订阅的流的类型。支持取值及含义如下:

  • 0 :音视频,
  • 1 :纯音频(当前该值无效)。
默认值为 0
FrameInterpolationMode
Integer
0

选择补帧模式。支持取值及含义如下:

  • 0:补最后一帧。
  • 1:补黑帧

默认值为0
自动布局模式下,没有补帧的逻辑。
补帧是指在音视频录制或合流转推时,视频的帧率通常是固定的。但是,因为网络波动或其他原因,实际帧率可能无法达到预设的帧率。此时,需要补帧以保持视频流畅。补最后一帧意味着补充的视频帧和中断前的最后一帧相同,此时看到的画面可能会有短暂静止;补黑帧意味着补充的视频帧是全黑的。
使用占位图、补帧和上一帧的关系:
你可以在 Region 中传入 Alternateimage 字段设置占位图,在 Control 中传入FrameInterpolationMode 字段设置补帧模式,但占位图优先级高于补帧模式。

  • Region.StreamIndex 对应的视频流停止发布时, Region 对应的画布空间会根据设置填充占位图或补帧。但当视频流为屏幕流时,补帧模式不生效。
  • Region.StreamIndex 对应的视频流发布后停止采集或推送时, Region 对应的画布空间会填充上一帧。
  • Region.StreamIndex 对应的视频流发布时,设置的占位图或补顿模式不造成任何影响。
MaxIdleTime
Integer
180
任务的空闲超时时间,超过此时间后,任务自动终止。取值范围为 [10, 86400],单位为秒,默认值为 180
SpatialConfig
Object
-
空间音频配置。若合流转推的音频参数设置为单声道,空间音频无效。
EnableSpatialRender
Boolean
false

是否开启空间音频处理功能。

  • false:关闭。
  • true:开启
默认值为 false
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:房间内有用户推 RTC 流时即触发 CDN 推流。
  • 1:调用接口发起推流任务后,无论房间内是否有用户推 RTC 流,均可触发 CDN 推流。
默认值为 0
任务超时逻辑不变,依然是无用户推流即判定为超时。
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:只有音量信息和时间戳。
默认值为 0。关于 SEI 结构,参看服务端合流转推 SEI 结构
SEIPayLoadType
Integer
100
设置 SEI 的 Payload Type,对 服务端合流转推 SEI 和 RTC 透传SEI 均生效。支持取值为 5100,默认为 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

请求示例

GET https://rtc.volcengineapi.com?Action=GetPushMixedStreamToCDNTask&Version=2023-11-01&AppId=661e****543cf&RoomId=Room1&TaskId=Task1&UserId=user1

返回示例

{
    "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": 144,
                            "WidthProportion": 640,
                            "HeightProportion": 288,
                            "ZOrder": 0,
                            "Alpha": 1,
                            "CornerRadius": 0,
                            "RenderMode": 0,
                            "SourceCrop": {
                                "LocationX": 430,
                                "LocationY": 340,
                                "WidthProportion": 430,
                                "HeightProportion": 340
                            },
                            "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": "20230****10420",
        "Action": "GetPushMixedStreamToCDNTask",
        "Version": "2023-11-01",
        "Service": "rtc",
        "Region": "cn-north-1"
    }
}

错误码

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