全部产品
Search
文档中心

视频直播:StartLiveMPUTask - 创建混流转推任务(新)

更新时间:Nov 15, 2024

创建混流转推任务。

接口说明

单个应用 ID 默认支持单路转推任务上限为 200 个,混流转码转推任务上限为 40。如果您需要提升配额,请提交工单

混流任务生命周期

启动

  • 主播首次开播,可以调用 StartLiveMPUTask 启动旁路。

    • 若无用户入会,会返回 channel 不存在错误。
    • 用户开始推流时才会输出旁路流。若单路任务用户未推流,则旁路流无法播放。
    • 混流任务需保证至少有一个用户有推流,旁路流才可播放。未推流的用户对应的布局画面会展示黑屏。
  • 客户业务服务器建议记录旁路任务状态、任务类型、任务参数。

    • 任务状态:启动、停止。
    • 任务类型:单路、混流。
    • 任务参数:即最新的入参,例如:调用 UpdateLiveMPUTask 成功后,记录最新任务参数。
  • 在连麦或者 PK 场景下,此时任务已经被更新为混流。若当前主播异常退出重新入会后,客户业务服务器可以根据保存的最新的任务类型和任务参数,直接调用 StartLiveMPUTask 启动混流任务。

    • 如果启动前任务未被系统自动清理,则直接启动成功。
    • 如果任务还未被系统自动清理,则会返回任务已存在错误码。

结束

  • 主播离会,需要主动调用 StopLiveMPUTask 停止旁路任务。
  • 若任务所指定的所有用户均已离会但未主动调用 StopLiveMPUTask,系统会在 2 分钟后对旁路任务进行停止。

QPS 限制

本接口的单用户 QPS 限制为 500 次/秒。超过限制,API 调用会被限流,这可能会影响您的业务,请合理调用。

调试

您可以在OpenAPI Explorer中直接运行该接口,免去您计算签名的困扰。运行成功后,OpenAPI Explorer可以自动生成SDK代码示例。

授权信息

下表是API对应的授权信息,可以在RAM权限策略语句的Action元素中使用,用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下:

  • 操作:是指具体的权限点。
  • 访问级别:是指每个操作的访问级别,取值为写入(Write)、读取(Read)或列出(List)。
  • 资源类型:是指操作中支持授权的资源类型。具体说明如下:
    • 对于必选的资源类型,用背景高亮的方式表示。
    • 对于不支持资源级授权的操作,用全部资源表示。
  • 条件关键字:是指云产品自身定义的条件关键字。
  • 关联操作:是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限,操作才能成功。
操作访问级别资源类型条件关键字关联操作
live:StartLiveMPUTaskcreate
*全部资源
*

请求参数

名称类型必填描述示例值
AppIdstring

应用 ID,仅支持传单个 ID。由大小写字母、数字、下划线、短划线(-)组成,最大 64 字符。

yourAppId
ChannelIdstring

频道 ID,仅支持传单个 ID。由大小写字母、数字、下划线、短划线(-)组成,最大 64 字符。

yourChannelId
TaskIdstring

任务 ID,仅支持传单个 ID。由大小写字母、数字、下划线、短划线(-)组成,最大 55 字符。此 ID 为旁路转推的标识,需保证唯一。

yourTaskId
MixModestring

混流模式。取值:

  • 0:单路转推,不混流转码,仅转推原始单路流,无需配置混流转码参数。
  • 1(默认值):混流转码转推。
0
StreamURLstring

直播推流地址,仅支持 RTMP 协议,仅支持传单个地址,最大长度不超过 2048 个字符。生成规则请参见推流地址和播放地址

