录制布局 - 音视频通话 2.0

开发者中心

音视频通话 2.0

服务端 API

录制布局

更新时间： 2024/03/25 11:00:41

本文主要介绍云端录制的合流布局模式。

功能介绍

云端录制的合流录制模式会进行合流转码，将多路音视频流混合成一路。在合流录制中，您需要设置用户视频画面大小及其在视频画布上的位置，即合流录制布局。

云端录制的合流录制模式支持两类合流录制布局：

录制布局	预设模板	描述
模板布局	仅包含主流时，模板布局支持：画廊模式主讲人模式悬浮模式垂直模式	使用系统预设的模板设置用户主流画面的大小和位置。若录制订阅名单中的成员开启了视频辅流（例如共享屏幕），该模版布局将失效。
模板布局	存在辅流的模版布局	若录制订阅名单中的成员开启了视频辅流（例如共享屏幕），系统会统一使用该模版布局。
自定义布局	-	您可以灵活设置主流和辅流在画面中的位置，还可以设置画布背景颜色、占位图等。

注意事项

支持通过 RESTful API 或控制台设置合流布局模式。
若您在控制台设置了布局模式，在调用创建云端录制任务 RESTful API 时，同时也设置了 layoutType 参数，则优先采用 RESTful API 接口中的设置。

使用模板布局

请在调用创建云端录制任务 RESTful API 时，通过录制布局配置参数 layoutType 选择一种预设的布局模式。出于不同业务场景的需求，云端录制服务提供五种预设的合流录制布局：

模板布局	参数设置	布局描述
画廊模式	layoutType = 0	多人加入时，用户画面平铺在画布上，并按照具体的人数平分整体画布，每个用户画面加载区域大小一致。
主讲人模式	layoutType = 1	设置某用户为主讲人，主讲人在画布上会显示为大视窗，铺满整个画布；其他用户的小视窗画面悬浮于主画面之上，展示方式根据房间总人数而定，不同人数区间展示为不同布局。最多支持共 9 个用户画面。
悬浮模式	layoutType = 3	主讲人在画布上会显示为大视窗，铺满整个画布；其他用户按照加入的顺序从画布左下角开始依次水平排列，显示为小视窗，最多 2 行，每行 4 个画面。小视窗会悬浮在大视窗底部。最多支持共 9 个用户画面。
垂直模式	layoutType = 4	主讲人在画布左侧会显示为大视窗；其他用户的小视窗画面在右侧垂直排列，最多两列，每列最多 4 个画面。最多支持共 9 个用户画面。
存在辅流的模版布局	layoutType = 0、1、3 或 4 时，若录制订阅名单中的成员开启了视频辅流，您设置的模版布局将失效，系统会统一使用存在辅流的模版布局。	辅流的画面内容铺满整个画布，单用户的小视窗画面悬浮在窗口右上角；或者辅流的画面内容在画布上方显示为大视窗，所有用户的小视窗画面在下方依次水平排列。最多支持共 5 个用户画面。

若您不希望因辅流的存在改变原先设置的布局模式，建议您使用自定义布局灵活设置主流和辅流在画面中的位置，以避免辅流带来的影响。

画廊模式

多人加入时，成员画面平铺在画布上，并按照具体的人数平分整体画布，每个成员画面加载区域大小一致。

画廊模式布局规则如下：

规则	说明
人数限制	合流视频画布上最多显示 9 个用户画面。
画面显示规则	如果某成员只发送音频，不发送视频，则不会被编号或显示在布局中。如果成员人数超出 9 人，仅显示前 9 名成员的画面。如果人员不足，则空位画面留空，显示背景色。如果有成员退出房间，系统会自动按照后续用户加入房间的顺序对空位画面进行补位。
布局规则	当房间成员人数为 1~2 人时，采用二分视频布局。当房间成员人数为 3~4 人时，采用四宫格视频布局。当房间成员人数为 5 人及以上时，采用九宫格视频布局，但仅显示服务端接收到的前 9 个视频流。
画面自适应	如果实际视频流的宽高比与视窗的宽高比不一致，视频画面会缩放以适应视窗的大小。
录制分辨率	可通过控制台在指定应用的功能配置里设置为竖屏（480x720）或横屏（720x480）。
成员占位顺序	按照成员加入房间的顺序为其编号。当有用户发布屏幕共享或自定义视频时，也按照其次序依次展现在指定位置上。

