更新云端录制合流布局

开始录制后，你可以调用 updateLayout 方法更新合流布局。例如，在开始录制时设置了 backgroundColor 为 "#FF0000"（红色），调用 updateLayout 方法更新合流布局时如果不再设置 backgroundColor 参数，背景色就会变为黑色（默认值）。

每次调用该方法都会覆盖原来的布局设置。

• 方法：POST
• 接入点：/v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/sid/{sid}/mode/{mode}/updateLayout

使用须知

• 对于每个声网账号，每秒钟的请求数限制为 10 次。如需提高此限制，请联系技术支持。
• updateLayout 请求仅在会话内有效。如果录制启动错误，或录制已结束，调用 updateLayout 将返回 404。
• 如果需要连续调用 updateLayout 方法更新合流布局，请在收到上一次 updateLayout 响应后再进行调用，否则可能导致请求结果与预期不一致。

HTTP 请求

路径参数

该 API 需要在 URL 中传入以下参数。

请求头

• Content-Type: application/json
• Authorization: 该字段的值需参考认证说明。

请求包体

该 API 需要在请求包体中传入以下参数：

clientRequest

clientRequest 中需要填写的内容如下：

• maxResolutionUid：（选填）String 类型，如果 mixedVideoLayout 设为 2（垂直布局），用该参数指定显示大视窗画面的用户 ID。
• mixedVideoLayout：（选填）Number 类型，设置视频合流布局，0、1、2 为预设的合流布局，3 为自定义合流布局。该参数设为 3 时必须设置 layoutConfig 参数。
  • 0：（默认）悬浮布局。第一个加入频道的用户在屏幕上会显示为大视窗，铺满整个画布，其他用户的视频画面会显示为小视窗，从下到上水平排列，最多 4 行，每行 4 个画面，最多支持共 17 个画面。
  • 1：自适应布局。根据用户的数量自动调整每个画面的大小，每个用户的画面大小一致，最多支持 17 个画面。
  • 2：垂直布局。指定一个用户在屏幕左侧显示大视窗画面，其他用户的小视窗画面在右侧垂直排列，最多两列，一列 8 个画面，最多支持共 17 个画面。
  • 3：自定义布局。设置 layoutConfig 参数自定义合流布局。
• backgroundColor：（选填）String 类型。视频画布的背景颜色。支持 RGB 颜色表，字符串格式为 # 号后 6 个十六进制数。默认值 "#000000" 黑色。
• backgroundImage：（选填）String 类型。视频画布的背景图的 URL 地址。背景图的显示模式为裁剪模式。裁剪模式下，优先保证画面被填满。背景图尺寸等比缩放，直至整个画面被背景图填满。如果背景图长宽与显示窗口不同，则背景图会按照画面设置的比例进行周边裁剪后填满画面。
• defaultUserBackgroundImage：（选填）String 类型。默认的用户画面背景图的 URL 地址。配置该参数后，当任一⽤户停止发送视频流超过 3.5 秒，画⾯将切换为该背景图；如果针对某 UID 单独设置了背景图，则该设置会被覆盖。
• layoutConfig：（选填）JSON Array。由每个用户对应的布局画面设置组成的数组，支持最多 17 个用户画面。当 layoutType 设为 3 时，可以通过该参数自定义合流布局。一个用户画面设置包括以下参数：
  • uid：（选填）String 类型。字符串内容为待显示在该画面的用户的 UID，32 位无符号整数。如果不指定 UID，会按照用户加入频道的顺序自动匹配 layoutConfig 中的画面设置。
  • x_axis：Float 类型。屏幕里该画面左上角的横坐标的相对值，范围是 [0.0,1.0]。从左到右布局，0.0 在最左端，1.0 在最右端。x_axi 也可设置为整数 0 或 1。
  • y_axis：Float 类型。屏幕里该画面左上角的纵坐标的相对值，范围是 [0.0,1.0]。从上到下布局，0.0 在最上端，1.0 在最下端。y_axi 也可设置为整数 0 或 1。
  • width：Float 类型。该画面宽度的相对值，取值范围是 [0.0,1.0]。width 也可设置为整数 0 和 1。
  • height：Float 类型。该画面高度的相对值，取值范围是 [0.0,1.0]。height 也可设置为整数 0 和 1。
  • alpha：（选填）Float 类型。图像的透明度。取值范围是 [0.0,1.0] 。默认值 1.0。0.0 表示图像为透明的，1.0 表示图像为完全不透明的。
  • render_mode：（选填）Number 类型。画面显示模式：
    • 0：（默认）裁剪模式。优先保证画面被填满。视频尺寸等比缩放，直至整个画面被视频填满。如果视频长宽与显示窗口不同，则视频流会按照画面设置的比例进行周边裁剪或图像拉伸后填满画面。
    • 1：缩放模式。优先保证视频内容全部显示。视频尺寸等比缩放，直至视频窗口的一边与画面边框对齐。如果视频尺寸与画面尺寸不一致，在保持长宽比的前提下，将视频进行缩放后填满画面，缩放后的视频四周会有一圈黑边。
