发版说明

升级必看Copy Anchor Link

单流录制 API 已从 v1 升级至 v2。迁移时需要将 start、update、query 和 stop 请求 URL 中的 mode/individual 改为 mode/raw，并按照如下差异更新业务逻辑：

• 删除 recordingConfig.streamMode。v2 不再支持 standard、default 和 original。
• HLS 输出改为音视频合并的一个 M3U8 文件。你需要同步调整播放器、文件解析逻辑和下游处理流程。
• v2 支持输出 MP4 和 MP3。需要在 avFileType 中指定 mp4；音频场景可直接指定 mp3。
• 删除请求中的 extensionServiceConfig，否则接口会拒绝请求。
• 如果使用消息通知服务，将 serviceScene 从 rtc_record 更新为 rtsc/raw-recording。
• 处理 uploadingStatus 时新增 stranded 状态分支。

详见实现单流录制和录制文件介绍。

新增功能Copy Anchor Link

该版本新增支持 S3 协议云存储。在调用 acquire 和 start 接口时，通过把 vendor 设为 11，你可以指定 S3 协议的云存储，如 Digital Ocean、MinIO 及部分自建云存储。S3 协议云存储的域名通过 extensionParams 下的 endpoint 指定。示例如下：

"storageConfig": {
  "secretKey": "xxxxx",
  "accessKey": "xxxxx",
  "bucket": "s3-digit-test",
  "vendor": 11,
  "region": 0,
  "fileNamePrefix": [
    "agora",
    "meituan",
    "test"
  ],
  "extensionParams": {
    "endpoint": "xxxxx.xxxxx.com"
  }
}

改进Copy Anchor Link

为了提升云端录制的安全性，本次发布在 start 和 update 请求 Body 的 storageConfig 中新增了可选字段 stsToken 和 stsExpiration。你需要确保 stsToken 的时效足够长，以便云端录制能够顺利上传文件至三方云存储。详见 start 和 update API 参考。

改进Copy Anchor Link

本次发布在 acquire 请求 Body 的 clientRequest 中新增可选字段 startParameter。你设置该字段后，声网可以更精确地分配资源调度，提升请求异常时的恢复能力，进而提高云端录制的可用性。填写 startParameter 字段时，必须和 start 请求 Body 的 clientRequest 内容保持一致。详见 acquire API 参考。

新增功能Copy Anchor Link

本次发布新增支持指定某个区域的资源进行录制。可用于加速录制文件上传。详见 acquire 中的 clientRequest.regionAffinity 字段。

改进Copy Anchor Link

本次改进如下：

• 数据安全合规性：在延时转码和延时混音的场景中，声网建议你不要填写 clientRequest.region 字段，也不要将其留空。否则，由于声网边缘服务器的动态调整和延时场景下录制文件缓存带来的数据合规风险，声网录制服务将无法正常使用。

• 跨区域多路录制保障：为避免单个区域网络故障对云端录制服务的影响，本次发布在 acquire 方法的 clientRequest 中新增 excludeResourceIds 字段。该字段用于排除指定的录制资源，以便新发起的录制任务可以使用新区域的资源，实现跨区域多路录制。详见多路任务保障。

新增功能Copy Anchor Link

新增支持指定阿里云存储的如下地区：

• 23：CN_Nanjing
• 24：CN_Fuzhou
• 25：CN_Wulanchabu
• 26：AP_Northeast_2
• 27：AP_Southeast_7

改进Copy Anchor Link

本次发布更新了声网转码脚本，以降低底噪。

本次发布的改进如下：

• 提升了单流录制 standard 模式生成 MPD 文件的播放器兼容性。
• 优化了单流录制音视频合并脚本，你可以参考转换录制文件格式获取最新的音视频合并脚本。

本次发布在全球范围内支持延时转码功能。你需要在调用 acquire 接口时将 scene 字段设置为 2（延时转码），设置为该场景后，录制服务会在录制后 24 小时内对录制文件进行转码生成 MP4 文件，并将 MP4 文件上传至你指定的第三方云存储。请注意第三方云存储的 region 必须与调用 acquire 时设置的 region 一致。详见旧版实现单流录制。

