本文提供 Agora Unity SDK 的发版说明。
该版本于 2020 年 12 月 30 日发布。
1. 集成变更
自该版本起,SDK 包中新增以下动态库:
各平台对应新增的文件如下:
平台 | 文件 |
---|---|
Android | libagora-fdkaac.so libagora-mpg123.so libagora-soundtouch.so libagora-ffmpeg.so |
iOS | Agorafdkaac.framework AgoraSoundTouch.framework Agoraffmpeg.framework |
macOS | Agorafdkaac.framework AgoraSoundTouch.framework Agoraffmpeg.framework |
Windows | libagora-fdkaac.dll libagora-mpg123.dll libagora-soundtouch.dll libagora-ffmpeg.dll |
如果你将 SDK 升级到 v3.2.1,请务必参考快速开始在你的项目中添加上述文件。
2. 云代理
该版本优化了 Agora 云代理架构。如果你已经在使用云代理,为避免新 SDK 和老云代理的兼容性问题,请在升级 SDK 前联系技术支持。详见云代理。
3. 安全合规
Agora 已通过 ISO 27001、ISO 27017、ISO 27018 国际认证,为全球用户提供安全可靠的实时互动云服务。详见 ISO 证书。
同时,为支持传输层加密,该版本新增 TLS(Transport Layer Security)加密和 UDP(User Datagram Protocol)加密方式。
1. 极速直播
该版本新增 SetClientRole
方法,支持设置观众的延时级别。你可以通过该方法在互动直播和极速直播之间切换:
详见极速直播产品概述。
2. 发布和订阅状态转换回调
该版本新增以下回调方便你了解音视频流当前的发布及订阅状态,有助于订阅和发布相关的数据统计:
OnAudioPublishStateChangedHandler
: 音频发布状态发生改变。OnVideoPublishStateChangedHandler
: 视频发布状态发生改变。OnAudioSubscribeStateChangedHandler
: 音频订阅状态发生改变。OnVideoSubscribeStateChangedHandler
: 视频订阅状态发生改变。3. 本地首帧发布回调
为提示用户本地音视频首帧已发布,该版本新增如下回调:
OnFirstLocalAudioFramePublishedHandler
:已发布本地音频首帧回调。该回调取代 OnFirstLocalAudioFrameHandler
回调,我们建议你不再使用 OnFirstLocalAudioFrameHandler
回调。OnFirstLocalVideoFramePublishedHandler
:已发布本地视频首帧回调。4. 自定义数据上报
该版本支持自定义数据上报。如需试用,请联系 sales@agora.io 开通并商定自定义数据格式。
1. 指定访问区域完善
该版本修改了区域访问限制的区域码(AREA_CODE)
,并新增日本和印度的区域码。最新区域码如下:
AREA_CODE_CN
: 中国大陆。AREA_CODE_NA
: 北美区域。AREA_CODE_EU
: 欧洲区域。AREA_CODE_AS
: 除中国大陆以外的亚洲区域。AREA_CODE_JP
: 日本。AREA_CODE_IN
: 印度。AREA_CODE_GLOB
:(默认)全球。如你此前调用 GetEngine
方法时指定了访问区域,在由之前版本升级至该版本时,请确保使用正确的区域码。
2. 会议场景
为提升多人会议的音频体验,该版本在 SetAudioProfile
中新增 AUDIO_SCENARIO_MEETING(8)
。
3. 美声与音效
为提升美声与音效 API 的易用性,该版本废弃 SetLocalVoiceChanger
和 SetLocalVoiceReverbPreset
,并新增如下方法替代:
SetVoiceBeautifierPreset
: 与 SetLocalVoiceChanger
相比,该方法删除了小男孩等变声音效和空旷音效。SetAudioEffectPreset
: 与 SetLocalVoiceReverbPreset
相比,该方法新增了小男孩等变声音效、空旷音效、3D 人声音效和电音音效,并删除了摇滚和嘻哈音效。SetAudioEffectParameters
: 对指定的音效选项进行更细节的设置。该版本支持的音效选项有 3D 人声和电音音效。4. CDN 直播推流
该版本新增 OnRtmpStreamingEventHandler
回调,报告 CDN 直播推流过程中发生的事件,如未成功添加背景图或水印。
5. 加密
该版本新增 EnableEncryption
方法,用于开启内置加密,并废弃原加密方法:
SetEncryptionSecret
SetEncryptionMode
与原加密方法相比,该方法新增对国密 SM4 加密模式的支持,你可以根据需要选择合适的加密模式。
6. 通话中质量透明
该版本进一步扩充了 LocalAudioStats
类、LocalVideoStats
类、RemoteVideoStats
类和 RemoteAudioStats
类的成员,提供更多音视频质量相关数据。
LocalAudioStats
类新增 txPacketLossRate
,表示本端到 Agora 边缘服务器的物理音频丢包率 (%)。
LocalVideoStats
类新增:
txPacketLossRate
: 本端到 Agora 边缘服务器的物理视频丢包率 (%)。captureFrameRate
: 本地视频采集帧率 (fps)。RemoteAudioStats
和 RemoteVideoStats
类中新增 publishDuration
,表示远端音频流和视频流的累计发布时长(毫秒)。
7. 设置音频编码属性
为提升音频性能,该版本对音频编码码率最大值进行如下优化:
Profile | 3.2.1 版本 | 3.2.1 版本之前 |
---|---|---|
AUDIO_PROFILE_DEFAULT |
直播场景: 64 Kbps通信场景: Windows: 16 KbpsAndroid/iOS/macOS: 18 Kbps | 直播场景: 52 Kbps通信场景:Windows: 16 KbpsAndroid/iOS/macOS: 18 Kbps |
AUDIO_PROFILE_SPEECH_STANDARD |
18 Kbps | 18 Kbps |
AUDIO_PROFILE_MUSIC_STANDARD |
64 Kbps | 48 Kbps |
AUDIO_PROFILE_MUSIC_STANDARD_STEREO |
80 Kbps | 56 Kbps |
AUDIO_PROFILE_MUSIC_HIGH_QUALITY |
96 Kbps | 128 Kbps |
AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO |
128 Kbps | 192 Kbps |
8. 日志扩容
该版本中,Agora SDK 日志文件的默认个数由 2 个增加至 5 个,单个日志文件的默认大小由 512 KB 扩大至 1024 KB。默认情况下,SDK 会生成 agorasdk.log
、agorasdk_1.log
、agorasdk_2.log
、agorasdk_3.log
、agorasdk_4.log
这 5 个日志文件。最新的日志永远写在 agorasdk.log
中。agorasdk.log
写满后,SDK 会从 1-4 中删除修改时间最早的一个文件,然后将 agorasdk.log
重命名为该文件,并建立新的 agorasdk.log
写入最新的日志。
9. 美颜
该版本支持在 macOS 中调用 SetBeautyEffectOptions
设置对比度、亮度、平滑度等参数,达到美白、磨皮、红润肤色等美颜效果。
10. 音频路由
为支持在更多 macOS 设备中播放音频,该版本在 AUDIO_ROUTE
枚举中新增 4 个枚举值,支持 USB 外围设备、HDMI 外围设备、DisplayPort 外围设备和 Apple AirPlay。
11. OPPO 耳返优化
该版本在 OPPO 如下机型上降低了耳返延时:
12. 优化弱网环境下的视频体验
13. 本地采集视频画质
在 iOS 设备上,为提升本地采集的视频画质,该版本对摄像头采集本地视频进行如下优化:
该版本修复了如下问题:
音频
SetAudioMixingPitch
方法时,部分参数不生效。视频
SDK
新增
SetClientRole
SetAudioEffectPreset
SetVoiceBeautifierPreset
SetAudioEffectParameters
EnableEncryption
OnAudioPublishStateChangedHandler
OnVideoPublishStateChangedHandler
OnAudioSubscribeStateChangedHandler
OnVideoSubscribeStateChangedHandler
OnFirstLocalAudioFramePublishedHandler
OnFirstLocalVideoFramePublishedHandler
OnRtmpStreamingEventHandler
LocalAudioStats
类中新增 txPacketLossRate
LocalVideoStats
类中新增 txPacketLossRate
和 captureFrameRate
RemoteAudioStats
和 RemoteVideoStats
类中新增 publishDuration
AUDIO_SCENARIO_TYPE
enum 中新增 AUDIO_SCENARIO_MEETING
(8)AUDIO_ROUTE
enum 中新增 AUDIO_ROUTE_USB
、AUDIO_ROUTE_HDMI
、AUDIO_ROUTE_DISPLAYPORT 和 ``AUDIO_ROUTE_AIRPLAY
废弃
SetLocalVoiceChanger
SetLocalVoiceReverbPreset
SetEncryptionSecret
SetEncryptionMode
OnFirstLocalAudioFrameHandler
该版本于 2020 年 9 月 16 日发布。
Agora 在该版本对通信场景采用了全新的系统架构,并升级了通信和直播场景下的 last mile 网络策略。在带宽不足时,新的网络策略能充分利用上下行有限带宽提升有效码率,从而增强弱网对抗能力,极大提升了弱网情况下通信和直播场景的终端用户体验。
由于通信场景采用了新的系统架构,为保证新老版本通信用户的互通兼容,我们使用了回退机制。如果频道内有老版本通信用户加入,则当前版本 (3.0.1) 的终端用户会回退成老版本通信。一旦回退,频道内所有用户都无法享受新版本带来的体验提升。因此我们强烈推荐同步升级所有终端用户到当前版本。
为确保享受全新架构和网络策略优化带来的好处,使用本地服务端录制的客户,请务必同步升级本地服务端录制 SDK 至 3.0.0 版本。
新增特性、改进与问题修复详见下文。
1. 静态库升级动态库(macOS 和 iOS)
该版本将 iOS 和 macOS 的静态库升级为动态库,且库名由 AgoraRtcEngineKit
变更为 AgoraRtcKit
。如果你由老版本的 SDK 升级至该版本,请务必在 Xcode 中重新导入 AgoraRtcKit.framework
,并将该库的 Embed 属性设置为 Embed & Sign。
如果你集成了加密库 AgoraRtcCryptoLoader.framework
,也需要重新导入库并将其 Embed 属性设置为 Embed & Sign。
2. 枚举更名
该版本将设置用户角色的 CLIENT_ROLE
枚举类更名为 CLIENT_ROLE_TYPE
,并对其包含的枚举进行了如下修改:
BROADCASTER
更名为 CLIENT_ROLE_BROADCASTER
AUDIENCE
更名为 CLIENT_ROLE_AUDIENCE
3. 通信场景上行默认不开启视频小流
从该版本起,Agora 在通信场景下,默认不开启视频小流。如需启用,请在成功加入频道后,调用 EnableDualStreamMode(true)
方法启用视频双流模式。在多人视频通信场景下,我们建议你开启视频双流。
1. 设置区域访问限制
该版本新增 GetEngine2
方法,支持在创建 IRtcEngine
实例时指定 SDK 访问的服务器区域。该功能为高级设置,适用于有访问安全限制的场景。目前支持的区域有中国大陆、北美、欧洲、亚洲(中国大陆除外)和全球(默认)。
2. 多频道管理
为方便用户在同一时间加入多个频道,该版本新增了 AgoraChannel
类。通过创建多个 AgoraChannel
对象,用户可以加入各 AgoraChannel
对象对应的频道中,实现多频道功能。
该版本还新增了 SetMultiChannelWant
为当前引擎开启多频道状态,和 SetForMultiChannelUser
在多频道中渲染本地和远端视图。
加入多个频道后,用户可以同时接收多个频道的流,但同一时间只能在一个频道发流。该功能适用于用户需要同时接收多个频道的流,或频繁切换频道发流的场景。详细的集成步骤和注意事项,请参考加入多频道。
3. 调整音乐文件音调
为方便调整混音时音乐文件的播放音调,该版本新增 SetAudioMixingPitch
方法。通过设置该方法的 pitch
参数,你可以升高或降低音乐文件的音调。该方法仅对音乐文件音调有效,对本地人声不生效。
4. 调节本地播放的指定远端用户音量
该版本新增 AdjustUserPlaybackSignalVolume
方法,用以调节本地用户听到的指定远端用户的音量。通话或直播过程中,你可以多次调用该方法,来调节多个远端用户在本地播放的音量,或对某个远端用户在本地播放的音量调节多次。
5. 美声和音效
为提高用户的音频体验,该版本在 SetLocalVoiceChanger
和 SetLocalVoiceReverbPreset
中分别新增以下枚举值:
VOICE_CHANGER_PRESET
枚举中新增了以 VOICE_BEAUTY
为前缀和以 GENERAL_BEAUTY_VOICE
为前缀的枚举值,分别实现音色变换或语聊美声功能。AUDIO_REVERB_PRESET
枚举中新增了以 AUDIO_REVERB_FX
为前缀的枚举值和 AUDIO_VIRTUAL_STEREO
,分别实现变声音效、新版曲风音效、新版空间塑造和虚拟立体声效果。6. 人脸检测
该版本在 Android 和 iOS 平台新增人脸检测功能。通过 EnableFaceDetection
方法开启人脸检测后,SDK 会实时触发 OnFacePositionChangedHandler
回调,向本地用户报告检测出的一系列结果,包括人脸距设备屏幕的距离。该功能可用于提醒用户注意用眼卫生,和屏幕保持一定距离。
1. 音频编码属性
为满足更高音质需求,该版本调整了直播场景下 AUDIO_PROFILE_DEFAULT(0)
对应的音频编码属性,详见下表:
SDK 版本 | AUDIO_PROFILE_DEFAULT(0) |
---|---|
3.0.1 | 48 KHz 采样率,音乐编码,单声道,编码码率最大值为 52 Kbps。 |
3.0.1 之前 | 32 KHz 采样率,音乐编码,单声道,编码码率最大值为 64 Kbps。 |
2. 质量透明
为方便开发者获取更多通话统计信息,该版本在 RtcStats
类中新增如下成员,方便更好地监控通话的质量和通话过程中的内存变动:
gatewayRtt
memoryAppUsageRatio
memoryTotalUsageRatio
memoryAppUsageInKbytes
在 iOS 上,为避免 iOS 14 设备中出现本地网络权限弹窗提示,gatewayRtt
参数默认关闭。详见 FAQ。 如果你不介意弹窗提示,且需启用该功能,请提交工单联系声网技术支持。
3. 屏幕共享
为支持更多屏幕共享使用场景,该版本新增支持调用 StartScreenCaptureByWindowId
方法时共享通用 Windows 平台(UWP)应用窗口。
4. 美颜
该版本新增 SetBeautyEffectOptions
对 Windows 平台的支持,你可以调用该接口设置对比度、亮度、平滑度等参数,达到美白、磨皮、红润肤色等美颜效果。
5. 其他提升
VIDEO_PIXEL_FORMAT
中新增 VIDEO_PIXEL_RGBA
,你可以将自采集的 RGBA 视频数据传递给 SDK。EnableWebSdkInteroperability
方法。OnVideoSizeChangedHandler
回调无响应、 VideoFrame
中 buffer
一直为空、水印、视频画面比例、画质模糊、视频不能全屏、连麦用户屏幕共享黑屏、屏幕共享黑边等视频问题。SetRemoteSubscribeFallbackOption
方法也生效的问题。SendStreamMessage
和 SetLiveTranscoding
中 TranscodingUser
不支持数组的问题。OnClientRoleChangedHandler
回调多次、App ID 和 Token 校验、日志目录乱码等问题。新增
GetEngine2
CreateChannel
AgoraChannel
类SetMultiChannelWant
SetForMultiChannelUser
SetAudioMixingPitch
AdjustUserPlaybackSignalVolume
VOICE_CHANGER_PRESET
枚举类型中新增 VOICE_BEAUTY_VIGOROUS
等 12 个枚举值AUDIO_REVERB_PRESET
枚举类型中新增 AUDIO_REVERB_FX_KTV
等 9 个枚举值EnableFaceDetection
OnFacePositionChangedHandler
RtcStats
类中新增 gatewayRtt
、memoryAppUsageRatio
、memoryTotalUsageRatio
和 memoryAppUsageInKbytes
成员RemoteAudioStats
结构体中新增 totalActiveTime
成员RemoteVideoStats
结构体中新增 totalActiveTime
成员AudioVolumeInfo
结构体新增 channelId
成员更名
枚举类 CLIENT_ROLE
更名为 CLIENT_ROLE_TYPE
。其包含的枚举 BROADCASTER
和 AUDIENCE
更名为 CLIENT_ROLE_BROADCASTER
和 CLIENT_ROLE_AUDIENCE
。
废弃
EnableWebSdkInteroperability
OnFirstRemoteVideoFrameHandler
,使用 OnRemoteVideoStateChangedHandler
取代OnUserMutedAudioHandler
, OnFirstRemoteAudioDecodedHandler
和 OnFirstRemoteAudioFrameHandler
,使用 OnRemoteAudioStateChangedHandler
取代OnStreamPublishedHandler
和 OnStreamUnpublishedHandler
,使用 OnRtmpStreamingStateChangedHandler
取代该版本于 2020 年 2 月 17 日发布。
Agora Unity SDK 广泛应用于游戏、教育、AR、VR 等场景。
该版本于 2019 年 12 月 23 日发布。功能特性及相关文档详见下文。
1. 多平台支持
该版本支持在 iOS、Android、macOS 和 Windows (x86/x86-64) 平台中集成。
2. 支持与 Web 互通
该版本提供 EnableWebSdkInteroperability
方法,用于打开直播场景下与 Agora Web SDK 的互通。
3. 视频渲染方式
该版本支持多样的视频渲染方式,你可以在 Unity 菜单中选择 Auto Graphics API 下任意的视频渲染模式。
4. 多线程渲染
该版本支持多线程渲染,你可以在 Unity 菜单中选择 Multithreaded Rendering 启用该功能。
5. 原始音视频数据
该版本支持原始音频数据和 RGBA 格式的原始视频数据,你可以获取原始音视频数据并自行处理。详见原始视频数据。
6. 音视频自采集
该版本提供音视频自采集的接口,你可以配置外部音视频源及推送音视频数据。详见自定义视频采集和渲染。
7. 加密
该版本支持加密功能,你可以对音视频流进行加密。下表展示移动端的加密库信息,若希望减小 SDK 体积且不使用加密功能,你可以把加密库移除。
平台 | 加密库 |
---|---|
Android | libagora-crypto.so |
iOS |
|
8. 云代理服务
支持使用云代理服务,方便部署企业防火墙的用户正常使用 Agora 的服务,详见使用云代理服务。
你可以参考以下文档集成 SDK,实现相应的实时音视频功能:
Agora 提供了开源的 Unity GitHub Sample,你也可以前往下载并体验。