全部产品
Search

搜索本产品

    ：创建混流转推任务（新）

    文档中心

    ：创建混流转推任务（新）

    更新时间：Dec 23, 2024

    创建混流转推任务。

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

    混流任务生命周期

    启动
    • 主播首次开播，可以调用StartLiveMPUTask启动旁路。
      • 若无用户入会，会返回channel不存在错误。
      • 用户开始推流时才会输出旁路流。若单路任务用户未推流，则旁路流无法播放。
      • 混流任务需保证至少有一个用户有推流，旁路流才可播放。未推流的用户对应的布局画面会展示黑屏。
    • 客户业务服务器建议记录旁路任务状态、任务类型、任务参数。
      • 任务状态：启动、停止。
      • 任务类型：单路、混流。
      • 任务参数：即最新的入参，例如：调用UpdateLiveMPUTask成功后，记录最新任务参数。
    • 在连麦或者PK场景下，此时任务已经被更新为混流。若当前主播异常退出重新入会后，客户业务服务器可以根据保存的最新的任务类型和任务参数，直接调用StartLiveMPUTask启动混流任务。
      • 如果启动前任务未被系统自动清理，则直接启动成功。
      • 如果任务还未被系统自动清理，则会返回任务已存在错误码。
    结束
    • 主播离会，需要主动调用StopLiveMPUTask停止旁路任务。
    • 若任务所指定的所有用户均已离会但未主动调用StopLiveMPUTask，系统会在2分钟后对旁路任务进行停止。

    QPS限制

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

    调试

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

    请求参数

    名称

    类型

    是否必选

    示例值

    描述
    Action String 是 StartLiveMPUTask

    系统规定参数。取值：StartLiveMPUTask。
    AppId String 是 yourAppId

    应用ID，仅支持传单个ID。由大小写字母、数字、下划线、短划线（-）组成，最大64字符。
    ChannelId String 是 yourChannelId

    频道ID，仅支持传单个ID。由大小写字母、数字、下划线、短划线（-）组成，最大64字符。
    TaskId String 是 yourTaskId

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

    混流模式。取值：

    • 0：单路转推，不混流转码，仅转推原始单路流，无需配置混流转码参数。
    • 1（默认值）：混流转码转推。
    StreamURL String 否 rtmp://example.com/live/stream

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

    说明
    • 对已开防盗链鉴权的域名，需要在推流地址中包含鉴权串。
    • 禁止同一个StreamURL在不同任务中同时使用。
    • 任务停止10S之内，禁止使用同一个StreamURL。
    MultiStreamURL Array 否

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

    说明 在设置任务的转推地址时，StreamURL参数与MultiStreamURL参数，只能配置其中一个参数，且必须配置其中一个参数。
    URL String 否 rtmp://example.com/live/stream****

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

    是否转推到阿里云CDN。

    • false为转推非阿里云CDN。
    • true为转推阿里云CDN。
    说明 该参数默认为false。
    Region String 否 CN-Shanghai

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

    • CN-Shanghai：上海。
    • AP-Singapore（默认值）：新加坡。
    • EMAA-Saudi：沙特。
    MaxIdleTime String 否 10

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

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

    单流转推参数，单流转推（MixMode=0）时必填。需要混流转码时不填。
    SourceType String 否 camera

    单流转推模式下视频输入流类型，仅针对视频流（StreamType=2）有效。取值：

    • camera（默认值）：摄像头。
    • shareScreen：屏幕共享。
    StreamType String 否 0

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

    • 0（默认值）：转推原始流。
    • 1：仅转推音频流。
    • 2：仅转推视频流。
    UserId String 是 yourSubUserId

    单流转推的用户ID，一次只能转推一路流。
    TranscodeParams Object 否

    混流转码转推参数，混流转码转推（MixMode=1）时必填。需要单流转推时不填。
    Background Object 否

    混流全局背景图。
    RenderMode String 否 1

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

    • 0：缩放并显示黑底。
    • 1（默认）：裁剪。
    URL String 否 yourImageUrl

    全局背景图URL，最大长度不超过2048个字符。
    EncodeParams Object 否

    转推输出的编码参数。
    AudioOnly String 否 false

    是否为纯音频，取值：

    • true：纯音频，仅需要设置音频相关参数。
    • false（默认值）：非纯音频，除VideoCodec参数与EnhancedParam参数外，其它参数均不能为空。
    AudioBitrate String 否 128

    音频码率，取值范围：[8, 500]，单位：kbps。
    AudioChannels String 否 2

    音频声道数，取值：1、2。
    AudioSampleRate String 否 44100

    音频采样率，取值：8000、16000、32000、44100、48000，单位：Hz。
    VideoCodec String 否 H.264

    视频编码格式。取值：

    • H.264（默认值）。
    • H.265。
    VideoBitrate String 否 3500

    视频码率，取值范围：[1, 10000]，单位：kbps。
    VideoFramerate String 否 25

    视频帧率，取值范围：[1, 60]，单位：fps。
    VideoGop String 否 20

    视频GOP，取值范围：[1, 60]。
    VideoHeight String 否 1000

    视频高，取值范围：[0, 1920]，单位：px。
    VideoWidth String 否 1920

    视频宽，取值范围：[0, 1920]，单位：px。
    EnhancedParam String 否 {"profile": "high", "preset": "veryfast"}

    编码增强参数，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，主要用于实时通讯领域。建议非编码器专业技术人员，不设置该选项。
    Layout Object 否

    视频布局信息。

    说明 视频转码时，需要指定视频布局信息，包括布局坐标(X，Y)，布局窗格(Width，Height)，叠放顺序(ZOrder)；纯音频转码时，禁止填写视频布局信息。
    UserPanes Array 否

    混流用户窗格信息。
    UserInfo Object 否

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

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

    混流转码模式下视频输入流类型，仅针对视频流（StreamType=2）有效。取值：

    • camera（默认值）：摄像头。
    • shareScreen：屏幕共享。
    ChannelId String 否 yourChannelId

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

    混流用户ID。
    Height String 否 0.2632

    窗格高，归一化百分比。
    Width String 否 0.3564

    窗格宽，归一化百分比。
    X String 否 0.2456

    坐标X，归一化百分比。
    Y String 否 0.3789

    坐标Y，归一化百分比。
    ZOrder String 否 0

    叠放顺序，0为最底层，1层在0层之上，以此类推。
    BackgroundImageUrl String 否 yourImageUrl

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

    子画面输出时的显示模式，取值：

    • 0：缩放并显示黑底。
    • 1（默认值）：裁剪。
    UserInfos Array 否

    混流时订阅的用户信息，不指定用户则所有用户混流。
    SourceType String 否 camera

    混流时订阅的视频输入流类型，仅针对视频流（StreamType=2）有效。取值：

    • camera（默认值）：摄像头。
    • shareScreen：屏幕共享。
    StreamType String 否 0

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

    • 0（默认值）：转推原始流。
    • 1：仅转推音频流。
    • 2：仅转推视频流。
    ChannelId String 否 yourChannelId

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

    混流时订阅的用户ID。
    SeiParams Object 否

    SEI配置参数。
    LayoutVolume Object 否

    布局和音量SEI，该参数内容可以为空，表示携带默认的布局和音量SEI。
    FollowIdr String 否 0

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

    • 0：不确保带SEI。
    • 1：确保带SEI。
    Interval String 否 1000

    SEI发送间隔，取值范围：[1000, 5000]，单位：毫秒。
    PassThrough Object 否

    透传SEI。
    FollowIdr String 否 0

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

    • 0：不确保带SEI。
    • 1：确保带SEI。
    Interval String 否 1000

    SEI发送间隔，取值范围：[1000, 5000]，单位：毫秒。
    PayloadContent String 否 yourPayloadContent

    透传SEI的payload内容。
    PayloadContentKey String 否 yourPayloadContentKey

    透传SEI的payload内容对应的key值。不设置时，key为默认值udd。
    PayloadType String 否 100

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

    布局和音量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

    生成该信息时的操作系统时间戳，单位为毫秒。

    ver

    SEI格式版本信息，如当前版本为1.0.0.20220915。

    udd

    客户自定义的场景化事件，通过PassThrough参数下发，内容由PayloadContent参数指定。

    说明 用户拉取转推流时，转推流的流媒体数据会包含SEI信息，用户可借助此功能传递一些自定义信息。SEI信息在解码视频流时可以从视频帧数据中获取，具体格式参考参数说明表PassThrough参数。
    以直播连麦场景为例：

    如果只是单主播，观众端接收的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接口发起了跨频道通话。如果不同频道的用户没有进行通话，则无法创建跨房间混流任务。如何发起跨房间通话，请参见跨房间订阅功能。

    返回数据

    名称

    类型

    示例值

    描述
    RequestId String 0F72851F-5DC1-1979-9B2C-450040316C3E

    请求ID。

    示例

    请求示例

    http(s)://live.aliyuncs.com/?Action=StartLiveMPUTask
