云端混流

最近更新时间:2019-07-01 16:05:19

接口描述

HTTP 协议请求接口 cgi

http://fcgi.video.qcloud.com/common_access
  • 只支持 HTTP 协议,此接口暂不支持 HTTPS 协议
  • 请使用 POST 方法访问
  • Content - Type 为 application/json

通过 URI 传递鉴权参数

http://fcgi.video.qcloud.com/common_access?appid=1252500000&interface=Mix_StreamV2&t=t&sign=sign

参数说明:

参数名称 参数含义 输入类型 备注 是否必填
appid 客户 ID int32 填写直播 APPID,用于区分不同客户的身份。 Y
interface 接口名称 string 混流接口名称固定填写:Mix_StreamV2。 Y
t 有效时间 int64 UNIX时间戳,即从1970年1月1日(UTC/GMT的午夜)开始所经过的秒数;这个字段表示的是请求过期时间,请您在获取当前时间(秒)的基础上加60秒偏移。 Y
sign 安全签名 string sign = MD5(key + t) ,即把加密 key 和 t 进行字符串拼接后,计算一下 md5 值。这里的 key 是您在云直播管理控制台中设置的 API 鉴权 key。 Y

安全签名 sign 计算方法:

key = "40328529ca4381a80c6ecf2e6aa57438"                    //API 鉴权 key 
t = 1490858347                                              //t 过期时间
key + t = "40328529ca4381a80c6ecf2e6aa574381490858347"      //key 和 t 进行字符串拼接
sign = MD5(key + t) = "7f29ed83c61b77de1b0d66936fd4fd44"   //对拼接后的字符串计算 MD5

混流参数

图片标题
云端混流将一系列由启动混流开始,到取消混流结束的操作称为一次混流会话。若几次混流请求,参数中的 mix_stream_session_id 与 output_stream_id 一致,则这几次操作属于同一个混流会话。

申请混流

示例:

    {
        "timestamp":int(time.time()),                       # UNIX 时间戳数
        "eventId":int(time.time()),                         # 取随机数即可,标识一次网络请求
        "interface":
        {
            "interfaceName":"Mix_StreamV2",                 # 固定值
            "para":
            {
                "app_id": appid,                            # 填写直播 APPID
                "interface": "mix_streamv2.start_mix_stream_advanced",  # 固定值
                "mix_stream_session_id" : "lewis_room",#标识一次网络请求
                "output_stream_id": "stream_lewis01",         # 填输出流 ID
                "input_stream_list":
                [
                    # 背景画面
                    {
                        "input_stream_id":"stream_lewis01",   # 流 ID
                        "layout_params":
                        {   
                            "image_layer": 1                # 图层号,背景填1;
                        }   
                    },
                    # 小画面1
                    {
                        "input_stream_id":"stream_lewis02",    # 流 ID
                        "layout_params":
                        {   
                            "image_layer": 2,               # 图层标识号
                            "image_width": 160,             # 画面宽度
                            "image_height": 240,            # 画面高度
                            "location_x": 380,              # x偏移:相对于背景画面左上角的横向偏移
                            "location_y": 630               # y偏移:相对于背景画面左上角的纵向偏移
                        }   
                    }
                ]
            }
        }
    }

完整的请求参数包括两部分:CGI 参数混流参数

CGI 参数说明:

参数名称 参数含义 输入类型 备注 是否必填
timestamp 当前时间 int64 取当前时间()即可。 Y
eventId 标识一次网络请求 int32 取随机值即可。 Y
interfaceName 接口标识 string Mix_StreamV2,固定值,表明使用混流接口 。 Y

混流参数说明:混流参数按作用可以分为三个部分:

  • 混流会话参数。
  • 输出流参数。
  • 输入流参数。

混流会话参数说明:

参数名称 参数含义 输入类型 范围 备注 是否必填
app_id 直播 APPID int32 直播 APPID。 Y
interface 混流接口名称 string mix_streamv2.start_mix_stream_advanced
mix_streamv2.cancel_mix_stream
申请混流:mix_streamv2.start_mix_stream_advanced。
取消混流:mix_streamv2.cancel_mix_stream。
Y
mix_stream_session_id 混流会话(申请混流开始到取消混流结束)标识 ID string 80字节以内,仅含字母、数字以及下划线的字符串 申请混流成功后,业务需要记录该值,在取消混流时,将申请混流时的 mix_stream_session_id 填入。
Y
mix_stream_template_id 输入模板 ID,若设置该参数,将按默认模板布局输出,无需填入自定义位置参数 int32 0,10,20,30,40,50
310,390,391,410,510,590,610
不填默认为0。
两输入源支持10,20,30,40,50。
三输入源支持310,390,391。
四输入源支持410。
五输入源支持510,590。
六输入源支持610。
N