本次发布新增 Amazon S3 支持区域。详见第三方云存储地区说明。

改进Copy Anchor Link

页面录制移动端网页模式Copy Anchor Link

页面录制支持移动端网页渲染模式。API 变更如下：

• 在 extensionServiceConfig 中新增 mobile 字段，将 mobile 设置为 true 后，录制服务使用移动端网页模式录制当前页面。
• extensionServiceConfig 中 videoWidth 和 videoHeight 字段的取值范围变更为 [240,1920]。

高可用录制文件合并脚本Copy Anchor Link

合流录制模式下，声网提供转码脚本，用于将原 M3U8 文件与启用高可用机制后生成的新 M3U8 文件合并为一个 MP4 文件。详见录制文件介绍。

新增功能Copy Anchor Link

音频单流不转码录制Copy Anchor Link

为了满足用户的多样化录制需求，该版本支持在单流录制且仅录制音频的场景下，通过设置 streamMode 字段开始单流音频不转码录制。详见单流音频不转码录制。

延时混音Copy Anchor Link

针对语音聊天场景，该版本支持在单流音频不转码录制场景下，通过设置 appsCollection 和 transcodeOptions 字段开启延时混音功能。开启后，录制服务会在录制结束后 24 小时内将指定频道内所有用户 ID 的录制文件合并且转码生成一个 MP3/M4A/AAC 文件，并将录制文件上传至你指定的第三方云存储。

单流录制生成合并的音视频文件Copy Anchor Link

调用 start 方法时，将 recordingConfig 字段的 streamMode 字段设置为 standard（标准模式），录制结束后你会得到 M3U8 音频索引文件、视频索引文件和合并的音视频索引文件。如果在 Web 端使用 VP8 编码，则得到一个合并的 MPD 音视频索引文件。 你可以直接播放该音视频索引文件，无需使用音视频格式转换脚本处理。声网推荐使用该模式。

支持第三方云存储对录制文件加密和打标签Copy Anchor Link

该版本新增 extensionParams 字段，用于支持第三方云存储服务对已上传的录制文件加密和打标签。该功能适用于 Amazon S3 和阿里云 OSS。

新增功能Copy Anchor Link

该版本新增阿里云平台（vendor 为 2）的如下区域：

• 19：AP_Southeast_6
• 20：CN_Heyuan
• 21：CN_Guangzhou
• 22：CN_Chengdu

详见阿里云参考文档。

问题修复Copy Anchor Link

开始合流录制时待录制的用户未发流的场景下，当用户开始发流，并中途停止发流或退出频道后，无法显示自定义的背景图或背景色。

升级必看Copy Anchor Link

为进一步提升实时音视频传输过程的安全性，该版本对加密模式进行了如下优化：

• 在 recordingConfig 的 decryptionMode 中新增 AES_128_GCM2 和 AES_256_GCM2 加密模式。新的 GCM 加密模式使用了安全性更高的密钥派生函数，支持设置密钥和盐。
• 在 recordingConfig 中新增 salt 字段，用于为 AES_128_GCM2 和 AES_256_GCM2 加密模式设置盐。

新增功能Copy Anchor Link

页面录制并推流到 CDNCopy Anchor Link

页面录制模式下，你可以在录制的过程中，将页面的内容和音频转化为一路音视频流，并推送到 CDN。详见实现页面录制并推流到 CDN。

第三方云存储平台Copy Anchor Link

第三方云存储平台新增谷歌云、华为云和百度智能云。

改进Copy Anchor Link

截图周期Copy Anchor Link

使用云端录制的云端截图功能，截图周期（captureInterval）取值范围从 [5,3600] 变更为 [1,3600]。

输出视频分辨率Copy Anchor Link

提高了页面录制输出视频的分辨率。将页面录制生成的视频分辨率上限从 1280 × 720 提高至 1920 × 1080，即 extensionServiceConfig 中页面录制的 videoWidth 和 videoHeight 字段的取值范围变更为 [480, 1920]。

