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

页面录制

更新时间 2022/08/08 04:19:46

本文介绍使用云端录制 RESTful API 进行页面录制以及页面录制并推流到 CDN的重点步骤。建议你同时参考云端录制 RESTful API 快速开始了解云端录制的基础流程。

页面录制自 2021 年 11 月 1 日起开始收费，详见页面录制计费说明。

功能描述

云端录制共支持三种录制模式：

  • 单流录制
  • 合流录制
  • 页面录制

页面录制模式下，录制服务将指定 URL 的页面内容和音频混合录制为一个音视频文件，如下图：

你可以使用页面录制还原在线课堂、视频会议等场景的完整体验。举例来说，当一个 Web 应用集成了 Agora SDK 以及 Agora 互动白板 SDK，页面录制可以录制页面内的全部元素，而不仅限于音视频流。

页面录制模式下，你还可以在录制的过程中，将页面的内容和音频转化为一路音视频流，并推送到 CDN，如下图：

前提条件

页面录制需满足以下前提条件：

  • 如果你需要同时使用页面录制和云端录制的其他功能，例如单流录制或截图，建议页面录制使用单独的 App ID，与其他业务的请求进行区分，便于 Agora 对页面录制进行独立的资源管理。
  • 你需要提供一个能通过 URL 访问的 Web 应用，作为待录制的内容源。（其他主播和观众可以使用该 Web 应用，也可以使用其他平台的应用。）
  • 你的 Web 应用需要兼容 Chrome 浏览器。
  • 由于云端录制仅录制浏览器窗口可见部分，该 Web 页面需要全部可见，即无需滚动条。
  • 如需还原主播端看到的全部内容，你需要将主播端的操作同步到应用中。

实现页面录制

参考以下步骤，实现页面录制。

获取 resource ID

在开始录制前，必须调用 acquire 方法请求一个用于云端录制的 resource ID。你需要将 scene 参数设置为 1，即分配页面录制资源。

请求示例

  • 请求 URL：

    https://api.agora.io/v1/apps/<yourappid>/cloud_recording/acquire

  • Content-type 为 application/json;charset=utf-8

  • Authorization 为 Basic authorization，生成方法请参考 RESTful API 认证。

  • 请求包体内容：

{
    "cname": "httpClient463224",
    "uid": "527841",
    "clientRequest": {
        "resourceExpiredHour": 24,
        "scene": 1
    }
}

开始录制

在调用 start方法时，将 mode 参数设置为 web，启用页面录制模式。该模式下，你还需要通过 extensionServiceConfig 设置页面录制的详细信息，以及通过 storageConfig 设置第三方云存储的信息。

录制模式的设置必须在开始录制的时候完成，不支持在录制开始后切换模式。

页面录制支持的 clientRequest 参数包括：

参数 配置内容 是否选填
recordingFileConfig 录制文件 选填
storageConfig 第三方云存储 必填
extensionServiceConfig 页面录制 必填

请求示例

  • 请求 URL：

    https://api.agora.io/v1/apps/<yourappid>/cloud_recording/resourceid/<resourceid>/mode/web/start

  • Content-type 为 application/json;charset=utf-8

  • Authorization 为 Basic authorization，生成方法请参考 RESTful API 认证。

请求包体内容：

{
    "cname": "httpClient463224",
    "uid": "527841",
    "clientRequest": {
        "token": "<token if any>",
        "extensionServiceConfig": {
            "errorHandlePolicy": "error_abort",
            "extensionServices": [
                {
                    "serviceName": "web_recorder_service",
                    "errorHandlePolicy": "error_abort",
                    "serviceParam": {
                        "url": "https://xxxxx",
                        "audioProfile": 0,
                        "videoWidth": 1280,
                        "videoHeight": 720,
                        "maxRecordingHour": 3
                    }
                }
            ]
        },
        "recordingFileConfig": {
            "avFileType": [
                "hls",
                "mp4"
            ]
        },
        "storageConfig": {
            "vendor": 2,
            "region": 3,
            "bucket": "xxxxx",
            "accessKey": "xxxxx",
            "secretKey": "xxxxx",
            "fileNamePrefix": [
                "directory1",
                "directory2"
            ]
        }
    }
}

停止录制

录制完成后，调用 stop 方法离开频道，停止录制。录制停止后如需再次录制，必须再调用 acquire 方法请求一个新的 resource ID。

页面录制停止前会持续计费，请根据实际业务情况设置合理的 maxRecordingHour，或主动停止页面录制。

请求示例

  • 请求 URL：

    https://api.agora.io/v1/apps/<yourappid>/cloud_recording/resourceid/<resourceid>/sid/<sid>/mode/web/stop

  • Content-type 为 application/json;charset=utf-8

  • Authorization 为 Basic authorization，生成方法请参考 RESTful API 认证。

  • 请求包体内容：