效果图展示如下：

1~2人	3~4人	5人及以上

主讲人模式

设置某成员为主讲人，主讲人的画面为画布中的主画面，显示区域为整个画布。房间中的其余成员画面悬浮于主画面之上，展示方式根据房间总人数而定，不同人数区间展示为不同布局。

规则	说明
人数限制	合流视频画布上最多显示 9 个用户画面。
画面显示规则	如果某成员只发送音频，不发送视频，则不会被编号或显示在布局中。如果成员人数超出 9 人，仅显示前 9 名成员的画面。如果人员不足，则多出的编号对应的画面留空，显示背景色。如果有成员退出房间，系统会自动按照后续用户加入房间的顺序对空白画面进行补位。
主讲人设置	如果录制任务中设置了主讲人，在主讲人加入之前，取第一个加入的成员作为主画面；主讲人加入之后，主讲人占据混屏主画面，原主画面成员按照动态自适应模式分配到其他位置；如果主讲人中途退出或关闭视频，则在其他成员中随机选取一个作为主画面。如果主讲人只发送音频，不发送视频，则将第一个加入的非主讲人成员画面设为主画面。如果未设置主讲人，则将第一个加入房间的成员作为主讲人。
画面自适应	如果实际视频流的宽高比与视窗的宽高比不一致，视频画面会缩放以适应视窗的大小。
录制分辨率	采用主讲人的视频分辨率。
成员编号顺序	按照成员加入房间的顺序为其编号。当有用户发布屏幕共享或自定义视频时，也按照其次序依次展现在指定位置上。

效果图展示如下：

1~2人	3~4人	5人及以上

悬浮模式

主讲人的画面在屏幕上会显示为大视窗，铺满整个画布；其他用户按照加入的顺序从画布左下角开始依次水平排列，显示为小视窗，最多 2 行，每行 4 个画面。小视窗悬浮在大视窗之上。

悬浮模式仅支持通过纯服务端方案进行配置，即仅通过调用创建录制任务接口来设置。
如果通过 layoutConfig.hostUid 参数设置了主讲人，则主讲人始终显示为大视窗。但该主讲人必须发布视频流，否则设置无效，即若通过 layoutConfig.hostUid 设置某未发布视频流的成员为主讲人，该成员不会显示为大视窗。如果未设置主讲人，则将第一个加入房间的发布视频流的成员视为主讲人。

规则	说明
人数限制	合流视频画布上最多显示 9 个用户画面。
画面显示规则	如果某成员只发送音频，不发送视频，则不会被编号或显示在布局中。如果成员人数超出 9 人，仅显示前 9 名成员的画面。如果人员不足，则空位画面留空，显示背景色。如果有成员退出房间，系统会自动按照后续用户加入房间的顺序对空位画面进行补位。
布局规则	当房间成员人数为 1 人时，仅显示此人的大视窗。当房间人数为 2 ~ 5 人时，第 2 ~ 5 人为小视窗，且悬浮于 1 的大视窗底部。当房间成员人数为 6 ~ 9 人时，第 2 ~ 9人为小视窗，分两排悬浮于 1 的大视窗底部。
主讲人设置	如果录制任务中设置了主讲人，在主讲人加入之前，取第一个加入的发布视频流的成员作为主画面；主讲人加入之后，主讲人占据混屏主画面，原主画面成员按照动态自适应模式分配到其他位置；如果主讲人中途退出或关闭视频，则在其他发布视频流的成员中随机选取一个作为主画面。如果主讲人只发送音频，不发送视频，则将第一个加入的发布视频流的非主讲人成员画面设为主画面。如果未设置主讲人，则将第一个加入房间的发布视频流的成员作为主讲人。
画面自适应	如果实际视频流的宽高比与视窗的宽高比不一致，视频画面会缩放以适应视窗的大小。
录制分辨率	采用主讲人的视频分辨率。
成员占位顺序	按照成员加入房间的顺序为其编号。当有用户发布屏幕共享或自定义视频时，也按照其次序依次展现在指定位置上。

