云直播云端混流

说明: 
使用云端混流功能将产生转码费用，相关计费说明请参见 直播转码。
接口描述
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，用于区分不同客户的身份。
是
interface
接口名称
string
混流接口名称固定填写：Mix_StreamV2。
是
t
有效时间
int64
UNIX时间戳，即从1970年1月1日（UTC/GMT的午夜）开始所经过的秒数；这个字段表示的是请求过期时间，请您在获取当前时间（秒）的基础上加60秒偏移。
是
sign
安全签名
string
sign = MD5（key + t） ，即把加密 key 和 t 进行字符串拼接后，计算 md5 值。这里的 key 是您在 域名管理 > 推流域名 > 基本信息中查看的 API key。
是
安全签名 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偏移：相对于背景画面左上角的纵向偏移
                        }   
                    }
                ]
            }
        }
    }
注意: 
混流指定画布时，需提前设置画布大小，具体设置详见 demo。
完整的请求参数包括两部分：CGI 参数，混流参数。
CGI 参数说明:
参数名称
参数含义
输入类型
备注
是否必填
timestamp
当前时间
int64
取当前时间（秒）即可。
是
eventId
标识一次网络请求
int32
取随机值即可。
是
interfaceName
接口标识
string
Mix_StreamV2，固定值，表明使用混流接口 。
是
混流参数说明：混流参数按作用可以分为三个部分：
混流会话参数。
输出流参数。
输入流参数。
混流会话参数说明：
参数名称
参数含义
输入类型
范围
备注
是否必填
app_id
直播 APPID
int32
-
直播 APPID。
是
interface
混流接口名称
string
mix_streamv2.start_mix_stream_advanced
mix_streamv2.cancel_mix_stream
申请混流：mix_streamv2.start_mix_stream_advanced。
取消混流：mix_streamv2.cancel_mix_stream。
是
mix_stream_session_id
混流会话（申请混流开始到取消混流结束）标识 ID
string
80字节以内，仅含字母、数字以及下划线的字符串
申请混流成功后，业务需要记录该值，在取消混流时，将申请混流时的 mix_stream_session_id 填入。
是
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。
否
输出流参数说明
参数名称
参数含义
输入类型
范围
备注
是否必填
output_stream_id
输出流 ID
string
80字节以内，仅含字母、数字以及下划线的字符串
指定输出流 ID。
是
output_stream_type
输出流类型
int32
0，1
不填默认为0。
当输出流为输入流 list 中的一条时，填写0。
当期望生成的混流结果成为一条新流时，该值填为1。
该值为1时，output_stream_id 不能出现在 input_stram_list 中，且直播后台中，不能存在相同 ID 的流。
否
output_stream_bitrate
输出码率
int32
[1，50000]
不填系统会自动判断。
否
输入源流参数说明
参数名称
参数含义
输入类型
范围
备注
是否必填
input_stream_id
输入流 ID
string
80字节以内，仅含字母、数字以及下划线的字符串
指定输入流 ID（即 StreamName）。
是
image_layer
图层标识号
int32
[1，16]
1)背景流（即大主播画面或画布）的 image_layer 填1。
2)纯音频混流，该参数也需填。
是
input_type
输入源类型
int32
[0，5]
目前支持：
不填默认为0。
0表示输入流为音视频。
2表示输入流为图片。
3表示输入流为画布。 
4表示输入流为音频。
5表示输入流为纯视频。
否
image_width
输入画面在输出时的宽度
double
像素：[0，3000]
百分比：[0.01，0.99]
不填默认为输入流的宽度。
使用百分比时，期望输出为（百分比 * 背景宽）。
否
image_height
输入画面在输出时的高度
double
像素：[0，3000]
百分比：[0.01，0.99]
不填默认为输入流的高度。
使用百分比时，期望输出为（百分比 * 背景高）。
否
location_x
x 偏移
double
像素：[0，3000]
百分比：[0.01，0.99]
不填默认为0。
相对于大主播背景画面左上角的横向偏移。 
使用百分比时，期望输出为（百分比 * 背景宽）。
否
location_y
y 偏移
double
像素：[0，3000]
百分比：[0.01，0.99]
不填默认为0。
相对于大主播背景画面左上角的纵向偏移。
使用百分比时，期望输出为（百分比 * 背景高）。
否
color
颜色
string
-
使用画布（input_type = 3）时填写，常用的颜色有：
红色：0xcc0033。
黄色：0xcc9900。
绿色：0xcccc33。
蓝色：0x99CCFF。
黑色：0x000000。
白色：0xFFFFFF。
灰色：0x999999。
否
picture_id
水印 ID
int32
-
使用图片（input_type = 2）时填写，填入将图片上传为水印后生成的 ID。
否
自定义位置参数的填写说明
﻿
﻿
注意: 
位置参数 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
-3100
-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
            }
        }
    }
