本文提供 Agora 视频 SDK 的发版说明。
该版本于 4 月 16 日发布。
集成变更
该版本新增与窗口共享相关的 libagora-wgc.dll
动态库。如果你将 SDK 升级到 v3.4.0 或更高版本,请务必在集成 SDK 时将该库拷贝至 agora_rtc_sdk.dll
所在文件夹中。
为减少集成 SDK 后的 app 体积,该版本将部分功能以插件列表(命名以 Extension
为后缀)的形式发布,详见插件列表。如果你不需要使用相关插件功能,你可以直接删除对应的插件并重新编译项目。
行为变更
为监听音乐文件播放状态改变的原因,该版本对 onAudioMixingStateChanged
回调进行如下修改:
errorCode
参数修改为 reason
参数。AUDIO_MIXING_ERROR_TYPE
,并新增 AUDIO_MIXING_REASON_TYPE
替代。通过 AUDIO_MIXING_REASON_TYPE
,你可以获取播放开始、暂停、停止或失败的原因。AUDIO_MIXING_STATE_TYPE
的部分逻辑。例如,循环播放音乐时,播放完成或开始播放都会触发 AUDIO_MIXING_STATE_PLAYING
状态。如果你将 SDK 升级到 v3.4.0 或更高版本,为保证你的业务功能不受影响,Agora 推荐你修改 onAudioMixingStateChanged
的实现。
自该版本起,adjustRecordingSignalVolume
仅调节麦克风采集信号音量。如需调节声卡采集信号音量,请改用 adjustLoopbackRecordingSignalVolume
。
1. 调节声卡采集信号音量
该版本新增 adjustLoopbackRecordingSignalVolume
,你可以在 enableLoopbackRecording
后调用该方法调节声卡采集的信号音量。
2. 音效文件播放进度
为控制音效文件的播放进度,该版本新增如下方法:
playEffect
[2/2]: 通过 startPos
参数,在播放音效文件时设置播放位置。setEffectPosition
: 在播放音效文件后,设置音效文件的播放位置。getEffectDuration
: 获取本地音效文件的总时长。getEffectCurrentPosition
: 获取音效文件的播放进度。同时,该版本废弃 playEffect
[1/2],请使用 playEffect
[2/2] 替代。
1. 视频编码
Agora SDK 允许你通过 degradationPreference
设置带宽受限时本地视频编码降级偏好,如降低视频帧率保障视频质量,降低视频质量保障视频帧率。自该版本起,degradationPreference
新增支持设为 MAINTAIN_BALANCED
,弱网下会降低视频帧率和视频质量,以在流畅性和视频质量之间取得平衡,适用于流畅性和画质均优先的场景,如一对一通话、一对一教学、多人会议。
2. 原始视频数据
getRotationApplied
和 getMirrorApplied
可将原始视频数据作旋转、镜像处理。为提升用户体验,该版本将这些回调函数支持处理的视频数据格式由 RGBA 拓展到 RGBA 和 YUV 420。
3. 窗口共享
该版本起对窗口共享进行如下优化:
startScreenCaptureByWindowId
支持共享大部分 UWP 应用窗口和采用 DirectX 渲染的窗口。此时,共享的窗口有黄色描边,且 captureMouseCursor(false)
不生效。startScreenCaptureByWindowId
共享指定窗口画面时,被其他窗口遮挡的区域被涂黑。4. 音乐文件播放进度
为方便控制音乐文件的播放进度,该版本进行如下优化:
startAudioMixing
并新增同名方法替代。新方法允许你通过 startPos
参数在播放音乐文件时设置播放位置。getAudioMixingDuration
并新增同名方法替代。新方法允许你通过 filePath
参数在播放本地音乐文件前获取该音乐文件总时长。5. 客户端录音
为在录音时设置录音内容,该版本新增 startAudioRecording
方法并废弃同名原方法。通过 startAudioRecording
[3/3] 的 config
参数,你可以设置录音音质、内容、采样率及录音文件的存储路径。
该版本还新增了错误码 ERR_ALREADY_IN_RECORDING(160)
。如果你在音乐文件播放完成前再次调用 startAudioRecording
[3/3],SDK 会报告该错误码。
6. 媒体设备出错
为方便用户了解本地音视频出错的原因,该版本进行如下优化:
LOCAL_VIDEO_STREAM_ERROR
中新增错误码 LOCAL_VIDEO_STREAM_ERROR_DEVICE_NOT_FOUND(8)
,报告无法找到本地视频采集设备。LOCAL_AUDIO_STREAM_ERROR
中新增如下错误码:LOCAL_AUDIO_STREAM_ERROR_NO_RECORDING_DEVICE(6)
: 报告无法找到本地音频采集设备。LOCAL_AUDIO_STREAM_ERROR_NO_PLAYOUT_DEVICE(7)
: 报告无法找到本地音频播放设备。该版本修复了如下问题:
getMirrorApplied
设置镜像后,视频画面出现上下颠倒。onPreEncodeVideoFrame
获取 RGBA 格式的视频数据。getMirrorApplied
和 getRotationApplied
处理本地编码前的视频数据。enableSoundPositionIndication(true)
后 onAudioVolumeIndication
回调的音量信息不准确。新增
adjustLoopbackRecordingSignalVolume
getAudioMixingDuration
[2/2]startAudioRecording
[3/3]getEffectDuration
setEffectPosition
getEffectCurrentPosition
playEffect
[2/2]startAudioMixing
[2/2]LOCAL_VIDEO_STREAM_ERROR
中新增 LOCAL_VIDEO_STREAM_ERROR_DEVICE_NOT_FOUND(8)
LOCAL_AUDIO_STREAM_ERROR
中新增 LOCAL_AUDIO_STREAM_ERROR_NO_RECORDING_DEVICE(6)
和 LOCAL_AUDIO_STREAM_ERROR_NO_PLAYOUT_DEVICE(7)
ERR_ALREADY_IN_RECORDING(160)
修改
废弃
getAudioMixingDuration
[1/2]startAudioRecording
[2/3]playEffect
[1/2]startAudioMixing
[1/2]AUDIO_MIXING_ERROR_TYPE
该版本于 2021 年 3 月 29 日发布,修复了 Mac 上使用神奇效果最小化共享的窗口时,远端用户看到扭曲画面的问题。
该版本于 2021 年 3 月 4 日发布。
基础变声
该版本新增 setVoiceConversionPreset
方法改变用户的声音。你可以把男声变得低沉、稳重,把女声变得甜美、中性。详见设置人声效果。
1. AES-GCM 加密模式
在安全要求高的场景中,为保证数据的保密性、完整性和真实性,提高数据加密的计算效率,该版本在 ENCRYPTION_MODE
中新增如下枚举值:
AES_128_GCM
: 128 位 AES 加密,GCM 模式。AES_256_GCM
: 256 位 AES 加密,GCM 模式。2. 远端音频统计
为监测通话中与音频相关的主观体验,该版本在 onRemoteAudioStats
中增加 mosValue
,报告 Agora 实时音频 MOS(平均主观意见分)评估系统对接收到的远端音频流的质量评分。
新增
setVoiceConversionPreset
ENCRYPTION_MODE
中新增 AES_128_GCM
和 AES_256_GCM
RemoteAudioStats
中新增 mosValue
该版本于 2021 年 1 月 22 日发布。
1. 集成变更
该版本新增如下文件。
libagora-core.dll
: Agora 基础计算框架。av1.dll
: AV1 框架,用于屏幕共享。请参考集成 SDK 将 SDK 集成至你的项目。
2. 行为变更
该版本废弃了 setDefaultMuteAllRemoteAudioStreams
和 setDefaultMuteAllRemoteVideoStreams
,并修改了 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.dll
动态库集成到你的项目文件中。4. 歌唱美声
在歌唱场景中,为美化歌声并添加混响效果,该版本新增 setVoiceBeautifierParameters
,并在 VOICE_BEAUTIFIER_PRESET
中添加 SINGING_BEAUTIFIER
枚举值。
你可以调用 setVoiceBeautifierPreset(SINGING_BEAUTIFIER)
美化男声并添加歌声在小房间的混响效果。如需更多设置,你可以调用 setVoiceBeautifierParameters(SINGING_BEAUTIFIER, param1, param2)
美化男声或女声,并添加歌声在小房间、大房间或大厅的混响效果。
5. 设置日志文件
为保证日志内容的完整性,该版本在 RtcEngineContext
中新增 logConfig
成员变量,在你初始化 RtcEngine
时可用于设置 Agora SDK 输出的日志文件。详见如何设置日志文件。
自该版本起,Agora 不推荐使用 setLogFile
、setLogFileSize
和 setLogFilter
方法设置日志文件。
6. 采集画质
为更好地控制摄像头采集的画质,该版本新增支持自定义采集分辨率并监听采集异常:
setCameraCapturerConfiguration
方法,将采集偏好设为 MANUAL(3)
并设置采集视频的宽高。onLocalVideoStats
回调的 captureBrightnessLevel
监听。onLocalVideoStateChanged(LOCAL_VIDEO_STREAM_STATE_FAILED, LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE)
回调监听。onLocalVideoStateChanged(LOCAL_VIDEO_STREAM_STATE_CAPTURING, LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE)
回调监听。7. 创建数据流
为了支持歌词同步、课件同步等场景,该版本废弃了原有的 createDataStream
方法,并使用新的同名方法替代,用于创建数据流,并设置数据流是否与发布到 Agora 频道内的音频流同步以及接收到的数据是否有序。
1. 屏幕共享
自该版本起,SDK 会根据实际情况自动开启 DXGI(DirectX Graphics Infrastructure)采集,大幅提升屏幕共享支持的视频帧率和分辨率。
2. 远端音频统计
为方便监测通话中与音频有关的主观体验,该版本在 onRemoteAudioStats
中增加 qoeQuality
和 qualityChangedReason
,报告接收远端音频时的体验质量以及体验质量较差的原因。
该版本修复了如下问题:
新增
setVoiceBeautifierParameters
VOICE_BEAUTIFIER_PRESET
中新增 SINGING_BEAUTIFIER
enableDeepLearningDenoise
joinChannel
[2/2]switchChannel
[2/2]createDataStream
RtcEngineContext
中新增 logConfig
RemoteAudioStats
中新增 qoeQuality
和 qualityChangedReason
setCloudProxy
LocalVideoStats
中新增 captureBrightnessLevel
CameraCapturerConfiguration
中新增 captureWidth
和 captureHeight
CAPTURER_OUTPUT_PREFERENCE
enum 中新增 CAPTURER_OUTPUT_PREFERENCE_MANUAL(3)
ERR_MODULE_NOT_FOUND (157)
废弃
setDefaultMuteAllRemoteVideoStreams
setDefaultMuteAllRemoteAudioStreams
setLogFile
setLogFileSize
setLogFilter
createDataStream
该版本于 2020 年 12 月 17 日发布,修复了如下问题:
enableEncryption
后,onFirstLocalVideoFramePublished
回调无法被触发。该版本于 2020 年 11 月 30 日发布。
1. 集成变更
自该版本起,SDK 包中新增以下文件:
libagora-fdkaac.dll
: Fraunhofer FDK AAC 动态库。libagora-mpg123.dll
: mpg123 动态库。libagora-soundtouch.dll
: SoundTouch 动态库。libagora-ffmpeg.dll
: FFmpeg 动态库。如果你将 SDK 升级到 v3.2.0 或更高版本,请务必在集成 SDK 时将上述 dll 文件拷贝至 libagora-rtc-sdk.dll
所在文件夹中。
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)
。LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_CLOSED(12)
错误码,提示你通过窗口 ID 共享的窗口已关闭,或通过窗口 ID 共享的全屏窗口已退出全屏。CONTENT_HINT_DETAILS
屏幕共享的流畅度和画质。2. 美声与音效
为提升美声与音效 API 的易用性,该版本废弃 setLocalVoiceChanger
和 setLocalVoiceReverbPreset
,并新增如下方法替代:
setVoiceBeautifierPreset
: 与 setLocalVoiceChanger
相比,该方法删除了小男孩等变声音效和空旷音效。setAudioEffectPreset
: 与 setLocalVoiceReverbPreset
相比,该方法新增了小男孩等变声音效、空旷音效、3D 人声音效和电音音效,并删除了摇滚和嘻哈音效。setAudioEffectParameters
: 对指定的音效选项进行更细节的设置。该版本支持的音效选项有 3D 人声和电音音效。3. 互动直播延时
互动直播场景下,观众看直播的延时降低了约 500 ms。
新增
setAudioEffectPreset
setVoiceBeautifierPreset
setAudioEffectParameters
AUDIO_SCENARIO_TYPE
enum
中新增 AUDIO_SCENARIO_MEETING(8)
LOCAL_VIDEO_STREAM_ERROR
enum
新增 LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_CLOSED(12)
setClientRole
废弃
setLocalVoiceChanger
setLocalVoiceReverbPreset
该版本于 2020 年 9 月 15 日发布。
该版本修复了 onFirstLocalVideoFrame
和 onFirstRemoteVideoFrame
回调的触发时机不准确的问题。
该版本于 2020 年 8 月 27 日发布。
该版本修改了区域访问限制的区域码 AREA_CODE
,最新区域码如下:
AREA_CODE_CN
: 中国大陆。AREA_CODE_NA
: 北美区域。AREA_CODE_EU
: 欧洲区域。AREA_CODE_AS
: 除中国大陆以外的亚洲区域。AREA_CODE_JP
: 日本。AREA_CODE_IN
: 印度。AREA_CODE_GLOB
:(默认)全球。如你此前调用 initialize
方法时指定了访问区域,在由之前版本升级至该版本时,请确保使用正确的区域码。
该版本于 2020 年 8 月 11 日发布。
1. 发布和订阅状态转换回调
该版本新增以下回调方便你了解音视频流当前的发布及订阅状态,有助于订阅和发布相关的数据统计:
onAudioPublishStateChanged
:音频发布状态发生改变。onVideoPublishStateChanged
:视频发布状态发生改变。onAudioSubscribeStateChanged
:音频订阅状态发生改变。onVideoSubscribeStateChanged
:视频订阅状态发生改变。2. 本地首帧发布回调
为提示用户本地音视频首帧已发布,该版本新增如下回调:
onFirstLocalAudioFramePublished
:已发布本地音频首帧回调。该回调取代 onFirstLocalAudioFrame
回调,我们推荐你不再使用 onFirstLocalAudioFrame
回调。onFirstLocalVideoFramePublished
:已发布本地视频首帧回调。3. 自定义数据上报
该版本支持自定义数据上报。如需试用,请联系 sales@agora.io 开通并商定自定义数据格式。
1. 指定访问区域完善
该版本新增以下枚举值,在调用 initialize
初始化 IRtcEngine
时提供更多区域选择。指定访问区域后,集成了 Agora SDK 的 app 会连接指定区域内的 Agora 服务器。
AREA_CODE_JAPAN
:日本。AREA_CODE_INDIA
:印度。2. 屏幕共享
为提升屏幕共享的用户体验,该版本新增如下功能:
ScreenCaptureParameters
结构体中新增 windowFocus
成员实现。ScreenCaptureParameters
结构体中新增 excludeWindowList
成员实现。onLocalVideoStateChanged
回调中新增状态码 LOCAL_VIDEO_STREAM_STATE_CAPTURING(1)
和错误码 LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_MINIMIZED(11)
实现。IVideoSource
类设置自定义的视频源。3. CDN 直播推流
为提升 CDN 直播推流用户体验,该版本新增 onRtmpStreamingEvent
回调,报告推流过程中发生的事件,如未成功添加背景图或水印。
4. 加密
该版本新增 enableEncryption
方法,用于开启内置加密,并废弃原加密方法:
setEncryptionSecret
setEncryptionMode
与原加密方法相比,该方法新增对国密 SM4 加密模式的支持,你可以根据需要选择合适的加密模式。
5. 通话中质量透明
该版本进一步扩充了 LocalAudioStats
类、LocalVideoStats
类、RemoteVideoStats
类和 RemoteAudioStats
类的成员,提供更多音视频质量相关数据。
LocalAudioStats
类新增 txPacketLossRate
,表示本端到 Agora 边缘服务器的物理音频丢包率 (%)。LocalVideoStats
类新增txPacketLossRate
:本端到 Agora 边缘服务器的物理视频丢包率 (%)。captureFrameRate
:本地视频采集帧率 (fps)。RemoteAudioStats
和 RemoteVideoStats
类中新增 publishDuration
,表示远端音频流和视频流的累计发布时长(毫秒)。6. 设置音频编码属性
为提升音频性能,该版本对音频编码码率最大值进行如下优化:
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 |
7. 日志扩容
该版本中,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
写入最新的日志。
8. 优化弱网环境下的视频体验
该版本修复了华为特定型号的笔记本上偶现啸叫的问题。
新增
onAudioPublishStateChanged
onVideoPublishStateChanged
onAudioSubscribeStateChanged
onVideoSubscribeStateChanged
onFirstLocalAudioFramePublished
onFirstLocalVideoFramePublished
enableEncryption
LocalAudioStats
struct 中新增 txPacketLossRate
LocalVideoStats
struct 中新增 txPacketLossRate
和 captureFrameRate
RemoteAudioStats
和 RemoteVideoStats
struct 中新增 publishDuration
ScreenCaptureParameters
struct 中新增 windowFocus
和 excludeWindowList
LOCAL_VIDEO_STREAM_STATE
enum 新增 LOCAL_VIDEO_STREAM_STATE_CAPTURING(1)
LOCAL_VIDEO_STREAM_ERROR
enum 新增 LOCAL_VIDEO_STREAM_ERROR_SCREEN_CAPTURE_WINDOW_MINIMIZED(11)
setVideoSource
IVideoSource
类IVideoFrameConsumer
类onRtmpStreamingEvent
ERR_NO_SERVER_RESOURCES(103)
WARN_APM_RESIDUAL_ECHO(1053)
废弃
setEncryptionSecret
setEncryptionMode
onFirstLocalAudioFrame
删除
WARN_ADM_IMPROPER_SETTINGS(1053)
该版本于 2020 年 6 月 18 日发布。主要修复如下问题:
registerVideoRenderFactory
(已废弃)方法导致的崩溃现象。该版本于 2020 年 5 月 27 日发布。
视频观测位置
自 v3.0.1 起,如果你想要获取 onPreEncodeVideoFrame
回调中的视频数据,除实现该回调外,还需要在 getObservedFramePosition
中将 POSITION_PRE_ENCODER(1 << 2)
设置为观测位置。
1. 调整音乐文件音调
为方便调整混音时音乐文件的播放音调,该版本新增 setAudioMixingPitch
方法。通过设置该方法的 pitch
参数,你可以升高或降低音乐文件的音调。该方法仅对音乐文件音调有效,对本地人声不生效。
2. 变声与混响
为提高用户的音频体验,该版本在 setLocalVoiceChanger
和 setLocalVoiceReverbPreset
中分别新增以下枚举值:
VOICE_CHANGER_PRESET
枚举中新增了以 VOICE_BEAUTY
为前缀和以 GENERAL_BEAUTY_VOICE
为前缀的枚举值,分别实现美音或语聊美声功能。AUDIO_REVERB_PRESET
枚举中新增了以 AUDIO_REVERB_FX
为前缀的枚举值和 AUDIO_VIRTUAL_STEREO
,分别实现增强版混响效果和虚拟立体声效果。你可以查看进阶功能变声与混响了解使用方法和注意事项。
3. 全屏显示视频
为提高用户观看视频的体验,该版本在视频显示模式中新增 RENDER_MODE_FILL(4)
模式。设置该模式后,视频尺寸会进行缩放和拉伸直至充满显示视图。你可以在调用以下方法设置用户视图时选择该显示模式:
setupLocalVideo
setupRemoteVideo
setLocalRenderMode
setRemoteRenderMode
4. 远端音视频数据后处理多频道支持
在多频道场景下,为方便后处理各频道的远端音视频数据,该版本新增如下 C++ 接口:
IAudioFrameObserver
类中新增 isMultipleChannelFrameWanted
和 onPlaybackAudioFrameBeforeMixingEx
。IVideoFrameObserver
类中新增 isMultipleChannelFrameWanted
和 onRenderVideoFrameEx
。成功注册音频或视频观测器后,如果你将 isMultipleChannelFrameWanted
的返回值设为 true
,就可以通过上述回调获取多个频道对应的音频、视频数据。在多频道场景下,我们建议你将返回值设为 true
。
设置视频观测位置
成功注册视频观测器后,你可以在视频处理的各节点观测并获取想要的视频数据,如本地采集的视频数据,接收的远端视频数据等。为降低设备耗能,该版本允许自定义视频观测位置。你可以通过修改 getObservedFramePosition
的返回值,设置只观测以下某个或多个位置的视频数据:
onClientRoleChanged
回调多次、App ID 和 Token 校验、日志目录乱码等问题。新增
setAudioMixingPitch
VOICE_CHANGER_PRESET
enum
中新增 VOICE_BEAUTY_VIGOROUS
等 12 个枚举值AUDIO_REVERB_PRESET
enum
VOICE_CHANGER_PRESET
enum
中新增 AUDIO_REVERB_FX_KTV
等 9 个枚举值RENDER_MODE_TYPE
enum
中新增 RENDER_MODE_FILL(4)
IAudioFrameObserver
类中新增 isMultipleChannelFrameWanted
和 onPlaybackAudioFrameBeforeMixingEx
IVideoFrameObserver
类中新增 isMultipleChannelFrameWanted
和 onRenderVideoFrameEx
getObservedFramePosition
RemoteAudioStats
结构体中新增 totalActiveTime
成员RemoteVideoStats
结构体中新增 totalActiveTime
成员WARN_ADM_WINDOWS_NO_DATA_READY_EVENT(1040)
和 WARN_ADM_INCONSISTENT_AUDIO_DEVICE(1042)
该版本于 2020 年 4 月 22 日发布。
设置区域访问限制
该版本在 RtcEngineContext
结构体中新增 areaCode
成员,支持在创建 IRtcEngine
实例时指定服务器的访问区域。该功能为高级设置,适用于有访问安全限制的场景。目前支持的区域有中国大陆、北美、欧洲、亚洲(中国大陆除外)和全球(默认)。
指定访问区域后,集成了 Agora SDK 的 app 在指定区域使用时,正常情况下会连接指定区域的 Agora 服务器;在非指定区域使用时,会从所在区域和指定区域的服务器地址中,择优选择服务器建立连接。
该版本修复了连麦用户屏幕共享黑屏的问题。
新增
RtcEngineContext
结构体中新增 areaCode
成员
该版本于 2020 年 3 月 5 日发布。
Agora 在该版本对通信场景采用了全新的系统架构,并升级了通信和直播场景下的 last mile 网络策略。在带宽不足时,新的网络策略能充分利用上下行有限带宽提升有效码率,从而增强弱网对抗能力,极大提升了弱网情况下通信和直播场景的终端用户体验。
由于通信场景采用了新的系统架构,为保证新老版本通信用户的互通兼容,我们使用了回退机制。如果频道内有老版本通信用户加入,则当前版本 (3.0.0) 的终端用户会回退成老版本通信。一旦回退,频道内所有用户都无法享受新版本带来的体验提升。因此我们强烈推荐同步升级所有终端用户到当前版本。
同时,我们对本地服务端录制进行了升级发布。为确保享受全新架构和网络策略优化带来的好处,使用本地服务端录制的客户,请务必同步升级本地服务端录制 SDK 至 3.0.0 版本。
新增特性、改进与问题修复详见下文。
1. 通信场景上行默认不开启视频小流
从该版本起,Agora 在通信场景下,默认不开启视频小流。如需启用,请在成功加入频道后,调用 enableDualStreamMode (true)
方法启用视频双流模式。在多人视频通信场景下,我们建议你开启视频双流。
1. 多频道管理
为方便用户在同一时间加入多个频道,该版本新增了 IChannel
和 IChannelEventHandler
类。通过创建多个 IChannel
对象,用户可以加入各 IChannel
对象对应的频道中,实现多频道功能。
加入多个频道后,用户可以同时接收多个频道的流,但只能同时在一个频道内发流。该功能适用于用户需要同时接收多个频道的流,或频繁切换频道发流的场景。详细的集成步骤和注意事项,请参考加入多频道。
2. 视频原始数据
为方便开发者获取传输各阶段的视频原始数据,满足更多场景需求,该版本在 IVideoFrameObserver
类中新增如下 C++ 回调接口:
onPreEncodeVideoFrame
:获取前处理后、编码前的本地视频原始数据。该方法适用于有视频前处理需求的开发场景。getSmoothRenderingEnabled
:设置是否对获取的视频数据(通过 onRenderVideoFrame
)进行平滑处理。平滑处理后的视频帧,出帧时间间隔会更均匀,因此视频自渲染的体验更好。3. 调节本地播放的指定远端用户音量
该版本新增 adjustUserPlaybackSignalVolume
方法,用以调节本地用户听到的指定远端用户的音量。通话或直播过程中,你可以多次调用该方法,来调节多个远端用户在本地播放的音量,或对某个远端用户在本地播放的音量调节多次。
4. 美颜
常见的视频社交、在线教育和连麦直播等场景中,用户普遍希望有基础的美颜功能。该版本新增接口 setBeautyEffectOptions,你可以调用该接口设置对比度、亮度、平滑度等参数,达到美白、磨皮、红润肤色等美颜效果。详情请参考美颜。
1. 音频编码属性
为满足更高音质需求,该版本调整了直播场景下 AUDIO_PROFILE_DEFAULT (0)
对应的音频编码属性,详见下表:
SDK 版本 | AUDIO_PROFILE_DEFAULT (0) |
---|---|
3.0.0 | 48 KHz 采样率,音乐编码,单声道,编码码率最大值为 52 Kbps。 |
3.0.0 之前 | 32 KHz 采样率,音乐编码,单声道,编码码率最大值为 64 Kbps。 |
2. 镜像模式
为提升视频镜像的使用体验,该版本增加了视频编码镜像和视频渲染镜像的功能:
VideoEncoderConfiguration
结构体中,新增 mirrorMode
成员,方便设置本地视频编码的镜像模式,即远端看本地是否镜像。VideoCanvas
结构体中,新增 mirrorMode
成员,方便用户在调用 setupLocalVideo
方法初始化本地视图时,设置本地看本地是否镜像,以及调用 setupRemoteVideo
方法初始化远端视图时,设置本地看远端是否镜像;同时在 setLocalRenderMode
和 setRemoteRenderMode
方法中新增 mirrorMode
参数,支持在通话中更新本地看本地,或本地看远端的镜像模式。3. 质量透明
为方便开发者获取更多通话统计信息,该版本在 RtcStats
类中新增 gatewayRtt
、memoryAppUsageRatio
、memoryTotalUsageRatio
和 memoryAppUsageInKbytes
成员,方便更好地监控通话的质量和通话过程中的内存变动。
4. 屏幕共享
为支持更多屏幕共享使用场景,该版本新增支持调用 startScreenCaptureByWindowId
方法时共享通用 Windows 平台(UWP)应用窗口。
5. 其他提升
该版本自动开启直播场景下 Native SDK 与 Web SDK 的互通,并废弃原有的 enableWebSdkInteroperability
方法。
新增
setBeautyEffectOptions
onPreEncodeVideoFrame
getSmoothRenderingEnabled
setLocalRenderMode
setRemoteRenderMode
VideoEncoderConfiguration
结构体新增 mirrorMode
成员VideoCanvas
结构体新增 channelId
、mirrorMode
成员AudioVolumeInfo
结构体新增 channelId
成员createChannel
IChannel
类IChannelEventHandler
类RtcStats
类中新增gatewayRtt
、memoryAppUsageRatio
、memoryTotalUsageRatio
和 memoryAppUsageInKbytes
成员废弃
RtcEngineParameters
类enableWebSdkInteroperability
setLocalRenderMode¹
,使用新的 setLocalRenderMode
取代setRemoteRenderMode¹
,使用新的 setRemoteRenderMode
取代setLocalVideoMirrorMode
,使用 setupLocalVideo
和 setLocalRenderMode
中的 mirrorMode
取代onFirstRemoteVideoFrame
,使用 onRemoteVideoStateChanged
取代onUserMuteAudio
, onFirstRemoteAudioDecoded
和 onFirstRemoteAudioFrame
,使用 onRemoteAudioStateChanged
取代onStreamPublished
和 onStreamUnpublished
,使用 onRtmpStreamingStateChanged
取代该版本于 2020 年 2 月10 日发布。
该版本修复了如下问题:
setRemoteSubscribeFallbackOption
方法也生效。该版本于 2019 年 9 月 19 日发布。新增特性与修复问题列表详见下文。
1. 人声检测
为判断本地用户是否说话,该版本在启用说话者音量提示 enableAudioVolumeIndication
方法中新增 bool 型的 report_vad
参数。启用该参数后,你会在 onAudioVolumeIndication
回调报告的 AudioVolumeInfo
结构体中获取本地用户的人声状态。
2. RGBA 视频原始数据
该版本新增支持 RGBA 格式的视频原始数据。你可以通过新增的 C++ 接口 getVideoFormatPreference
,设置想要获取的视频原始数据的格式。
同时为提高开发体验,Agora 支持对 RGBA 格式的视频原始数据分别通过 C++ 接口 getRotationApplied
和 getMirrorApplied
进行旋转和镜像处理。
1. 直播水印
为提高直播水印的用户体验,解决视频方向模式为 Adaptive
时,水印位置和方向可能和预期不符的问题,该版本废弃了原有的 addVideoWatermark
接口,并使用一个新的同名接口进行取代。同名接口下,Agora 使用 WatermarkOptions
类对水印进行设置,其中:
visibleInPreview
成员设置本地预览是否能看见水印。positionInLandscapeMode
/positionInPortraitMode
成员设置视频编码横屏/竖屏模式时的水印坐标。同时,该版本对水印功能的性能进行了优化。和之前版本相比,该功能的 CPU 占用降低了 5% - 20%。
2. 设置客户端录音采样率
为方便用户设置客户端录音的采样率,该版本废弃了原有的 startAudioRecording
方法,并使用新的同名方法进行取代。新的方法下,录音采样率可设为 16、32、44.1 或 48 kHz。原方法仅支持固定的 32 kHz 采样率,该版本继续保留原方法但我们不推荐使用。
其他
IAgoraRtcEngine.h 头文件中的拼写错误。
为提升用户体验,Agora SDK 在该版本中对 API 进行了如下变动:
新增
startAudioRecording
addVideoWatermark
getVideoFormatPreference
getRotationApplied
getMirrorApplied
enableAudioVolumeIndication
,新增 report_vad
参数AudioVolumeInfo
类,新增 vad
成员废弃
startAudioRecording
addVideoWatermark
该版本于 2019 年 8 月 16 日发布。新增特性与修复问题详见下文。
1. RTMP 推流
该版本起,Agora 删除如下接口:
configPublisher
setVideoCompositingLayout
clearVideoCompositingLayout
如果你的 App 使用上述接口实现 RTMP 推流功能,请确保将 Native SDK 升级至最新版本,并改用如下接口实现推流:
新的推流实现方法,详见推流到 CDN。
2. 远端视频状态
为方便用户了解远端视频状态,该版本删除了原有的 onRemoteVideoStateChanged
接口,并使用一个新的同名接口进行取代。新接口下, state
参数扩展为 STOPPED(0)、STARTING(1)、DECODING(2)、FROZEN(3) 和 FAILED(4)。同时,新接口还增加了 reason
参数,用以报告远端视频状态发生改变的原因。因此,如果你将 Native SDK 升级至该版本,请确保重新实现 onRemoteVideoStateChanged
接口。
同时,扩展后的 state 参数和新增的 reason 参数搭配使用,可以涵盖大部分远端视频状态,因此该版本废弃了如下接口。你可以继续使用这些接口,但我们不再推荐。详细的取代方案,请参考 API 文档:
onRemoteVideoStateChanged
回调不同。新接口只有在远端视频流状态发生改变时,才会触发。3. 关闭/开启本地音频采集
为提高通信场景下,本地用户关闭麦克风后听到的音质,该版本在 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
参数报告本地音频统计信息。
1. 通话中质量透明
该版本进一步扩充了 RtcStats
、LocalVideoStats
和 RemoteVideoStats
类的成员。各类新增成员如下:
RtcStats
类:累计发送音频/视频字节数及累计接收音频/视频字节数LocalVideoStats
类:本地视频的编码码率、宽高、发送帧数及编码类型RemoteVideoStats
类:远端视频在网络对抗后的丢包率2. 直播视频质量提升
该版本改善了弱网条件下直播视频卡顿问题,提升了画面清晰度,优化了网络极端丢包情况下的直播画面流畅度。
3. 屏幕共享质量提升
该版本提升了通信场景下,下行网络状况不佳时,屏幕共享文字的清晰度。该改进只在屏幕共享的内容类型 ContentHint 设置为 Details(2) 时生效。
4. 摄像头热插拔
为提升 Windows 平台设备使用体验,该版本支持使用 RtcEngineContext
类中的 context
成员支持摄像头设备热插拔,并实现如下改进:
5. 其他改进
音频
muteRemoteAudioStream
方法调用无效的问题。视频
onRemoteVideoStateChanged
回调行为不符预期的问题。其他
为提升用户体验,Agora SDK 在该版本中对 API 进行了如下变动:
新增
onLocalAudioStateChanged
onRemoteAudioStateChanged
onRemoteVideoStateChanged
onLocalAudioStats
switchChannel
startChannelMediaRelay
updateChannelMediaRelay
stopChannelMediaRelay
onChannelMediaRelayStateChanged
onChannelMediaRelayEvent
RtcEngineContext
类新增 context
成员RtcStats
类新增 txAudioBytes
,txVideoBytes
,rxAudioBytes
和 rxVideoBytes
成员LocalVideoStats
类新增 encodedBitrate
,encodedFrameWidth
,encodedFrameHeight
,encodedFrameCount
和 codedType
成员RemoteVideoStats
类新增 packetLossRate
成员废弃
onMicrophoneEnabled
,请改用 onLocalAudioStateChanged
的 LOCAL_AUDIO_STREAM_STATE_CHANGED(0) 或 LOCAL_AUDIO_STREAM_STATE_RECORDING(1)。
onRemoteAudioTransportStats
,请改用 onRemoteAudioStats
。
onRemoteVideoTransportStats
,请改用 onRemoteVideoStats
。
onUserEnableVideo
,请改用 onRemoteVideoStateChanged
的如下参数搭配:
onUserEnableLocalVideo
,请改用 onRemoteVideoStateChanged
的如下参数搭配:
onFirstRemoteVideoDecoded
,请改用 onRemoteVideoStateChanged
的 REMOTE_VIDEO_STATE_STARTING(1) 或 REMOTE_VIDEO_STATE_DECODING(2)。
删除
configPublisher
setVideoCompositingLayout
clearVideoCompositingLayout
onRemoteVideoStateChanged
该版本于 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 类和远端视频统计数据 RemoteVideoStats 类中新增 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
成员totalFrozenTime
和 frozenRate
成员废弃
lowLatency
成员该版本于 2019 年 6 月 12 日发布。新增特性、功能改进与修复问题列表详见下文。
如下内容涉及 SDK 的行为变更。如果你是由之前版本的 SDK 升级至该版本,升级前请务必阅读。
1. RTMP 推流
为提高推流服务的易用性,该版本对推流接口的参数设置进行了如下限制:
类/接口 | 参数限制 |
---|---|
LiveTranscoding 类 | |
RtcImage 类 | url :字符长度不得超过 **1024 字节 |
addPublishStreamUrl | url :字符长度不得超过 **1024 字节 |
removePublishStreamUrl | url :字符长度不得超过 **1024 字节 |
同时,该版本在 LiveTranscoding
类中新增 audioCodecProfile 参数,支持设置音频编码的规格。默认规格为 LC-AAC。
此外,该版本还对 onStreamPublished 方法的 error
参数新增了五个错误码,方便快速定位与排查问题。
2、RemoteVideoStats 类参数更名
为更精准地表达远端视频流的统计信息,该版本将 RemoteVideoStats 类中的 receivedFrameRate
参数更名为 rendererOutputFrameRate。
1、添加媒体附属信息
常见的直播场景中,主播给观众分发商品链接、优惠券、在线答题等,能构建更为丰富的直播互动方式。为满足该部分社交类直播 App 开发者的需求,该版本新增 registerMediaMetadataObserver 接口以及 IMediaMetadataObserver 类,目前允许主播在发出的视频帧中添加 Metadata,发送媒体附属信息。
2、优化屏幕共享
为确保屏幕共享画面完整性,保持共享屏幕的宽高比,避免画面裁剪和拉伸,该版本对屏幕共享的编码策略进行了优化。新版本下 Agora 按如下策略进行编码。假设 dimensions
值为 1920 x 1080,即 2073600 像素:
dimensions
,如 1000 x 1000,SDK 直接按 1000 x 1000 进行编码dimensions
,如 2000 x 2000,SDK 将保持屏幕分辨率的宽高比 1:1,取 dimensions
以内的最大分辨率,即 1440 x 1440, 进行编码屏幕共享按用户在 ScreenCaptureParameters 类下设置的 dimensions 值进行计费。如果用户没有设置 dimensions
的值,SDK 会按 1920 x 1080 计费。
同时,为方便用户选择屏幕共享时是否采集鼠标,该版本在 ScreenCaptureParameters
类中新增 captureMouseCursor 参数。该参数默认采集鼠标。
3、本地视频状态回调
为方便开发者了解本地视频状态,该版本新增 onLocalVideoStateChanged 回调。该回调下,本地视频有 STOPPED
、CAPTURING
、ENCODING
和 FAILED
四种状态。当本地视频状态为 FAILED
时,用户可以参考该回调 error
参数返回的错误码进行问题排查。该回调能帮助开发者辨别本地视频故障是由采集还是编码引起的。原有的 onCameraReady
和 onVideoStopped
回调在该版本废弃,我们不再推荐。
4、推流状态回调
为方便推流用户了解当前的推流状态,并在推流出错时了解原因排查问题,该版本新增 onRtmpStreamingStateChanged 回调。该回调下,推流有 IDLE
、CONNECTING
、RUNNING
、RECOVERING
和 FAILURE
五种状态。当推流状态为 FAILURE 时,用户可以参考该回调 errCode
参数返回的错误码进行问题排查。原有的 onStreamPublished
和 onStreamUnpublished
回调仍可以使用,但我们不再推荐。
5、网络连接失败原因梳理
为方便开发者更好地排查网络连接相关故障,该版本梳理并整合了网络连接相关的错误码,在原有 onConnectionStateChanged 回调的 reason
参数中新增八个导致网络连接失败的原因。新增后,只要网络连接发生错误,SDK 都会返回该回调。同时该版本废弃了原有的警告码 WARN_LOOK_UP_CHANNEL_REJECTED(105)
和错误码 ERR_TOKEN_EXPIRED(109)
、ERR_INVALID_TOKEN(110)
。
6、本地网络连接类型回调
为方便用户了解本地网络的连接类型,该版本新增 onNetworkTypeChanged 回调。该回调下,本地网络连接有 UNKNOWN
、DISCONNECTED
、LAN
、WIFI
、2G
、3G
、4G
七种类型。当网络连接短暂中断时,该回调能帮助开发者辨别引起中断的原因是网络切换还是网络条件不好。
7、获取播放伴奏音量
为方便开发者获取伴奏的播放音量,排查音量相关问题,该版本新增 getAudioMixingPlayoutVolume 和 getAudioMixingPublishVolume 方法,用以分别获取音乐文件在本地和远端的播放音量。
8、精确回调远端音频首帧解码
为更精准地获取远端用户的出声时间,该版本新增 onFirstRemoteAudioDecoded 回调,用以向 App 层报告 SDK 已完成远端音频首帧解码。在远端用户加入频道后首次发送音频,或远端用户 15 秒不发音频后再次发送时,该回调均会被触发。该回调与 onFirstRemoteAudioFrame
的区别在于,onFirstRemoteAudioFrame
在收到首个音频包时触发,先于 onFirstRemoteAudioDecoded
。
9、其他新增特性
1、质量透明
2、其他改进
音频
视频
其他
onNetworkQuality
回调的问题为提升用户体验,Agora 在 v2.4.1 版本中对 API 进行了如下变动:
全平台 C++ 接口行为一致
从该版本起,Native SDK 保证了各平台 C++ 接口的行为一致性,方便用户通过统一的 C++ 接口,在各平台保持业务逻辑一致。同时在 C++ 头文件的 IRtcEngine
类中实现了 RtcEngineParameters
类下的所有方法。各接口的适用范围及使用注意事项详见 Agora C++ API Reference for All Platforms 首页。
新增
LiveTranscoding
类新增参数 audioCodecProfileScreenCaptureParameters
类新增参数 captureMouseCursorRtcStats
类新增参数 txPacketLossRate 和 rxPacketLossRateLocalVideoStats
类新增参数 encoderOutputFrameRate 和 rendererOutputFrameRateRemoteVideoStats
类新增参数 decoderOutputFrameRate 和 rendererOutputFrameRate(替换 receivedFrameRate)废弃
enableAudioQualityIndication
onCameraReady
,请改用onLocalVideoStateChanged 回调中的 LOCAL_VIDEO_STREAM_STATE_CAPTURING(1)onVideoStopped
,请改用 onLocalVideoStateChanged 回调中的 LOCAL_VIDEO_STREAM_STATE_STOPPED(0)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)ERR_START_CAMERA(1003)
,请改用 onLocalVideoStateChanged 回调中的 LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE(4)ERR_VDM_WIM_DEVICE_IN_USE(1502)
,请改用 onConnectionStateChanged 回调中的 LOCAL_VIDEO_STREAM_ERROR_DEVICE_BUSY(3)2.4.0 版
该版本于 2019 年 4 月 1 日发布。新增特性、功能改进与修复问题列表详见下文。
该版本针对原有的屏幕共享进行了升级,并支持如下功能:
startScreenCaptureByScreenRect
)startScreenCaptureByWindowId
)setScreenCaptureContentHint
)updateScreenCaptureParameters
)该版本废弃了原有的 startScreenCapture 接口。Agora 推荐你使用新接口实现屏幕共享。新接口下,用户需要在代码中设计获取 screenRect
和 windowId
的代码逻辑,详情请参考开始屏幕共享。
在语音聊天室场景中添加变声和混响效果,能有效增强社交的趣味性。该版本在原有音效设置接口的基础上,新增 setLocalVoiceChanger
和 setLocalVoiceReverbPreset
方法,开发者无需手动设置音效参数,直接选择想要的本地语音变声或混响效果。
该版本新增 enableSoundPositionIndication
和 setRemoteVoicePosition
方法,支持本地用户听声辨位。用户需要在加入频道前调用 enableSoundPositionIndication
开启远端用户的语音立体声,然后在 setRemoteVoicePosition
中设置远端用户声音出现的位置,通过左右耳听到的声音差异,对远端用户的声音产生方位感。在多人在线游戏场景,如射击游戏中,该功能可以增加游戏角色的方位感,模拟真实场景。
在通话前进行 Last-mile 网络探测,可以有效帮助本地用户判断和预测上行网络质量是否良好。该版本新增通话前 Last-mile 网络探测接口 startLastmileProbeTest
、stopLastmileProbeTest
及 onLastmileProbeResult
,向用户反馈开始通话前上下行网络的带宽、丢包、网络抖动和往返时延数据。
该版本新增音频设备回路测试接口 startAudioDeviceLoopbackTest
与 stopAudioDeviceLoopbackTest
,用于测试本地的麦克风和播放设备能否正常工作。该测试在本地进行,不涉及网络传输。
该版本新增接口 setRemoteUserPriority
用于设置远端用户的优先级。该方法可以与 setRemoteSubscribeFallbackOption
搭配使用。如果开启了订阅流回退选项,弱网下 SDK 会优先保证高优先级用户收到的流的质量。
该版本为播放音乐文件新增回调 onAudioMixingStateChanged
,方便用户获知音乐文件的播放状态(成功/失败),以及播放出错的原因。同时新增一个警告码 701,当播放音乐文件时,本地音乐文件不存在、文件格式不支持或无法访问在线音乐文件 URL 时,均会触发该警告码。
Agora SDK 有 2 个日志文件,每个文件默认大小为 512 KB。为解决该大小无法满足部分用户需求的问题,该版本新增接口 setLogFileSize
,用于设置 SDK 输出的日志文件大小。
该版本在设置直播转码的 LiveTranscoding
类中,新增 backgroundImage
参数,支持设置直播转码合图的背景图片。
该版本新增云代理服务,方便部署企业防火墙的用户正常使用 Agora 的服务,详见使用云代理服务。
intervalInSeconds
,用于设置返回测试结果的时间间隔。LocalVideoStats
类中新增 targetBitrate
,targetFrameRate
,qualityAdaptIndication
三个参数,分别反映目标码率、目标帧率与和上次返回的本地视频流统计信息相比,本地视频质量的自适应情况。一般场景下,Agora 默认的视频编码配置能满足需求。对于特定场景,该版本提供如下功能让用户选择视频偏好:
VideoEncoderConfiguration
类中新增 2 个参数 minFrameRate 和 degradationPrefer,分别用于设置最低视频编码帧率,以及带宽受限时编码帧率的偏好。这两个参数需要搭配使用。setCameraCapturerConfiguration
,通过设置摄像头采集偏好,用户可以根据实际场景选择优先保证设备性能还是视频质量。具体场景及参数选择,请参考 API 文档。enableLocalAudio
接口导致的蓝牙断开的问题renderMode
的默认值,修复了用户在没有设置的情况 下,窗口和画面比例不符合引发的拉伸问题为提升用户体验,Agora 在 v2.4.0 版本中对 API 进行了如下变动:
setBeautyEffectOptions
startScreenCaptureByScreenRect
startScreenCaptureByWindowId
updateScreenCaptureParameters
setScreenCaptureContentHint
setLocalVoiceChanger
setLocalVoiceReverbPreset
enableSoundPositionIndication
setRemoteVoicePosition
startLastmileProbeTest
stopLastmileProbeTest
setRemoteUserPriority
startEchoTest
startAudioDeviceLoopbackTest
stopAudioDeviceLoopbackTest
setCameraCapturerConfiguration
setLogFileSize
onAudioMixingStateChanged
onLastmileProbeResult
startEchoTest
startScreenCapture
setVideoQualityParameters
2.3.3 版
该版本于 2019 年 1 月 24 日发布。功能改进与修复问题详见下文。
为提升用户体验,屏幕共享做了大量算法优化。针对不同的共享场景提供不同的屏幕共享策略,尤其针对 PPT 翻页和网页浏览场景,提升了屏幕共享过程中的流畅度和清晰度。同时改善了通信场景下屏幕共享开启阶段画面模糊的现象。
修复了 onNetworkQuality
回调不准确的问题。
2.3.2 版
该版本于 2019 年 1 月 16 日发布。新增特性与修复问题详见下文。
2.3.2 除了下文提到的功能和改进外,整体提升直播场景下视频弱网下抗丢包能力,提高流畅度,降低卡顿率。升级前,请了解版本兼容性:
如果你的 Native SDK 是由 v2.0.8 升级至 v2.3.2,Agora 建议你另外参考升级指南了解主要 API 的变动。
为方便用户在通话或直播中使用外部视频数据,该版本新增如下接口,支持使用 Push 方式进行视频自采集。启用后,应用程序需要将外部的视频帧封装成 AgoraVideoFrame
格式后,推送给 Agora SDK 进行编码和传输。该方法适用于用户在发送端自己做采集、渲染,然后把视频帧发送给 Agora SDK 进行编码和传输的场景。本地渲染需要用户自己完成。
setExternalVideoSource
:配置外部视频源pushVideoFrame
:推送外部视频帧为提升外部音频源的使用体验,该版本新增如下接口,支持使用 Pull 方式进行音频自渲染。启用后,应用程序会采用主动拉取的方式从音频引擎拉取远端已解码混音后的音频帧,用于外部音频播放。
setExternalAudioSink
: 设置外部音频自渲染pullAudioFrame
:拉取音频帧用于外部播放和语音观测器中的 onPlaybackAudioFrame
方法相比,该方法的优势在于:
onPlaybackAudioFrame
方法时,SDK 主动每 10 ms 回调数据给应用程序。如果应用程序处理有延时,就有可能会导致音频播放抖动;pullAudioFrame
方法时,SDK 主动拉取音频帧。通过设置 AudioFrame 中的 samples
参数,SDK 可以指定需要的播放采样数量;同时 SDK 内部会通过调整缓存,帮助应用程序处理延时,从而有效避免因外部音频播放抖动导致的异常,如音频不同步等问题。Agora 推荐使用该方法。Agora SDK 会根据网络条件进行码率自适应。为满足用户在直播场景下对视频清晰度的要求,该版本在 setVideoEncoderConfiguration 接口中新增 minBitrate 参数,强制视频编码器输出高质量图片。如果将参数设为高于默认值,在网络状况不佳情况下可能会导致网络丢包,并影响视频播放的流畅度。因此如非对画质有特殊需求,Agora 建议不要修改该参数的值。
为方便用户控制混音音乐文件的播放音量,该版本在已有 adjustAudioMixingVolume
的基础上新增 adjustAudioMixingPlayoutVolume
和 adjustAudioMixingPublishVolume
接口,用于分别控制混音音乐文件在本地和远端的播放音量。
添加新的方法后,原有的 adjustPlaybackSignalVolume 由控制人声和音乐的音量改为仅控制人声的音量。因此,如果要静音本地播放,需同时设置 adjustPlaybackSignalVolume(0)
和 adjustAudioMixingPlayoutVolume(0)
。
该版本梳理了用户在音频采集到播放过程中可能会需要调整音量的场景,及各场景对应的 API,供用户参考使用。详见官网文档调整通话音量。
网络不理想的环境下,直播音视频的质量都会下降。为提升直播效率,Agora 新增了 setLocalPublishFallbackOption
和 setRemoteSubscribeFallbackOption
两个接口。 用户设置这两个接口后,在网络条件差、无法同时保证音视频质量的情况下,SDK 会自动将视频流从大流切换为小流,或直接关闭视频流,从而保证或提高音频质量。同时 SDK 会持续监控网络质量,并在网络质量改善时恢复音视频流。在推流回退为音频流时,或由音频流恢复为音视频流,触发 onLocalPublishFallbackToAudioOnly
或 onRemoteSubscribeFallbackToAudioOnly
回调。
为方便统计每个用户的音视频上下行码率、帧率及丢包率,该版本新增 onRemoteAudioTransportStats
和 onRemoteVideoTransportStats
回调。 通话或直播过程中,当用户收到远端用户发送的音视频数据包后,会周期性地发生该回调上报,频率约为 2 秒 1 次。 回调中包含用户的 UID、音/视频接收码率、丢包率、以及延迟时间(毫秒)。 并在统计频道内通话相关数据的 Rtcstats 类中增加 lastmileDelay
参数,返回客户端到 vos 服务器的延迟。
为满足场景中视频旋转的需要,提升自定义视频源画质,该版本引入 setVideoEncoderConfiguration
替换原 setVideoProfile
接口,来设置视频编码属性。 新接口中的 VideoEncoderConfiguration
类对应一套视频参数,包含视频的分辨率 dimension
、帧率 frame rate
、码率 bitrate
、最低编码码率minBitrate
以及视频方向 orientationMode
,其中 Agora 建议保留 minBitrate
的默认设置。原接口 setVideoProfile
仍可使用,但不再推荐。
为提升声卡采集易用性,该版本在 enableLoopbackRecording
接口中新增参数 deviceName,支持用户使用虚拟声卡进行采集。该参数 NULL 时默认使用当前声卡采集。如需使用虚拟声卡,直接使用虚拟声卡的产品名传参即可。
为提升质量透明的用户体验,该版本废弃了原有的 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
播放音乐文件时出现的崩溃问题setVideoProfile
设备视频编码属性时,出现的共享画面左右颠倒的问题为提升用户体验,Agora 在 v2.3.2 版本中对 API 进行了如下变动:
setVideoEncoderConfiguration
setExternalVideoSource
pushVideoFrame
setExternalAudioSink
pullAudioFrame
setLocalPublishFallbackOption
setRemoteSubscribeFallbackOption
getConnectionState
adjustAudioMixingPlayoutVolume
adjustAudioMixingPublishVolume
onConnectionStateChanged
onLocalPublishFallbackToAudioOnly
onRemoteSubscribeFallbackToAudioOnly
onRemoteAudioStats
onRemoteAudioTransportStats
onRemoteVideoTransportStats
2.2.2 版
该版本于 2018 年 6 月 21 日发布。修复问题列表详见下文。
2.2.1 版
该版本于 2018 年 5 月 30 日发布。内部代码优化。
2.2.0 版
该版本于 2018 年 5 月 4 日发布。新增特性与修复问题列表详见下文。
为更好地提升用户体验,Agora SDK 在 2.1 版本中对动态密钥进行了升级。 如果你当前使用的 SDK 是 2.1 之前的版本,并希望升级到 2.1 或更高版本,请务必参考 动态密钥升级说明 。
本次发版新增如下功能:
播放音效 playEffect
接口新增了一个 publish
参数,用于在播放音效时,远端用户可以听到本地播放的音效。
如果你的 SDK 是由之前版本升级到 v2.2 版本,请务必关注该接口功能的变动。
通过 Agora 部署的代理服务器,方便有企业防火墙的用户设置代理服务器,以使用 Agora 的服务。
修复了连麦后退出频道后再进入频道连麦对端看不到自己的问题。
新增 onRemoteVideoStateChanged
接口,以获知远端视频流的状态。
在本地直播及旁路直播中增加水印功能,允许用户将一张 PNG 图片作为水印添加到正在进行的本地直播或旁路直播中。新增 addVideoWatermark
和 clearVideoWatermarks
接口,以添加或删除本地直播水印;LiveTranscoding
接口中新增 watermark
参数,用于控制旁路直播中水印的添加。
本次发版改进如下功能:
改进 enableAudioVolumeIndication
接口的功能,无论频道内是否有人说话,都会在回调中按设置的时间间隔返回说话者音量提示。
根据用户对频道内实时网络质量监测的需求,在 onNetworkQuality
中改进了返回数据的准确度。
为方便用户在进频道前检查当前网络是否能支撑语音或视频通话,在 onLastmileQuality
中,由通过恒定码率监测优化为根据用户设定的 Video Profile 的码率进行监测,提高返回数据的准确度。且在网络状态为 unknown 时,依然以 2 秒的间隔返回回调。
提升了用户在播放音乐等场景下的音乐音质。
修复了大量用户同时直播连麦时,偶发的抖屏现象
修复了 Windows 设备在直播场景下偶发的音频卡顿问题
2.1.3 版
该版本于 2018 年 4 月 19 日发布。新增特性与修复问题列表详见下文。
该版本的 SDK 修改了 setVideoProfile
方法在直播场景下的码率值,修改后的码率值与 2.0 版本一致。
修复了部分手机上,用户离开频道后,开启自带的录音设备时,偶现录音出错的问题。
改进了通信和直播场景下屏幕共享的效果,缩短了用户从屏幕共享模式切换回普通模式需要的时间间隔。
2.1.2 版
该版本于 2018 年 4 月 2 日发布。新增特性与修复问题列表详见下文。
SDK 升级至 2.1.2 的直播场景后,相同分辨率下,视频更清晰,但带宽也会变大。
修复了连麦后退出频道后再进入频道连麦对端看不到自己的问题。
修复了通信场景的屏幕共享清晰度小于直播场景的问题。
2.1.1 版
该版本于 2018 年 3 月 16 日发布。
请正在或已集成 2.1 SDK 的客户尽快升级更新! 本次发版修复了一个的系统风险,请尽快升级以免对服务造成影响。
2.1.0 版
该版本于 2018 年 3 月 7 日发布。新增特性与修复问题列表详见下文。
本次发版新增如下功能:
新增了一个游戏开黑场景,用于节省流量和去除杂音,通过调用 API setAudioProfile
实现。
在直播场景下,主播如果需要通过内置的麦克风美化和定制自己的语音输入,可以通过调用 API setLocalVoiceEqualization
和 setLocalVoiceReverb
轻易地设置音效均衡和混响来实现所需要的效果。
新增 RESTful API 查询用户在频道中的状态信息,查询指定频道内的分角色用户列表,查询厂商频道列表,查询用户是否为连麦用户等。
在直播场景下,同一频道内支持 17 位主播同时进行视频直播和连麦。
直播场景下,可以将采集到的视频添加到正在进行的直播中,直播室里的主播和观众可以一起边看电影、比赛或演出,边进行点评、互动等功能,会让现有的直播话题更广、体验更好。 仅支持拉入一路流,格式包括: RTMP, HLS, FLV。赛事直播最多同时支持 5 人连麦直播。详见 外部输入直播视频源 。
在 2.1.0 以前: Agora SDK 仅支持视频通话场景下的屏幕共享功能;
从 2.1.0 开始: Agora SDK 正式支持直播场景下的屏幕共享功能;
新增 API enableLoopbackRecording
开启视声卡采集,开启后 SDK 可以采集到本地播放的所有声音。
本次发版改进如下功能:
改进 | 描述 |
卡顿 | 改善了观众模式下的卡顿现象 |
卡顿 | 改善了特定设备导致的卡顿现象 |
鉴权模型优化 | 旧鉴权模型一个密钥只能对应一个服务权限(例如加入频道),而新的一个 Token 包含了所有的服务权限(例如加入频道,连麦,推流等) |
计费优化 | 计费系统针对极小分辨率统一按音频计费,例如 16 * 16 |
修复了摄像头采集失败问题;
修复了偶现的崩溃;
修复了偶现的视频卡顿问题;
2.0 版
该版本于 2017 年 12 月 6 日发布。新增特性与修复问题列表详见下文。
致各位开发者:
由于 Agora 的产品升级, 当 Windows SDK 升级至 2.0 将不支持 Agora Recording Server(<=1.8.2)的调用接口,相关 API 将被废弃。
受影响范围
startRecordingService
,stopRecordingService
以及 refreshRecordingServiceStatus
,将在后续版本中不再支持。解决方案
我们提供了两种方案供您选择:
方案一: 将 Agora Recording Server(<= version 1.8.2)升级到 Agora Recording SDK( >= version 1.12)。Agora Recording SDK 无需在客户端触发录制,将不影响 Windows SDK 的后续升级(推荐该方法)
附上 Agora Recording SDK 的使用方法:
方案二:如果你希望继续使用 Agora Recording Server,维持 Windows SDK 版本不变(<=v1.14),将不影响您继续使用 Windows SDK的 API 触发录制。
若您有任何疑问,可以通过以下方式获得技术支持:
通信场景支持视频大小流功能,新增 API setRemoteVideoStreamType
和 enableDualStreamMode
;
通信和直播场景下支持音频自采集功能,新增以下 API:
名称 | 描述 |
setExternalAudioSource |
设置外部音频采集参数: 采样率,通道数等 |
pushExternalAudioFrame |
推送外部音频帧 |
通信和直播场景下支持服务端踢人功能。如有需要,请联系 sales@agora.io 开通该功能。
支持 Windows 64 位;
增加音量、静音设置/获取接口以及系统音量、静音同步引擎事件接口, 详见:
名称 | 描述 |
setPlaybackDeviceVolume |
设置播放设备音量 |
getPlaybackDeviceVolume |
获取播放设备音量 |
setRecordingDeviceVolume |
设置麦克风音量 |
getRecordingDeviceVolume |
获取麦克风音量 |
setPlaybackDeviceMute |
静音播放设备 |
getPlaybackDeviceMute |
获取播放设备静音状态 |
setRecordingDeviceMute |
静音麦克风 |
getRecordingDeviceMute |
获取麦克风静音状态 |
onAudioDeviceVolumeChanged |
当放音、录音、应用程序音量发生变化时触发该回调 |
修复了加入频道后出现的崩溃。
1.14 版
该版本于 2017 年 10 月 20 日发布。新增特性与修复问题列表详见下文。
新增 API setAudioProfile
设置音频参数和应用场景。
新增 API setLocalVoicePitch
提供基础变声功能。
直播场景: 新增 API setInEarMonitoringVolume
提供调节耳返音量功能。
优化了在高码率下的音频体验。
秒开: 直播场景下,单流模式时观众加入频道 1 秒内看见主播图像(均值为 885 ms, 网络状态良好时可达 788 ms)。
节省带宽:
1.14 以前: 如果你选择不听某人的音频或不看某人的视频,音视频流会照发。
1.14 开始: 如果你选择不听或不看某人的流,则不会下发,从而节省带宽。
精准的码率控制:
1.14 以前: 码率控制不够精准,上下波动幅度较大。波动过大容易造成网络拥塞,增加丢包、丢帧的概率,影响了带宽估计模块的精度,特别是在弱网低码率情况下尤为明显。
1.14 开始: 精准的码率控制,要多少给多少,不多给也不少给,避免波动过大造成的网络拥塞,减少传输延时,有助于减少网络卡顿。
修复了部分 Windows 机器上无声音的问题。
修复了部分 Windows 机器上的摄像头问题。
1.13.1 版
该版本于 2017 年 9 月 28 日发布。新增特性与修复问题列表详见下文。
优化了特定场景下出现的回声问题。
1.13 版
该版本于 2017 年 9 月 4 日发布。新增特性与修复问题列表详见下文。
新增 API onClientRoleChanged
用于提醒直播场景下主播、观众上下麦的回调。
新增单独关闭语音播放的功能。
新增功能支持服务端推流失败回调。
屏幕共享直播场景下采集声卡选项动态开启和关闭。
软编情况下,视频属性可控。
可以在客户端设置推流的 Profile。
屏幕共享: 提升了画质清晰度和流畅度。
屏幕共享: 通信场景下新增动态更新截图区域。
修复了部分机型上偶现的崩溃。
1.12 版
该版本于 2017 年 7 月 25 日发布。新增特性与修复问题列表详见下文。
直播场景下, 新增 API 方法 injectStream
在当前频道内插入一条 RTMP 流。该功能目前为 beta 版
在 API 方法 setEncryptionMode
里新增加密模式 aes-128-ecb
。
在 API 方法 startAudioRecording
里新增参数 quality
用于设置录音音质。
新增 API onActiveSpeaker
提示当前频道内谁在说话。
通信场景下,删除了原有的 API 方法 setScreenCaptureWindow
,更新 API 方法 startScreenCapture
共享整个屏幕、指定窗口或指定区域
通信场景下,启用屏幕共享功能后,在屏幕共享过程中可以显示鼠标
通信场景下针对 320 x 180 分辨率提供了以下改进方案:
网络和设备状态较差的情况下仍能保证画质流畅度。
网络和设备状态良好的情况下可以做到比 180P 更好的画质清晰度。
修复了部分机型上偶现的崩溃问题。