预估订阅人数峰值Copy Anchor Link

为了支持更大的预估订阅人数峰值，该版本新增 recordingConfig 中的 subscribeUidGroup 字段的以下枚举值：

• 4：18 到 32 个用户 ID
• 5：33 到 49 个用户 ID

升级必看Copy Anchor Link

你需要在合并单流录制生成的文件时确保使用如下服务器版本：

• CentOS 7.0 及以上
• Ubuntu 14.04 及以上
• Debian 8.0 及以上

新增功能Copy Anchor Link

页面加载超时检测Copy Anchor Link

为了保证页面录制的有效性和完整性，该版本支持页面加载超时检测功能。详见检测页面加载超时。

暂停页面录制Copy Anchor Link

start 和 update 方法新增 onhold 字段，用于在页面录制开始或进行时暂停录制。

录制同时截图Copy Anchor Link

支持在一个录制进程中同时进行录制和截图，且仅收取录制费用。详见云端截图。

改进Copy Anchor Link

该版本进行了如下改进：

• web_recorder_stopped 回调新增错误码及错误信息，用于提示页面录制异常退出原因，用户可以根据该信息采取相应措施。
• update 方法新增 webRecordingConfig 字段，用于在页面录制过程中更新相关字段。

新增功能Copy Anchor Link

云端截图回调Copy Anchor Link

该版本增加了 recorder_snapshot_file 回调，用于截图成功的通知，且返回截图文件名称。

Amazon S3 云存储区域新增Copy Anchor Link

新增 Amazon S3 使用区域如下：

• 20：AP_NORTHEAST_3
• 21：EU_NORTH_1
• 22：ME_SOUTH_1
• 23：US_GOV_EAST_1

新增功能Copy Anchor Link

start 方法中新增 maxVideoDuration 字段，用于设置页面录制生成的 MP4 切片文件的最大时长。

改进Copy Anchor Link

当页面状态为 404 或 5XX 错误时，页面录制服务自动退出，避免继续录制错误页面。

问题修复Copy Anchor Link

该版本修复了页面录制偶现的录制文件无声问题。

新增功能Copy Anchor Link

限定访问区域Copy Anchor Link

该版本在 acquire 方法中新增 region 字段，用于限定云端录制服务访问的区域。一旦指定了访问区域，云端录制服务将不会访问指定区域以外的服务器。支持的区域如下：

• 中国大陆
• 亚洲区域（除中国大陆）
• 北美
• 欧洲

第三方云存储支持微软云Copy Anchor Link

第三方云存储平台新增微软云（Microsoft Azure）。

改进Copy Anchor Link

优化了页面录制的编码设置，同等画质下码率降低。

问题修复Copy Anchor Link

修复了 Chrome V8 漏洞引发的安全问题。

API 变更Copy Anchor Link

该版本 API 变更如下：

• acquire 方法新增 region 字段。
• web_recorder_started 回调中新增 recorderStartTime 字段。
• 新增 web_recorder_reload 回调。

新增功能Copy Anchor Link

合流录制支持输出 MP4 格式Copy Anchor Link

为了满足用户多样化需求，合流录制模式新增支持输出 MP4 格式的录制文件。在调用 start 方法时，将 avFileType 字段设置为 ["hls","mp4"]，即可在录制过程中实时获得 MP4 文件。

AES-GCM 加密模式Copy Anchor Link

在安全要求高的场景中，为保证数据的保密性、完整性和真实性，提高数据加密的计算效率，该版本在 decryptionMode 字段中新增以下加密模式：

• 128 位 AES 加密，GCM 模式。
• 256 位 AES 加密，GCM 模式。

开启加密功能后，同一频道内的所有用户都必须使用相同的加密模式和密钥。

改进Copy Anchor Link

页面录制过程中，录制服务将自动检测并修复偶现的录制文件无声问题。修复后，待录制页面会刷新；如有必要，你的 Web 应用需要保证刷新前后的状态一致。

API 变更Copy Anchor Link

该版本 API 变更如下：

• start 方法中的 decryptionMode 字段新增枚举值 5 和 6。
• uploaded 和 backuped 回调中新增 fileList 字段。