效果图展示如下：

1~2人	2~5人	6人及以上

垂直模式

垂直模式仅支持通过纯服务端方案进行配置，即仅通过调用创建录制任务接口来设置。
如果通过 layoutConfig.hostUid 参数设置了主讲人，则主讲人始终显示为大视窗。但该主讲人必须发布视频流，否则设置无效，即若通过 layoutConfig.hostUid 设置某未发布视频流的成员为主讲人，该成员不会显示为大视窗。如果未设置主讲人，则将第一个加入房间的发布视频流的成员视为主讲人。

规则	说明
人数限制	合流视频画布上最多显示 9 个用户画面。
画面显示规则	如果某成员只发送音频，不发送视频，则不会被编号或显示在布局中。如果成员人数超出 9 人，仅显示前 9 名成员的画面。如果人员不足，则空位画面留空，显示背景色。如果有成员退出房间，系统会自动按照后续用户加入房间的顺序对空位画面进行补位。
布局规则	当房间成员人数为 1 人时，仅显示此人的大视窗。当房间人数为 2 ~ 5 人时，第 2 ~ 5 人为小视窗，在右侧垂直排成一列。当房间成员人数为 6 ~ 9 人时，第 2 ~ 9 人为小视窗，在右侧垂直排成两列。
主讲人设置	如果录制任务中设置了主讲人，在主讲人加入之前，取第一个加入的发布视频流的成员作为主画面；主讲人加入之后，主讲人占据混屏主画面，原主画面成员按照动态自适应模式分配到其他位置；如果主讲人中途退出或关闭视频，则在其他发布视频流的成员中随机选取一个作为主画面。如果主讲人只发送音频，不发送视频，则将第一个加入的发布视频流的非主讲人成员画面设为主画面。如果未设置主讲人，则将第一个加入房间的发布视频流的成员作为主讲人。
画面自适应	如果实际视频流的宽高比与视窗的宽高比不一致，视频画面会缩放以适应视窗的大小。
录制分辨率	采用主讲人的视频分辨率。
成员占位顺序	按照成员加入房间的顺序为其编号。当有用户发布屏幕共享或自定义视频时，也按照其次序依次展现在指定位置上。

效果图展示如下：

1~2人	2~5人	6人及以上

存在辅流的模板布局

当通话中存在辅流时，已设置的仅包含主流的模板布局不生效,录制的布局模式自动切换为存在辅流的模板布局。辅流场景的布局效果图如下。

在用户关闭辅流后，录制布局会自动切换回原先设置的模板布局。
教育场景中，若您需要将单人的主流、辅流分别录制，同时生成两个录制文件，请联系网易云信技术支持。

规则	说明
人数限制	合流视频画布上最多显示 5 个用户画面。
画面显示规则	如果某成员只发送音频，不发送视频，则不会被编号或显示在布局中。如果成员人数超出 5 人，仅显示前 5 名成员的画面。如果人员不足，则多处的编号对应的画面留空，显示背景色。如果有成员退出房间，系统会自动按照后续用户加入房间的顺序对空白画面进行补位。
布局规则	当房间成员人数为 1 人时，辅流的画面内容占满整屏，用户画面悬浮在窗口右上角。当房间人数为 2 ~ 5 人时，屏幕上方显示辅流的画面内容，在窗口底部展示 1 ~ 5 人的小视窗。
主讲人设置	按用户布局设置生效。非画廊模式时，主讲人配置生效。
画面自适应	如果实际视频流的宽高比与视窗的宽高比不一致，视频画面会缩放以适应视窗的大小。
录制分辨率	采用辅流的视频分辨率。
成员编号顺序	按照成员加入房间的顺序为其编号。

效果图展示如下：

1人	2~5人

使用自定义布局

使用自定义布局模式，您可以根据需求灵活设置视频画面的大小和位置。

请在调用创建云端录制任务 RESTful API 时，设置录制布局配置参数 layoutType 为 2（表示自定义布局），同时传入 layout 参数设置合流录制的画面布局，包括背景画布、用户画面、辅流画面和占位图片的设置。

layout的参数说明如下表所示。

