你可以使用此接口查询指定合流转推任务的相关信息。
你可以调用GetPushMixedStreamToCDNTask
接口,指定你所属的AppId
,查询指定 RoomId
下的合流转推任务。
你可以查询由客户端或服务端发起的合流转推任务,但返回的参数结构均为服务端的参数结构。
不支持查询端云一体场景下客户端合流转推任务。
通过此接口仅能查询距今 72 小时内开始的合流转推任务。
在查询前,你必须已经在控制台上开通转推直播服务。
请求频率:QPS 不得超过 60。
下表仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共参数。
参数 | 类型 | 是否必选 | 示例值 | 描述 |
---|---|---|---|---|
Action | String | 是 | GetPushMixedStreamToCDNTask | 接口名称。当前 API 的名称为 GetPushMixedStreamToCDNTask 。 |
Version | String | 是 | 2023-06-01 | 接口版本。当前 API 的版本为 2023-06-01 。 |
AppId | String | 是 | You****pId | 你的音视频应用的唯一标志 |
RoomId | String | 是 | Your_RoomId | 房间的 ID,是房间的唯一标志 |
TaskId | String | 否 | Your_TaskId | 要查询的转推直播任务 ID。通过服务端发起时,该值为调用 OpenAPI 时传入的 TaskId。通过客户端 SDK 发起时,TaskId 是按照 TaskId 和 UserId 均为非必填参数,但是你需要至少填一个参数以保证可以正常发起请求。 |
UserId | String | 否 | Your_UserId | 客户端发起转推任务的用户 ID。 你在客户端发起多个任务,当使用该接口进行查询时:
|
下表仅列出本接口特有的返回参数,公共返回参数请参见返回结构。
参数 | 类型 | 示例值 | 描述 |
---|---|---|---|
PushMixedStreamToCDNTask | Object | 合流转推任务信息 | |
StartTime | Long | 1677237518000 | 任务开始时间戳,Unix 时间,单位为毫秒 |
EndTime | Long | 1677239022000 | 任务结束时间戳,Unix 时间,单位为毫秒。 0 表示任务未结束 |
Status | Long | 3 | 任务状态。
|
StopReason | String | StopByAPI | 任务停止的原因
|
PushStreamState | Integer | 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 编码时生效。取值范围为
|
AudioBitrate | Integer | - | 音频码率。取值范围为 当 当
当
|
AudioSampleRate | Integer | 48000 | 音频采样率。默认值 48000 ,取值为 [32000,44100,48000] ,单位是 Hz。值不合法时,自动调整为默认值。 |
AudioChannels | Integer | 2 | 音频声道数。
|
Layout | Object | - | 房间内多路流合为一路时的布局参数 |
LayoutMode | Integer | 0 | |
MainVideoStream | Object | - | 在垂直布局模式下生效,指定主画面流的属性。垂直布局时,此参数必填。 |
Index | Integer | 0 | 在自定义布局中,使用 Index 对流进行标志。后续在 Layout.regions.StreamIndex 中,你需要使用 Index 指定对应流的布局设置。 |
UserId | String | Your_UserId | 用户Id,表示这个流所属的用户。 |
StreamType | Integer | 0 | 流的类型,值可以取 0 或1 ,默认值为0 。0 表示普通音视频流,1 表示屏幕流。 |
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[] | 在自定义布局模式下,你可以使用 自定义布局模式下,对于
| |
StreamIndex | Integer | 0 | 流的标识。这个标志应和 TargetStreams.StreamList.Stream.Index 对应。 |
LocationX | Integer | 0 | 视频流对应区域左上角的横坐标相对整体画面左上角原点的横向位移,取值的范围为 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 | 画面的渲染模式,值的范围为
|
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 |
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 。值不合法时,自动调整为默认值。假如该路流为音视频流, MediaType 设为1 ,则只混入音频内容。 |
AlternateImageFillMode | Integer | 0 | 画面的渲染模式。
0 。值不合法时,自动调整为默认值。 |
Control | Object | - | 音视频扩展配置。 |
MediaType | Integer | 0 | 流的类型,用于全局控制订阅的流的类型。默认值为 0 ,可以取0 和1 。0 表示音视频,1 表示纯音频,暂不支持纯视频。值不合法时,自动调整为默认值。 |
FrameInterpolationMode | Integer | 0 | 选择补帧模式。默认值为 自动布局模式下,没有补帧的逻辑。 补帧是指在音视频录制或合流转推时,视频的帧率通常是固定的。但是,因为网络波动或其他原因,实际帧率可能无法达到预设的帧率。此时,需要补帧以保持视频流畅。补最后一帧意味着补充的视频帧和中断前的最后一帧相同,此时看到的画面可能会有短暂静止;补黑帧意味着补充的视频帧是全黑的。 使用占位图、补帧和上一帧的关系: 你可以在
|
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 | 转推直播推流模式,用于控制触发推流的时机。取值为
|
SEIConfig | Object | (仅对转推直播有效)SEI 相关配置。 | |
UserConfigExtraInfo | String | - | 设置SEI数据结构中 app_data 参数的值,最大长度为 4096 。此参数支持动态更新。 |
PassthroughRTCSEIMessage | Boolean | true | 是否透传 RTC 流里的 SEI 信息。
true 。 |
VolumeIndicationInterval | Float | 2 | 用户说话音量的回调间隔,单位为秒,取值范围为 [0.5,∞] ,默认值为 2 。仅当用户说话音量发生变化时此回调才会被触发。 |
VolumeIndicationMode | Boolean | false | (仅对转推直播有效)是否开启音量指示模式。
默认值为 VolumeIndicationMode = true 的同时设置 MediaType = 1 ,该流推向 CDN 地址时,服务端会补黑帧。 关于音量指示模式的用法,参看 音量指示模式。 |
TalkVolume | Integer | 30 | 有效说话音量大小。取值范围为 [0,255] ,默认值为0 。 |
AddVolumeValue | Boolean | false | SEI 中是否包含用户说话音量值。
false 。值不合法时自动调整为默认值。 |
SEIContentMode | Integer | 0 | 开启音量指示模式后,非关键帧携带 SEI 包含的信息类型。
|
SEIPayLoadType | Integer | 100 | 设置 SEI 的 Payload Type ,对 服务端合流转推 SEI 和 RTC 透传SEI 均生效。取值为 5 或 100 ,默认为 100 。 |
SEIPayloadUUID | String | 566f6c63656e67696e65525443534549 | 该字段为长度为 32 位的 16 进制字符,每个字符的范围为 仅当 SEIPayloadType = 5 时,服务端合流转推SEI 的 SEIPayloadUUID 为固定值:566f6c63656e67696e65525443534549 ,对应16位字符串 VolcengineRTCSEI 。 |
GET https://rtc.volcengineapi.com?Action=GetPushMixedStreamToCDNTask&Version=2023-06-01&AppId=You****pId&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": 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": "Your_****estId", "Action": "GetPushMixedStreamToCDNTask", "Version": "2023-06-01", "Service": "rtc", "Region": "cn-north-1" } }
您可访问公共错误码,获取更多错误码信息。