录制 SDK 发版说明

简介

声网本地服务端录制 SDK for Linux (简称本地服务端录制 SDK) 在声网 Native SDK 或/和声网 Web SDK 的基础上提供通信和直播录制功能。点击录制产品概述了解关键特性。

兼容性

本地服务端录制 SDK 与以下 SDK 兼容:

SDK	描述
声网 Native SDK	本地服务端录制 SDK 与全平台声网 Native SDK (1.7.0 或更高版本) 兼容，如果频道内有任何人使用了 1.6 版本的声网 Native SDK， 则整个频道无法录制。
声网 Web SDK	本地服务端录制 SDK 与声网 Web SDK (1.12.0 或更高版本兼容)。

从 2.2.0 版本起，下载包里有两个包，Java 和 C++ 。

已知问题和局限性

• 在用移动客户端 (仅 Android 系统) 录像的过程中，从前置摄像头切换到后置摄像头后，画面将被倒置。
• 如果在频道内调用 leaveChannel, 录制会停止, 但默认录制文件最后会包含一段空白片段，这个时间段由调用 joinChannel 时在 config 里设定的 idleLimitSec 字段值决定。详见 录制 API。
• 由于录制的音视频文件是没有加密的，如果要满足 HIPAA 要求，需使用磁盘加密工具对硬盘进行加密，例如 cryptsetup。

3.0.7 版

该版本于 2022 年 09 月 29 日发布。

新增特性

该本版新增 setLocalAccessPoint 方法，用于在成功部署声网混合云、私有化平台后，指定 Local Access Point 来设置本地代理。你可以联系 sales@agora.io 了解和部署声网混合云或声网私有化平台。

3.0.6 版

该版本于 2021 年 05 月 18 日发布。新增特性、改进与修复问题列表详见下文。

新增特性

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

• "aes-128-gcm": 128 位 AES 加密，GCM 模式。
• "aes-256-gcm": 256 位 AES 加密，GCM 模式。

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

合流录制支持录制 MP3
为了满足用户多样化需求，在合流录制模式下录制音频时，生成的音频文件新增 MP3 格式，且支持只生成 MP3 格式文件。你可以通过命令行和调用 API 设置 cfgFilePath 参数来实现该功能，详见命令行录制 和 cfgFilePath 参数设置。

改进

• 支持通过 cfgFilePath 参数设置 PCM 帧格式的原始音频数据的采样率（getAudioFrame 为 2 或 3）。具体设置方式详见设置录制格式。
• 优化回调 onActiveSpeaker 和 onAudioVolumeIndication 灵敏度和准确性。
• 支持通过调用 mixedVideoAudio 方法，在单流和合流录制模式下生成 MP4 文件，提升用户体验。

3.0.6 版本前	3.0.6 版本及以后
录制生成 TS 文件，录制结束后通过转码脚本将 TS 文件转码为 MP4 文件。	录制同时生成 TS 文件和 MP4 文件。

API 变更

MIXED_AV_CODEC_TYPE 新增如下枚举值：

AV_CODEC_INDIVIDUAL_TS_ONLY: 单流录制模式下，仅生成 TS 格式的视频文件，和 AAC 格式的音频文件。
AV_CODEC_INDIVIDUAL_TS_AND_MP4: 单流录制模式下，同时生成 TS 和 MP4 格式的视频文件，AAC 格式的音频文件。
AV_CODEC_MIXED_TS_ONLY: 合流录制模式下音频和视频混合成一个文件，仅生成 TS 格式文件。
AV_CODEC_MIXED_TS_AND_MP4: 合流录制模式下音频和视频混合成一个文件，同时生成 MP4 和 TS 格式文件。

问题修复

修复转码脚本不支持带有下划线的 UID 导致解析错误的问题。

3.0.5 版

该版本于 2021 年 01 月 13 日发布。新增特性、改进与修复问题列表详见下文。

新增特性

VIDEO_FRAME_TYPE 中新增 VIDEO_JPG_FILE，用于获取 JPG 文件格式的视频数据。

改进

• 通过将录制生成的 MP4 文件中的 moov 信息前置，加快视频播放，支持边加载边播放。
• 在单流录制模式下，取消无法同时输出原始音频数据和原始视频数据的限制。

问题修复

