旁路推流画面布局

更新时间: 2024/03/25 11:00:43

在配置旁路推流任务时,您可以自定义房间推流画面的布局,本文档为您介绍推流画面布局的设置方式和推荐设置。

功能介绍

网易云信互动直播产品提供简单易用的互动直播功能,当您通过各端 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,即黑色。支持以下格式的颜色码:

  • 256 ✖ 256 ✖ R + 256 ✖ G + B的和。请将对应 RGB 的值分别带入此公式计算即可。
  • 十六进制颜色码,即 #RRGGBB 或 RRGGBB 格式。例如 #CC00FF。

用户画面

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。

  • 最大值为 100,表示该区域图像位于最上层。
  • 最小值为 0(默认值),表示该区域图像位于最下层。
width Integer 该用户图像在画布中的宽度。
取值范围为 0~1920,若设置为奇数值,会自动向下取偶。
height Integer 该用户图像在画布中的高度。
取值范围为 0~1920,若设置为奇数值,会自动向下取偶。

adaption

Integer

用于设置占位图片和指定区域的适应属性。可设置为:

  • 0:适应图片。即保证视频内容全部显示,未覆盖区域默认填充背景色。
  • 1(默认):适应区域。即保证所有区域被填满,视频超出部分会被裁剪。若未设置或设置为非 0 和 1 的正整数,则取默认值 1。
    如果 adaption 设置为负数,NERTC 服务端会返回 414 错误。

pushAudio

Boolean

是否在直播中混流该用户的对应音频主流。可设置为:

  • true:在直播中混流该用户的对应音频主流。
  • false:在直播中将该用户音频主流设置为静音。若未设置,默认为 true。

pushVideo

Boolean

是否在直播中向观看者播放该用户的对应视频主流。可设置为:

  • true:在直播中播放该用户的视频主流。
  • false:在直播中不播放该用户的视频主流。若未设置,则默认为 true。

辅流布局

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

用于设置占位图片和指定区域的适应属性。可设置为:

  • 0:适应图片。即保证视频内容全部显示,未覆盖区域默认填充背景色。
  • 1(默认):适应区域。即保证所有区域被填满,视频超出部分会被裁剪。若未设置或设置为非 0 和 1 的正整数,则取默认值 1。
    如果 adaption 设置为负数,NERTC 服务端会返回 414 错误。

zOrder

Integer

直播视频上辅流视频的图层编号。取值范围为 0 ~ 100。

  • 最小值为 0(默认值),表示该区域图像位于最下层。
  • 最大值为 100,表示该区域图像位于最上层。

pushAudio

Boolean

是否在直播中混流该用户的对应音频辅流。可设置为:

  • true:在直播中混流该用户的对应音频辅流。
  • false:在直播中将该用户的音频辅流设置为静音。若未设置,默认为 true。

pushVideo

Boolean

是否在直播中向观看者播放该用户的对应视频辅流。可设置为:

  • true(默认):在直播中播放该用户的视频辅流。
  • false:在直播中不播放该用户的视频辅流。

占位图片

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

用于设置占位图片和指定区域的适应属性。可设置为:

  • 0:适应图片。即保证视频内容全部显示,未覆盖区域默认填充背景色。
  • 1(默认):适应区域。即保证所有区域被填满,视频超出部分会被裁剪。若未设置或设置为非 0 和 1 的正整数,则取默认值 1。
    如果 adaption 设置为负数,NERTC 服务端会返回 414 错误。

zOrder

Integer

直播视频上辅流视频的图层编号。取值范围为 0~100,默认为 0。

  • 最小值为 0(默认值),表示该区域图像位于最下层。
  • 最大值为 100,表示该区域图像位于最上层。
  1. users、subStreams 和 images 三个属性均支持设置 zOrder 参数,但在视窗有重叠部分的情况下,三者图层展示的优先顺序为 users > subStreams > images。
  2. images 支持最多设置 6 张图片。

默认辅流布局

如果房间中有成员开启了辅流形式的屏幕共享,即同时开启了摄像头和屏幕共享两路视频流,且您未设置 subStreams 参数,则旁路推流画面默认设置为以下辅流布局模式。您也可以通过 subStreams 参数调整辅流画面在直播画面中的位置。

默认辅流布局

如果您需要通过用户进入房间的顺序设置摄像头画面布局,在您的业务逻辑中,应根据用户进入房间顺序进行数值累加的方式生成 uid。

规则
说明
人数限制 合流视频画布上最多显示 5 个用户画面。

画面显示规则

如果某成员只发送音频,不发送视频,则不会显示在布局中。

  • 如果成员人数超出 5 人,仅显示 uid 最小的 5 名成员的画面;如果人员不足5人,则仅显示在线成员画面,无人区域留空,显示黑色。
  • 如果有成员退出房间,系统会自动按照新的 uid 排序,显示前 5 名成员画面。

布局规则

画布中包含主画面和次画面,主画面为屏幕共享视频,次画面为房间中uid 最小的 5 位成员摄像头视频,从小到大排序。

  • 当多个推流任务中多个用户开启辅流时,主画面默认显示 uid 最小的用户的辅流画面。
  • 如果您需要通过用户进入房间的顺序设置摄像头画面布局,在您的业务逻辑中,应根据用户进入房间顺序进行数值累加的方式生成 uid。
分辨率 画布外框为辅流分辨率,屏幕共享画面基于辅流分辨率自动缩放。

布局示例

以通过服务端 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 悬浮布局

双人横向平铺

  • 显示效果

    image

  • 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
    }]
}

三人纵向平铺

  • 显示效果

    image

  • 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 悬浮布局

  • 显示效果

    image

  • 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
        }]
    }
此文档是否对你有帮助?
有帮助
去反馈
  • 功能介绍
  • 限制说明
  • 设置画面布局
  • 背景画布
  • 用户画面
  • 辅流布局
  • 占位图片
  • 默认辅流布局
  • 布局示例
  • 请求示例
  • 效果展示
  • 常用布局设置
  • 双人横向平铺
  • 三人纵向平铺
  • 1 + N 悬浮布局