本文介绍使用云端录制 RESTful API 进行页面录制以及页面录制并推流到 CDN的重点步骤。建议你同时参考云端录制 RESTful API 快速开始了解云端录制的基础流程。
云端录制共支持三种录制模式:
页面录制模式下,录制服务将指定 URL 的页面内容和音频混合录制为一个音视频文件,如下图:
你可以使用页面录制还原在线课堂、视频会议等场景的完整体验。举例来说,当一个 Web 应用集成了 Agora SDK 以及 Agora 互动白板 SDK,页面录制可以录制页面内的全部元素,而不仅限于音视频流。
页面录制模式下,你还可以在录制的过程中,将页面的内容和音频转化为一路音视频流,并推送到 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
}
}
在调用 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 前,必须调用 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
设置页面录制和推流到 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"
]
}
}
}
录制及推流完成后,调用 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 日起开始收费,详见页面录制计费说明。
updateLayout
方法。start
方法中填入的 URL 无法正常打开,录制服务会在 start
成功后自动退出。你可以参考云端录制集成最佳实践,使用退避策略多次调用 query
,来确认录制服务正常启动。maxVideoDuration
的值或大小超过约 2 GB 左右时创建一个新的 MP4 文件。start
方法中填入的 URL 会自动触发客户端发布音视频流,录制服务也会成为一个发流端,因此,你的应用中可能会出现一个黑屏的用户画面。