旁路推流画面布局
更新时间: 2023/07/13 02:47:56
在配置旁路推流任务时,您可以自定义房间推流画面的布局,本文档为您介绍推流画面布局的设置方式和推荐设置。
功能介绍
网易云信互动直播产品提供简单易用的互动直播功能,当您通过各端 SDK 实现音视频通话后,可以将房间画面进行旁路推流和录制,即将实时音视频流转为标准直播流,进行互动直播。首先在云端进行混流、转码、编码等操作,然后生成旁路转推的视频流,并推送到视频直播中进行大规模下行加速的直播观看。如果您开通了点播服务,也可以将直播内容录制并保存到点播服务中,随时观看回放。
设置旁路推流任务时,可以自定义推流画面的各路视频流的布局方式,例如调整整张画布(Canvas)的大小和颜色,以及各路视频主、辅流的图像大小、位置等。
限制说明
- 用户窗口边界不能超出 canvas 画布。
- 视频互动的画面布局中,最多 7 人参与;纯语音互动最多 21 人。如果人数超限,可能会造成服务故障。
- 如果有一位或多位房间成员开启了辅流形式的屏幕共享,即同时开启了摄像头和屏幕共享两路视频流,画面布局默认为指定辅流布局模式,您也可以通过
subStreams
参数调整各个辅流视频的画面位置。
设置画面布局
您可以通过客户端 API 接口或服务端 API 接口的 layout
参数设置旁路推流的画面布局。
网易云信 NERTC 为您提供 layout 参数一键生成工具。在调用接口设置画面布局之前,您可以通过该工具在线配置旁路推流的画面布局,工具会根据您的布局配置,自动生成对应 JSON 格式的配置参数,帮助您快速配置 layout
参数。
背景画布
canvas
参数用于设置混流视频的背景画布属性,包括背景画布的高度、宽度和颜色。
参数名称 | 类型 | 描述 |
---|---|---|
height | Integer | 整体画布的高度,单位为 px。取值范围为 0~1920,若设置为奇数值,会自动向下取偶。 |
width | Integer | 整体画布的宽度,单位为 px。取值范围为 0~1920,若设置为奇数值,会自动向下取偶。 |
color |
Integer |
画面背景颜色,默认为 0,即黑色。支持以下格式的颜色码:
|
用户画面
users
参数用于设置混流视频中每个参与者对应的画面属性。
参数名称 | 类型 | 描述 |
---|---|---|
uid | Integer | 将指定 uid 对应用户的视频主流拉入直播。 如果添加多个 users,则 uid 不能重复。 |
x | Integer | 通过 x 和 y 指定画布坐标中的一个点,该点将作为用户图像的左上角。 x 参数用于设置画布的横轴坐标值。 取值范围为 0~1920,若设置为奇数值,会自动向下取偶。 |
y | Integer | 通过 x 和 y 指定画布坐标中的一个点,该点将作为用户图像的左上角。 y 参数用于设置画布的纵轴坐标值。 取值范围为 0~1920,若设置为奇数值,会自动向下取偶。 |
zOrder |
Integer |
直播视频上用户视频帧的图层编号。取值范围为 0~100,默认为 0。
|
width | Integer | 该用户图像在画布中的宽度。 取值范围为 0~1920,若设置为奇数值,会自动向下取偶。 |
height | Integer | 该用户图像在画布中的高度。 取值范围为 0~1920,若设置为奇数值,会自动向下取偶。 |
adaption |
Integer |
用于设置占位图片和指定区域的适应属性。可设置为:
|
pushAudio |
Boolean |
是否在直播中混流该用户的对应音频主流。可设置为:
|
pushVideo |
Boolean |
是否在直播中向观看者播放该用户的对应视频主流。可设置为:
|
辅流布局
subStreams
参数用于设置混流视频中所有参与者发布的视频辅流对应的画面属性。
当房间内有用户开启辅流形式的屏幕共享后,若您未通过 subStreams
参数设置辅流画面的属性,则房间的旁路推流画面默认展示为默认辅流布局。
参数名称 | 类型 | 描述 |
---|---|---|
uid | Integer | 将指定 uid 对应用户发布的辅流拉入直播。 如果添加多个 subStreams,则 uid 不能重复。 |
x | Integer | 通过 x 和 y 指定画布坐标中的一个点,该点将作为辅流视频的左上角。 x 参数用于设置画布的横轴坐标值。 取值范围为 0 ~ 1920,若设置为奇数值,会自动向下取偶。 |
y | Integer | 通过 x 和 y 指定画布坐标中的一个点,该点将作为辅流视频的左上角。 y 参数用于设置画布的纵轴坐标值。 取值范围为 0 ~ 1920,若设置为奇数值,会自动向下取偶。 |
width | Integer | 该辅流视频在画布中的宽度。 取值范围为 0 ~ 1920,若设置为奇数值,会自动向下取偶。 |
height | Integer | 该辅流视频在画布中的高度。 取值范围为 0 ~ 1920,若设置为奇数值,会自动向下取偶。 |
adaption |
Integer |
用于设置占位图片和指定区域的适应属性。可设置为:
|
zOrder |
Integer |
直播视频上辅流视频的图层编号。取值范围为 0 ~ 100。
|
pushAudio |
Boolean |
是否在直播中混流该用户的对应音频辅流。可设置为:
|
pushVideo |
Boolean |
是否在直播中向观看者播放该用户的对应视频辅流。可设置为:
|
占位图片
images
用于设置混流视频中的占位图片属性,包括占位图片的位置、适应性、url 等。
参数名称 | 类型 | 描述 |
---|---|---|
url | String | 占位图片的URL。 |
x | Integer | 通过 x 和 y 指定画布坐标中的一个点,该点将作为占位图片的左上角。 x 参数用于设置画布的横轴坐标值。 取值范围为 0~1920,若设置为奇数值,会自动向下取偶。 |
y | Integer | 通过 x 和 y 指定画布坐标中的一个点,该点将作为占位图片的左上角。 y 参数用于设置画布的纵轴坐标值。 取值范围为 0~1920,若设置为奇数值,会自动向下取偶。 |
width | Integer | 该占位图片在画布中的宽度。 取值范围为 0~1920,若设置为奇数值,会自动向下取偶。 |
height | Integer | 该占位图片在画布中的高度。 取值范围为 0~1920,若设置为奇数值,会自动向下取偶。 |
adaption |
Integer |
用于设置占位图片和指定区域的适应属性。可设置为:
|
zOrder |
Integer |
直播视频上辅流视频的图层编号。取值范围为 0~100,默认为 0。
|
- users、subStreams 和 images 三个属性均支持设置 zOrder 参数,但在视窗有重叠部分的情况下,三者图层展示的优先顺序为 users > subStreams > images。
- images 支持最多设置 6 张图片。
默认辅流布局
如果房间中有成员开启了辅流形式的屏幕共享,即同时开启了摄像头和屏幕共享两路视频流,且您未设置 subStreams
参数,则旁路推流画面默认设置为以下辅流布局模式。您也可以通过 subStreams
参数调整辅流画面在直播画面中的位置。
规则 |
说明 |
---|---|
人数限制 | 合流视频画布上最多显示 5 个用户画面。 |
画面显示规则 |
如果某成员只发送音频,不发送视频,则不会显示在布局中。
|
布局规则 |
画布中包含主画面和次画面,主画面为屏幕共享视频,次画面为房间中uid 最小的 5 位成员摄像头视频,从小到大排序。
|
分辨率 | 画布外框为辅流分辨率,屏幕共享画面基于辅流分辨率自动缩放。 |
布局示例
以通过服务端 API 创建推流任务为例,为您展示通过服务端 API 接口的 layout
参数设置旁路推流画面布局的方式。
请求示例
在本示例中,音视频房间中有两位主播/连麦者,其推流画面布局为横向左右均分布局,原始画布为深灰色,其中一人掉线后显示占位图片。
{
"taskId" : "stream_1",
"streamUrl": "rtmp://test.url",
"layout":{
"canvas": {
"width": 720,
"height": 640,
"color": 16777215
},
"users": [{
"uid": 66601,
"x": 0,
"y": 0,
"width": 360,
"height": 640,
"adaption": 1,
"pushAudio": true,
"pushVideo": true
},
{
"uid": 66602,
"x": 360,
"y": 0,
"width": 360,
"height": 640,
"adaption": 1,
"pushAudio": true,
"pushVideo": true
}
],
"images": [{
"url": "www.163.com/test.jpg",
"x": 360,
"y": 0,
"width": 360,
"height": 640,
"adaption": 1
}]
},
"record":true,
"version": 1,
"config": {
"singleVideoNoTrans": true,
"audioParam": {
"bitRate": 64
}
}
}
}
效果展示
-
原始画布:
-
增加占位图片:
-
正常显示画面:
-
右侧用户断线:
-
左侧用户断线:
常用布局设置
互动直播支持自定义配置视频布局,您也可以参考以下典型的常用布局配置,优化您的自定义布局。
- 双人横向平铺布局
- 三人纵向平铺
- 1 + N 悬浮布局
双人横向平铺
-
显示效果
-
layout参数配置示例
{
"canvas": {
"width": 640,
"height": 360,
"color": 16777215
},
"users": [{
"uid": 66601,
"x": 0,
"y": 0,
"width": 320,
"height": 360
},
{
"uid": 66602,
"x": 320,
"y": 0,
"width": 320,
"height": 360
}
],
"images": [{
"url": "www.163.com/test.jpg",
"x": 360,
"y": 0,
"width": 360,
"height": 640,
"adaption": 1
}]
}
三人纵向平铺
-
显示效果
-
layout 参数配置示例
{
"canvas": {
"width": 360,
"height": 640,
"color": 16777215
},
"users": [{
"uid": 123,
"x": 0,
"y": 0,
"width": 360,
"height": 640
},
{
"uid": 456,
"x": 0,
"y": 320,
"width": 180,
"height": 320
},
{
"uid": 789,
"x": 180,
"y": 320,
"width": 180,
"height": 320
}
],
"images": [{
"url": "www.163.com/test.jpg",
"x": 360,
"y": 0,
"width": 360,
"height": 640,
"adaption": 1
}]
}
1 + N 悬浮布局
-
显示效果
-
layout 参数配置示例
{
"canvas": {
"width": 360,
"height": 640,
"color": 16777215
},
"users": [{
"uid": 123,
"x": 0,
"y": 0,
"width": 360,
"height": 640,
"adaption": 1
},
{
"uid": 456,
"x": 45,
"y": 390,
"width": 110,
"height": 213
},
{
"uid": 789,
"x": 185,
"y": 390,
"width": 110,
"height": 213
}
],
"images": [{
"url": "www.163.com/test.jpg",
"x": 360,
"y": 0,
"width": 360,
"height": 640,
"adaption": 1
}]
}