新增功能Copy Anchor Link

在合流录制模式下，你可以为视频画布以及单个用户画面设置背景图，并在录制过程中更新背景图。详见设置背景色或背景图。

改进Copy Anchor Link

添加了金山云存储的异常重试逻辑，在上传录制文件失败时，录制服务会进行重试。

问题修复Copy Anchor Link

该版本修复如下问题：

• 上传切片文件至腾讯云存储 COS 偶现文件丢失。
• 页面录制无法正常渲染 emoji 表情符号。
• 在录制静态页面时，videoFps 设置过高的情况下偶现录制失败。

API 变更Copy Anchor Link

该版本 API 变更如下：

• start 方法中的 transcodingConfig 字段新增 backgroundImage、defaultUserBackgroundImage 以及 backgroundConfig 字段。
• updateLayout 方法中的 clientRequest 字段新增 backgroundImage、defaultUserBackgroundImage 以及 backgroundConfig 字段。
• web_recorder_stopped 回调中新增 fileList 字段。

该版本提高了页面录制中针对视频源分辨率的限制，将待录制页面中任一视频源的分辨率上限从 1280 × 720 提高至 1920 × 1080。

新增功能Copy Anchor Link

在单流录制模式下，你可以开启延时转码。开启后，录制服务会在录制结束后 24 小时内将录制文件转码生成 MP4 文件，并将 MP4 文件上传至你指定的第三方云存储。

API 变更Copy Anchor Link

该版本 API 变更如下：

• acquire 方法的 scene 字段新增枚举值 2，用于设置延时转码场景。

• start 方法中的 clientRequest 新增 appsCollection 字段。

• 新增以下回调，用于报告转码的状态：

  • transcoder_started
  • transcoder_completed
  • download_failed
  • postpone_transcode_final_result

• 所有云端录制回调新增 serviceScene 字段，表示当前运行的录制场景或录制阶段。

新增功能Copy Anchor Link

新增页面录制模式。在该模式下，录制服务会将指定网页的页面内容和音频混合录制为一个音视频文件。

API 变更Copy Anchor Link

该版本 API 变更如下：

• 请求 URL 中的 mode 参数新增支持 web（页面录制模式）。

• acquire 方法新增 scene 字段，用于设置云端录制资源使用场景。

• start 方法中的 extensionServiceConfig 新增 "web_recorder_service" 服务。

• 新增以下回调，用于报告页面录制状态：

  • web_recorder_started
  • web_recorder_stopped
  • web_recorder_capability_limit

该版本进行了性能优化及服务稳定性优化，并修复了如下问题：

• 订阅小流不生效。
• 偶现的部分内容未被录制的问题。

新增功能Copy Anchor Link

在合流模式下，支持将录制文件上传至阿里视频点播服务（VoD）。

API 变更Copy Anchor Link

该版本 API 变更如下：

• start 方法中新增了 extensionServiceConfig 字段，用于指定阿里视频点播服务的配置。

• 新增 vod_started 回调和 vod_triggered 回调，提供阿里视频点播服务上传模块的状态。

新增功能Copy Anchor Link

灵活的用户 ID 订阅Copy Anchor Link

提供更为灵活的用户 ID 订阅，支持设置音频和视频的订阅白名单或黑名单，以及在录制过程中更新订阅名单。详见设置订阅名单。

高可用的回调Copy Anchor Link

该版本增加了 session_failover 回调，在启用高可用机制后触发，返回启用高可用机制后的新录制用户 ID。

API 变更Copy Anchor Link

该版本 API 变更如下：

• start 方法中新增了 unSubscribeVideoUids 和 unSubscribeAudioUids 字段，用于指定订阅黑名单。

• 新增 update 方法，用于在录制过程中更新订阅名单。

• 新增 session_failover 回调。

本次发布新增了对金山云存储的支持。

本次发布新增了截图功能，详见云端截图。

本次发布提高了云端录制服务的可用性。当出现服务器断网、进程被杀时，云端录制会自动切换到新的服务器，在短时间内恢复录制服务。详情见云端录制服务器断网、进程被杀的处理。

