本文提供 Agora 音频 SDK 的发版说明。
如果您的应用以 Android 9 为目标平台,您应牢记以下行为变更。对设备序列信息和 DNS 信息进行的这些更新可增强用户隐私保护。
构建序列号弃用
在 Android 9 中,Build.SERIAL
始终设置为 "UNKNOWN" 以保护用户的隐私。
如果您的应用需要访问设备的硬件序列号,您应改为请求 READ_PHONE_STATE 权限,然后调用 getSerial()
。
DNS 隐私
以 Android 9 为目标平台的应用应采用私有 DNS API。 具体而言,当系统解析程序正在执行 DNS-over-TLS 时,应用应确保任何内置 DNS 客户端均使用加密的 DNS 查找与系统相同的主机名,或停用它而改用系统解析程序。
详情请参考 Android 隐私权变更。
该版本于 2021 年 1 月 22 日发布。
1. 集成变更
该版本新增 Agora 基础计算框架 libagora-core.so
。请参考集成 SDK 将 SDK 集成至你的项目。
2. 行为变更
该版本废弃了 setDefaultMuteAllRemoteAudioStreams
,并修改了 mute
相关方法的如下行为:
mute
相关方法需要在加入频道或切换频道后调用,否则会不生效。mute
相关方法都能独立控制用户的订阅状态。一起调用 muteAll
为前缀的方法和 muteRemote
为前缀的方法时,后调用的方法会生效。muteAll
为前缀的方法设置是否订阅所有音频流,包含调用时刻之后加入频道的用户的音频流,即 muteAll
为前缀的方法包含了 setDefaultMute
为前缀的方法的功能。Agora 不推荐一起调用 muteAll
和 setDefaultMute
为前缀的方法,否则设置可能会不生效。更多介绍见设置订阅状态。
1. 频道媒体选项
为方便开发者更灵活地控制媒体流订阅,该版本新增 joinChannel
[2/2] 和 switchChannel
[2/2] 方法,支持设置用户加入频道和切换频道时是否订阅频道内所有的远端音频流。
2. 云代理
为提升 Agora 云代理的易用性,该版本新增 setCloudProxy
方法设置云代理并允许你选择连接 UDP 协议的云代理。详见云代理。
3. AI 降噪
为在传统降噪模式的基础上消除非平稳噪声,该版本新增 enableDeepLearningDenoise
,用于开启 AI 降噪模式。
libagora_ai_denoise_extension.so
动态库集成到你的项目文件中。4. 歌唱美声
在歌唱场景中,为美化歌声并添加混响效果,该版本新增 setVoiceBeautifierParameters
,并添加 SINGING_BEAUTIFIER
枚举值。
你可以调用 setVoiceBeautifierPreset(SINGING_BEAUTIFIER)
美化男声并添加歌声在小房间的混响效果。如需更多设置,你可以调用 setVoiceBeautifierParameters(SINGING_BEAUTIFIER, param1, param2)
美化男声或女声,并添加歌声在小房间、大房间或大厅的混响效果。
5. 设置日志文件
为保证日志内容的完整性,该版本在 RtcEngineConfig
中新增 mLogConfig
成员变量,在你初始化 RtcEngine
时可用于设置 Agora SDK 输出的日志文件。详见如何设置日志文件。
自该版本起,Agora 不推荐使用 setLogFile
、setLogFileSize
和 setLogFilter
方法设置日志文件。
6. 创建数据流
为了支持歌词同步、课件同步等场景,该版本废弃了原有的 createDataStream
方法,并使用新的同名方法替代,用于创建数据流,并设置数据流是否与发布到 Agora 频道内的音频流同步以及接收到的数据是否有序。
1. 原始音频数据
该版本补齐了 Android 平台的原始音频数据接口。你可以从原始音频数据接口获取原始音频数据,并进行前处理或后处理,获取想要的播放效果。
onPlaybackFrameBeforeMixing
onMixedFrame
isMultipleChannelFrameWanted
onPlaybackFrameBeforeMixingEx
2. 远端音频统计
为方便监测通话中与音频有关的主观体验,该版本在 onRemoteAudioStats
中增加 qoeQuality
和 qualityChangedReason
,报告接收远端音频时的体验质量以及体验质量较差的原因。
该版本修复了如下问题:
新增
setVoiceBeautifierParameters
SINGING_BEAUTIFIER
枚举值enableDeepLearningDenoise
joinChannel
[2/2]switchChannel
[2/2]createDataStream
RtcEngineConfig
类中新增 mLogConfig
成员变量onPlaybackFrameBeforeMixing
onMixedFrame
isMultipleChannelFrameWanted
onPlaybackFrameBeforeMixingEx
RemoteAudioStats
类中新增 qoeQuality
和 qualityChangedReason
成员变量setCloudProxy
ERR_MODULE_NOT_FOUND(157)
废弃
setDefaultMuteAllRemoteAudioStreams
setLogFile
setLogFileSize
setLogFilter
createDataStream
该版本于 2020 年 12 月 17 日发布,修复了如下问题:
Client.on(disable-local-video)
或 Client.on(mute-video)
回调。该版本于 2020 年 11 月 30 日发布。
1. 集成变更
SDK 包变更
自该版本起,SDK 包中新增以下文件:
libagora-fdkaac.so
: Fraunhofer FDK AAC 动态库。libagora-mpg123.so
: mpg123 动态库。libagora-soundtouch.so
: SoundTouch 动态库。如果你将 SDK 升级到 v3.2.0 或更高版本,请务必将上述文件拷贝至 libagora-rtc-sdk.so
所在文件夹中。
此外,该版本将 SDK 包中的 libagora-crypto.so
文件合并入 libagora-rtc-sdk.so
文件中。集成 libagora-rtc-sdk.so
后,你可以直接使用内置加密功能。
拼写更正
该版本更正了 API 拼写错误,将 USER_PRIORITY_NORANL
修改为 USER_PRIORITY_NORMAL
。
2. 云代理
该版本优化了 Agora 云代理架构。如果你已经在使用云代理,为避免新 SDK 和老云代理的兼容性问题,请在升级 SDK 前联系技术支持。详见云代理。
3. 安全合规
Agora 已通过 ISO 27001、ISO 27017、ISO 27018 国际认证,为全球用户提供安全可靠的实时互动云服务。详见 ISO 证书。
同时,为支持传输层加密,该版本新增 TLS(Transport Layer Security)加密和 UDP(User Datagram Protocol)加密方式。
极速直播
该版本新增 setClientRole
方法,支持设置观众的延时级别。你可以通过该方法在互动直播和极速直播之间切换:
详见极速直播产品概述。
1. 会议场景
为提升多人会议的音频体验,该版本在 setAudioProfile
中新增 AUDIO_SCENARIO_MEETING(8)
。
2. 美声与音效
为提升美声与音效 API 的易用性,该版本废弃 setLocalVoiceChanger
和 setLocalVoiceReverbPreset
,并新增如下方法替代:
setVoiceBeautifierPreset
: 与 setLocalVoiceChanger
相比,该方法删除了小男孩等变声音效和空旷音效。setAudioEffectPreset
: 与 setLocalVoiceReverbPreset
相比,该方法新增了小男孩等变声音效、空旷音效、3D 人声音效和电音音效,并删除了摇滚和嘻哈音效。setAudioEffectParameters
: 对指定的音效选项进行更细节的设置。该版本支持的音效选项有 3D 人声和电音音效。3. 互动直播延时
互动直播场景下,观众看直播的延时降低了约 500 ms。
该版本修复了用户使用小米音箱进行通话时偶现的录音问题。
新增
setClientRole
setAudioEffectPreset
setVoiceBeautifierPreset
setAudioEffectParameters
AUDIO_SCENARIO_TYPE
enum 中新增 AUDIO_SCENARIO_MEETING
(8)废弃
setLocalVoiceChanger
setLocalVoiceReverbPreset
该版本于 2020 年 8 月 27 日发布。该版本修改了区域访问限制的区域码 AreaCode
,最新区域码如下:
AREA_CODE_CN
: 中国大陆。AREA_CODE_NA
: 北美区域。AREA_CODE_EU
: 欧洲区域。AREA_CODE_AS
: 除中国大陆以外的亚洲区域。 AREA_CODE_JP
: 日本。AREA_CODE_IN
: 印度。AREA_CODE_GLOB
:(默认)全球。如你此前调用 create
方法时指定了访问区域,在由之前版本升级至该版本时,请确保使用正确的区域码。
该版本于 2020 年 8 月 11 日发布。
1. 发布和订阅状态转换回调
该版本新增以下回调方便你了解音频流当前的发布及订阅状态,有助于订阅和发布相关的数据统计:
onAudioPublishStateChanged
: 音频发布状态发生改变。onAudioSubscribeStateChanged
: 音频订阅状态发生改变。2. 本地首帧发布回调
该版本新增 onFirstLocalAudioFramePublished
提示用户本地音频首帧已发布。该回调取代 onFirstLocalAudioFrame
回调,我们建议你不再使用 onFirstLocalAudioFrame
回调。
3. 自定义数据上报
该版本支持自定义数据上报。如需试用,请联系 sales@agora.io 开通并商定自定义数据格式。
1. 指定访问区域完善
该版本新增以下枚举值,在调用 create
创建 RtcEngine
实例时提供更多区域选择。指定访问区域后,集成了 Agora SDK 的 app 会连接指定区域内的 Agora 服务器。
AREA_CODE_JAPAN
: 日本。AREA_CODE_INDIA
: 印度。2. 加密
该版本新增 enableEncryption
方法,用于开启内置加密,并废弃原加密方法:
setEncryptionSecret
setEncryptionMode
与原加密方法相比,该方法新增对国密 SM4 加密模式的支持,你可以根据需要选择合适的加密模式。
3. 通话中质量透明
该版本进一步扩充了 LocalAudioStats
类和 RemoteAudioStats
类的成员,提供更多音频质量相关数据。
LocalAudioStats
类新增 txPacketLossRate
,表示本端到 Agora 边缘服务器的物理音频丢包率 (%)。RemoteAudioStats
类中新增 publishDuration
,表示远端音频流的累计发布时长(毫秒)。4. 设置音频编码属性
为提升音频性能,该版本对音频编码码率最大值进行如下优化:
Profile | 3.1.0 版本 | 3.1.0 版本之前 |
---|---|---|
AUDIO_PROFILE_DEFAULT | ||
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 |
5. 日志扩容
该版本中,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
写入最新的日志。
6. OPPO 耳返优化
该版本在 OPPO 如下机型上降低了耳返延时:
7. 其他改进
该版本修复了如下问题:
setAudioMixingPitch
方法时,部分参数不生效。新增
onAudioPublishStateChanged
onAudioSubscribeStateChanged
onFirstLocalAudioFramePublished
enableEncryption
LocalAudioStats
类中新增 txPacketLossRate
RemoteAudioStats
类中新增 publishDuration
onRtmpStreamingEvent
ERR_NO_SERVER_RESOURCES(103)
废弃
setEncryptionSecret
setEncryptionMode
onFirstLocalAudioFrame
该版本于 2020 年 5 月 27 日发布。
1. 调整音乐文件音调
为方便调整混音时音乐文件的播放音调,该版本新增 setAudioMixingPitch
方法。通过设置该方法的 pitch
参数,你可以升高或降低音乐文件的音调。该方法仅对音乐文件音调有效,对本地人声不生效。
2. 变声与混响
为提高用户的音频体验,该版本在 setLocalVoiceChanger
和 setLocalVoiceReverbPreset
中分别新增以下枚举值:
VOICE_BEAUTY
为前缀和以 GENERAL_BEAUTY_VOICE
为前缀的枚举值,分别实现美音或语聊美声功能。AUDIO_REVERB_FX
为前缀的枚举值和 AUDIO_VIRTUAL_STEREO
,分别实现增强版混响效果和虚拟立体声效果。你可以查看进阶功能变声与混响了解使用方法和注意事项。
3. 远端音频数据后处理多频道支持 (C++)
在多频道场景下,为方便后处理各频道的远端音频数据,该版本新增如下 C++ 接口:
IAudioFrameObserver
类中新增 isMultipleChannelFrameWanted
和 onPlaybackAudioFrameBeforeMixingEx
。成功注册音频观测器后,如果你将 isMultipleChannelFrameWanted
的返回值设为 true
,就可以通过上述回调获取多个频道对应的音频数据。在多频道场景下,我们建议你将返回值设为 true
。
onRemoteAudioStateChanged
回调不准、音频无声、混音、声音卡顿等问题。onClientRoleChanged
回调多次、偶现崩溃、上麦逻辑、加密互通等问题。该版本新增以下 API:
setAudioMixingPitch
VOICE_BEAUTY
为前缀、以 GENERAL_BEAUTY_VOICE
为前缀和以 AUDIO_REVERB_FX
为前缀的枚举值,以及 AUDIO_VIRTUAL_STEREO
枚举值RemoteAudioStats
中新增 totalActiveTime
该版本于 2020 年 4 月 22 日发布。
设置区域访问限制
该版本新增 create
方法,支持在创建 RtcEngine
实例时指定服务器的访问区域。该功能为高级设置,适用于有访问安全限制的场景。目前支持的区域有中国大陆、北美、欧洲、亚洲(中国大陆除外)和全球(默认)。
指定访问区域后,集成了 Agora SDK 的 app 在指定区域使用时,正常情况下会连接指定区域的 Agora 服务器;在非指定区域使用时,会从所在区域和指定区域的服务器地址中,择优选择服务器建立连接。
该版本修复了音频无声的问题。
新增
该版本于 2020 年 3 月 4 日发布。并于 2020 年 3 月 24 日修复了偶现的音频无声、混音、onClientRoleChanged
回调多次、崩溃等问题。
Agora 在该版本对通信场景采用了全新的系统架构,并升级了通信和直播场景下的 last mile 网络策略。在带宽不足时,新的网络策略能充分利用上下行有限带宽提升有效码率,从而增强弱网对抗能力,极大提升了弱网情况下通信和直播场景的终端用户体验。
由于通信场景采用了新的系统架构,为保证新老版本通信用户的互通兼容,我们使用了回退机制。如果频道内有老版本通信用户加入,则当前版本 (3.0.0) 的终端用户会回退成老版本通信。一旦回退,频道内所有用户都无法享受新版本带来的体验提升。因此我们强烈推荐同步升级所有终端用户到当前版本。
同时,我们对本地服务端录制进行了升级发布。为确保享受全新架构和网络策略优化带来的好处,使用本地服务端录制的客户,请务必同步升级本地服务端录制 SDK 至 3.0.0 版本。
日志默认保存路径改变
为避免权限问题,该版本默认日志路径由 /storage/emulated/0/<package name>/
变更为 /storage/emulated/0/Android/data/<package name>/files/
。
1. 多频道管理
为方便用户在同一时间加入多个频道,该版本新增了 RtcChannel
和 IRtcChannelEventHandler
类。通过创建多个 RtcChannel
对象,用户可以加入各 RtcChannel
对象对应的频道中,实现多频道功能。
加入多个频道后,用户可以同时接收多个频道的流,但只能同时在一个频道内发流。该功能适用于用户需要同时接收多个频道的流,或频繁切换频道发流的场景。详细的集成步骤和注意事项,请参考《加入多频道》。
2. 调节本地播放的指定远端用户音量
该版本新增 adjustUserPlaybackSignalVolume
方法,用以调节本地用户听到的指定远端用户的音量。通话或直播过程中,你可以多次调用该方法,来调节多个远端用户在本地播放的音量,或对某个远端用户在本地播放的音量调节多次。
3. 媒体播放器组件
为丰富直播玩法,Agora 发布了媒体播放器组件,支持主播在直播过程中,播放本地或在线媒体资源,并同步分享给频道内所有用户。详情请参考《媒体播放器组件发版说明》。
1. 音频编码属性
为满足更高音质需求,该版本调整了直播场景下 AUDIO_PROFILE_DEFAULT (0)
对应的音频编码属性,详见下表:
SDK 版本 | AUDIO_PROFILE_DEFAULT (0) |
---|---|
3.0.0 | 48 KHz 采样率,音乐编码,单声道,编码码率最大值为 52 Kbps。 |
3.0.0 之前 | 32 KHz 采样率,音乐编码,单声道,编码码率最大值为 44 Kbps。 |
2. 质量透明
为方便开发者获取更多通话统计信息,该版本在 RtcStats
类中新增 gatewayRtt
、memoryAppUsageRatio
、memoryTotalUsageRatio
和 memoryAppUsageInKbytes
成员,方便更好地监控通话的质量和通话过程中的内存变动。
3. 其他提升
该版本自动开启直播场景下 Native SDK 与 Web SDK 的互通,并废弃原有的 enableWebSdkInteroperability
方法。
行为变更
enableLocalAudio
(false) 后,不会引起通话音量切换为媒体音量。 setEnableSpeakerPhone
(true),不会将语音路由切换到外放。新增
AudioVolumeInfo
结构体新增 channelId
成员RtcStats
结构体新增 gatewayRtt
, memoryAppUsageRatio
, memoryTotalUsageRatio
, and memoryAppUsageInKbytes
成员createRtcChannel
RtcChannel
类IRtcChannelEventHandler
类废弃
enableWebSdkInteroperability
onUserMuteAudio
,onFirstRemoteAudioDecoded
和 onFirstRemoteAudioFrame
,使用 onRemoteAudioStateChanged
取代onStreamPublished
和 onStreamUnpublished
,使用 onRtmpStreamingStateChanged
取代该版本于 2020 年 2 月 17 日发布。
该版本修复了 Android 设备上的部分异常。
该版本于 2019 年 10 月 18 日发布。
该版本修复了部分 Android 设备上的崩溃问题。
该版本于 2019 年 9 月 19 日发布。新增特性与修复问题详见下文。
1. 人声检测
为判断本地用户是否说话,该版本在启用说话者音量提示 enableAudioVolumeIndication 方法中新增 bool 型的 report_vad
参数。启用该参数后,你会在 onAudioVolumeIndication
回调报告的 AudioVolumeInfo 结构体中获取本地用户的人声状态。
2. 删除指定事件句柄
在特定场景下,开发者不想再接收某些事件的回调。该版本新增 removeHandler 方法,你可以调用该方法删除不再需要的事件句柄。
1. 设置客户端录音采样率
为方便用户设置客户端录音的采样率,该版本废弃了原有的 startAudioRecording
方法,并使用新的同名方法进行取代。新的方法下,录音采样率可设为 16、32、44.1 或 48 kHz。原方法仅支持固定的 32 kHz 采样率,该版本继续保留原方法但我们不推荐使用。
2. 错误码梳理
为提高用户体验,该版本对各平台的错误码 Error Code 进行了梳理。其中 Java 平台的 ErrorCode 类中,补齐如下错误码:
ERR_ALREADY_IN_USE(19)
ERR_WATERMARK_PATH(125)
ERR_INVALID_USER_ACCOUNT(134)
ERR_AUDIO_BT_SCO_FAILED(1030)
ERR_ADM_NO_RECORDING_DEVICE(1359)
ERR_VCM_UNKNOWN_ERROR(1600)
ERR_VCM_ENCODER_INIT_ERROR(1601)
ERR_VCM_ENCODER_ENCODE_ERROR(1602)
ERR_VCM_ENCODER_SET_ERROR(1603)
各错误码的详细描述及排查办法,详见 Error Codes。
音频
setEnableSpeakerphone
方法后行为与预期不符。startAudioMixing
方法播放在线音乐 URL 失败。其他
新增
report_vad
参数vad
成员废弃
startAudioRecording
该版本于 2019 年 8 月 16 日发布。新增特性与修复问题详见下文。
1. RTMP 推流
该版本起,Agora 删除如下接口:
configPublisher
如果你的 App 使用上述接口实现 RTMP 推流功能,请确保将 Native SDK 升级至最新版本,并改用如下接口实现推流:
新的推流实现方法,请参考推流到 CDN。
2. 关闭/开启本地音频采集
为提高通信模式下,本地用户关闭麦克风后听到的音质,该版本在 enableLocalAudio
(true) 后,将系统音量修改为媒体音量。调用 enableLocalAudio
(false) 后,系统音量自动切换为通话音量。
1. 快速切换频道
为方便直播频道中的观众用户快速切换到其他频道,该版本新增 switchChannel
方法。和先调 leaveChannel
,再调 joinChannel
相比,该方法能实现更快的频道切换。调用 switchChannel
方法切换到其他直播频道后,本地会先收到离开原频道的回调 onLeaveChannel
,再收到成功加入新频道的回调 onJoinChannelSuccess
。
2. 跨频道媒体流转发
跨频道媒体流转发,指将主播的媒体流转发至其他直播频道,实现主播跨频道与其他主播实时互动的场景。该版本新增如下接口,通过将源频道中的媒体流转发至目标频道,实现跨直播间连麦功能:
在跨频道媒体流转发过程中,SDK 会通过onChannelMediaRelayStateChanged
和 onChannelMediaRelayEvent
回调报告媒体流转发的状态和事件。
该场景的实现方法、API 调用时序、示例代码及开发注意事项,请参考跨直播间连麦。
3. 本地及远端音频状态
为方便用户了解本地及远端的音频状态,该版本新增 onLocalAudioStateChanged
和 onRemoteAudioStateChanged
回调。新的回调下,本地及远端音频有如下状态:
error
参数中返回的错误码定位及排查问题。reason
参数中了解引起远端音频状态发生改变的原因。4. 本地音频数据
为方便更好地了解通话质量,获取更多质量相关数据,该版本新增 onLocalAudioStats
回调,通过 numChannels
、sentSampleRate
、sentBitrate
参数报告本地音频统计信息。
5. 远端音频帧拉取
为提升音频播放体验,该版本新增如下接口,支持使用拉取的方式获取远端音频数据。App 可以对拉取到的原始音频数据进行处理后再渲染,获取想要的音频效果。
该方法和 onPlaybackFrame
回调相比,区别在于:
onPlaybackFrame
:SDK 每 10 毫秒通过回调将音频数据传输给 App。如果 App 处理延时,可能会导致音频播放抖动。pullPlaybackAudioFrame
:App 主动拉取音频数据。通过设置音频数据,SDK 可以调整缓存,帮助 App 处理延时,从而有效避免音频播放抖动。1. 通话中质量透明
该版本进一步扩充了 RtcStats
类的成员:
RtcStats
类:累计发送音频字节数及累计接收音频字节数2. 其他改进
音频
startAudioMixing
播放音乐文件失败的问题。其他
为提升用户体验,Agora SDK 在该版本中对 API 进行了如下变动:
新增
setExternalAudioSink
pullPlaybackAudioFrame
onLocalAudioStateChanged
onRemoteAudioStateChanged
onLocalAudioStats
switchChannel
startChannelMediaRelay
updateChannelMediaRelay
stopChannelMediaRelay
onChannelMediaRelayStateChanged
onChannelMediaRelayEvent
RtcStats
类新增 txAudioBytes
和 rxAudioBytes
成员废弃
onMicrophoneEnabled
,请改用 onLocalAudioStateChanged
的 LOCAL_AUDIO_STREAM_STATE_CHANGED(0) 或 LOCAL_AUDIO_STREAM_STATE_RECORDING(1)。onRemoteAudioTransportStats
,请改用 onRemoteAudioStats
。删除
configPublisher
该版本于 2019 年 8 月 1 日发布。修复了与 Web SDK 的互通问题。
该版本于 2019 年 7 月 20 日发布。新增特性详见下文。
该版本于 2019 年 7 月 8 日发布。新增特性与修复问题列表详见下文。
1. 全平台支持 String 型的用户 ID
很多 App 使用 String 类型的用户 ID。为降低开发成本,Agora 新增支持 String 型的 User account,方便用户通过如下接口直接使用 App 账号加入 Agora 频道:
对于其他接口,Agora 沿用 Int 型的 UID。Agora Engine 会维护 UID 和 User account 映射表,你可以随时通过 String user account 获取 UID,或者通过 UID 获取 String user account,无需自己维护映射表。
为保证通信质量,频道内所有用户需使用同一数据类型的用户 ID,即频道内的所有用户 ID应同为 Int 型或同为 String 型。
Note:
同一频道内,Int 型的 User ID 和 String 型的 User account 不可混用。目前支持 String 型 User account 的 SDK 如下:
如果你的频道内有不支持 String 型 User account 的用户,则只能使用 Int 型的 User ID。
如果你使用该版本的 Native SDK 将用户 ID切换至 String 型 User account,请确保所有终端用户同步升级。
如果使用 String 型的 User account,请确保你的服务端用户生成 Token 的脚本已升级至最新版本。如果使用 String 型 User account 加入频道,请确保使用该 User account 或其对应的 Int 型 UID 来生成 Token。你可以调用 getUserInfoByUserAccount
来获取 User account 所对应的 UID。
2. 音频卡顿回调
为监控通话过程中的音频传输质量,方便开发者客观体验通信质量,该版本在远端音频统计数据 RemoteAudioStats 类中新增 totalFrozenTime
和 frozenRate
成员,报告远端用户在加入频道后发生音频的卡顿时长及卡顿率。
同时,该版本在 RemoteAudioStats 类中还新增 numChannels
、receivedSampleRate
和 receivedBitrate
成员。
为方便开发者统计掉线率,该版本在 onConnectionStateChanged 回调的 reason
参数中添加 CONNECTION_CHANGED_KEEP_ALIVE_TIMEOUT(14)
成员,表示 SDK 与服务器连接保活超时,引起 SDK 连接状态发生改变。
音频
其他
为提升用户体验,Agora 在 v2.8.0 版本中对 API 进行了如下变动:
新增
numChannels
,receivedSampleRate
,receivedBitrate
,totalFrozenTime
和 frozenRate
成员废弃
lowLatency
成员该版本于 2019 年 6 月 12 日发布。新增特性、功能改进与修复问题列表详见下文。
如下内容涉及 SDK 的行为变更。如果你是由之前版本的 SDK 升级至该版本,升级前请务必阅读。
RTMP 推流
为提高推流服务的易用性,该版本对推流接口的参数设置进行了如下限制:
类/接口 | 参数限制 |
---|---|
LiveTranscoding 类 | |
AgoraImage 类 | url :字符长度不得超过 1024 字节 |
addPublishStreamUrl | url :字符长度不得超过 1024 字节 |
removePublishStreamUrl | url :字符长度不得超过 1024 字节 |
同时,该版本在 LiveTranscoding
类中新增 audioCodecProfile 参数,支持设置音频编码的规格。默认规格为 LC-AAC。
此外,该版本还对 onStreamPublished 方法的 error
参数新增了五个错误码,方便快速定位与排查问题。
1、推流状态回调
为方便推流用户了解当前的推流状态,并在推流出错时了解原因排查问题,该版本新增 onRtmpStreamingStateChanged 回调。该回调下,推流有 IDLE
、CONNECTING
、RUNNING
、RECOVERING
和 FAILURE
五种状态。当推流状态为 FAILURE
时,用户可以参考该回调 errCode
参数返回的错误码进行问题排查。原有的 onStreamPublished
和 onStreamUnpublished
回调仍可以使用,但我们不再推荐。
2、网络连接失败原因梳理
为方便开发者更好地排查网络连接相关故障,该版本梳理并整合了网络连接相关的错误码,在原有 onConnectionStateChanged 回调的 reason
参数中新增八个导致网络连接失败的原因。新增后,只要网络连接发生错误,SDK 都会返回该回调。同时该版本废弃了原有的警告码 WARN_LOOK_UP_CHANNEL_REJECTED(105)
和错误码 ERR_TOKEN_EXPIRED(109)
、ERR_INVALID_TOKEN(110)
。
3、本地网络连接类型回调
为方便用户了解本地网络的连接类型,该版本新增 onNetworkTypeChanged 回调。该回调下,本地网络连接有 UNKNOWN
、DISCONNECTED
、LAN
、WIFI
、2G
、3G
、4G
七种类型。当网络连接短暂中断时,该回调能帮助开发者辨别引起中断的原因是网络切换还是网络条件不好。
4、获取播放伴奏音量
为方便开发者获取伴奏的播放音量,排查音量相关问题,该版本新增 getAudioMixingPlayoutVolume 和 getAudioMixingPublishVolume方法,用以分别获取音乐文件在本地和远端的播放音量。
5、精确回调远端音频首帧解码
为更精准地获取远端用户的出声时间,该版本新增 onFirstRemoteAudioDecoded 回调,用以向 App 层报告 SDK 已完成远端音频首帧解码。在远端用户加入频道后首次发送音频,或远端用户 15 秒不发音频后再次发送时,该回调均会被触发。该回调与 onFirstRemoteAudioFrame
的区别在于,onFirstRemoteAudioFrame
在收到首个音频包时触发,先于 onFirstRemoteAudioDecoded
。
1、在线音效叠加
为提高用户体验,构造丰富有趣的实时音视频场景,该版本新增支持同时播放多个在线音效文件。开发者可以通过多次调用 playEffect 方法,传入不同的在线音效文件的 URL,实现音效叠加。
2、质量透明
3、其他改进
enableAudioQualityIndication
方法,也可以收到 onRemoteAudioStats 回调音频
startAudioMixing
播放伴奏时,音频无法通过蓝牙播放的问题其他
onNetworkQuality
回调的问题为提升用户体验,Agora 在 v2.4.1 版本中对 API 进行了如下变动:
全平台 C++ 接口行为一致
从该版本起,Native SDK 保证了各平台 C++ 接口的行为一致性,方便用户通过统一的 C++ 接口,在各平台保持业务逻辑一致。同时在 C++ 头文件的 IRtcEngine
类中实现了 RtcEngineParameters
类下的所有方法。各接口的适用范围及使用注意事项详见 Agora C++ API Reference for All Platforms 首页。
新增
LiveTranscoding
类新增参数 audioCodecProfileRtcStats
类新增参数 txPacketLossRate 和 rxPacketLossRate废弃
enableAudioQualityIndication
WARN_LOOKUP_CHANNEL_REJECTED(105)
,请改用 onConnectionStateChanged 回调中的 CONNECTION_CHANGED_REJECTED_BY_SERVER(10)ERR_TOKEN_EXPIRED(109)
,请改用 onConnectionStateChanged 回调中的 CONNECTION_CHANGED_TOKEN_EXPIRED(9)ERR_INVALID_TOKEN(110)
,请改用 onConnectionStateChanged 回调中的 CONNECTION_CHANGED_INVALID_TOKEN(8)2.4.0 版
该版本于 2019 年 4 月 1 日发布。新增特性、功能改进与修复问题列表详见下文。
在语音聊天室场景中添加变声和混响效果,能有效增强社交的趣味性。该版本在原有音效设置接口的基础上,新增 setLocalVoiceChanger
和 setLocalVoiceReverbPreset
方法,开发者无需手动设置音效参数,直接选择想要的本地语音变声或混响效果。详情请参考变声与混响。
该版本新增 enableSoundPositionIndication
和 setRemoteVoicePosition
方法,支持本地用户听声辨位。用户需要在加入频道前调用 enableSoundPositionIndication
开启远端用户的语音立体声,然后在 setRemoteVoicePosition
中设置远端用户声音出现的位置,通过左右耳听到的声音差异,对远端用户的声音产生方位感。在多人在线游戏场景,如射击游戏中,该功能可以增加游戏角色的方位感,模拟真实场景。
在通话前进行 Last-mile 网络探测,可以有效帮助本地用户判断和预测上行网络质量是否良好。该版本新增通话前 Last-mile 网络探测接口 startLastmileProbeTest
、stopLastmileProbeTest
及 onLastmileProbeResult
,向用户反馈开始通话前上下行网络的带宽、丢包、网络抖动和往返时延数据。
该版本为播放音乐文件新增回调 onAudioMixingStateChanged
,方便用户获知音乐文件的播放状态(成功/失败),以及播放出错的原因。同时新增一个警告码 701,当播放音乐文件时,本地音乐文件不存在、文件格式不支持或无法访问在线音乐文件 URL 时,均会触发该警告码。
Agora SDK 有 2 个日志文件,每个文件默认大小为 512 KB。为解决该大小无法满足部分用户需求的问题,该版本新增接口 setLogFileSize
,用于设置 SDK 输出的日志文件大小。
支持使用云代理服务,方便部署企业防火墙的用户正常使用 Agora 的服务,详见使用云代理服务。
startEchoTest
中新增参数 intervalInSeconds
,用于设置返回测试结果的时间间隔。LocalVideoStats
类中新增 targetBitrate
,targetFrameRate
,qualityAdaptIndication
三个参数,分别反映目标码率、目标帧率与和上次返回的本地视频流统计信息相比,本地视频质量的自适应情况。enableLocalAudio
接口导致的蓝牙断开的问题为提升用户体验,Agora 在 v2.4.0 版本中对 API 进行了如下变动:
setLocalVoiceChanger
setLocalVoiceReverbPreset
enableSoundPositionIndication
setRemoteVoicePosition
startLastmileProbeTest
stopLastmileProbeTest
startEchoTest
setLogFileSize
onAudioMixingStateChanged
onLastmileProbeResult
startEchoTest
2.3.3 版
该版本于 2019 年 1 月 24 日发布。修复问题详见下文。
onNetworkQuality
回调不准确的问题。2.3.2 版
该版本于 2019 年 1 月 16 日发布。新增特性与修复问题列表详见下文。
2.3.2 整体提升直播模式下视频弱网抗丢包能力,提高流畅度,降低卡顿率。升级前,请了解以下版本兼容性:
为方便用户控制混音音乐文件在本地及远端的播放音量,该版本在已有 adjustAudioMixingVolume
的基础上新增 adjustAudioMixingPlayoutVolume
和 adjustAudioMixingPublishVolume
接口,用于分别控制混音音乐文件在本地和远端的播放音量。
添加新的方法后,原有的 adjustPlaybackSignalVolume 由控制人声和音乐的音量改为仅控制人声的音量。因此,如果要静音本地播放,需同时设置 adjustPlaybackSignalVolume(0)
和 adjustAudioMixingPlayoutVolume(0)
。
该版本梳理了用户在音频采集到播放过程中可能会需要调整音量的场景,及各场景对应的 API,供用户参考使用。详见官网文档调整通话音量。
为提升质量透明的用户体验,该版本废弃了原有的 onAudioQuality
回调,并新增 onRemoteAudioStats
回调进行取代。和原来的接口相比,新接口使用更为综合的算法,通过引入音频丢帧率、端到端的音频延迟、接收端网络抖动的缓冲延迟等参数,使回调结果更贴近用户感受。同时,该版本优化了 onNetworkQuality
的算法,对上下行网络质量采用不同的计算方法,使评分更精准。
onRemoteAudioStats
:通话中远端音频流的统计信息回调。用于替换 onAudioQuality
onNetworkQuality
:通话中每个用户的网络上下行 Last mile 质量报告回调Agora SDK 计划在下一个版本对如下 API 进行进一步改进:
onLastmileQuality
:通话前网络上下行 Last mile 质量报告回调该版本对数据统计相关回调进行了统一梳理,相关回调及算法详见通话中数据统计。
为提升 SDK 使用数据统计的准确性和合理性,该版本新增如下接口,用以获取 SDK 的网络连接状态,以及连接状态发生改变的原因。
getConnectionState
:获取 SDK 的网络连接状态onConnectionStateChanged
:SDK 的网络连接状态已改变回调该版本废弃了原有的 onConnectionInterrupted
和 onConnectionBanned
回调。
在新的接口下,SDK 共有 5 种连接状态:未连接、正在连接、已连接、正在重新建立连接和连接失败。当连接状态发生改变时,都会触发 onConnectionStateChanged
回调。当条件满足时,原有的 onConnectionInterrupted
和 onConnectionBanned
回调也会触发,但 Agora 不再推荐使用。
为方便用户(开发者)收集最终用户(应用程序使用者)对使用应用进行通话或直播的反馈,该版本将 rate
接口中的打分范围缩小为 1 - 5,减少最终用户的打分干扰。Agora 建议在应用程序中集成该接口,方便应用程序收集用户反馈。
startAudioMixing
播放音乐文件时出现的崩溃问题为提升用户体验,Agora 在 v2.3.2 版本中对 API 进行了如下变动。
getConnectionState
adjustAudioMixingPlayoutVolume
adjustAudioMixingPublishVolume
onConnectionStateChanged
onRemoteAudioStats
2.3.1 版
该版本于 2018 年 10 月 12 日发布。新增特性与修复问题列表详见下文。
应用程序在加入频道时,语音功能是默认打开的。为满足用户只接收而不发送音频流的需求,该版本新增 enableLocalAudio
接口,方便应用程序在进入频道后关闭或重新开启本地语音功能。关闭本地语音功能后,应用程序会收到 onMicrophoneEnabled
回调,并停止采集本地音频流。该方法不影响接收和播放远端音频流。
该功能与 muteLocalAudioStream
的区别在于前者不采集不发送,而后者是采集但不发送。
2.3.0 版
该版本于 2018 年 8 月 31 日发布。新增特性与修复问题列表详见下文。
Agora SDK 在 v2.3.0 版本中,全面提升了视频功能的稳定性及可用性,保证了更加可靠的实时通信。同时音视频质量也得到进一步提高。 视频方面,通过优化编码性能,增强了弱网对抗能力,减少卡顿时间,提升视频流畅度;音频方面,采用深度学习算法,改进了通话中的音频质量。
该版本中 LiveTranscoding Class 从 io.agora.live
Package 移到了 io.agora.rtc.live
Package。
该版本修改了 API constants.java
中的拼写错误。
public static final int SOFEWARE_ENCODER = 1;
public static final int SOFTWARE_ENCODER = 1;
为更好地提升用户体验,Agora SDK 在 v2.1.0 版本中对动态密钥进行了升级。如果你当前使用的 SDK 是 v2.1.0 之前的版本,并希望升级到 v2.1.0 或更高版本,请务必参考 动态密钥升级说明 。
本次发版新增如下功能:
由于 Token 具有一定的时效,在通话过程中如果 Token 即将失效,SDK 会提前 30 秒触发回调 onTokenPrivilegeWillExpire
,提醒应用程序更新 Token。当收到该回调时,用户需要重新在服务端生成新的 Token,然后调用 renewToken
将新生成的 Token 传给 SDK。
为方便统计每个用户的音频上下行码率、帧率及丢包率,该版本新增 onRemoteAudioTransportStats
回调。 通话或直播过程中,当用户收到远端用户发送的音视频数据包后,会周期性地发生该回调上报,频率约为 2 秒 1 次。 回调中包含用户的 UID、音频接收码率、丢包率、以及延迟时间(毫秒)。 并在统计频道内通话相关数据的 Rtcstats 类中增加 lastmileDelay
参数,返回客户端到 vos 服务器的延迟。
为提升用户体验,Agora 在 v2.3.0 版本中对 API 进行了梳理,并针对部分接口进行了如下处理:
为避免在直播转码推流中添加多个相同 User,以下接口在 v2.3.0 版本中进行删除,并将 addUser
返回类型由 void 变更为 int。
setUser
以下接口与录制相关,在 v2.3.0 版本后不再支持。Agora 提供专门的 Recording SDK 用于更好的录制服务,详见 Agora Recording SDK 发版说明。
startRecordingService
stopRecordingService
refreshRecordingServiceStatus
onRefreshRecordingServiceStatus
以下接口长期处于弃用状态,现进行删除,v2.3.0 版本后不再支持:
monitorConnectionEvent
monitorBluetoothHeadsetEvent
monitorHeadsetEvent
setPreferHeadset
setSpeakerphoneVolume
2.2.3 版
该版本于 2018 年 7 月 5 日发布。新增特性与修复问题列表详见下文。
为更好地提升用户体验,Agora SDK 在 v2.1.0 版本中对动态密钥进行了升级。如果你当前使用的 SDK 是 v2.1.0 之前的版本,并希望升级到 v2.1.0 或更高版本,请务必参考 动态密钥升级说明 。
onLeaveChannel
回调偏慢的问题。2.2.2 版
该版本于 2018 年 6 月 21 日发布。修复问题列表详见下文。
onLeaveChannel
回调偏慢的问题2.2.1 版
该版本于 2018 年 5 月 30 日发布。新增特性与修复问题列表详见下文。
2.2.0 版
该版本于 2018 年 5 月 4 日发布。新增特性与修复问题列表详见下文。
本次发版新增如下功能:
播放音效 playEffect
接口新增了一个 publish
参数,用于在播放音效时,远端用户可以听到本地播放的音效。
如果你的 SDK 是由之前版本升级到 v2.2 版本,请务必关注该接口功能的变动。
通过部署 Agora 提供的代理服务器安装包,设有企业防火墙的用户可以设置代理服务器,使用 Agora 的服务。
本次发版改进如下功能:
改进 enableAudioVolumeIndication
接口的功能,无论频道内是否有人说话,都会在回调中按设置的时间间隔返回说话者音量提示。
根据用户对频道内实时网络质量监测的需求,在 onNetworkQuality
中改进了返回数据的准确度。
为方便用户在进频道前检查当前网络是否能支撑语音或视频通话,在 onLastmileQuality
中,由通过恒定码率监测优化为根据用户设定的 Video Profile 的码率进行监测,提高返回数据的准确度。且在网络状态为 unknown 时,依然以 2 秒的间隔返回回调。
提升了用户在播放音乐等场景下的音乐音质。
2.1.3 版
该版本于 2018 年 4 月 19 日发布。新增特性与修复问题列表详见下文。
修复了部分手机上,用户离开频道后,开启自带的录音设备时,偶现录音出错的问题。
2.1.2 版
该版本于 2018 年 4 月 2 日发布。新增特性与修复问题列表详见下文。
修复了之前版本 SDK 在 dtx + aac 模式下会视频卡顿的问题。
2.1.1 版
该版本于 2018 年 3 月 16 日发布。
请正在或已集成 2.1 SDK 的客户尽快升级更新! 本次发版修复了一个的系统风险,请尽快升级以免对服务造成影响。
2.1.0 版
该版本于 2018 年 3 月 7 日发布。新增特性与修复问题列表详见下文。
本次发版新增如下功能:
新增了一个游戏开黑场景,用于节省流量和去除杂音,通过调用 API setAudioProfile
实现。
在直播场景下,主播如果需要通过内置的麦克风美化和定制自己的语音输入,可以通过调用 API setLocalVoiceEqualization
和 setLocalVoiceReverb
轻易地设置音效均衡和混响来实现所需要的效果。
新增 RESTful API 查询用户在频道中的状态信息,查询指定频道内的分角色用户列表,查询厂商频道列表,查询用户是否为连麦用户等。详见控制台 RESTful API。
提供一套全新的 API,直播场景优化 API,将原来 API 封装在底层,更快集成,更多功能扩展性。升级到 SDK 2.1 的用户可以选择使用新 API 或者老 API,两套方案均可以使用。
本次发版改进如下功能:
改进 | 描述 |
卡顿 | 改善了观众模式下的卡顿现象 |
卡顿 | 改善了特定设备导致的卡顿现象 |
鉴权模型优化 | 旧鉴权模型一个密钥只能对应一个服务权限(例如加入频道),而新的一个 Token 包含了所有的服务权限(例如加入频道,连麦,推流等) |
2.0.2 版
该版本于 2017 年 12 月 15 日发布。新增特性与修复问题列表详见下文。
修复了偶现的语音路由问题。
2.0 版
该版本于 2017 年 12 月 6 日发布。新增特性与修复问题列表详见下文。
通信和直播场景下支持音频自采集功能,新增以下 API:
名称 | 描述 |
setExternalAudioSource |
设置外部音频采集参数: 采样率,通道数等 |
pushExternalAudioFrame |
推送外部音频帧 |
通信和直播场景下支持服务端踢人功能。
新增以下 Android 模拟器支持: 夜神、雷电、逍遥。
1.14 版
该版本于 2017 年 10 月 20 日发布。新增特性与修复问题列表详见下文。
新增 API setAudioProfile 设
置音频参数和应用场景。
新增 API setLocalVoicePitch
提供基础变声功能。
直播场景: 新增 API setInEarMonitoringVolume
提供调节耳返音量功能。
优化了在高码率下的音频体验。
秒开: 直播场景下,单流模式时观众加入频道 1 秒内看见主播图像 (均值为 226 ms, 网络状态良好时可达 204 ms)。
节省带宽:
1.14 以前: 如果你选择不听某人的音频或不看某人的视频,音视频流会照发。
1.14 开始: 如果你选择不听或不看某人的流,则不会下发,从而节省带宽。
1.13.1 版
该版本于 2017 年 9 月 28 日发布。新增特性与修复问题列表详见下文。
优化了特定场景下出现的回声问题。
1.13 版
该版本于 2017 年 9 月 4 日发布。新增特性与修复问题列表详见下文。
新增 API onClientRoleChanged
用于提醒直播场景下主播、观众上下麦的回调。
新增支持 Android 模拟器。
新增单独关闭语音播放的功能。
新增功能支持服务端推流失败回调。
修复了部分机型上偶现的崩溃
1.12 版
该版本于 2017 年 7 月 25 日发布。新增特性与修复问题列表详见下文。
setEncryptionMode
里新增了加密模式 aes-128-ecb
。startAudioRecording
里新增了参数 quality
用于设置录音音质。