说明
  • 对已开防盗链鉴权的域名,需要在推流地址中包含鉴权串。
    • 禁止同一个 StreamURL 在不同任务中同时使用。
    • 任务停止 10S 之内,禁止使用同一个 StreamURL。
    rtmp://example.com/live/stream
    MultiStreamURLarray<object>

    多地址转推参数,可填写多个直播推流地址。

    说明 在设置任务的转推地址时,StreamURL 参数与 MultiStreamURL 参数,只能配置其中一个参数,且必须配置其中一个参数。
    object
    URLstring

    直播推流地址,仅支持 RTMP 协议,最大长度不超过 2048 个字符。生成规则请参见推流地址和播放地址

    rtmp://example.com/live/stream****
    IsAliCdnboolean

    是否转推到阿里云 CDN。

    • false 为转推非阿里云 CDN。
    • true 为转推阿里云 CDN。
    说明 该参数默认为 false。
    false
    Regionstring

    请求的混流服务所在区域。取值:

    • CN-Shanghai:上海。
    • AP-Singapore(默认值):新加坡。
    • EMAA-Saudi:沙特。
    CN-Shanghai
    MaxIdleTimestring

    空闲超时时间;单位为秒,取值范围为[10,86400]。

    说明 设置此参数后,会在任务处于空闲状态的时长大于 MaxIdleTime 时,自动停止该任务;若不设置此参数,则会在房间关闭后,立刻停止该任务。
    10
    SingleSubParamsobject

    单流转推参数,单流转推(MixMode=0)时必填。需要混流转码时不填。

    SourceTypestring

    单流转推模式下视频输入流类型,仅针对视频流(StreamType=2)有效。取值:

    • camera(默认值):摄像头。
    • shareScreen:屏幕共享。
    camera
    StreamTypestring

    单流转推模式下转推流类型。取值:

    • 0(默认值):转推原始流。
    • 1:仅转推音频流。
    • 2:仅转推视频流。
    0
    UserIdstring

    单流转推的用户 ID,一次只能转推一路流。

    yourSubUserId
    TranscodeParamsobject

    混流转码转推参数,混流转码转推(MixMode=1)时必填。需要单流转推时不填。

    Backgroundobject

    混流全局背景图。

    RenderModestring

    子画面输出时的显示模式:

    • 0:缩放并显示黑底。
    • 1(默认):裁剪。
    1
    URLstring

    全局背景图 URL,最大长度不超过 2048 个字符。

    yourImageUrl
    EncodeParamsobject

    转推输出的编码参数。

    AudioOnlystring

    是否为纯音频,取值:

    • true:纯音频,仅需要设置音频相关参数。
    • false(默认值):非纯音频,除 VideoCodec 参数与 EnhancedParam 参数外,其它参数均不能为空。
    false
    AudioBitratestring

    音频码率,取值范围:[8, 500],单位:kbps。

    128
    AudioChannelsstring

    音频声道数,取值:1、2。

    2
    AudioSampleRatestring

    音频采样率,取值:8000、16000、32000、44100、48000,单位:Hz。

    44100
    VideoCodecstring

    视频编码格式。取值:

    • H.264(默认值)。
    • H.265。
    H.264
    VideoBitratestring

    视频码率,取值范围:[1, 10000],单位:kbps。

    3500
    VideoFrameratestring

    视频帧率,取值范围:[1, 60],单位:fps。

    25
    VideoGopstring

    视频 GOP,取值范围:[1, 60]。

    20
    VideoHeightstring

    视频高,取值范围:[0, 1920],单位:px。

    1000
    VideoWidthstring

    视频宽,取值范围:[0, 1920],单位:px。

    1920
    EnhancedParamstring

    编码增强参数,JSON 字符串,目前支持的可选配置包括 profile 与 preset。

    • profile:编码级别。当视频编码格式为 H.264 时,profile 支持的可选值包括:"baseline", "main", "high";当视频编码格式为 H.265 时,profile 支持的可选值包括:"main"。

    • preset:调节编码速度和质量的平衡。preset 支持的可选值包括:"ultrafast", "superfast", "veryfast", "faster", "fast", "medium", "slow", "slower", "veryslow" "placebo"。每个值代表了一种编码速度与输出视频质量的策略,从"ultrafast"(极快,编码速度优先)到"placebo"(追求极致质量,编码极慢)。

    说明 例如设置 superfast,主要用于实时通讯领域。建议非编码器专业技术人员,不设置该选项。
    {"profile": "high", "preset": "veryfast"}
    Layoutobject

    视频布局信息。

    说明 视频转码时,需要指定视频布局信息,包括布局坐标(X,Y),布局窗格(Width,Height),叠放顺序(ZOrder);纯音频转码时,禁止填写视频布局信息。
    UserPanesarray<object>

    混流用户窗格信息。

    object

    混流用户窗格信息。

    UserInfoobject

    该窗格对应的混流用户信息,不填时后台按照上行主播的进房顺序自动填充。

    说明
  • 如果指定混流用户信息,该用户信息需要已在 TranscodeParams.UserInfos 参数中配置。
    • 仅针对原始流和视频流有效。
    SourceTypestring

    混流转码模式下视频输入流类型,仅针对视频流(StreamType=2)有效。取值:

    • camera(默认值):摄像头。
    • shareScreen:屏幕共享。
    camera
    ChannelIdstring

    混流用户所在的频道 ID,同频道内混流的用户可不填,跨频道混流时建议填写该参数。

    yourChannelId
    UserIdstring

    混流用户 ID。

    yourSubUserId
    Heightstring

    窗格高,归一化百分比。

    0.2632
    Widthstring

    窗格宽,归一化百分比。

    0.3564
    Xstring

    坐标 X,归一化百分比。

    0.2456
    Ystring

    坐标 Y,归一化百分比。

    0.3789
    ZOrderstring

    叠放顺序,0 为最底层,1 层在 0 层之上,以此类推。

    0
    BackgroundImageUrlstring

    子画面的背景图 URL,最大长度不超过 2048 个字符。当用户关闭摄像头或未进入房间时,会在布局位置填充为此图片。

    yourImageUrl
    RenderModestring

    子画面输出时的显示模式,取值:

    • 0:缩放并显示黑底。
    • 1(默认值):裁剪。
    1
    UserInfosarray<object>

    混流时订阅的用户信息,不指定用户则所有用户混流。

    object

    混流用户信息。

    SourceTypestring

    混流时订阅的视频输入流类型,仅针对视频流(StreamType=2)有效。取值:

    • camera(默认值):摄像头。
    • shareScreen:屏幕共享。
    camera
    StreamTypestring

    混流时订阅的转推流类型。取值:

    • 0(默认值):转推原始流。
    • 1:仅转推音频流。
    • 2:仅转推视频流。
    0
    ChannelIdstring

    混流时订阅用户所在的频道 ID,同频道内混流的用户可不填,跨频道混流时建议填写该参数。

    yourChannelId
    UserIdstring

    混流时订阅的用户 ID。

    yourSubUserId
    SeiParamsobject

    SEI 配置参数。

    LayoutVolumeobject

    布局和音量 SEI,该参数内容可以为空,表示携带默认的布局和音量 SEI。

    FollowIdrstring

    发送 IDR 关键帧时是否确保携带 SEI,取值:

    • 0:不确保带 SEI。
    • 1:确保带 SEI。
    0
    Intervalstring

    SEI 发送间隔,取值范围:[1000, 5000],单位:毫秒。

    1000
    PassThroughobject

    透传 SEI。

    FollowIdrstring

    发送 IDR 关键帧时是否确保携带 SEI,取值:

    • 0:不确保带 SEI。
    • 1:确保带 SEI。
    0
    Intervalstring

    SEI 发送间隔,取值范围:[1000, 5000],单位:毫秒。

    1000
    PayloadContentstring

    透传 SEI 的 payload 内容。

    yourPayloadContent
    PayloadContentKeystring

    透传 SEI 的 payload 内容对应的 key 值。不设置时,key 为默认值 udd。

    yourPayloadContentKey
    PayloadTypestring

    SEI 消息的自定义 payload_type,取值范围 100-254。不设置时,SEI 的 payload_type 为默认值为 5。

    100

    布局和音量 SEI

    参数说明
    canvas画布信息,参数信息:
    - w:画布宽,单位:像素。
    - h:画布高,单位:像素。
    - bgnd:画布的背景颜色,格式为 RGB 定义下的十六进制整数。
    stream视频流信息,参数信息:
    - uid:主播的用户 ID。
    - paneid:该区域在窗格编号,取值[0,8]。
    - zorder:该区域的叠放层级,取值范围 [0,99]。
    - x:该区域在画布中对应的 x 坐标,归一化百分比。
    - y:该区域在画布中对应的 y 坐标,归一化百分比。
    - w:该区域的宽度,归一化百分比。
    - h:该区域的高度,归一化百分比。
    - type:该区域视频流的类型,取值:0:摄像头;1:屏幕共享。
    - status:该区域视频流的状态,取值:0:还未拉取到;1:已拉取到。
    - muted:主播被静音状态,取值:0:未被静音;1:被静音。主播 PK 时,A 主播将 B 主播静音,B 主播 muted 字段将显示被静音状态。
    - vol:主播的音量(分贝),取值:[0,255]。
    - vad :语音检测,取值:[0,150],150 是有人声,非 150 就是从有人声到无声的拖尾时间。
    ts生成该信息时的操作系统时间戳,单位为毫秒。
    verSEI 格式版本信息,如当前版本为 1.0.0.20220915。
    udd客户自定义的场景化事件,通过 PassThrough 参数下发,内容由 PayloadContent 参数指定。

    以直播连麦场景为例:

    如果只是单主播,观众端接收的 SEI 信息里 stream 集合只有一个成员信息;如果是主播正在连麦或者 PK,观众端接收的 SEI 信息里 stream 集合会有多个成员信息。 例如,当主播 111 单主播推流时,观众端收到的 SEI 帧格式如下:
    {"canvas":{"w":1920,"h":1080,"bgnd":0},"stream":[{"uid":"111","paneid":-1,"zorder":0,"x":0,"y":0,"w":0,"h":0,"type":0,"status":1,"muted":0,"vol":0,"vad":0}],"ver":"1.0.0.20220915","ts":1697696105170} 当主播 111 和观众 222 进行连麦时,观众端收到的 SEI 帧格式如下:
    {"canvas":{"w":1920,"h":1080,"bgnd":0},"stream":[{"uid":"111","paneid":0,"zorder":1,"x":0,"y":0.25,"w":0.5,"h":0.5,"type":0,"status":1,"muted":0,"vol":1,"vad":119},{"uid":"222","paneid":1,"zorder":1,"x":0.5018382,"y":0.25,"w":0.5,"h":0.5,"type":0,"status":1,"muted":0,"vol":60,"vad":123}],"ver":"1.0.0.20220915","ts":1697696106230} 判断 stream 数组的个数可以知道当前直播布局是否发生切换,stream 数组的个数为 1 时,则是单主播推流;stream 数组的个数大于 1,则主播在连麦或 PK 中。通过成员的布局信息,知道每个成员在混流布局中的具体位置。

    透传 SEI

    • 自定义 SEI,通过 StartLiveMPUTask 命令启动混流转推任务,在 PassThrough 参数中,指定 PayloadContent 内容;也可以在 UpdateLiveMPUTask 命令更新混流转推任务时,在 PassThrough 参数中,指定 PayloadContent 内容。
    • 自定义 SEI 可以周期性发送,通过 PassThrough 参数中的 Interval 来设定周期,单位为 ms;
    • 自定义 SEI 也可以跟随关键帧发送,通过 PassThrough 参数中的 FollowIdr 来设定。
      • 既可以按照 Interval 来周期性发送,也可以将 SEI 跟随关键帧来发送,如 Interval:1000,FollowIdr: 1 表示每隔 1000ms 发送一次自定义 SEI,并且在发送关键帧时携带自定义 SEI。
      • 当不携带 Interval 以及不携带 FollowIdr 时,表示该自定义 SEI 只在调用时发送一次。

    例如,当主播 111 单主播推流时,调用 UpdateLiveMPUTask 命令下发周期性 SEI,PassThrough 参数中的 Interval 设置为 1000,FollowIdr 设置为 0,PayloadContent 设置为"hello world",那么每隔 1000ms 将发送一次自定义 SEI,观众端收到的 SEI 帧格式如下:
    {"canvas":{"w":1920,"h":1080,"bgnd":0},"stream":[{"uid":"111","paneid":-1,"zorder":0,"x":0,"y":0,"w":0,"h":0,"type":0,"status":1,"muted":0,"vol":0,"vad":0}],"ver":"1.0.0.20220915","ts":1697696109876,"udd":"hello world"}

    跨频道多用户混流

    若您需要将跨多个频道中的多个主播进行混流布局并转推到直播服务时,您需要将发起跨频道通话的主播的 UserID、ChannelID,以及对端的 UserID 作为入参创建混流任务。示例如下: 在直播 PK 场景中,频道 channelA 的主播 userA,通过客户端接口发起了和频道 channelB 主播 userB 的跨频道 PK,并将两个主播的混流画面输出给频道 channelA 的麦下观众观看。则,此时创建混流任务时关于频道和用户参数的指定示范如下:

    • ChannelID: 指定为 channelA
    • UserInfos->UserId :分别指定 userA 和 userB
    说明 创建跨频道多用户的混流任务的前提是,已经通过客户端 SDK 接口发起了跨频道通话。如果不同频道的用户没有进行通话,则无法创建跨房间混流任务。如何发起跨房间通话,请参见跨房间订阅功能

    返回参数

    名称类型描述示例值
    object

    请求 ID。

    RequestIdstring

    请求 ID。

    0F72851F-5DC1-1979-9B2C-450040316C3E

    示例

    正常返回示例

    JSON格式

    {
      "RequestId": "0F72851F-5DC1-1979-9B2C-450040316C3E"
    }

    错误码

    HTTP status code错误码错误信息
    400InvalidParam%s
    400InvalidAppId%s
    403OperationDeniedYour account has not enabled the Live service
    403Forbidden%s
    404MissingParam%s
    500InternalErrorInternalError

    访问错误中心查看更多错误码。

    变更历史

    变更时间变更内容概要操作
    2024-11-14OpenAPI 错误码发生变更、OpenAPI 入参发生变更查看变更详情
    2024-10-30OpenAPI 错误码发生变更查看变更详情
    2024-08-13OpenAPI 错误码发生变更查看变更详情
    2024-08-06OpenAPI 错误码发生变更、OpenAPI 入参发生变更查看变更详情
    2024-07-04OpenAPI 错误码发生变更查看变更详情
    2024-06-12OpenAPI 错误码发生变更查看变更详情
    2024-03-07OpenAPI 错误码发生变更查看变更详情
    2024-03-01OpenAPI 错误码发生变更查看变更详情
    2023-12-26OpenAPI 错误码发生变更查看变更详情