输出流参数说明

参数名称 参数含义 输入类型 范围 备注 是否必填
output_stream_id 输出流 ID string 80字节以内,仅含字母、数字以及下划线的字符串 指定输出流 ID。 Y
output_stream_type 输出流类型 int32 0,1 不填默认为0。
当输出流为输入流 list 中的一条时,填写0。
当期望生成的混流结果成为一条新流时,该值填为1。
该值为1时,output_stream_id 不能出现在 input_stram_list 中,且直播后台中,不能存在相同 ID 的流。
N
output_stream_bitrate 输出码率 int32 [1,50000] 不填系统会自动判断。 N

输入源流参数说明

参数名称 参数含义 输入类型 范围 备注 是否必填
input_stream_id 输入源 ID string 80字节以内,仅含字母、数字以及下划线的字符串 指定输入源 ID。 Y
image_layer 图层标识号 int32 [1,16]
1)背景流(即大主播画面或画布)的 image_layer 填1。
2)纯音频混流,该参数也需填。
Y
input_type 输入源类型 int32 [0,5] 目前支持:
不填默认为0。
0表示输入源为音视频。
2表示输入源为图片。
3表示输入源为画布。
4表示输入源为音频。
5表示输入源为纯视频。
N
image_width 输入画面在输出时的宽度 double 像素:[0,3000]
百分比:[0.01,0.99]
不填默认为输入流的宽度。
使用百分比时,期望输出为(百分比 * 背景宽)。
N
image_height 输入画面在输出时的高度 double 像素:[0,3000]
百分比:[0.01,0.99]
不填默认为输入流的高度。
使用百分比时,期望输出为(百分比 * 背景高)。
N
location_x x 偏移 double 像素:[0,3000]
百分比:[0.01,0.99]
不填默认为0。
相对于大主播背景画面左上角的横向偏移。
使用百分比时,期望输出为(百分比 * 背景宽)。
N
location_y y 偏移 double 像素:[0,3000]
百分比:[0.01,0.99]
不填默认为0。
相对于大主播背景画面左上角的纵向偏移。
使用百分比时,期望输出为(百分比 * 背景高)。
N
color 颜色 string 使用画布(input_type = 3)时填写,常用的颜色有:
红色:0xcc0033。
黄色:0xcc9900。
绿色:0xcccc33。
蓝色:0x99CCFF。
黑色:0x000000。
白色:0xFFFFFF。
灰色:0x999999。
N
picture_id 水印 ID int32 使用图片(input_type = 2)时填写,填入将图片上传为水印后生成的 ID。 N

自定义位置参数的填写说明
图片描述

注意:

位置参数 location_x 和 location_y 为小画面左上角相对背景画面左上角的绝对像素距离。

接口返回

{"code":0, "message":"Success!", "event_id": "1527240138","timestamp":1490079362}

参数说明:

参数名 参数含义 类型 备注
code 返回错误码 int32 0表示成功,其他表示失败。
message 错误信息 string 返回错误信息。
timestamp 时间戳 int64 返回时间。
event_id 请求 ID int32 网络请求标识。

常见错误码说明:

错误码 原因 排查建议
-1 解析输入参数错误 检查请求体 body json 格式是否正确。
检查 interface name 是否为 mix_streamv2.start_mix_stream_advanced。
检查 input_stream_list 是否为空。
-2 输入参数错误 检查 appid 和 eventid 是否为0。
检查画面参数是否溢出。
-3 流数目错误 检查输入流数目是否在[1,16]范围内。
-4 流参数错误 检查输入输出长宽在(0,3000)范围内。
检查输入流数目是否在(0,16]范围内。
检查输入流是否携带 layout_params 。
检查 input_type 是否支持(合法数值:0,2,3,4,5)。
检查流 ID 长度是否满足(1,80)。
-11 图层错误 检查图层个数与输入流个数是否一致。
检查图层 ID 是否重复。
检查图层 ID 是否在(0,16]之间。
-20 输入参数与接口不匹配 检查输入流条数是否匹配模板 ID。
检查颜色参数是否正确。
-21 混流输入流条数错误 检查输入流的条数是否至少为两条。
-28 获取背景长宽失败 如果设置画布,检查画布的长宽是否设置。
检查背景流是否存在(推流后需等待5s再混流)。
-29 裁剪参数错误 检查裁剪位置是否超出流的长宽。
-33 水印图片 ID 错误 检查输入图片 ID 是否设置。
-34 获取水印图片 URL 失败 检查图片是否上传成功,是否已经生成 URL。
-111 output_stream_id 参数与 output_stream_type 不匹配 output_stream_type 为0,output_stram_id 必须出现在 input_stream_list 中。
output_stream_type 为1,output_stram_id 必须不在 input_stream_list 中。
-300 输出流 ID 已经被使用 检查当前输出流是否已经是另一个混流的输出流。
-505 输入流无法在 upload 查到 是否推流成功5s后发起混流。
检查能否播放
检查混流参数中 appid 是否填写正确。
-507 流长宽参数查询失败 检查画布宽、高是否设置。
检查推流是否已经成功,建议推流后5s再开始混流。
-508 输出流 ID 错误 检查是否存在同样 sessionid 使用不同输出流 ID 的情况。
-10031 触发混流失败 建议推流后等待5s再混流。
-30300
-31001
-31002
取消混流时 sessionid 不存在 检查 sessionid 是否存在。
-31003 输出流 ID 与 session 中输出流 ID 不匹配 检查取消混流时填入的输出流 ID。
-31004 输出流码率不合法 检查输出流码率是否在[1,50000]之间。
其他 其他错误,请联系客服提供技术支持