• 修复了当录制视频格式为 VIDEO_FORMAT_JPG_VIDEO_FILE_TYPE 时，获取的 JPG 格式的截图不带旋转信息的问题。
• 进一步修复 Java 调用 leaveChannel 方法离开频道时崩溃的问题。

3.0.4 版

该版本于 2020 年 11 月 25 日发布。新增特性与修复问题列表详见下文。

新增特性

cfgFilePath 中新增 Chunk_Time_Span 参数，支持在直播场景的单流录制模式下设置录制文件切片的间隔时间。

问题修复

该版本修复了以下问题：

• 频道内的主播反复登录登出的情况下，录制服务器的物理内存消耗显著增长。
• 调用 onActiveSpeaker 无法收到相应回调。
• 调用 onAudioVolumeIndication 无法收到相应回调。
• 调用 Java API setUserBackground 导致程序崩溃。
• 录制完成后，无法用转码脚本合并时长小于 0.02 s 的视频。
• 合流录制模式下，通过 audioProfile 设置输出音频为双声道不生效。

3.0.3 版

该版本于 2020 年 9 月 17 日发布。该版本新增特性如下：

新增特性

录制崩溃后录制文件可修复

在过去的版本中，由于录制崩溃，录制生成的 MP4 文件可能无法播放。针对该问题，自 3.0.3 版本起，声网录制 SDK 提供如下解决方案：

• 录制 SDK 在录制过程中生成 TS 格式的视频文件，并在录制正常结束后自动转封装为 MP4 文件。即使录制过程中偶现崩溃，最终生成的 MP4 文件依然可以播放。
• 录制 SDK 新增 crash_restore.sh 脚本。当录制服务因多次崩溃而异常退出时，你可以运行该脚本将 TS 文件转封装为 MP4 文件，并修复内容缺失的 uid_UID_timestamp.txt 文件。

详见 《录制崩溃后修复录制文件》。

3.0.2 版

该版本于 2020 年 7 月 15 日发布。该版本修复了以下问题：

• uid_UID_timestamp.txt 偶现时间戳溢出。
• 日志文件中因单行数据过长导致尾部乱码且内容丢失。
• 合流录制生成的 MP4 文件无法通过 Windows Media Player 播放器播放。

3.0.1 版

该版本于 2020 年 3 月 16 日发布。该版本修复了单流录制模式下，录制文件的文件名中时间戳异常的问题。

3.0.0 版

该版本于 2020 年 2 月 20 日发布。新增特性、改进与修复问题如下。

新增特性

1. 添加水印

3.0.0 版本新增添加水印功能，支持在合流模式下对录制的视频添加图片、文字或时间戳水印，作为防伪、宣传等用途。

你可以在 setVideoMixingLayout 方法中设置水印，也可以调用 updateWatermarkConfigs 方法添加、更新或删除水印设置，详见水印。

2. 录制指定用户的音视频

从 3.0.0 版本起，支持选择录制指定用户的音频或视频。你可以在调用 joinChannel 方法加入频道时：

1. 先将 RecordingConfig 中的 autoSubscribe 设为 false；
2. 然后设置 subscribeVideoUids 和 subscribeAudioUids 参数指定要录制视频和音频的用户 UID

此后，你可以调用 updateSuscribeVideoUids 和 updateSuscribeAudioUids 方法更新需要录制视频和音频的用户 UID。

3. 保留最后一帧

从 3.0.0 版本起，合流录制模式下，用户离开频道后，支持保留其视频的最后一帧。你可以在 setVideoMixingLayout 方法中设置 keepLastFrame 参数选择是否保留最后一帧。

4. 云代理服务

3.0.0 版本支持使用云代理服务，方便部署企业防火墙的用户正常使用声网的服务，详见使用云代理服务。

5. 新增回调

3.0.0 版本新增以下回调。具体说明和注意事项请点击各回调名查看。

频道事件

• onRejoinChannelSuccess：录制端重新加入频道时触发
• onConnectionStateChanged：网络连接状态改变时触发

体验提升

• onRemoteVideoStats：报告远端视频流统计信息
• onRemoteAudioStats：报告远端音频流统计信息
• onRecordingStats：报告录制统计信息

媒体事件