参数名称	类型	是否必选	描述
canvas	JSON	必选	用于设置混流视频的整体画布属性。详细参数说明请参见设置背景画布。
users	JSON 数组	必选	用于设置混流视频中每个参与者对应的画面属性。详细参数说明请参见设置用户画面。用户窗口边界不能超出 canvas 画布。视频互动中，`users` 和 `subStreams` 的用户个数总和不超过 16。如果人数超限，可能会造成服务故障。
subStreams	JSON 数组	可选	用于设置混流视频中所有参与者发布的视频辅流对应的画面属性。开启辅流形式屏幕共享之后，辅流画面默认展示为指定布局样式，详细信息请参考存在辅流的模板布局。您也可以通过此参数调整每个辅流画面在直播画面中的位置。详细参数说明请参见设置辅流画面。
images	JSON 数组	可选	用于设置混流视频中占位图片属性。若参数 users 指定的用户未上线，会在其对应的区域展示占位图片。详细参数说明请参见设置占位图片。

设置背景画布

canvas 参数用于设置合流画面的背景画布属性，包括背景画布的高度、宽度和颜色。

参数名称	类型	是否必选	示例	描述
height	Integer	必选	640	整体画布的高度，单位为 px。取值范围为 0~1920，若设置为奇数值，会自动向下取偶。
width	Integer	必选	360	整体画布的宽度，单位为 px。取值范围为 0~1920，若设置为奇数值，会自动向下取偶。
color	Integer	可选	#CC00FF	画面背景颜色，默认为 0，即黑色。支持以下格式的颜色码： 256 ✖ 256 ✖ R + 256 ✖ G + B的和。请将对应 RGB 的值分别带入此公式计算即可。十六进制颜色码，即 #RRGGBB 或 RRGGBB 格式。例如 #CC00FF。

参数名称

类型

是否必选

示例

描述

height

Integer

必选

640

整体画布的高度，单位为 px。取值范围为 0~1920，若设置为奇数值，会自动向下取偶。

width

Integer

必选

360

整体画布的宽度，单位为 px。取值范围为 0~1920，若设置为奇数值，会自动向下取偶。

color

Integer

可选

#CC00FF

画面背景颜色，默认为 0，即黑色。支持以下格式的颜色码：

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

设置用户画面

users 参数用于设置合流画面中每个参与者对应的画面属性。

参数名称	类型	是否必选	示例	描述
uid	Integer	可选	1111	为指定 uid 的用户设置主流布局。如果添加多个 users，则 uid 不能重复。如果不填 uid，则按照视频用户的加入顺序占位贴图。
x	Integer	必选	0	通过 x 和 y 指定画布坐标中的一个点，该点将作为用户图像的左上角。 x 参数用于设置画布的横轴坐标值。取值范围为 0~1920，若设置为奇数值，会自动向下取偶。
y	Integer	必选	0	通过 x 和 y 指定画布坐标中的一个点，该点将作为用户图像的左上角。 y 参数用于设置画布的纵轴坐标值。取值范围为 0~1920，若设置为奇数值，会自动向下取偶。
zOrder	Integer	可选	1	自定义布局上用户视频画面的图层编号。取值范围为 0~100，默认为 0。最大值为 100，表示该区域图像位于最上层。最小值为 0（默认值），表示该区域图像位于最下层。
width	Integer	必选	360	该用户图像在画布中的宽度。取值范围为 0~1920，若设置为奇数值，会自动向下取偶。
height	Integer	必选	360	该用户图像在画布中的高度。取值范围为 0~1920，若设置为奇数值，会自动向下取偶。
adaption	Integer	可选	1	用于设置占位图片和指定区域的适应属性。可设置为： 0：适应图片。即保证视频内容全部显示，未覆盖区域默认填充背景色。 1：适应区域。即保证所有区域被填满，视频超出部分会被裁剪。若未设置或设置为非 0 和 1 的正整数，则取默认值 1。如果 adaption 设置为负数，NERTC 服务端会返回 414 错误。

设置辅流画面

subStreams 参数用于设置合流画面中每个辅流画面的属性。

