「Agora 云端录制 SDK」FAQ 大汇总

云端录制常见FAQ


更多 Agora云端录制 SDK 相关链接:

Agora 云端录制 官网FAQ
Agora GitHub 链接1: 可下载demo
Agora GitHub 链接2: 可下载demo
Agora GitHub 社区


论坛内常见FAQ相关链接:

RTC 常见FAQ:论坛链接
RTM 常见FAQ:论坛链接
Web 常见FAQ:论坛链接
小知识 常见FAQ:论坛链接
本地录制 常见FAQ:论坛链接
小程序 常见FAQ:论坛链接
灵动课堂 常见FAQ:论坛链接

点击问题展开答案


Q1. 如何停止云端录制?& 云录制会不会自动停止?

参考文档:官网文档解释


Q2. 云录制常见调用逻辑(顺序)错误

参考文档:官网文档解释


常见调用错误

  • acquire :arrow_right: start :arrow_right: start 用同一个 resource ID 重复调用 start ,会收到 HTTP 状态码 201,错误码 7。
  • acquire :arrow_right: start :arrow_right: acquire :arrow_right: start 用相同的参数重复调用 acquirestart ,会收到 HTTP 状态码 400,错误码 53。
  • acquire :arrow_right: start :arrow_right: 停止录制 :arrow_right: query 停止录制后再去调用 query ,会收到 HTTP 状态码 404,错误码 404。停止录制有以下几种情况:
    • 主动调用 stop
    • 频道内没有用户超过设定的时间自动停止录制。
    • 异步检查参数错误导致录制停止,包括 start 请求的 transcodingConfigstorageConfig 中的参数错误。
  • acquire :arrow_right: start :arrow_right: stop & query 调用 stop 的过程中调用 query ,会影响 stop 的响应内容:响应的 HTTP 状态码为 206,并且响应中没有 fileList 字段。

Q3. 如何获取 M3U8 文件地址?

参考文档:官网文档解释


你可以通过以下方式获得 M3U8 文件名信息:


Q4. 本地服务端录制支持的播放器列表

根据选择的录制模式不同,在录制结束后生成的录制文件也不一样。

  • 在单流录制模式下,会生成每个用户的音频文件和视频文件,通常需要使用转码脚本将这些文件合成为一个 MP4 文件播放。
  • 在合流录制模式下,如果 mixedVideoAudio 参数设置为 0 ,会生成一个包含所有用户音频的文件和一个包含所有用户视频的文件,也同样需要使用转码脚本将音频文件和视频文件合成为一个 MP4 文件。因此我们推荐合流录制时将 mixedVideoAudio 参数设置为 2 ,这样可以直接录制得到一个 MP4 文件。

下面列出转码后的录制文件、 mixedVideoAudio 设为 1 得到的录制文件以及 mixedVideoAudio 设为 2 得到的录制文件在各个平台对播放器的支持。

转码后的录制文件包括:

  • 单流模式的录制文件转码合成的 MP4 文件。
  • 合流模式下,将 mixedVideoAudio 参数设置为 0 得到的录制文件转码合成的 MP4 文件。
平台 播放器/浏览器 转码后文件 mixedVideoAudio=1 mixedVideoAudio=2
Linux VLC Media Player 支持 支持 支持
Linux FFplay 支持 支持 支持
Linux Chrome 不支持 不支持 不支持
Windows Media Player 支持 不支持 支持
Windows KM Player 支持 支持 支持
Windows VLC Player 支持 支持 支持
Windows Chrome (49.0.2623+) 支持 支持 支持
macOS QuickTime Player 支持 支持 支持
macOS VLC 不支持 不支持 不支持
macOS Movist 支持 支持 支持
macOS MPlayerX 支持 支持 支持
macOS KM Player 不支持 不支持 不支持
macOS Chrome (47.0.2526.111+) 支持 支持 支持
macOS Safari (11.0.3+) 支持 支持 支持
iOS Default Player 支持 支持 支持
iOS VLC for Mobile 不支持 不支持 支持
iOS KM Player 支持 支持 支持
iOS Safari (9.0+) 支持 支持 支持
Android Default Player 支持 支持 支持
Android MX Player 支持 支持 支持
Android VLC for Android 支持 支持 支持
Android KM Player 支持 支持 支持
Android Chrome (49.0.2623+) 支持 支持 支持

