开始云端录制
本文介绍如何通过发送 RESTful API 请求在一个实时音视频互动频道内实现云端录制功能。
为方便快速体验,声网在 GitHub 上提供一个 Postman collection,包含了云端录制 RESTful API 的所有示例请求。你只需将该 Collection 导入 Postman,并设置环境变量,便可快速体验云端录制 RESTful API 的基本功能。
技术原理
实现云端录制的完整流程如下所示:
具体步骤如下:
-
获取 Resource ID。开始录制前,调用
acquire
方法获取云端录制资源。成功调用该方法后,你可以在响应包体中得到一个 Resource ID。 -
获取 Resource ID 后 2 秒内开始录制。调用
start
方法加入频道开始录制。开始录制后,响应包体中会返回一个标识当前录制进程的录制 ID。 -
结束录制。调用
stop
方法即可停止录制。 -
上传录制文件。录制结束后,云端录制服务上传录制文件到你指定的第三方云存储。
前提条件
开始前请确保你的开发环境满足如下要求:
- 有一个使用声网 RTC SDK 实现了音视频互动功能的项目,且频道内有用户并正在发流。
- 参考开通服务为该项目开通云端录制服务,并完成 HTTP 基本认证。
- 已开通第三方云存储服务。目前仅支持公有云,支持的第三方云存储服务商如下:
实现云端录制
下图为实现云端录制需要调用的 API 时序图:
其中,查询录制状态(query
)、更新订阅名单(update
)和更新合流布局(updateLayout
)均为可选,且可多次调用,但须在录制过程中,即开始录制后到结束录制前调用。
acquire:获取服务资源
在开始云端录制前,调用 acquire
方法获取一个云端录制 Resource ID。
你需要在该方法的请求 Body 中填入 cname
和 uid
字段,其中 cname
为待录制的频道名,uid
标识录制服务。
- 录制服务相当于频道中一个不发流的客户端。请求 Body 中的
uid
字段用于标识录制服务,不可与频道内的任何已有 UID 重复。例如,如果频道内已有两个用户,UID 分别为123
和456
,则uid
不可为"123"
或"456"
。 uid
的数据格式为 String 型,但字符串的内容必须为整型。如"321"
,而非"张三"
。- 请确保频道内所有用户均使用整型 UID。
成功调用该方法后,响应包体会返回一个 Resource ID。你需要在 2 秒内使用该 Resource ID 开始录制。一个 Resource ID 仅可用于一次录制。Resource ID 在获取到的 5 分钟内有效,需尽快使用。
# 将 <appid> 替换为你的声网项目的 App ID
curl --location --request POST 'https://api.sd-rtn.com/v1/apps/<appid>/cloud_recording/acquire' \
# 将 <Authorization> 替换为 Basic HTTP 认证生成的 Base64 编码凭证
--header 'Authorization: Basic <Authorization>' \
--header 'Content-Type: application/json' \
--data-raw '{
# 将 <YourChannelName> 替换为你需要录制的频道名称
"cname": "<YourChannelName>",
# 将 <YourRecordingUID> 替换为你标识该录制服务的 UID
"uid": "<YourRecordingUID>",
"clientRequest": {}
}'
start:开始录制
获得 Resource ID 后 2 秒內调用 start
方法加入频道开始录制。你可以选择录制模式为单流录制或合流录制。
调用该方法成功后,你可以从响应包体中获得一个 Sid(录制 ID)。该 ID 是一次录制周期的唯一标识。
# 将 <appid> 替换为你的声网项目的 App ID
# 将 <resourceid> 替换为通过 acquire 方法获取的 Reource ID
# 将 <mode> 替换为 individual(单流录制)或 mix(合流录制)
curl --location --request POST 'https://api.sd-rtn.com/v1/apps/<appid>/cloud_recording/resourceid/<resourceid>/mode/<mode>/start' \
# 将 <Authorization> 替换为 Basic HTTP 认证生成的 Base64 编码凭证
--header 'Authorization: Basic <Authorization>' \
--header 'Content-Type: application/json' \
--data-raw '{
# 将 <YourChannelName> 替换为你需要录制的频道名称
"cname": "<YourChannelName>",
# 将 <YourRecordingUID> 替换为你标识该录制服务的 UID
"uid": "<YourRecordingUID>",
"clientRequest": {
# 将 <YourToken> 替换成你在控制台获取的临时 Token
"token": "<YourToken>",
# 设置云存储相关字段
"storageConfig": {
"secretKey": "<YourSecretKey>",
"vendor": 0,
"region": 0,
"bucket": "<YourBucketName>",
"accessKey": "<YourAccessKey>"
},
# 设置录制相关字段
"recordingConfig": {
# 确保与声网 RTC SDK 的设置一致
"channelType": 0
}
}
}'
query:查询录制状态
录制过程中,你可以多次调用 query
方法查询录制的状态。
调用该方法成功后,你可以从响应包体中获得当前录制的状态和录制文件的相关信息。你可以参考云端录制最佳集成实践来实现录制过程中的服务状态监控和获取 M3U8 文件名。
# 将 <appid> 替换为你的声网项目的 App ID
# 将 <resourceid> 替换为通过 acquire 方法获取的 Reource ID
# 将 <sid> 替换为通过 start 方法获取的 sid
# 将 <mode> 替换为 individual(单流录制)或 composite(合流录制)
curl --location --request GET 'https://api.sd-rtn.com/v1/apps/<appid>/cloud_recording/resourceid/<resourceid>/sid/<sid>/mode/<mode>/query' \
# 将 <Authorization> 替换为 Basic HTTP 认证生成的 Base64 编码凭证
--header 'Authorization: Basic <Authorization>' \
--header 'Content-Type: application/json' \
stop:停止录制
录制完成后,调用 stop
方法停止录制。
调用该方法成功后,你可以从响应包体中获得录制文件上传的状态和录制文件的信息。
# 将 <appid> 替换为你的声网项目的 App ID
# 将 <resourceid> 替换为通过 acquire 方法获取的 Reource ID
# 将 <sid> 替换为通过 start 方法获取的 sid
# 将 <mode> 替换为 individual(单流录制)或 mix(合流录制)
curl --location --request POST 'https://api.sd-rtn.com/v1/apps/<appid>/cloud_recording/resourceid/<resourceid>/sid/<sid>/mode/<mode>/stop' \
# 将 <Authorization> 替换为 Basic HTTP 认证生成的 Base64 编码凭证
--header 'Authorization: Basic <Authorization>' \
--header 'Content-type: application/json;charset=utf-8' \
--data-raw '{
# 将 <YourRecordingUID> 替换为你标识该录制服务的 UID
"uid": "<YourRecordingUID>",
# 将 <YourChannelName> 替换为你正在录制的频道名称
"cname": "<YourChannelName>",
"clientRequest": {}
}'
后续步骤
管理录制文件
开始录制后,声网服务器会将录制内容切片为多个 TS/WebM 文件并不断上传至预先设定的第三方云存储,直至录制结束。你可以参考管理录制文件了解录制文件的命名规则、文件大小以及切片规则。
使用 Token 鉴权
为保障通信安全,在正式生产环境中,你需要在自己的 App 服务端生成 Token。详见使用 Token 鉴权。
开发注意事项
字段设置
- 如果请求 Body 中的
uid
字段与频道内的 UID 重复、或使用了非整型 UID,均会导致录制失败。 start
请求返回200
后,仅代表 RESTful API 请求成功。要确保录制成功启动并正常进行,你还需要调用query
查询录制状态。transcodingConfig
字段设置不合理、第三方云存储信息有误、token 信息有误等均会导致query
方法返回 404。详见为什么成功开启云端录制后调用 query 方法返回 404?。- 如果频道内无用户的状态超过一段时间,录制程序会自动退出。默认的时间段是 30 秒。你可以通过
start
API 中的clientRequest.recordingConfig.maxIdleTime
字段来控制这个时间段。请结合具体的业务需求来设置最大的空闲频道时间。在maxIdleTime
设置的时间范围内,即使频道空闲,录制仍会持续进行,并产生计费。
API 调用
- 为确保成功开始云端录制,请在每次
acquire
请求获取到 Resource ID 后的 2 秒内立即发起对应的start
请求。批量获取 Resource ID 后进行批量start
请求可能导致请求失败。acquire
和start
的请求需配对调用。Resource ID 在获取到的 5 分钟内有效,需尽快使用。超时需要重新申请 Resource ID。 - 获得
sid
(录制 ID)后一段时间内,你将无法调用query
,updateLayout
和stop
方法。默认的时间段是 72 小时。你可以通过acquire
方法中的clientRequest.resourceExpiredHour
来设置改时间段。
故障迁移
针对网络故障,以及非声网云服务,非声网软件,基础设施和不可抗力等因素可能导致的风险,声网云录制为了更好的用户体验,提供高可用自动任务迁移服务。当故障确认后,该服务会在尽量短的时间(预计 90 秒内)完成,在此期间会存在录制中断,录制文件丢失等风险。
对于频道内较多观众端或对高可用要求极高场景,你需要基于自身业务特点综合考虑能否接受高可用迁移影响,决策是否要采用更高的质量保障措施,例如关键任务多路录制(使用不同 uid
发起多路录制任务),或通过周期性频道查询和消息通知服务获知录制任务状态,及时重新发起录制任务。
参考文档
进阶功能
了解基础的云端录制开始步骤后,你可以尝试根据业务需求使用云端录制进阶功能:
API 参考
参考以下文档了解字段详情和响应状态码: