设置云端录制布局 - 音视频通话 2.0

开发者中心

音视频通话 2.0

服务端 API

设置云端录制布局

更新时间： 2025/06/11 18:16:33

本文主要介绍如何调用网易云信服务端接口设置云端录制的合流布局模式。通过控制台设置合流布局的步骤，请参考开通云端录制。

布局模式

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

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

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

支持通过 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 人

使用自定义布局

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

指定自定义布局

请在调用创建云端录制任务接口时，请求体参数设定要求如下：

设置录制布局模式参数 layoutConfig.layoutType 为 2，表示启用自定义布局。
设置录制布局配置参数 layoutConfig.layout，设计合流录制的画面布局，包括背景画布（canvas）、用户画面（users）、辅流画面（subStreams）和占位图片（images）的设置。

布局参数说明

layout 布局参数说明如下：

canvas 参数用于设置合流画面的背景画布属性，包括背景画布的高度、宽度和颜色。
users 参数用于设置合流画面中每个参与者对应的画面属性。
subStreams 参数用于设置合流画面中每个辅流画面的属性。
images 参数用于设置合流画面中的占位图片属性，包括占位图片的位置、适应性、图片 url 等。
- users、subStreams 和 images 三个属性均支持设置 zOrder 参数（即图层编号），但在视窗有重叠部分的情况下，三者图层展示的优先顺序为 users > subStreams > images。
- images 支持最多设置 6 张图片。

完整参数结构如下表所示。

参数名称	类型	是否必选	示例	说明
- canvas	JSON	是	-	用于设置混流视频的整体画布属性。
height	Integer	是	640	整体画布的高度，单位为 px。取值范围为 0~1920，若设置为奇数值，会自动向下取偶。
width	Integer	是	360	整体画布的宽度，单位为 px。取值范围为 0~1920，若设置为奇数值，会自动向下取偶。
color	Integer 或 String	否	#CC00FF	画面背景颜色，默认为 0，即黑色。支持以下格式的颜色码：整形：256 - 256 - R + 256 - G + B 的和。请将对应 RGB 的值分别带入此公式计算即可。字符型：十六进制颜色码，即 #RRGGBB 或 RRGGBB 格式。例如 #CC00FF。
- users	JSON 数组	是	-	用于设置混流视频中每个参与者对应的画面属性。用户窗口边界不能超出 canvas 画布。视频互动中，`users` 和 `subStreams` 的用户个数总和不超过 16。如果人数超限，可能会造成服务故障。
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	JSON 数组	否	-	用于设置混流视频中所有参与者发布的视频辅流对应的画面属性。开启辅流形式屏幕共享之后，辅流画面默认展示为指定布局样式，详细信息请参考存在辅流的模板布局。您也可以通过此参数调整每个辅流画面在直播画面中的位置。
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	JSON 数组	否	-	用于设置混流视频中占位图片属性。若参数 users 指定的用户未上线，会在其对应的区域展示占位图片。
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，表示该区域图像位于最上层。

设置视窗位置

使用自定义布局时，需要通过 x、y、width 和 height 设置元素的位置和区域大小，如下图所示：

自定义布局示例

实现此布局的 示例代码 如下：

JSON{
    "layoutConfig":{
    "layoutType":2,
    "layout":{
        "canvas": {
            "width": 1280,
            "height": 720,
            "color": "#CC00FF"
            },
        "users": [{
                "uid": 123,//主播 uid
                "x": 920,
                "y": 40,
                "width": 320,
                "height": 240,
                "adaption": 0,
                "zOrder": 1
            }],

        "subStreams":[{
                "uid": 123,//主播 uid
                "x": 40,
                "y": 160,
                "width": 640,
                "height": 480,
                "adaption": 0,
                "zOrder": 1

            }],
        "images": [{
                "url": "xxxxxx",
                "x": 920,
                "y": 340,
                "width": 320,
                "height": 240,
                "adaption": 0,
                "zOrder": 1
            }]
        }
    }
}

更新录制布局

您可以在录制任务创建后，通过调用更新录制布局接口修改录制布局配置。需要注意以下几点：

支持修改的场景：
- 仅支持自定义布局模式（layoutConfig.layoutType=2）的修改
- 支持两种任务类型：
  - 普通录制任务模式：recordConfig.recordType 取值为 0、1、2 时，且 layoutConfig.layoutType=2。
  - 模板文件集合模式：recordConfig.recordType 取值为 100 时，且 recodConfig.modeList[].layoutType=2。（招标采购场景主要采用该模式，有关这种业务场景的更多信息，请参考招采场景集成最佳实践）。
可修改的布局（layoutConfig.layout）参数：
- 可修改 layoutConfig.layout 中的 users、subStreams 和 images 参数。
- 无法修改 layoutConfig.layout.canvas 参数（一旦录制任务启动后不支持修改）。
- 对于 layoutType 不为 2 的布局，虽然接口允许修改相关参数，但由于这些参数实际不会被使用，所以修改没有实际作用。
- 修改布局时，请保持原有布局模式（layoutType）不变。

接口使用示例

更新录制布局时，您只需要在更新录制布局接口请求体中修改需要更新的布局参数，其余参数保持原云端录制任务的设置（可通过查询云端录制配置接口查询）：

JSON{
  // 其余参数保持原云端录制任务的设置
  "layoutConfig": {
    "layoutType": 2,
    "layout": {
      "users": [
        {
          "uid": 123,
          "x": 100,
          "y": 50,
          "width": 320,
          "height": 240,
          "adaption": 0,
          "zOrder": 2
        }
      ],
      "subStreams": [
        {
          "uid": 123,
          "x": 50,
          "y": 300,
          "width": 640,
          "height": 480,
          "adaption": 0,
          "zOrder": 1
        }
      ],
      "images": [
        {
          "url": "https://example.com/image.jpg",
          "x": 800,
          "y": 50,
          "width": 320,
          "height": 240,
          "adaption": 0,
          "zOrder": 1
        }
      ]
    }
  }
}

此文档是否对你有帮助？

有帮助

去反馈

布局模式
使用模板布局
画廊模式
主讲人模式
悬浮模式
垂直模式
存在辅流的模板布局
使用自定义布局
指定自定义布局
布局参数说明
设置视窗位置
自定义布局示例
更新录制布局