• backgroundConfig：（选填）JSON Array。数组内容为各 UID 单独的背景图设置。
  • uid：String 类型。用户 UID。
  • image_url：String 类型。该 UID 的背景图的 URL 地址。配置背景图后，当该⽤户停止发送视频流超过 3.5 秒，画⾯将切换为该背景图。
  • render_mode：（选填）Number 类型。画面显示模式。
    • 0：（默认）裁剪模式。优先保证画面被填满。背景图尺寸等比缩放，直至整个画面被背景图填满。如果背景图长宽与显示窗口不同，则背景图会按照画面设置的比例进行周边裁剪后填满画面。
    • 1：缩放模式。优先保证背景图内容全部显示。背景图尺寸等比缩放，直至背景图的一边与画面边框对齐。如果背景图尺寸与画面尺寸不一致，在保持长宽比的前提下，将背景图进行缩放后填满画面，缩放后的背景图四周会有一圈黑边。

请求示例

• 请求 URL：

    https://api.sd-rtn.com/v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/sid/{sid}/mode/{mode}/updateLayout

• Content-type 为 application/json;charset=utf-8
• Authorization 为 Basic authorization，生成方法请参考 RESTful API 认证。
• 请求包体内容：

更新合流布局

{
    "cname":"httpClient463224",
    "uid":"527841",
    "clientRequest":{
        "mixedVideoLayout":3,
        "backgroundColor":"#FF0000",
        "layoutConfig":[
            {
                "uid":"1",
                "x_axis":0.1,
                "y_axis":0.1,
                "width":0.1,
                "height":0.1,
                "alpha":1,
                "render_mode":1
            },
            {
                "uid":"2",
                "x_axis":0.2,
                "y_axis":0.2,
                "width":0.1,
                "height":0.1,
                "alpha":1,
                "render_mode":1
            }
        ]
    }
}

HTTP 响应

如果返回的 HTTP 状态码为 200，表示请求成功，响应包体中包含以下字段：

• resourceId：String 类型，云端录制使用的 resource ID。
• sid：String 类型，录制 ID。标识一次录制周期。

如果 HTTP 状态码不为 200，请参考响应状态码排查问题。

响应示例

{
    "resourceId":"JyvK8nXHuV1BE64GDkAaBGEscvtHW7v8BrQoRPCHxmeVxwY22-x-kv4GdPcjZeMzoCBUCOr9q-k6wBWMC7SaAkZ_4nO3JLqYwM1bL1n6wKnnD9EC9waxJboci9KUz2WZ4YJrmcJmA7xWkzs_L3AnNwdtcI1kr_u1cWFmi9BWAWAlNd7S7gfoGuH0tGi6CNaOomvr7-ILjPXdCYwgty1hwT6tbAuaW1eqR0kOYTO0Z1SobpBxu1czSFh1GbzGvTZG",
    "sid":"38f8e3cfdc474cd56fc1ceba380d7e1a"
}