• onRemoteAudioStreamStateChanged：远端用户音频流状态改变时触发
• onRemoteVideoStreamStateChanged：远端用户视频流状态改变时触发

改进

• 从 3.0.0 版本起，你可通过 RecordingConfig 中的 enableIntraRequest 参数关闭关键帧请求。关闭后，频道内的所有发流端均每 2 秒发送一次关键帧。单流模式下录制的视频无需转码，即可指定播放位置观看。
• 从 3.0.0 版本起，自定义配置文件中不强制要求设置录制文件的路径。如果你设置了 cfgFilePath 参数指定配置文件，配置文件中填写你需要设置的选项即可，不是必须设置 "Recording_Dir" 的值。

问题修复

• 修复了在合流模式录制时，有时录制的合流视频会多出一个画面的问题。
• 修复了录制视频可能出现视频播放速度异常的问题。
• 修复了 syslog 过多的问题。
• 修复了在 setVideoMixingLayout 方法中设置 alpha 参数导致录制服务崩溃的问题。
• 修复了仅录制音频或仅录制视频时，录制指定 UID 不生效的问题。
• 修复了网络较差时，onRemoteAudioStreamStateChanged 和 onRemoteVideoStreamStateChanged 流状态改变回调报告的信息不准确的问题。
• 修复了音频录制拉伸的问题。
• 修复了合流录制模式下视频一开始出现黑帧的问题。

2.3.4 版

该版本于 2019 年 8 月 5 日发布。改进和修复问题详见下文。

改进

• Java API 以下方法由 private 变为 public：
  • setUserBackground 方法，支持设置指定 UID 用户的背景图片。当该用户在线且没有发送视频流时，会显示该背景图片。
  • setLogLevel 方法，支持设置 log 过滤等级。设置后，SDK 只会生成等于和低于所设等级的 log。
• 增强 Java API 健壮性。
• 增强异常崩溃信息收集能力。

修复问题

• 修复合流录制时切换频道模式会切片的问题。
• 修复直播模式下合流录制时不能只录制音频的问题。
• 修复 libyuv 崩溃的问题。
• 修复 Java 调用 leaveChannel 方法离开频道崩溃的问题。

2.3.3 版

该版本于 2019 年 4 月 1 日发布。新增特性与问题修复详见下文。

新增功能

1. 支持监控网络连接状态

为及时获取本地服务端录制 SDK 与服务器的连接状态，该版本新增如下回调，用于监控本地服务端录制 SDK 的网络连接丢失、中断状态。

• onConnectionLost：网络连接丢失回调。
• onConnectionInterrupted：网络连接中断回调。

2. 提示首帧出图

为及时获取本地对远端音视频流的接收情况，该版本新增如下回调，通知本地服务端录制 SDK 成功接收远端音视频首帧。

• onFirstRemoteAudioFrame：已接收远端音频首帧回调。
• onFirstRemoteVideoDecoded：已完成远端视频首帧解码回调。

3. 获取流状态

为监控本地服务端录制 SDK 接收音视频流的状态，该版本新增 onReceivingStreamStatusChanged 回调，提示本地服务端录制 SDK 接收音频流或视频流的状态发生了变化。

4. 获取说话者音量

为监控频道内通话的实时状态，了解说话者的具体信息，该版本新增 onAudioVolumeIndication 获取频道内说话者的人数、 用户 ID 及音量等信息。

问题修复

• 修复了手动模式下，本地服务端录制 SDK 退出频道后再次进入频道时，转码脚本失败的问题。
• 修复了调用 mixedVideoAudio 时非法参数导致程序崩溃的问题。
• 修复了在录制高清视频时出现卡顿的问题。
• 修复了录制视频帧率设置无效的问题。
• 修复了录制 Java sample code 手动模式编译出错的问题。
• 修复了使用转码命令 -f . -m 3 转码不成功的问题。

2.3.0 版

该版本于 2019 年 1 月 15 日发布。新增特性与改进问题详见下文。

本地服务端录制 SDK 从 2.3.0 版本起，可支持费用独立计算，录制的用量和费用不与语音通话/语音直播 SDK、视频通话/视频直播 SDK混合在一起。具体可咨询商务。

新增功能

1. 合流模式音频录制支持双声道

合流模式下音频录制支持双声道高音质：采样率 48 kHz，双声道，码率 192 Kbps。