参数名称	类型	是否必选	示例	描述
uid	Integer	可选	1111	为指定 uid 的用户设置辅流布局。如果添加多个 users，则 uid 不能重复。如果不填 uid，则按照视频用户的加入顺序占位贴图。
x	Integer	必选	360	通过 x 和 y 指定画布坐标中的一个点，该点将作为辅流视频的左上角。 x 参数用于设置画布的横轴坐标值。取值范围为 0~1920，若设置为奇数值，会自动向下取偶。
y	Integer	必选	0	通过 x 和 y 指定画布坐标中的一个点，该点将作为辅流视频的左上角。 y 参数用于设置画布的纵轴坐标值。取值范围为 0~1920，若设置为奇数值，会自动向下取偶。
width	Integer	必选	360	该辅流视频在画布中的宽度。取值范围为 0~1920，若设置为奇数值，会自动向下取偶。
height	Integer	必选	640	该辅流视频在画布中的高度。取值范围为 0~1920，若设置为奇数值，会自动向下取偶。
adaption	Integer	可选	1	用于设置占位图片和指定区域的适应属性。可设置为： 0：适应图片。即保证视频内容全部显示，未覆盖区域默认填充背景色。 1：适应区域。即保证所有区域被填满，视频超出部分会被裁剪。若未设置或设置为非 0 和 1 的正整数，则取默认值 1。如果 adaption 设置为负数，NERTC 服务端会返回 414 错误。
zOrder	Integer	可选	1	自定义布局上辅流视频的图层编号。取值范围为 0~100，默认为 0。最小值为 0（默认值），表示该区域图像位于最下层。最大值为 100，表示该区域图像位于最上层。

设置占位图片

images 用于设置合流画面中的占位图片属性，包括占位图片的位置、适应性、url 等。

参数名称	类型	是否必选	示例	描述
url	String	必选	www.163.com/test.jpg	占位图片的 URL。
x	Integer	必选	360	通过 x 和 y 指定画布坐标中的一个点，该点将作为占位图片的左上角。 x 参数用于设置画布的横轴坐标值。取值范围为 0~1920，若设置为奇数值，会自动向下取偶。
y	Integer	必选	0	通过 x 和 y 指定画布坐标中的一个点，该点将作为占位图片的左上角。 y 参数用于设置画布的纵轴坐标值。取值范围为 0~1920，若设置为奇数值，会自动向下取偶。
width	Integer	必选	360	该占位图片在画布中的宽度。取值范围为 0~1920，若设置为奇数值，会自动向下取偶。
height	Integer	必选	640	该占位图片在画布中的高度。取值范围为 0~1920，若设置为奇数值，会自动向下取偶。
adaption	Integer	可选	1	用于设置占位图片和指定区域的适应属性。可设置为： 0：适应图片。即保证视频内容全部显示，未覆盖区域默认填充背景色。 1：适应区域。即保证所有区域被填满，视频超出部分会被裁剪。若未设置或设置为非 0 和 1 的正整数，则取默认值 1。如果 adaption 设置为负数，NERTC 服务端会返回 414 错误。
zOrder	Integer	可选	1	直播视频上辅流视频的图层编号。取值范围为 0~100，默认为 0。最小值为 0（默认值），表示该区域图像位于最下层。最大值为 100，表示该区域图像位于最上层。

users、subStreams 和 images 三个属性均支持设置 zOrder 参数，但在视窗有重叠部分的情况下，三者图层展示的优先顺序为 users > subStreams > images。
images 支持最多设置 6 张图片。

通过控制台设置合流布局

该功能将逐步废弃并下线，建议您使用服务端提供的 RESTful API 设置合流布局，不推荐使用控制台进行相关配置。

通过控制台设置合流布局的步骤请参见配置云端录制布局。

此文档是否对你有帮助？

有帮助

去反馈

功能介绍
注意事项
使用模板布局
画廊模式
主讲人模式
悬浮模式
垂直模式
存在辅流的模板布局
使用自定义布局
设置背景画布
设置用户画面
设置辅流画面
设置占位图片
相关参考
设置视窗位置
布局示例
通过控制台设置合流布局

功能介绍

注意事项

使用模板布局

画廊模式

主讲人模式

悬浮模式

垂直模式

存在辅流的模板布局

使用自定义布局

设置背景画布

设置用户画面

设置辅流画面

设置占位图片

相关参考

设置视窗位置

布局示例

通过控制台设置合流布局