取消混流

使用 mix_streamv2.cancel_mix_stream 接口取消混流,取消混流参数中只需填入 CGI 参数及混流会话参数即可。
示例:

{
        "timestamp":int(time.time()),           # UNIX时间戳数
        "eventId":int(time.time()),             # 混流事件ID,取时间戳即可
        "interface":
        {
            "interfaceName":"Mix_StreamV2",     # 固定取值"Mix_StreamV2"
            "para":
            {
                "app_id": appid,                # 填写直播APPID
                "interface": "mix_streamv2.cancel_mix_stream",  # 取消混流
                "mix_stream_session_id" : "lewis_room",# 标识一次网络请求
                "output_stream_id": "stream_lewis01"# 输出流id
            }
        }
    }

注意:

取消混流后,半分钟后才可使用相同的 session id 申请混流。

云端混流功能说明

功能支持列表

  • 最大支持同时16条流混流
  • 支持混入5种输入源类型(音视频,纯音频,纯视频,水印,画布)
  • 支持混流合成全新流
  • 支持裁剪,水印功能
  • 支持模板配置
  • 支持混流录制
  • 支持自动混流
  • 支持实时混流种类与位置切换
  • 混流启动与取消无缝平滑过渡

常见云端场景示例

demo 文件可在最下方 DEMO 下载中获取。

大主播与小主播连麦

图片描述

参考 demo_template_20.py

主播PK

图片描述

参考 demo_pk.py

多人会议/多人游戏

图片描述

参考 demo_stream_and_canvas.py

语音通话

参考 demo_audio.py

常用布局模板说明

常用的模板有10、30、40、310、410、510和610。使用这八种模板时,输入流不需要填写位置和长宽参数,为原始画面的等比例缩放。只需要传入模板 ID 即可。
模板10效果图:
图片描述
模板30效果图:
图片描述
模板40效果图:
图片描述
模板310效果图:
图片描述
模板410效果图:
图片描述
模板510效果图:
图片描述
模板610效果图:
图片描述

云端裁剪

参数说明:

{
    "input_stream_id":"5000_lewis03",    # 流ID
    "layout_params":
    {   
        "image_layer": 3,               # 图层标识号
        "image_width": 320,             # 画面宽度
        "image_height": 240,            # 画面高度
        "location_x": 580,              # x偏移:相对于背景画面左上角的横向偏移
        "location_y": 830               # y偏移:相对于背景画面左上角的纵向偏移
    }
    "crop_params":
    {
        "crop_width":200,               # 裁剪宽度
        "crop_height":100,              # 裁剪高度
        "crop_x":100,                   # 裁剪x偏移:相对于原画面左上角的横向偏移
        "crop_y":1                      # 裁剪y偏移:相对于原画面左上角的纵向偏移
    }
}

示意图:
图片描述

裁剪参数

参数名称 参数含义 输入类型 范围 备注 是否必填
crop_width 裁剪源画面的宽度 int32 像素:[0,3000] N
crop_height 裁剪源画面的高度 int32 像素:[0,3000] N
crop_x 相对裁剪源画面左上角横向偏移。 int32 像素:[0,3000] N
crop_y 相对裁剪源画面左上角纵向偏移。 int32 像素:[0,3000] N