Q5. 云端录制常见错误码及处理方法

本文总结了开发者在集成 Agora 云端录制过程中遇到的常见问题及答案。

更多云端录制相关链接:
云录制 RESTful API 请求示例
云端录制官方文档

Error code 8

{"code":8, "reason":"response detail error 8"}

HTTP 请求头部字段错误,有以下几种情况:

  • Content-type 错误,请确保 Content-typeapplication/json;charset=utf-8
  • 请求 URL 中缺少 cloud_recording 字段。
  • 使用了错误的 HTTP 方法。
  • 请求包体不是合法的 JSON 格式。

Error code 2

{"code":2, "reason":"response detail error 2"}

原因分析 :参数不合法。请确保参数类型正确、⼤小写正确、必填的参数均已填写。例如以下情况:

  • uid 不是 string 类型
  • uid 是 string 类型,但是不能转成 uint32_t 类型的整数

Appid is invalid

{“message”:"appid is invalid"}

原因分析

  • appid 未开通云录制服务权限(请先在控制台自行开通云录制服务权限)
  • appid 与 CustomerId 不匹配

Query/Stop 返回 404

{"code":404, "serverResponse": {"fileList":"", "status":0}}

原因分析 :后端已经退出了录制,此时再去调用 Query 或 Stop 会返回 httpcode 404。
如果没有调用 Stop,则需要根据其他信息判断为什么会结束录制, 详情请见下一条 FAQ

Start 调⽤成功了,Query/Stop 却收到 404,录制文件没有上传至云存储。

通过 start 方法成功开启云端录制后,调用 query 方法返回 404 状态码,可能原因如下:

  • 云端录制启动后,录制服务会进行参数检查,如果检查出现问题,则有可能导致录制停止。请检查 transcoding 等参数设置是否正确。你可以参考如何设置录制视频的分辨率 设置 transcoding
  • 第三方云存储信息有误,如 accessKeysecretKey 错误,导致录制文件上传失败。如果你开通了 Agora 消息通知服务,当你的云存储配置出错时,你会收到 cloud_recording_error 事件的通知。
  • clientRequest 中的 token 有误,导致云端录制无法加入频道。请确认你的项目是否已启用 App 证书。如果你的项目已启用 App 证书,则务必在该参数中传入你项目的动态秘钥 ;如果未启用,则无需设置该参数。详见校验用户权限
  • 云端录制启动后,频道内没有用户发流,当超过 maxIdleTime 即最长空闲频道时间后,云录制会自动退出。
  • 云端录制服务器断网或进程被杀。此时,调用 queryupdateLayout 、或 stop 均会返回 404。云端录制的故障处理中心会在 90 秒内判断故障原因,并采取相应的应对措施。你可以在一段时间后再次调用 query 方法,查询录制服务是否已恢复。详情见云端录制服务器断网、进程被杀的处理

调用 Stop,返回 400 错误

stop 请求的 url 或 body 有误。例如请求的 body 里面没有 cname, uid 等信息

Invalid authentication credentials

{"message":"Invalid authentication credentials"}

原因分析

  • customer ID 和 customer certificate 不一致
  • appid 没有开通云录制服务权限
  • 认证信息输入有误(authentication 是 basic xxx 格式,不能漏掉 basic )
  • header 的格式不正确(例如: application/json;charset-utf-8 必须⼤小写一致,并且中间没有空格)

Start 报错 code:53

{"sid":"", "code":53}

原因分析 :录制已经在进行中。当采用相同参数再次调用 acquire 获得新的 resource ID,并用于 start 请求时,会发生该错误。如需发起多路录制,需要在 acquire 方法中填入不同的 UID。

