发版说明
v4.0.0 版
该版本于 2022 年 8 月 3 日发布。
升级必看
兼容性变更
v4.0.0 SDK 对部分功能的实现方式进行了优化，从而导致与 v3.7.0 不兼容。升级 SDK 后，你需要结合实际业务场景更新 app 代码，详见迁移指南。
- 多频道
- 媒体流发布控制
- 自定义视频采集与渲染（Media IO 方式）
- 警告码
新增特性
1. 多路媒体流
该版本支持通过设置 AgoraRtcChannelMediaOptions，实现一个 AgoraRtcEngineKit 实例同时采集多路音视频源并发布到远端，适应各种业务场景。例如：
- 同时发布一路摄像头采集的视频流、屏幕共享流、自采集视频流和媒体播放器的视频流。
- 同时发布单路麦克风采集、自采集的音频流和媒体播放器的音频流。
该版本支持通过 createCustomVideoTrack 方法实现自定义视频采集。你可以参考如下步骤，体验同时发布多路自定义采集视频流：
创建自采集视频轨道：调用
createCustomVideoTrack方法创建一个自定义视频轨道，并获得视频轨道 ID。设置频道中待发布的自采集视频轨道：在每个频道的
AgoraRtcChannelMediaOptions中，将customVideoTrackId参数设置为你想要发布的视频轨道 ID，并将publishCustomVideoTrack设置为true。推送外部视频源：调用
pushVideoFrame，并将customVideoTrackId指定为你想要发布的自定义视频轨道 ID，即可根据步骤 2 的设置，实现在多个频道中发布对应的自定义视频源。
结合多频道能力，你还可以体验如下功能：
- 将多组音视频流通过不同的用户 ID（
uid）发布到远端。 - 将多路音频流混音后通过一个用户 ID（
uid）发布到远端。 - 将多组视频频流通过不同的用户 ID（
uid）发布到远端。 - 将多路视频流合图后通过一个用户 ID（
uid）发布到远端。
2. 超高清分辨率 （Beta）
为提升视频互动体验，SDK 对视频采集、编码、解码、渲染全流程做出了优化，自该版本起支持 4K 分辨率。优化了 FEC（Forward Error Correction）算法，可根据视频帧包数与帧率进行自适应切换，降低 4K 场景下的视频卡顿率。
你可以在调用 setVideoEncoderConfiguration 时，设置编码分辨率为 4K (3840 × 2160)、帧率为 60 fps。当你的设备不支持 4K 时，SDK 支持自动回退到适合的分辨率和帧率。
3. 内置媒体播放器
为减少 SDK 包体积、集成时间，以及简化 API 的调用步骤，该版本支持内置媒体播放器。调用 createMediaPlayerWithDelegate 创建媒体播放器后，你可以通过 AgoraRtcMediaPlayerProtocol 类的一系列方法体验内置媒体播放器的各类功能：
- 自动播放本地、在线、自定义的媒体资源。
- 预先加载待播放的媒体资源。
- 根据网络情况切换媒体资源的播放线路。
- 将媒体播放器的音视频流推送到任意频道、分享给远端用户。
- 实时缓存媒体资源文件，该功能开启后，播放器会预先缓存当前正在播放的媒体文件的部分数据到本地，可提高播放流畅度，帮助节省网络流量。
4. 新版 AI 降噪
自该版本起，SDK 支持新版 AI 降噪（相对于 v3.7.0 中的基础 AI 降噪）功能。相比原版 AI 降噪，新版 AI 降噪具有更好的人声保真度、更干净的噪声抑制，并新增了去混响（Dereverberation）能力。
5. 超高音质
为还原音频的细节、提升音频的清晰度，该版本在 AgoraVoiceBeautifierPreset 中新增 AgoraVoiceBeautifierUltraHighQuality。在语聊、歌唱等以人声为主的场景中，你可以调用 setVoiceBeautifierPreset 并使用该枚举体验超高音质。
6. 空间音效
该版本提供如下方案实现空间音效，你可以任选一种方案使用：
本地直角坐标系计算方案: 该方案使用
AgoraLocalSpatialAudioKit类实现空间音效，通过 SDK 计算远端用户的空间坐标。你需要分别调用updateSelfPosition和updateRemotePosition更新本地和远端用户的空间坐标，本地用户才能听到远端用户的空间音效。本地球坐标系计算方案: 该方案使用
AgoraRtcEngineKit类的enableSpatialAudio和setRemoteUserSpatialAudioParams实现空间音效。你需要向 SDK 传入本地用户与远端用户的相对水平角、俯仰角、距离与朝向，本地用户才能听到远端用户的空间音效。如果你的 app 基于空间坐标来确定用户位置，在使用空间音效时，你还需要通过用户的空间坐标自行计算出用户间的相对水平角、俯仰角、距离与朝向。
该版本还支持对媒体播放器设置空间音效，你可以任选一种方案使用：
本地直角坐标系计算方案: 该方案通过 SDK 计算媒体播放器的空间坐标。你需要在
AgoraCloudSpatialAudioKit或AgoraLocalSpatialAudioKit类中分别调用updateSelfPosition和updatePlayerPositionInfo更新本地用户和媒体播放器的空间坐标，本地用户才能听到媒体播放器的空间音效。本地球坐标系计算方案: 该方案使用
AgoraRtcMediaPlayerProtocol类的setSpatialAudioParams实现空间音效。你需要向 SDK 传入本地用户与媒体播放器的相对水平角、俯仰角、距离与朝向，本地用户才能听到媒体播放器的空间音效。如果你的 app 基于空间坐标来确定本地用户和媒体播放器的位置，在使用空间音效时，你还需要通过本地用户与媒体播放器的空间坐标自行计算出两者间的相对水平角、俯仰角、距离与朝向。
7. 实时合唱
该版本为实时合唱赋予了如下能力：
- 支持两人及两人以上合唱。
- 每位歌手相互独立。一位歌手出现问题或退出合唱，其他歌手还可以继续合唱。
- 极低延时体验。每位歌手可以实时听到彼此的歌声，观众也可以实时听到每位歌手。
该版本在 AgoraAudioScenario 中新增 AgoraAudioScenarioChorus 枚举设置极低延时。使用该枚举后，在网络条件良好的情况下，用户可以体验到极低延时的实时合唱。
8. 云市场插件
为在 Agora SDK 的基础上增强实时音视频互动性，该版本支持声网云市场插件的一站式解决方案：
- 方便集成：只需执行简单统一的 API 即可实现模块化功能的集成，将实时互动模块集成效率提高约 95%。
- 可扩展性设计：模块化和可扩展的 SDK 设计风格赋予了 Agora SDK 良好的可扩展性，更有利于开发者基于声网云市场插件生态快速搭建好用的实时互动应用。
- 打造生态系统：可容纳众多开发者的实时音视频 app 社区，提供多种扩展组合。添加并开启云市场插件后，开发者可以实现更为丰富的实时音视频互动功能，详见实现插件功能。
- 助力服务商：支持服务商将技术产品以插件的形式与 Agora SDK 做技术上的融合，在声网云市场中展示并售卖，与 Agora 一起共建开发者的实时互动生态系统。如何开发和发布插件详见服务商流程。
9. 增强的频道管理
为满足各类业务场景对频道管理的需求，该版本在 AgoraRtcChannelMediaOptions 中新增了如下功能：
- 设置或切换多种音视频源的发布
- 设置或切换频道场景、用户角色
- 设置或切换订阅视频的大小流类型
- 控制音频发布时延
在调用 joinChannelByToken 或 joinChannelExByToken 时设置 AgoraRtcChannelMediaOptions，明确媒体流发布和订阅行为，例如，是否发布摄像头采集或者屏幕共享的视频流，是否要主动订阅远端用户的音视频流。加入频道后，调用 updateChannelWithMediaOptions 随时更新 AgoraRtcChannelMediaOptions 中的设置，例如，切换发布的音视频源。
10. 屏幕共享
该版本优化了开启屏幕共享的逻辑，你可以根据实际场景选择不同的方式开启屏幕共享：
- 在加入频道前调用
startScreenCapture，然后调用joinChannelByToken[2/4] 加入频道并设置publishScreenCaptureVideo为true，即可开始屏幕共享。 - 在加入频道后调用
startScreenCapture，然后调用updateChannelMediaOptions设置publishScreenCaptureVideo为true，即可开始屏幕共享。
11. 设置音视频流订阅黑/白名单
该版本新增音视频流订阅黑/白名单功能，支持灵活订阅频道内发流用户的音视频流。你可以通过以下 API 来将指定用户的用户 ID 加入到相应的音视频黑白名单中，从而实现订阅/不订阅指定用户的音频或视频流。在多频道场景下，你可以通 AgoraRtcEngineKit(Ex) 类下的同名方法来实现该功能。
setSubscribeAudioBlacklist：设置音频订阅黑名单。setSubscribeAudioWhitelist：设置音频订阅白名单。setSubscribeVideoBlacklist：设置视频订阅黑名单。setSubscribeVideoWhitelist：设置视频订阅白名单。
如果某个用户同时在音频或视频订阅的黑、白名单中，只有黑名单会生效。
12. 设置音频场景
为方便用户灵活修改音频场景，该版本新增 setAudioScenario 方法，支持你根据业务需求设置音频场景。例如，如果你在频道内想将音频场景从自动场景 （AgoraAudioScenarioDefault）切换为高音质场景 （AgoraAudioScenarioGameStreaming），你可以调用该方法。
13. 设置本地代理
该本版新增 setLocalAccessPoint 方法，用于在成功部署声网混合云、私有化平台后，指定 Local Access Point 来设置本地代理。你可以联系 sales@agora.io 了解和部署声网混合云或声网私有化平台。
14. 垫片推流
该版本新增垫片推流功能，支持你在发流时使用本地 png 格式的图片来替代当前发布的视频流画面进行推流。你可以通过 enableVideoImageSource 来开启该功能，并通过 options 参数自定义垫片图片；在你关闭垫片功能之后，远端用户看到的依旧是当前你发布的视频流画面。
改进
1. 快速切换频道
该版本通过 leaveChannel 和 joinChannelByToken 切换频道即可实现和 v3.7.0 中 switchChannelByToken 一样的切换速度，无需额外调用 switchChannelByToken 方法。
2. 推送外部视频帧
该版本新增支持推送 I422 格式的外部视频帧，你可以通过 pushExternalVideoFrame 方法将 I422 格式的外部视频帧推送至 SDK。
3. 本地人声音调
该版本在 reportAudioVolumeIndicationOfSpeakers 的 AgoraRtcAudioVolumeInfo 中新增 voicePitch 参数。你可以通过 voicePitch 获取本地用户的人声音调，从而实现唱歌评分等业务功能。
4. 设备权限管理
该版本新增 permissionError 方法，当获取音频采集设备或摄像头权限开启失败时自动上报，用户可根据该回调的提示开启相应的设备权限。
5. 本地视频预览
该版本优化了 startPreview 方法的调用逻辑。如果你需要开启本地视频预览，你可以直接通过 startPreview 方法来开启视频预览，无调用时序要求。
6. 订阅视频流
你可以通过 setRemoteDefaultVideoStreamType 方法，根据你想要订阅的视频流分辨率和码率来灵活设置默认订阅视频流类型。