{
    "cname": "httpClient463224",
    "uid": "527841",
    "clientRequest": {}
}

响应示例

"Code": 200,
"Body":
{
    "resourceId": "JyvK8nXHuV1BE64GDkAaBGEscvtHW7v8BrQoRPCHxmeVxwY22-x-kv4GdPcjZeMzoCBUCOr9q-k6wBWMC7SaAkZ_4nO3JLqYwM1bL1n6wKnnD9EC9waxJboci9KUz2WZ4YJrmcJmA7xWkzs_L3AnNwdtcI1kr_u1cWFmi9BWAWAlNd7S7gfoGuH0tGi6CNaOomvr7-ILjPXdCYwgty1hwT6tbAuaW1eqR0kOYTO0Z1SobpBxu1czSFh1GbzGvTZG",
    "sid": "38f8e3cfdc474cd56fc1ceba380d7e1a",
    "serverResponse": {
        "extensionServiceState": [
            {
                "payload": {
                    "fileList": [
                        {
                            "filename": "a836026b2d4e3b276ba0de9f51a16f41_QIBO.m3u8",
                            "sliceStartTime": 1625663059301
                        },
                        {
                            "filename": "a836026b2d4e3b276ba0de9f51a16f41_QIBO_0.mp4",
                            "sliceStartTime": 1625663059301
                        }
                    ],
                    "state": "exit"
                },
                "serviceName": "web_recorder_service"
            },
            {
                "payload": {
                    "uploadingStatus": "uploaded"
                },
                "serviceName": "upload_service"
            }
        ]
    }
}

实现页面录制并推流到 CDN

参考以下步骤，实现页面录制并推流到 CDN。

获取 resource ID

在开始页面录制并推流到 CDN 前，必须调用 acquire 方法请求一个用于云端录制的 resource ID。你需要将 scene 参数设置为 1，即分配页面录制资源。

请求示例

  • 请求 URL：

    https://api.agora.io/v1/apps/<yourappid>/cloud_recording/acquire

  • Content-type 为 application/json;charset=utf-8

  • Authorization 为 Basic authorization，生成方法请参考 RESTful API 认证。

  • 请求包体内容：

{
    "cname": "httpClient463224",
    "uid": "527841",
    "clientRequest": {
        "resourceExpiredHour": 24,
        "scene": 1
    }
}

开始页面录制并推流到 CDN

在调用 start方法时，将 mode 参数设置为 web，启用页面录制模式。该模式下，你还需要通过 extensionServiceConfig 设置页面录制和推流到 CDN的详细信息，以及通过 storageConfig 设置第三方云存储的信息。

录制模式的设置必须在开始录制的时候完成，不支持在录制开始后切换模式。

页面录制并推流到 CDN 支持的 clientRequest 参数包括：

参数 配置内容 是否选填
recordingFileConfig 录制文件 选填
storageConfig 第三方云存储 必填
extensionServiceConfig 页面录制 必填
extensionServiceConfig.serviceName 要进行页面录制推流到 CDN，你需要将其设置为 "rtmp_publish_service"。 必填
extensionServiceConfig.serviceParam.outputs.rtmpUrl CDN 推流地址。 必填

请求示例

  • 请求 URL：

    https://api.agora.io/v1/apps/<yourappid>/cloud_recording/resourceid/<resourceid>/mode/web/start

  • Content-type 为 application/json;charset=utf-8

  • Authorization 为 Basic authorization，生成方法请参考 RESTful API 认证。

请求包体内容：

{
    "cname": "httpClient463224",
    "uid": "527841",
    "clientRequest": {
        "token": "<token>",
        "extensionServiceConfig": {
            "extensionServices": [
                {
                    "serviceName": "web_recorder_service",
                    "errorHandlePolicy": "error_abort",
                    "serviceParam": {
                        "url": "https://xxxxx",
                        "audioProfile": 0,
                        "videoWidth": 1280,
                        "videoHeight": 720,
                        "maxRecordingHour": 3,
                        "maxVideoDuration": 200
                    }
                },
                {
                    "serviceName": "rtmp_publish_service",
                    "errorHandlePolicy": "error_ignore",
                    "serviceParam": {
                        "outputs": [
                            {
                                "rtmpUrl": "rtmp://xxx"
                            }
                        ]
                    }
                }
            ]
        },
        "recordingFileConfig": {
            "avFileType": [
                "hls",
                "mp4"
            ]
        },
        "storageConfig": {
            "vendor": 2,
            "region": 3,
            "bucket": "xxxxx",
            "accessKey": "xxxxx",
            "secretKey": "xxxxx",
            "fileNamePrefix": [
                "directory1",
                "directory2"
            ]
        }
    }
}