裸数据不支持双声道。

audio profile 开放 0 和 1 两种设置，具体如下：

• 单流模式（file mode）：
  • 默认行为或者 audio profile=0，采样率 48 kHz，与原始音频流的单/双声道保持一致，码率根据发送端的码率自适应。
• 单流模式（裸数据）
  • 固定采样率 48 kHz，声道与原始流保持一致
    • PCM：码率可能改变
    • AAC：码率与 file mode 单流的保持一致
• 合流模式（file mode）：
  • audio profile=0，采样率 48 kHz，单声道，码率 48 Kbps
  • audio profile=1，采样率 48 kHz，单声道，码率 128 Kbps
  • audio profile=2，采样率 48 kHz，双声道，码率 192 Kbps
• 合流模式（裸数据）
  • 固定采样率 48 kHz，单声道

2. 增加 Web 播放器支持

实时转码后的录像文件，和转码脚本转码后的录像文件支持 Android、iOS/macOS、Windows 平台下的 Chrome 和 Safari 浏览器的播放。各平台浏览器播放支持如下表所示：

平台	Chrome	Safari
Android	Chrome 49+	N/A
iOS	✘	Safari 9+
macOS 10+	Chrome 47+	Safari 11+
Windows	Chrome 49+	N/A

3. 支持合流模式自定义背景图片

• 合流模式没有视频时可以显示背景图片使录制画面更好看
• 合流模式某个用户没有视频时可以用自定义图片代替该用户的视频画面

仅适用于合流模式，且不支持裸数据和截图。

4. 示例代码中增加预置的合流布局模版

为提高本地服务端录制 SDK 自带的示例代码的易用性，增加两种预置的合流布局模版：

自适应布局 （bestFit）

根据录制画面的数量自动调整每个画面的大小，每个画面大小一致，最多支持 17 个录制画面。例如：

垂直布局 （verticalPresentation）

指定一个 uid 在屏幕左侧显示大流画面，其他用户的小流画面在右侧垂直排列，最多两列，一列 8 个画面，最多支持共 17 个录制画面。例如：

5. 支持合流模式录制时截图

在合流模式下录制时，支持对每个用户分别截图，并且截图和录制订阅同一路流。

6. 支持说话者监测功能

增加 onActiveSpeaker 回调，用于返回频道内说话的用户 UID。

说话者监测功能默认为关闭状态，通过设置 RecordingConfig 中的 audioIndicationInterval 参数开启。将该参数设置为正整数，SDK 会按照设置的时间间隔返回 onActiveSpeaker 回调。

改进

• 改善了单流模式下的音画同步问题。
• 支持单流模式非实时转码下的录像视频自动旋转。
• 修改手动模式录制的 idle 行为：
  • 2.3.0 以前的版本，手动模式录制时，idle 一进入频道就开始生效。如果一开始频道内只有一个本地服务端录制 SDK，进程挂起，会导致录制退出频道，idle 不能发挥真正的作用。
  • 2.3.0 版本，startService之后，idle 才生效。
• 优化日志信息级别，把一些重要的信息从 INFO 中分拆到 NOTICE，WARN，以及 ERROR 中。
• 优化录制目录命名，确保目录名称的唯一性。

2.2.3 版

该版本于 2018 年 10 月 18 日发布。修复问题列表详见下文。

修复问题

• 由 .backtrace 引起的 coredump 文件丢失。
• Java jni 引起的崩溃和稳定性的优化。
• manually mode 下转码脚本的 bug 修复。
• Web 端客户加入频道后录制视频生成两份视频文件。
• 偶现的主线程释放后子线程继续使用引起的崩溃。

2.2.2 版

该版本于 2018 年 8 月 1 日发布。新增特性与修复问题列表详见下文。

改进

• jpeg 图片命名改动：从 uid\YmdHMS.jpg 改成 uid\YmdHMS\ms.jpg
• 转码脚本自动旋转
• java 包结构改动

修复问题

主要修复了以下问题：

• web 录制时间不正常
• 内存泄漏
• 三方互通 bug
• h.264 parser bug
• 音画不同步

2.2.1 版

该版本于 2018 年 6 月 5 日发布。新增特性与修复问题列表详见下文。

改进

