录制布局 - 音视频通话 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，表示该区域图像位于最上层。