该版本于 2023 年 7 月 27 日发布。
通配 Token
该版本新增通配 Token。生成 Token 时,在用户 ID 不为 0 的情况下,声网支持你将频道名设为通配符,从而生成可以加入任何频道的通配 Token。在需要频繁切换频道及多频道场景下,使用通配 Token 可以避免 Token 的重复配置,有助于提升开发效率,减少你的 Token 服务端的压力。详见使用通配 Token。
预加载频道
该版本新增 preloadChannelByToken [1/2]
和 preloadChannelByToken [2/2]
方法,支持角色为观众的用户在加入频道前预先加载一个或多个频道。该方法调用成功后可以减少观众加入频道的时间,从而缩短观众听到主播首帧音频的耗时,提升观众端的音频体验。
在同时预加载多个频道时,为避免观众在切换不同频道时需多次申请 Token 从而导致切换频道时间增长,因此声网推荐使用通配 Token 来减少你的业务服务端获取 Token 导致的耗时,进一步加快切换频道的速度,详见使用通配 Token。
跨频道连麦优化
该版本将跨频道连麦时媒体流转发的目标频道增加至 6 个,在调用 startOrUpdateChannelMediaRelay
和 startOrUpdateChannelMediaRelayEx
时,你可以指定最多 6 个目标频道。
该版本修复了以下问题:
新增
preloadChannelByToken [1/2]
preloadChannelByToken [2/2]
updatePreloadChannelToken
该版本于 2023 年 6 月 21 日发布。
该版本改进了网络传输策略,提升了音视频交互的流畅度。
该版本修复了以下问题:
setAINSMode
开启 AI 降噪功能后,接收端用户偶现回声。该版本于 2023 年 5 月 24 日发布。
该版本对部分功能的实现方式进行了优化,请在升级到该版本后更新 app 代码。
1. 媒体发布选项
AgoraRtcChannelMediaOptions
中的 publishCustomAudioTrackEnableAec
已删除,请改用 publishCustomAudioTrack
。AgoraRtcChannelMediaOptions
中的成员 publishCustomAudioSourceId
变更为 publishCustomAudioTrackId
。2. 音频录制
sharedMediaRecorderWithRtcEngine
方法,可通过该版本新增的 createMediaRecorder
方法来创建录制对象。startRecording
、stopRecording
、setMediaRecorderDelegate
中的 connection
参数。AgoraMediaRecorder
类中的 destroy
方法,你可直接调用该版本新增的 destroyMediaRecorder
方法来销毁录制对象以释放资源。3. 虚拟声卡
自该版本起,SDK 新增对第三方虚拟声卡的支持,你可以将第三方虚拟声卡作为 SDK 的音频输入或输出设备。你可以通过 stateChanged
回调来了解当前 SDK 选择的输入输出设备是否为虚拟声卡。
4. 其他兼容性变更
didApiCallExecute
已删除,请改用相关频道和媒体的事件通知得知 API 的执行结果。startChannelMediaRelay
、updateChannelMediaRelay
、startChannelMediaRelayEx
和 updateChannelMediaRelayEx
已废弃,请改用 startOrUpdateChannelMediaRelay
和 startOrUpdateChannelMediaRelayEx
。1. AI 降噪
该版本新增AI 降噪功能。开启该功能后,SDK 会智能识别和消除背景噪音,无论是在嘈杂的公共场所,还是在需要保持低延迟的实时竞技场景,都能够确保声音传输的清晰度,为用户提供更高质量的音频体验。你可以通过该版本新增的 setAINSMode
方法开启 AI 降噪,并根据实际场景,将降噪模式设置为均衡模式、强降噪模式或低延时模式。
2.本地录制远端音频(Beta)
该版本新增本地录制远端音频功能。本地用户可以录制远端用户的音频流,便于将来回放、分析或分享,适用于在线教育、企业培训、在线会议等多类场景。为更准确报告录制状态,该版本在 stateDidChanged
、informationDidUpdated
中新增 channelId
和 uid
参数,用于表示录制的音频流的具体信息,并新增 createMediaRecorder 方法,用于创建本地或远端的录制对象。
你可以通过如下方法体验本地录制远端音频功能:
createMediaRecorder
:创建录制对象。如需同时录制本地和远端的音频,可以多次调用该方法创建多个录制对象。setMediaRecorderDelegate
:设置录制回调对象。startRecording
:开始录制。stopRecording
:停止录制。destroyMediaRecorder
:销毁录制对象。3. 多端同步
在实时合唱的场景中,可能会出现网络原因导致各接收端下行链路不一致的情况,该版本新增 getNtpWallTimeInMs
方法获取当前的 NTP (网络时间协议) 时间,用于对齐多个接收端的歌词和音乐,实现合唱同步、歌词进度同步等,为用户提供更佳的协同体验。
1.优化变声
该版本新增了 setLocalVoiceFormant
方法,用于设置共振峰比率以改变语音的音色。该方法还可以和 setLocalVoicePitch
方法一起使用,同时调节音调和音色,实现更多样化的变声效果。
2. 优化跨频道连麦
该版本新增 startOrUpdateChannelMediaRelay
和 startOrUpdateChannelMediaRelayEx
方法,通过一个方法实现开始跨频道转发和更新转发的目标频道,提升了接口易用性;同时,优化内部交互次数,有效降低调用了延迟。在降低开发难度的同时,为开发者提供更顺畅的使用体验。
3. 多路音频自采集
为更好地满足音频自采集的场景需求,该版本新增了 createCustomAudioTrack
和 destroyCustomAudioTrack
方法用于创建和销毁自定义音频轨道,并提供了两种音频轨道类型供用户选择,进一步提升了自采集音频处理的灵活性和易用性:
该版本修复了以下问题:
getdefaultaudiodevice
后返回值中的 type
字段信息错误。新增
startOrUpdateChannelMediaRelay
startOrUpdateChannelMediaRelayEx
getNtpWallTimeInMs
setAINSMode
createCustomAudioTrack
destroyCustomAudioTrack
createMediaRecorder
destroyMediaRecorder
AudioTrackConfig
AgoraRecorderStreamInfo
AUDIO_AINS_MODE
AgoraAudioTrackType
AgoraApplicationScenarioType
AgoraRtcEngineConfig
中新增 domainLimit
和 autoRegisterAgoraExtensions
属性stateDidChanged
、informationDidUpdated
中新增 channelId
和 uid
参数废弃
startChannelMediaRelay
startChannelMediaRelayEx
updateChannelMediaRelay
updateChannelMediaRelayEx
didReceiveChannelMediaRelayEvent
AgoraChannelMediaRelayEvent
删除
didApiCallExecute
AgoraRtcChannelMediaOptions
中的 publishCustomAudioTrackEnableAec
sharedMediaRecorderWithRtcEngine
AgoraMediaRecorder
类中的 destroy
startRecording
、stopRecording
、setMediaRecorderDelegate
中删除 connection
参数该版本于 2023 年 2 月 8 日发布。
快速出声
该版本新增 enableInstantMediaRendering
方法,用于开启音频帧的加速渲染模式,可加快用户加入频道后的首帧出声速度。
新增
enableInstantMediaRendering
该版本于 2022 年 12 月 19 日发布。
1. 耳机均衡器
该版本新增 setHeadphoneEQParameters
方法,用于调节耳机均衡器的低频和高频参数,主要应用于空间音效场景。如果在调用 setHeadphoneEQPreset
后仍未达到预期的耳机均衡效果,你可以调用该方法进行调节。
2. MPUDP (MultiPath UDP)
自该版本起,SDK 支持 MPUDP 协议,在 UDP 协议的基础上,允许连接并使用多个路径来最大化信道资源的使用。你可以同时在移动端和桌面端使用不同的物理网卡并将其聚合,达到有效对抗网络抖动、提升传输质量的效果。
3. 设备管理
该版本新增了一系列回调,帮助你更好地了解音视频设备的状态。
onAudioDeviceStateChanged
(C++):当音频设备的状态发生改变时上报。onAudioDeviceVolumeChanged
(C++):当音频设备或 app 的音量发生改变时上报。4. 多频道管理
该版本增加了一系列多频道相关的方法,你可以通过调用这些方法,实现对多频道中音视频流的管理。
muteLocalAudioStreamEx
方法,分别用于取消或恢复发布本地音频流。muteAllRemoteAudioStreamsEx
方法,分别用于取消或恢复订阅所有远端用户的音频流。startRtmpStreamWithoutTranscodingEx
、startRtmpStreamWithTranscodingEx
、updateRtmpTranscodingEx
和 stopRtmpStreamEx
方法,用于实现多频道场景下的旁路推流。startChannelMediaRelayEx
、updateChannelMediaRelayEx
、pauseAllChannelMediaRelayEx
、resumeAllChannelMediaRelayEx
和 stopChannelMediaRelayEx
方法,用于实现多频道场景下的跨频道媒体流转发。leaveChannelEx
[2/2] 方法,相较于 leaveChannelEx
[1/2] 方法新增了 options
参数,用于在多频道场景下离开频道时,选择是否停止麦克风采集。5. 日志上传
使用声网私有媒体服务器的场景下,为支持用户在调用 setLocalAccessPoint
方法时的进阶设置,该版本在 AgoraLocalAccessPointConfiguration
中新增 advancedConfig
成员参数,该参数支持如下设置:
logUploadServer
:默认情况下,SDK 会将日志上传至声网的日志服务器。你可以通过该参数自定义日志上传的服务器。
6. 用户角色切换
为方便用户分辨切换后的用户角色属于互动直播还是极速直播,该版本在 didClientRoleChanged
回调中新增 newRoleOptions
参数,该参数取值如下:
AgoraAudienceLatencyLevelLowLatency
(1): 低延时,属于极速直播。AgoraAudienceLatencyLevelUltraLowLatency
(2): 超低延时,属于互动直播。1. 跨频道媒体流转发
该版本对 updateChannelMediaRelay
方法做了如下优化:
AgoraChannelMediaRelayEventUpdateDestinationChannelRefused
(8),你需要重新调用 updateChannelMediaRelay
方法。2. AIAEC
该版本基于 AI 方法重构了AEC 算法,相比传统 AEC 算法,新的算法可以在较恶劣的回信比 (echo-to-signal) 条件下保存完整、清晰、流畅的近端人声,显著提高系统的回声消除和双讲性能,带给用户更舒适的通话和直播体验。适用于会议、语聊、K 歌等场景。
其他改进
AgoraAudioScenarioMeeting
) 默认参数配置下的回声消除性能。该版本修复了以下问题:
启动并停止音频采集设备测试后,启动音频播放设备测试时必现无声。
在直播场景下,主播在扬声器和听筒之间进行切换后,观众听主播的声音会听到滋啦杂声。
调用 getExtensionProperty
失败,返回空字符串。
新增
setHeadphoneEQParameters
muteLocalAudioStreamEx
muteAllRemoteAudioStreamsEx
startRtmpStreamWithoutTranscodingEx
startRtmpStreamWithTranscodingEx
updateRtmpTranscodingEx
stopRtmpStreamEx
startChannelMediaRelayEx
updateChannelMediaRelayEx
pauseAllChannelMediaRelayEx
resumeAllChannelMediaRelayEx
stopChannelMediaRelayEx
leaveChannelEx
[2/2]AgoraLocalAccessPointConfiguration
中增加 advancedConfig
成员didClientRoleChanged
中增加 newRoleOptions
adjustUserPlaybackSignalVolumeEx
enableAudioVolumeIndicationEx
废弃
didApiCallExecute
,改用具体方法触发的回调。删除
AgoraLiveTranscoding
类中的废弃成员参数 backgroundImage
和 watermark
didReceiveChannelMediaRelayEvent
中删除 AgoraChannelMediaRelayEventUpdateDestinationChannelRefused
(8)该版本于 2022 年 9 月 29 日发布。
如果你已经使用了以下类或方法,请在升级到该版本后重新调用方法并更新参数设置。
为提高代码易用性,该版本将以下类中 Optional
类型的参数变更为 Bool
、Int
等基本数据类型:
AgoraMediaSource
中的 isAgoraSource
和 isLiveSource
由 Optional
型变为 Bool
型。AgoraRtcChannelMediaOptions
中的所有参数类型由 Optional
变为 Bool
型或 Int
型。1. 耳返
该本版新增耳返功能。你可以调用 enableInEarMonitoring
开启耳返功能。
成功开启耳返功能后,你可以调用 setAudioFrameDelegate
注册音频观测器,SDK 会触发 onEarMonitoringAudioFrame
回调报告耳返原始音频数据。你可以使用自己的音效处理模块对耳返音频数据进行前处理,实现自定义音效,声网推荐你在如下两种方式中选其一来设置耳返音频数据格式:
setEarMonitoringAudioFrameParametersWithSampleRate
方法设置耳返音频数据格式,SDK 会根据该方法中的参数计算采样间隔,并根据该采样间隔触发 onEarMonitoringAudioFrame
回调。getEarMonitoringAudioParams
回调的返回值中设置耳返音频数据格式,SDK 会根据该回调的返回值计算采样间隔,并根据该采样间隔触发 onEarMonitoringAudioFrame
回调。如需调节耳返音量,你可以调用 setInEarMonitoringVolume
。
2. 本地网络连接类型
为方便用户在任何阶段知悉本地网络的连接类型,该版本新增 getNetworkType
方法。你可以通过该方法获取正在使用的网络连接的类型,包括 UNKNOWN、DISCONNECTED、LAN、WIFI、2G、3G、4G、5G。当本地网络连接类型发生改变时,SDK 会触发 networkTypeChangedToType
回调,报告当前的网络连接类型。
3. 音强选流
该版本新增音强选流功能。该功能开启后,声网服务器会根据音量大小对音频流进行筛选,选出 N 路音量最大的音频流并传输至接收端。N 默认为 3 路,如需自定义设置 N,请联系技术支持。
同时,声网还支持发流端自定义设置是否参与音强选流,不参与选流的音频流会直接和被选出的 N 路音频流一同传输至接收端。在大型会议等多人发流的场景下,开启音强选流功能可以帮助减轻接收端的下行带宽压力和系统资源消耗,详见音强选流。
4. 空间音效
该版本新增了如下适用于空间音效场景的特性,在虚拟互动场景下可以有效提升用户的临场感体验。
setZones
设置隔声区域和声音衰减系数。当音源(可以为用户或媒体播放器)跟听声者分属于音障区域内部和外部时,会体验到类似真实环境中声音在遇到建筑隔断时的衰减效果。你也可以通过调用 setPlayerAttenuation
和 setRemoteAudioAttenuation
方法分别针对媒体播放器和用户设置声音衰减属性,并指定是否使用该设置强制覆盖 setZones
中的声音衰减系数。SpatialAudioParams
中的 enable_doppler
参数开启多普勒音效,在声源和接收方发生高速相对位移的情况下(比如赛车游戏场景),接收方会体验到明显的音调变化。setHeadphoneEQPreset
方法使用预设的耳机均衡效果,以改善耳机的听感。新增
enableInEarMonitoring
setEarMonitoringAudioFrameParametersWithSampleRate
onEarMonitoringAudioFrame
setInEarMonitoringVolume
getEarMonitoringAudioParams
getNetworkType
AgoraRtcChannelMediaOptions
中新增 isAudioFilterable
setZones
setPlayerAttenuation
setRemoteAudioAttenuation
muteRemoteAudioStream
SpatialAudioParams
setHeadphoneEQPreset
AgoraHeadphoneEQPreset
废弃
startEchoTest
[2/3]该版本于 2022 年 8 月 3 日发布。
兼容性变更
v4.0.0 SDK 对部分功能的实现方式进行了优化,从而导致与 v3.7.0 不兼容。升级 SDK 后,你需要结合实际业务场景更新 app 代码,详见迁移指南。
1. 多路媒体流
该版本通过设置 AgoraRtcEngineKit(Ex)
和 AgoraRtcChannelMediaOptions
实现一个 AgoraRtcEngineKit
实例同时采集多组音频流并发布到远端:
调用 joinChannelByToken
加入首个频道后,多次调用 joinChannelExByToken
加入多个频道,通过不同的用户 ID(localUid
)和 AgoraRtcChannelMediaOptions
设置发布指定的流到不同的频道。
结合多频道能力,你还可以体验如下功能:
uid
)发布到远端。uid
)发布到远端。2. 内置媒体播放器
为减少 SDK 包体积、集成时间,以及简化 API 的调用步骤,该版本支持内置媒体播放器。调用 createMediaPlayerWithDelegate
创建媒体播放器后,你可以通过 AgoraRtcMediaPlayerProtocol
类的一系列方法体验内置媒体播放器的各类功能:
3. 新版 AI 降噪
自该版本起,SDK 支持新版 AI 降噪(相对于 v3.7.0 中的基础 AI 降噪)功能。相比原版 AI 降噪,新版 AI 降噪具有更好的人声保真度、更干净的噪声抑制,并新增了去混响(Dereverberation)能力。
4. 超高音质
为还原音频的细节、提升音频的清晰度,该版本在 AgoraVoiceBeautifierPreset
中新增 AgoraVoiceBeautifierUltraHighQuality
。在语聊、歌唱等以人声为主的场景中,你可以调用 setVoiceBeautifierPreset
并使用该枚举体验超高音质。
5. 空间音效
该版本提供本地直角坐标系计算方案实现空间音效:
该方案使用 AgoraLocalSpatialAudioKit
类实现空间音效,通过 SDK 计算远端用户的空间坐标。你需要分别调用 updateSelfPosition
和 updateRemotePosition
更新本地和远端用户的空间坐标,本地用户才能听到远端用户的空间音效。
该方案通过 SDK 计算媒体播放器的空间坐标。你需要在 AgoraCloudSpatialAudioKit
或 AgoraLocalSpatialAudioKit
类中分别调用 updateSelfPosition
和 updatePlayerPositionInfo
更新本地用户和媒体播放器的空间坐标,本地用户才能听到媒体播放器的空间音效。
6. 实时合唱
该版本为实时合唱赋予了如下能力:
该版本在 AgoraAudioScenario
中新增 AgoraAudioScenarioChorus
枚举设置极低延时。使用该枚举后,在网络条件良好的情况下,用户可以体验到极低延时的实时合唱。
7. 云市场插件
为在声网 SDK 的基础上增强实时音视频互动性,该版本支持声网云市场插件的一站式解决方案:
8. 增强的频道管理
为满足各类业务场景对频道管理的需求,该版本在 AgoraRtcChannelMediaOptions
结构体中新增了如下功能:
在调用 joinChannelByToken
或 joinChannelExByToken
时设置 AgoraRtcChannelMediaOptions
,明确媒体流发布和订阅行为,例如是否要主动订阅远端用户的音频流。加入频道后,调用 updateChannelWithMediaOptions
随时更新 AgoraRtcChannelMediaOptions
中的设置,例如,切换发布的音频源。
9. 设置音频流订阅黑/白名单
该版本新增音频流订阅黑/白名单功能,支持灵活订阅频道内发流用户的音频流。你可以通过以下 API 来将指定用户的用户 ID 加入到相应的音频黑白名单中,从而实现订阅/不订阅指定用户的音频流。在多频道场景下,你可以通 AgoraRtcEngineKit(Ex)
类下的同名方法来实现该功能。
setSubscribeAudioBlacklist
:设置音频订阅黑名单。setSubscribeAudioWhitelist
:设置音频订阅白名单。如果某个用户同时在音频订阅的黑、白名单中,只有黑名单会生效。
9. 设置音频场景
为方便用户灵活修改音频场景,该版本新增 setAudioScenario
方法,支持你根据业务需求设置音频场景。例如,如果你在频道内想将音频场景从自动场景 (AgoraAudioScenarioDefault
)切换为高音质场景 (AgoraAudioScenarioGameStreaming
),你可以调用该方法。
10. 设置本地代理
该本版新增 setLocalAccessPoint
方法,用于在成功部署声网混合云、私有化平台后,指定 Local Access Point 来设置本地代理。你可以联系 sales@agora.io 了解和部署声网混合云或声网私有化平台。
1. 快速切换频道
该版本通过 leaveChannel
和 joinChannelByToken
切换频道即可实现和 v3.7.0 中 switchChannelByToken
一样的切换速度,无需额外调用 switchChannelByToken
方法。
2. 本地人声音调
该版本在 reportAudioVolumeIndicationOfSpeakers
的 AgoraRtcAudioVolumeInfo
中新增 voicePitch
参数。你可以通过 voicePitch
获取本地用户的人声音调,从而实现唱歌评分等业务功能。