&AppId=yourAppId
&ChannelId=yourChannelId
&TaskId=yourTaskId
&MixMode=0
&StreamURL=rtmp://example.com/live/stream
&MultiStreamURL=[{"URL":"rtmp://example.com/live/stream****"}]
&Region=CN-Shanghai
&SingleSubParams={"SourceType":"camera","StreamType":"0","UserId":"yourSubUserId"}
&TranscodeParams={"Background":{"RenderMode":"1","URL":"yourImageUrl"},"EncodeParams":{"AudioOnly":"false","AudioBitrate":"128","AudioChannels":"2","AudioSampleRate":"44100","VideoCodec":"H.264","VideoBitrate":"3500","VideoFramerate":"25","VideoGop":"20","VideoHeight":"1000","VideoWidth":"1920","EnhancedParam":"{\"profile\": \"high\", \"preset\": \"veryfast\"}"},"Layout":{"UserPanes":[{"UserInfo":{"SourceType":"camera","ChannelId":"yourChannelId","UserId":"yourSubUserId"},"Height":"0.2632","Width":"0.3564","X":"0.2456","Y":"0.3789","ZOrder":"0","BackgroundImageUrl":"yourImageUrl","RenderMode":"1"}]},"UserInfos":[{"SourceType":"camera","StreamType":"0","ChannelId":"yourChannelId","UserId":"yourSubUserId"}]}
&SeiParams={"LayoutVolume":{"FollowIdr":"0","Interval":"1000"},"PassThrough":{"FollowIdr":"0","Interval":"1000","PayloadContent":"yourPayloadContent","PayloadContentKey":"yourPayloadContentKey"},"PayloadType":"100"}
&公共请求参数

    正常返回示例

    XML格式

    HTTP/1.1 200 OK
Content-Type:application/xml

<StartLiveMPUTaskResponse>
    <RequestId>0F72851F-5DC1-1979-9B2C-450040316C3E</RequestId>
</StartLiveMPUTaskResponse>

    JSON格式

    HTTP/1.1 200 OK
Content-Type:application/json

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

    错误码

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