停止页面录制以及推流到 CDN

录制及推流完成后，调用 stop 方法离开频道，停止录制及推流。录制进程停止后如需再次录制，必须再调用 acquire 方法请求一个新的 resource ID。

请求示例

  • 请求 URL：

    https://api.agora.io/v1/apps/<yourappid>/cloud_recording/resourceid/<resourceid>/sid/<sid>/mode/web/stop

  • Content-type 为 application/json;charset=utf-8

  • Authorization 为 Basic authorization，生成方法请参考 RESTful API 认证。

  • 请求包体内容：

{
    "cname": "httpClient463224",
    "uid": "527841",
    "clientRequest": {}
}

响应示例

"Code": 200,
"Body":
{
    "resourceId": "JyvK8nXHuV1BE64GDkAaBGEscvtHW7v8BrQoRPCHxmeVxwY22-x-kv4GdPcjZeMzoCBUCOr9q-k6wBWMC7SaAkZ_4nO3JLqYwM1bL1n6wKnnD9EC9waxJboci9KUz2WZ4YJrmcJmA7xWkzs_L3AnNwdtcI1kr_u1cWFmi9BWAWAlNd7S7gfoGuH0tGi6CNaOomvr7-ILjPXdCYwgty1hwT6tbAuaW1eqR0kOYTO0Z1SobpBxu1czSFh1GbzGvTZG",
    "sid": "38f8e3cfdc474cd56fc1ceba380d7e1a",
    "serverResponse": {
        "extensionServiceState": [
            {
                "payload": {
                    "fileList": [
                        {
                            "filename": "a836026b2d4e3b276ba0de9f51a16f41_QIBO.m3u8",
                            "sliceStartTime": 1625663059301
                        },
                        {
                            "filename": "a836026b2d4e3b276ba0de9f51a16f41_QIBO_0.mp4",
                            "sliceStartTime": 1625663059301
                        }
                    ],
                    "state": "exit"
                },
                "serviceName": "web_recorder_service"
            },
            {
                "payload": {
                    "state": "onhold"
                },
                "serviceName": "rtmp_publish_service"
            },            
            {
                "payload": {
                    "uploadingStatus": "uploaded"
                },
                "serviceName": "upload_service"
            }
        ]
    }
}

响应包体中的参数说明详见页面录制并推流到 CDN。

录制生成文件

录制后共生成一个 M3U8 文件和多个 TS 文件。根据 avFileType 参数的设置，还有可能生成一个或多个 MP4 文件。录制文件的命名规则详见管理录制文件。

计费

页面录制自 2021 年 11 月 1 日起开始收费，详见页面录制计费说明。

开发注意事项

针对 Web 应用的限制

  • 待录制页面中任一视频源的分辨率都不得超过 1920 × 1080。
  • 页面录制生成的视频分辨率最高为 1920 × 1080。
  • 待录制页面不得使用 WebGL 功能。
  • 待录制页面的下行带宽不得超过 10 Mbps，上行带宽不得超过 2 Mbps。
  • 请尽量避免你的 Web 应用占用过多的 CPU 内存和带宽，且该 Web 应用的使用目的应合法合规。
  • 页面录制支持 video 元素启用了 autoplay 属性后在无用户交互状态下自动播放。但如果待录制页面中的 video 元素未启用 autoplay 属性，其内容将不会自动播放，这将会导致页面录制无法录制到该视频。
  • 待录制页面不得跳转至不同域名的 URL，同时尽量避免其他任何形式的跳转。如待录制页面需登录操作，需先自行处理登录操作，再进行录制。
  • 你可以使用页面加载超时检测功能，来避免页面加载超时导致的录制内容与预期不一致的问题。

RESTful API 请求

  • 从发起请求到开始页面录制，有 5s 左右的延时。建议提前发起录制请求，以保证录制内容完整。
  • 页面录制不支持 updateLayout 方法。
  • 如果你在 start 方法中填入的 URL 无法正常打开，录制服务会在 start 成功后自动退出。你可以参考云端录制集成最佳实践，使用退避策略多次调用 query，来确认录制服务正常启动。

其他

  • 录制过程中，录制服务会在当前 MP4 文件时长超过约 maxVideoDuration 的值或大小超过约 2 GB 左右时创建一个新的 MP4 文件。
  • 如果你在 start 方法中填入的 URL 会自动触发客户端发布音视频流，录制服务也会成为一个发流端，因此，你的应用中可能会出现一个黑屏的用户画面。
  • 进行页面录制时，录制服务相当于一个使用 Web 应用的客户端，因此，如果你的 Web 应用包含用户列表，建议你在用户列表中隐藏该用户。