文档中心
云端录制
Console Agora.io 社区 提交工单
简体中文
search-icon

更新云端录制

更新时间 2022/01/13 07:44:32

在云端录制过程中，你可以调用 update 方法更新云端录制订阅名单和页面录制设置，或调用 updateLayout 方法更新合流布局。

update：更新云端录制

在录制过程中，可以随时调用 update 方法更新云端录制的订阅名单和页面录制设置。每次调用该方法都会覆盖原来的设置。

  • 方法：POST
  • 接入点：/v1/apps/<appid>/cloud_recording/resourceid/<resourceid>/sid/<sid>/mode/<mode>/update

对于每个 Agora 账号，每秒钟的请求数限制为 10 次。如需提高此限制，请提交工单联系技术支持。

HTTP 请求

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

参数 类型 描述
appid String 你的项目使用的 App ID
resourceid String 通过 acquire 请求获取的 resource ID。
sid String 通过 start 请求获取的录制 ID。
mode String 录制模式，支持单流模式 individual 、合流模式 mix（默认模式）和页面录制模式 web。

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

参数 类型 描述
cname String 待录制的频道名。
uid String 字符串内容为云端录制服务在频道内使用的 UID，用于标识该录制服务，需要和你在 acquire 请求中输入的 UID 相同。
clientRequest JSON 客户请求参数，你需要根据不同的场景设置对应的字段。
  • streamSubscribe 为 JSON 类型，用于更新订阅名单。仅适用于单流录制模式 individual和合流录制模式 mix。
  • webRecordingConfig 为 JSON 类型，用于更新页面录制参数。仅适用于页面录制模式 web 。
  • rtmpPublishConfig 为 JSON 类型，用于更新页面录制并推流到 CDN的参数。仅适用于页面录制模式 web 。
    		•

    streamSubscribe 包含以下参数：

    • audioUidList：（选填）JSON 类型。音频订阅名单。如果 recordingConfig 中的 streamTypes 为 1 （只订阅视频），设置该参数会报错。
      • subscribeAudioUids：（选填）JSONArray 类型，由 UID 组成的数组，指定订阅哪几个 UID 的音频流。数组长度不得超过 32，数组不可为空。详见设置订阅名单。
      • unSubscribeAudioUids: （选填）JSONArray 类型，由 UID 组成的数组，指定不订阅哪几个 UID 的音频流。云端录制会订阅频道内除指定 UID 外所有 UID 的音频流。数组长度不得超过 32，数组不可为空。详见设置订阅名单。
    • videoUidList：（选填）JSON 类型。视频订阅名单。如果 recordingConfig 中的 streamTypes 为 0 （只订阅音频），设置该参数会报错。
      • subscribeVideoUids：（选填）JSONArray 类型，由 UID 组成的数组，指定订阅哪几个 UID 的视频流。数组长度不得超过 32，数组不可为空。详见设置订阅名单。
      • unSubscribeVideoUids：（选填）JSONArray 类型，由 UID 组成的数组，指定不订阅哪几个 UID 的视频流。云端录制会订阅频道内除指定 UID 外所有 UID 的视频流。数组长度不得超过 32，数组不可为空。详见设置订阅名单。

    webRecordingConfig 包含以下参数：

    • onhold：（选填）Bool 类型。设置是否在页面录制过程中暂停页面录制。

      • true：在页面录制过程中暂停页面录制。录制服务不生成切片文件。

      • (默认) false：继续进行页面录制。如果页面录制已暂停，调用 update 方法并将 onhold 参数设置为 false 继续页面录制。

        如果需要连续调用 update 方法暂停或继续页面录制，请在收到上一次 update 响应后再进行调用，否则可能导致请求结果与预期不一致。

    • url:（选填）String 类型。设置待录制页面的地址。

    rtmpPublishConfig 包含以下参数：

    • outputs：JSON Array 类型。你需要设置以下参数：
      • rtmpUrl：String 类型。CDN 推流地址。

    请求示例

    • 请求 URL：
    https://api.agora.io/v1/apps/<appid>/cloud_recording/resourceid/<resourceid>/sid/<sid>/mode/<mode>/update
    • Content-type 为 application/json;charset=utf-8
    • Authorization 为 Basic authorization，生成方法请参考 RESTful API 认证。
    • 请求包体内容如下：

    更新订阅名单

    {
    "uid": "527841",
    "cname": "httpClient463224",
    "clientRequest": {
        "streamSubscribe": {
            "audioUidList": {
                "subscribeAudioUids": [
                    "#allstream#"
                ]
            },
            "videoUidList": {
                "unSubscribeVideoUids": [
                    "444",
                    "555",
                    "666"
                ]
            }
        }
    }
}

    更新页面录制参数

    {
    "cname": "httpClient463224",
    "uid": "527841",
    "clientRequest": {
        "webRecordingConfig": {
            "url": "https://xxxxx",
            "onhold": false
        }
    }
}

    更新页面录制推流的 CDN 地址

    {
    "cname":"httpClient463224",
    "uid":"527841",
    "clientRequest":{
        "rtmpPublishConfig": {
          "outputs": [
             {
                "rtmpUrl": "rtmp://xxx",
             }
           ]
        }
    }
}

    HTTP 响应

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

    • code: Number 类型，响应状态码。
    • resourceId: String 类型，云端录制使用的 resource ID。
    • sid: String 类型，录制 ID。成功开始云端录制后，你会得到一个 sid （录制 ID)。该 ID 是一次录制周期的唯一标识。

    响应示例

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

    updateLayout：更新合流布局

    在录制过程中，可以随时调用 updateLayout 方法更新合流布局的设置。

    每次调用该方法都会覆盖原来的布局设置，例如在开始录制时设置了 backgroundColor 为 "#FF0000"（红色），调用该方法更新合流布局时如果不设置 backgroundColor 参数，背景色会变为默认值黑色。

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

    对于每个 Agora 账号，每秒钟的请求数限制为 10 次。如需提高此限制，请提交工单联系技术支持。

    HTTP 请求

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

    参数 类型 描述
    appid String 你的项目使用的 App ID。必须使用和待录制的频道相同的 App ID。
    resourceid String 通过 acquire 请求获取的 resource ID。
    sid String 通过 start 请求获取的录制 ID。
    mode String 录制模式，只支持合流模式 mix （默认模式）。

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

    参数 类型 描述
    cname String 待录制的频道名。
    uid String 字符串内容为云端录制服务在频道内使用的 UID，用于标识该录制服务，需要和你在 acquire 请求中输入的 UID 相同。
    clientRequest JSON 特定的客户请求参数，对于该请求请参考下面的列表设置。

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

    • maxResolutionUid：（选填）String 类型，如果 layoutType 设为 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：（选填）JSONArray 类型。由每个用户对应的布局画面设置组成的数组，支持最多 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：（选填）JSONArray 类型。数组内容为各 UID 单独的背景图设置。

      • uid：String 类型。用户 UID。
      • image_url：String 类型。该 UID 的背景图的 URL 地址。配置背景图后，当该⽤户停止发送视频流超过 3.5 秒，画⾯将切换为该背景图。
      • render_mode：（选填）Number 类型。画面显示模式。
        • 0：（默认）裁剪模式。优先保证画面被填满。背景图尺寸等比缩放，直至整个画面被背景图填满。如果背景图长宽与显示窗口不同，则背景图会按照画面设置的比例进行周边裁剪后填满画面。
        • 1：缩放模式。优先保证背景图内容全部显示。背景图尺寸等比缩放，直至背景图的一边与画面边框对齐。如果背景图尺寸与画面尺寸不一致，在保持长宽比的前提下，将背景图进行缩放后填满画面，缩放后的背景图四周会有一圈黑边。
      以上背景图设置中，URL 支持 HTTP 和 HTTPS 协议，背景图片支持 JPG 和 BMP 格式。图片大小不得超过 6MB。录制服务成功下载图片后，设置才会生效；如果下载失败，则设置不⽣效。不同参数可能会互相覆盖，具体规则详见设置背景色或背景图。

    请求示例

    • 请求 URL：
    https://api.agora.io/v1/apps/<appid>/cloud_recording/resourceid/<resourceid>/sid/<sid>/mode/<mode>/updateLayout
    • Content-type 为 application/json;charset=utf-8
    • Authorization 为 Basic authorization，生成方法请参考 RESTful API 认证。
    • 请求包体内容：
    {
    "uid": "527841",
    "cname": "httpClient463224",
    "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，表示请求成功，响应包体中包含以下字段：

    • code：Number 类型，响应状态码。
    • resourceId：String 类型，云端录制使用的 resource ID。
    • sid：String 类型，录制 ID。成功开始云端录制后，你会得到一个 sid （录制 ID)。该 ID 是一次录制周期的唯一标识。

    响应示例

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