API 变更Copy Anchor Link

该版本 API 变更如下：

• acquire 方法中新增了 resourceExpiredHour 字段，用于设置云端录制 RESTful API 的调用时效。

• RESTful API 回调通知中新增事件 session_exit，提供云端录制服务的退出状态。

调用 start 方法后，你可以通过 query 请求立刻获得录制文件名，而不再需要等待 15 秒。

本次发布新增了对腾讯云存储的支持。

新增功能Copy Anchor Link

单流录制Copy Anchor Link

RESTful API 新增单流录制模式，支持分开录制每个用户 ID 的音频流和视频流。使用方法详见旧版实现单流录制。同时，声网提供了音视频合并脚本，用于合并单流录制模式下生成的音频和视频文件。使用方法详见转换录制文件格式。

录制指定用户 ID 的音视频流Copy Anchor Link

RESTful API 新增 subscribeAudioUids 和 subscribeVideoUids 字段，支持录制指定用户 ID 的音视频流。

自定义录制文件存储路径Copy Anchor Link

RESTful API 新增 fileNamePrefix 字段，支持指定录制文件在第三方云存储的存储位置。

频道状态变化的时间戳Copy Anchor Link

RESTful API 回调通知中新增事件 recorder_audio_stream_state_changed 和 recorder_video_stream_state_changed，提供音频流和视频流状态变化的时间，和该路流对应的用户 ID。

音视频格式转换脚本Copy Anchor Link

声网提供了音视频格式转换脚本，用于 TS、MP3、MP4 等文件格式之间的转换。使用方法详见转换录制文件格式。

同步回放Copy Anchor Link

通过 RESTful API 回调或解析 M3U8 文件，你可以获取录制开始时的时间戳，从而将录制的音视频和其他数据流文件（白板、课件、课堂聊天记录等）同步回放。详情见同步回放。

改进Copy Anchor Link

在出现错误时，你会在 HTTP 响应包体内收到相应的错误信息，而不只是错误码。错误码详情见云端录制 RESTful API。

问题修复Copy Anchor Link

如果因为第三方云存储的 bucket 及 key 字段值错误导致上传失败，云端录制服务将会直接报错，而不再将切片文件上传至声网备份云。

新增功能Copy Anchor Link

自定义合流布局Copy Anchor Link

RESTful API 新增自定义的合流布局。使用方法详见自定义合流布局。

你可以在开始录制时将 mixedVideoLayout 设为 3，并在 layoutConfig 中设置每个用户的画面大小和位置。你也可以在录制过程中调用 updateLayout 方法随时更新合流布局。

自定义背景色Copy Anchor Link

RESTful API 新增 backgroundColor 字段，支持自定义合流的画布背景色。无论使用何种合流布局，都可以通过该字段设置画布的背景色。

录制的时间戳Copy Anchor Link

为方便开发者获得精准的录制开始时间，RESTful API 提供录制开始第一片切片的 Unix 时间戳 sliceStartTime，可以通过 query 方法查询获得。同时在 RESTful API 的回调通知中新增事件 recorder_slice_start，提供第一片录制切片开始的时间和上一次录制失败的时间。

改进Copy Anchor Link

RESTful API 优化了对 resourceId 和 cname 以及 uid 是否对应的检查。

问题修复Copy Anchor Link

修复了默认的合流布局中存在的一些小问题。

该版本变更如下：

• 将合流布局默认背景色修改为黑色。
• 改善了在弱网环境下录制的视频卡顿问题。

本次发布主要新增了对 RESTful API 的支持，无需集成 SDK，直接通过网络请求来控制云端录制。

本次发布主要包括以下功能：

• 声网 RTC Native SDK 和声网 Web SDK 的高清音视频通话的录制
• 频道内所有用户的音视频合流录制
• 支持 3 种合流布局样式：Float（默认布局）、BestFit（自适应布局）、Vertical（垂直布局）。
• 第三方云存储，目前支持阿里云和 Amazon S3
• 提供 C++ 和 Java SDK 包