Query 在 Start 后的 15s 内无法获取到文件名和 Status

Start 成功后,第⼀片录制切片上传完成后才会有文件名信息,而第⼀片切片的时间是 15s。所以只有在 Start 成功 15s 后才能 Query 到信息。

返回 501/504 报错

录制服务正在退出。该错误可能在调用了 stop ⽅法后再调用 query 时发生。

Acquire 返回 400

  • 检查 acquire 请求的 url 和 body 是否合法,例如 clientRequest 有没有写成 requestId。
  • 检查 appid 是否有开通云录制服务权限,Agora 已支持用户在控制台自助开通云端录制服务权限,请参考:

https://docs.agora.io/cn/cloud-recording/cloud_recording_rest?platform=All%20Platforms#开通云端录制服务

为什么无法通过浏览器调用云端录制 RESTful API

要使用云端录制 RESTful API,Web API 需要发送跨域请求。根据 CORS 规范,浏览器针对跨域请求会先发送一个 OPTIONS 请求,查询服务器是否允许跨域请求,然后才有可能发起真正的 POST 请求。但是由于云端录制 RESTful API 不支持 OPTIONS 方法,所以无法支持 Web API 调用的方式。

返回错误码 62
调用 Acquire 请求时,如果出现该错误,表示你填入的 App ID 没有开通云端录制权限。

返回错误码 65
多为网络抖动引起。使用相同 resource ID 重试即可。

返回错误码 432
请求参数错误。请求参数不合法,或请求中的 App ID,频道名或用户 ID 与 resource ID 不匹配。

返回错误码 433
resource ID 过期。获得 resource ID 后必须在 5 分钟内开始云端录制。请重新调用 acquire 获取新的 resource ID。

返回错误码 435
没有录制文件产生。频道内没有用户加入,无录制对象。

"no Route matched with those values ":
该错误可能由 HTTP 方法填写错误导致,例如将 GET 方法填写为 POST。


Q6. 本地服务端录制是否支持像云录制一样在录制过程中改变布局?

本地服务端录制过程中可以调用setVideoMixingLayout改变布局,但是画布大小无法改变即 canvasWidth和canvasHeight。


Q7. 合流录制中updateSubscribeVideoUids() 这个接口,如果开始指定了A进行录制,后续又调此接口更新订阅为A+B,那么此时是新起一个录制文件对A+B进行录制,还是在原有的那段A的文件中加入B的画面?

录制文件不会切分开,是会在原有的录制中加入新的用户的画面。


Q8. 本地录制中调用命令行录制是否可以获取录制文件的路径? 类似 getProperties()

目前命令行录制获取不到录制文件的路径,只能知道录制的目录,默认在录制当前目录下按照日期自动生成子目录,获取不到具体的录制文件名。


Q9. RecordingSampleM ars = new RecordingSampleM(RecordingSdk);ars.createChannel(args);是否会导致阻塞?

这个方法会一直阻塞,只有等结束录制才会退出。


Q10. RecordingSampleM可以用作多频道录制吗?

RecordingSampleM不可以用作多频道录制,如果要多频道录制,需要每个线程实例化一个RecordingSampleM。


Q11. RecordingSampleM与RecordingSample区别是什么?

RecordingSampleM可以在命令行输入参数 “quit”、“start”、“stop”等选项,RecordingSample不可以。


Q12. 本地服务端录制 getProperties这个接口中返回的是包含文件名的绝对路径还是第一级子目录?

参考文档:官网文档解释

如果有cfgFilePath->Recording_Dir配置
getProperties返回的路径是:cfgFilePath->Recording_Dir配置路径2. 如果没有配置cfgFilePath->Recording_Dir,有recordFileRootDir配置
getProperties返回的路径是:recordFileRootDir配置 / 录制日期 / ChannelID+目录生成时间(UTC时间)3. 如果没有recordFileRootDir配置
getProperties返回的路径是: ./录制日期 / ChannelID+目录生成时间(UTC时间)