• 提升了通信模式的性能。相同性能的机器能够支持的录制通道数多达 2.2 版的 2.5 倍。
• 减少了寻找端口的时间。
• 寻找端口的时间不再计入 idle 时间。

修复问题

主要修复了以下问题：

• 端口冲突导致寻找端口时间过长，超出 idle 时间，以至未连接成功就下线。

2.2.0 版

该版本于 2018 年 5 月 4 日发布。新增特性与修复问题列表详见下文。

下载包里有两个包，Java 和 C++ 。

修复问题

主要修复了以下问题：

• 修复了日志过大的问题
• 修复了录制过程中视频快进的异常问题
• 修复了某些间歇性故障
• 性能提升
• 提高了稳定性

2.1.0 版

该版本于 2018 年 3 月 7 日发布。新增特性与修复问题列表详见下文。

新增功能

功能	描述
选择录制模式	支持用户在进入频道时，选择自动或手动模块，方便灵活控制录制
自由控制录制开始和结束时间	新增接口解绑了进入频道和开始录制操作。如果选择的是自动录制模式，当频道内有人出现时才会启动录制。如果选择的是手动录制模式，则开发者有能力手动控制录制开始和结束的时间点
混音裸数据	混合语音裸数据
支持 Java 版	新增 Java 环境下的 API

改进

改进	描述
优化转码脚本	支持设置转码帧率和分辨率，且支持合流模式和单流模式

修复问题

主要修复了以下问题:

• 修复了偶现的录制文件转码失败问题;
• 修复了偶现的录制画面翻转问题;
• 修复了录制过程中偶现的音频异常问题;

2.0.0 版

该版本于 2017 年 11 月 21 日发布。新增特性与修复问题列表详见下文。

• 裸数据优化，多种格式支持:
  • 修改了参数 decodeAudio 和 decodeVideo 并新增 VideoJpgFrame 结构体。
  • 修改了参数 getAudioFrame和 getVideoFrame。
• 屏幕截图，新增参数 captureInterval用户设置截图的时间间隔。
• 视频大小流，新增参数 streamType 。
• 纯视频录制，新增参数 isVideoOnly。
• 只要使用了转码脚本，转码完成后会生成一个convert.log文件，和音视频文件在同一个路径下。
• UID\_HHMMSSMS.txt 里新增了视频旋转信息。

1.3.0 版

该版本于 2017 年 10 月 2 日发布。新增特性与修复问题列表详见下文。

新增功能

• 支持音视频混合录制, 在 API joinChannel里新增参数 mixedVideoAudio 和 cfgFilePath。
• 新增合并同一个 uid 音视频文件功能，详见 合流录制。
• 新增 API getProperties用于在录制开启时便能立即获取录制路径而无需加入频道。
• 修改了 onError 和 onLeaveChannel 回调。

1.2.0 版

该版本于 2017 年 8 月 21 日发布。新增特性与修复问题列表详见下文。

新增功能

• 新增功能获取音视频裸数据
• 新增功能支持鉴黄截图
• 新增日志文件 recording\sys.log 便于用户查找问题原因
• 新增功能支持本地服务端录制 SDK 时间戳

1.1.0 版

该版本于 2017 年 7 月 25 日发布。新增特性与修复问题列表详见下文。

新增功能

• 支持 Web 端录制功能, 生成的录制文件格式为 UID\_HHMMSSMS.webm
• 新增实时合流功能
• 新增了回调功能
• 修改了转码文件格式
• 新增了自由设置 UDP 端口的功能

修复问题

• 修复了偶现的错误时间戳问题
• 修复了偶现的转码失败问题
• 修复了偶现的 VLC 文件无法播放的问题

1.0.1 版

该版本于 2017 年 6 月 27 日发布。新增特性与修复问题列表详见下文。

修复问题

直播场景下: 修复了服务器端的一个崩溃。

1.0.0 版

该版本于 2017 年 6 月 15 日发布。本次发版为本地服务端录制 SDK 的第一次发版，主要包括以下功能:

• 录制通信或直播模式
• 录制一个频道内所有参与者的语音和视频内容
• 同时录制多个频道内所有参与者的语音和视频内容
• 同时录制一个或多个频道内所有参与者的纯语音内容
• 支持加密频道(使用了声网 SDK 内置的加密方案)的录制