注意:

  • 输入的宽高和位置参数全部是像素绝对值,对于不同分辨率的流,需要不同处理。
  • 位置参数 crop_x 和 crop_y 表示相对原始流左上角绝对像素的位置坐标。
  • 如果 layout_params 中指定了 image_width 和 image_height,会将裁剪后的画面缩放到指定的宽高。示例中,会将从原始画面裁剪出的200 * 100的画面缩放成320 * 249输出。

自动混流

若需求较简单,只要实现一个大主播和一个小主播混流,可以使用自动混流功能。只需在原先的推流地址中加入自动混流参数 mixv2=t_id:x;session_id:xxx;layer:x 即可使用。
示例:

rtmp://1234.livepush.myqcloud.com/live/1234_lewis01?from=interactive&bizid=1234&mixv2=t_id:1;session_id:1234_lewis_room;layer:b
rtmp://1234.livepush.myqcloud.com/live/1234_lewis02?from=interactive&bizid=1234&mixv2=t_id:1;session_id:1234_lewis_room;layer:s

说明:

在两条流均推流成功后,会自动开始混流,输出流 ID 为背景流 ID,示例中输出流 ID 为1234_lewis01。

参数说明

参数 含义 输入类型 范围 备注 是否必填
t_id 模板 ID int32 1 目前只支持填1。 Y
session_id 混流操作标识 string 80 字节以内,仅含字母、数字以及下划线的字符串 参与自动混流的两条流,session_id 需一致。 Y
layer 图层 string s,b 大主播图层,填 b。
小主播图层,填 s。
Y

自动混流效果图
图片标题

注意:

  • 自动混流只支持两条输入流,音视频混流和纯音频混流均支持。
  • 自动混流的输入源中有一条流断流则自动取消。
  • 自动混流不支持自定义长宽和位置参数。

混流常见问题Q&A

  1. Q:推流后混流,为什么会返回-505错误码?
    A:推流后等待5s左右再混流。
  2. Q:混流接口返回 code 为-505时,如何自查?
    A:混流接口报-505,代表该流 ID 在直播后台中无数据。1、可以通过拉流的方式查看是否推流成功。如果拉流成功,则说明推流成功。2、如果可以拉流,但接口报-505,请检查混流参数中,appid 填写是否正确。
  3. Q:纯音频混流后听不到小主播声音?
    A:检查纯音频流的 input_type 是否填为4。
  4. Q:连麦场景,输出流 ID 不变,小主播流 ID 变化,是否要取消混流后再重新混流?
    A:不需要,直接用新的小主播 ID 发新的混流请求即可。
  5. Q:申请混流后,如果一直未取消混流,会出现什么情况?
    A:混流会一直进行,直到收到取消混流命令。
  6. Q:混流过程中,输入流突然断开会出现什么情况?
    A:非背景流断开,断掉的流画面会停在最后一帧,背景流断开,则整个画面都会卡住。在15分钟内该流以同一流 ID 重新推流成功,则自动恢复混流。
  7. Q:如何获取录制的混流结果
    A:请参考录制文档 录制
  8. Q:为什么混流后的视频有黑边?
    A:混流后有黑边有两种情况:1、原始流就有黑边;2、混流参数中的输出长宽比与原始流的长宽比不匹配。如混流期望的长宽比为16 : 9,原始视频长宽比为4 : 3,混流后台会在原始视频长宽比基础上补黑边,满足期望的16 : 9输出。
    如果不希望产生黑边,也有两种方案,1、输出长宽比与输入长宽比一致。2、使用裁剪参数,请参考裁剪功能的使用方法。
  9. Q:为什么混流的小主播画面有的时候与期望的位置不同?
    A:这种情况一般是参与混流的输入源分辨率发生了变化引起的,例如,申请混流时,长宽为1280 * 720,过了一段时间后,流分辨率变为了2560 * 1440,这个时候,混流输出的画面就会发生改变,与期望的输出有区别。
    不建议在混流过程中,变更输入流的分辨率,如确有需要,需计算位置参数后重新申请混流
  10. Q:混流输出是否支持 H265 编码?
    A:混流目前只支持输出 H264 编码。即使输入流均为 H265 编码,输出流也以 H264 编码输出。
  11. Q:取消混流后,再次取消,返回-30300错误?
    A:取消混流接口只需要调用一次,成功后无需重复调用。
  12. Q:混流过程中,输入流断开后何时自动取消混流
    A:以两条流混流为例,如果其中一条流断开,混流不会自动取消,如果开了录制,录制也将继续进行。如果两条流均断开,15分钟后混流自动取消。

DEMO 下载

混流 demo 下载:请单击 此处 下载 demo。