注意: 
1. 申请混流后，请至少等待5s后再取消混流。
2. 取消混流后，半分钟后才可使用相同的 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]
-
否
crop_height
裁剪源画面的高度
int32
像素：[0，3000]
-
否
crop_x
相对裁剪源画面左上角横向偏移
int32
像素：[0，3000]
-
否
crop_y
相对裁剪源画面左上角纵向偏移
int32
像素：[0，3000]
-
否
注意：
输入的宽高和位置参数全部是像素绝对值，对于不同分辨率的流，需要不同处理。
位置参数 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,2]
1：两条音视频流混流。
2：两条纯音频混流。
是
session_id
混流操作标识
string
80 字节以内，仅含字母、数字以及下划线的字符串
参与自动混流的两条流，session_id 需一致。
是
layer
图层
string
s，b
大主播图层，填 b。
小主播图层，填 s。
是
自动混流效果图
﻿
﻿
注意：
自动混流只支持两条输入流，音视频混流和纯音频混流均支持。
自动混流的输入源中有一条流断流则自动取消。
自动混流不支持自定义长宽和位置参数。
混流常见问题
1. 推流后混流，为什么会返回-505错误码？
推流后等待5s左右再混流。
2. 混流接口返回 code 为-505时，如何自查？
混流接口报-505，代表该流 ID 在直播后台中无数据。1、可以通过拉流的方式查看是否推流成功。如果拉流成功，则说明推流成功。2、如果可以拉流，但接口报-505，请检查混流参数中，appid 填写是否正确。
3. 纯音频混流后听不到小主播声音？
检查纯音频流的 input_type 是否填为4。
4. 连麦场景，输出流 ID 不变，小主播流 ID 变化，是否要取消混流后再重新混流？
不需要，直接用新的小主播 ID 发新的混流请求即可。
5. 申请混流后，如果一直未取消混流，会出现什么情况？
混流会一直进行，直到收到取消混流命令。
6. 混流过程中，输入流突然断开会出现什么情况？
非背景流断开，断掉的流画面会停在最后一帧，背景流断开，则整个画面都会卡住。在15分钟内该流以同一流 ID 重新推流成功，则自动恢复混流。
7. 如何获取录制的混流结果？
请参考录制文档 录制。
8. 为什么混流后的视频有黑边？
混流后有黑边有两种情况：1、原始流就有黑边；2、混流参数中的输出长宽比与原始流的长宽比不匹配。如混流期望的长宽比为16：9，原始视频长宽比为4：3，混流后台会在原始视频长宽比基础上补黑边，满足期望的16：9输出。
如果不希望产生黑边，也有两种方案，1、输出长宽比与输入长宽比一致。2、使用裁剪参数，请参考裁剪功能的使用方法。
9. 为什么混流的小主播画面有的时候与期望的位置不同？
这种情况一般是参与混流的输入源分辨率发生了变化引起的，例如，申请混流时，长宽为1280 * 720，过了一段时间后，流分辨率变为了2560 * 1440，这个时候，混流输出的画面就会发生改变，与期望的输出有区别。
不建议在混流过程中，变更输入流的分辨率，如确有需要，需计算位置参数后重新申请混流。
10. 混流输出是否支持 H265 编码？
混流目前只支持输出 H264 编码。即使输入流均为 H265 编码，输出流也以 H264 编码输出。
11. 取消混流后，再次取消，返回-30300错误?
取消混流接口只需要调用一次，成功后无需重复调用。
12. 混流过程中，输入流断开后何时自动取消混流？
以两条流混流为例，如果其中一条流断开，混流不会自动取消，如果开了录制，录制也将继续进行。如果两条流均断开，15分钟后混流自动取消。
13. 为何调用混流时，画面会出现回退？
混流转码实现机制中，会尽量保证双方画面的一致，因此在处理过程中会有轻微的回退现象。为避免这种情况对业务使用造成影响，如无特殊使用场景，请勿频繁调用混流接口。
14. 混流过程中，如果有主播下播，混流会自动更改混流布局吗？
15. 不会，混流调度不会修改客户的布局参数，如果有主播下播的业务场景，需要业务方自行重新计算布局参数，重新发起混流。
DEMO 下载
混流 demo 下载：请单击 此处 下载 demo。

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

参数名	参数含义	类型	备注
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 -3100 -31002	取消混流时 sessionid 不存在	检查 sessionid 是否存在。
-31003	输出流 ID 与 session 中输出流 ID 不匹配	检查取消混流时填入的输出流 ID。
-31004	输出流码率不合法	检查输出流码率是否在[1，50000]之间。
其他	其他错误，请联系客服提供技术支持	-

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

云端混流

本页目录：

接口描述

HTTP 协议请求接口 cgi

通过 URI 传递鉴权参数

混流参数

申请混流

接口返回

取消混流

云端混流功能说明

功能支持列表

常见云端场景示例

大主播与小主播连麦

主播 PK

多人会议/多人游戏

语音通话

常用布局模板说明

云端裁剪

自动混流

混流常见问题

DEMO 下载