# SDK 升级后的 API 设置 (/zh-CN/realtime-media/rtc/reference/after-migrate/unity) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 声网支持将 RTC SDK 从 2.x、3.x、4.0.0 Preview 或 4.0.0 Beta 版本升级到 4.x 版本,升级步骤以及版本间的变更介绍见[迁移指南](/zh-CN/realtime-media/rtc/reference/migration-guide)。 本文介绍在 SDK 升级后需要修改 API 以及相关实现代码的场景,以帮助你顺利完成迁移。 :::info[信息] 如无特别说明,本文 API 名称均以 C++ 为例,平台均以 Windows 为例。 ::: ## 升级前版本为 2.x 或 3.x [#升级前版本为-2x-或-3x-5] 如果你已经在 v2.x 或 v3.x 中用到了本节介绍的功能和场景,可参考对应示例更新 App 代码。 ### 单频道 [#单频道-5] 本节提供单频道中常用功能的示例代码。 #### 初始化引擎 [#初始化引擎-5] **v2.x & v3.x** - Android: [实现互动直播](/zh-CN/realtime-media/rtc/get-started/quick-start)及[示例项目](https://github.com/Shengwang-Community/API-Examples/blob/legacy/Android/APIExample/app/src/main/java/io/agora/api/example/examples/basic/JoinChannelVideo.java) - iOS: [实现互动直播](/zh-CN/realtime-media/rtc/get-started/quick-start)及[示例项目](https://github.com/Shengwang-Community/API-Examples/tree/legacy/iOS/APIExample/Examples/Basic/JoinChannelVideo) - Windows: [实现互动直播](/zh-CN/realtime-media/rtc/get-started/quick-start)及[示例项目](https://github.com/Shengwang-Community/API-Examples/blob/legacy/windows/APIExample/APIExample/Basic/LiveBroadcasting/CLiveBroadcastingDlg.cpp) - macOS: [实现互动直播](/zh-CN/realtime-media/rtc/get-started/quick-start)及[示例项目](https://github.com/Shengwang-Community/API-Examples/tree/legacy/macOS/APIExample/Examples/Basic/JoinChannelVideo) **v4.x** - Android: [实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start)及[示例项目](https://github.com/Shengwang-Community/API-Examples/blob/main/Android/APIExample/app/src/main/java/io/agora/api/example/examples/basic/JoinChannelVideo.java) - iOS: [实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start)及[示例项目](https://github.com/Shengwang-Community/API-Examples/tree/main/iOS/APIExample/APIExample/Examples/Basic/JoinChannelVideo) - Windows: [实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start)及[示例项目](https://github.com/Shengwang-Community/API-Examples/blob/main/windows/APIExample/APIExample/Basic/LiveBroadcasting/CLiveBroadcastingDlg.cpp) - macOS: [实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start)及[示例项目](https://github.com/Shengwang-Community/API-Examples/tree/main/macOS/APIExample/Examples/Basic/JoinChannelVideo) #### 默认发布麦克风和摄像头采集的音视频流 [#默认发布麦克风和摄像头采集的音视频流-5] **v2.x & v3.x** ```cpp // 通过 muteLocalAudioStream 和 muteLocalVideoStream 控制是否发流 // true 为暂停发布音频流,false 为继续发布音频流 m_rtcEngine->muteLocalAudioStream(false); // true 为暂停发布视频流,false 为继续发布视频流 m_rtcEngine->muteLocalVideoStream(false); ``` **v4.x** ```cpp // m_rtcEngine 可以定义为 IRtcEngine* 或者 IRtcEngineEx* // IRtcEngineEx 继承自 IRtcEngine,拥有更丰富的 API 以及多频道的能力 // 建议通过 ChannelMediaOptions 精细化控制音视频流的发布 // 注意:v4.x 默认可通过 ChannelMediaOptions 精细化控制音视频的发布及订阅 ChannelMediaOptions options; options.channelProfile = CHANNEL_PROFILE_LIVE_BROADCASTING; options.clientRoleType = CLIENT_ROLE_BROADCASTER; // true 为订阅音频流,false 为不订阅音频流 options.autoSubscribeAudio = true; // true 为订阅视频流,false 为不订阅视频流 options.autoSubscribeVideo = true; // true 为发布麦克风采集的音频流,false 为不发布 options.publishMicrophoneTrack = true; // true 为发布摄像头采集的视频流,false 为不发布 options.publishCameraTrack = true; // ex 频道则需使用 updateChannelMediaOptionsEx 替代 m_rtcEngine->updateChannelMediaOptions(options); ``` #### 将视频源从摄像头切换为共享的屏幕 [#将视频源从摄像头切换为共享的屏幕-5] **v2.x & v3.x** ```cpp SIZE size; size.cx = 100; size.cy = 100; IScreenCaptureSourceList* infos = m_rtcEngine->getScreenCaptureSources(size, size, true); ScreenCaptureSourceInfo info = infos->getSourceInfo(index); ScreenCaptureParameters capParam; // 根据实际需求,调用 startScreenCaptureByDisplayId、startScreenCaptureByWindowId 或 startScreenCaptureByScreenRect 来共享屏幕 m_rtcEngine->startScreenCaptureByDisplayId((int)info.sourceId, regionRect, capParam); // 停止屏幕共享 m_rtcEngine->stopScreenCapture(); ``` **v4.x** ```cpp SIZE size; size.cx = 100; size.cy = 100; agora::rtc::Rectangle regionRect = { 0, 0, 0, 0 }; IScreenCaptureSourceList* infos = m_rtcEngine->getScreenCaptureSources(size, size, true); ScreenCaptureSourceInfo info = infos->getSourceInfo(index); ScreenCaptureParameters capParam; m_rtcEngine->startScreenCaptureByDisplayId((int)info.sourceId, regionRect, capParam); ChannelMediaOptions options; options.publishCameraTrack = false; // 发布屏幕共享流 options.publishScreenTrack = true; m_rtcEngine->updateChannelMediaOptions(options); ...... // 停止发布屏幕共享流 options.publishScreenTrack = false; m_rtcEngine->updateChannelMediaOptions(options) // 停止屏幕共享 m_rtcEngine->stopScreenCapture(); ``` #### 发布 mp4 视频 [#发布-mp4-视频-5] **v2.x & v3.x** 需要独立进程并通过 MediaPlayer Kit 实现,详见[媒体播放器组件(3.x)](/zh-CN/realtime-media/rtc/build/audio/media-player)。 **v4.x** 初始化 MediaPlayer。 1. 发布麦克风和摄像头采集的流 ```cpp ChannelMediaOptions options; options.channelProfile = CHANNEL_PROFILE_LIVE_BROADCASTING; options.clientRoleType = CLIENT_ROLE_BROADCASTER; options.autoSubscribeAudio = true; options.autoSubscribeVideo = true; // 默认发布麦克风采集的音频流 options.publishMicrophoneTrack = true; // 默认发布摄像头采集的视频流 options.publishCameraTrack = true; // 加入频道 m_rtcEngine->joinChannel(APP_TOKEN, szChannelId, 0, options); ``` 2. 切换为发布媒体播放器的音视频流 ```cpp IMediaPlayer* m_mediaPlayer = m_rtcEngine->createMediaPlayer().get(); ChannelMediaOptions options; // 停止发布麦克风采集的音频流 options.publishMicrophoneTrack = false; // 停止发布摄像头采集的视频流 options.publishCameraTrack = false; // 指定发布的媒体播放器的 playerId options.publishMediaPlayerId = m_mediaPlayer->getMediaPlayerId(); // 切换为媒体播放器的音频流 options.publishMediaPlayerAudioTrack = true; // 切换为媒体播放器的视频流 options.publishMediaPlayerVideoTrack = true; m_rtcEngine->updateChannelMediaOptions(options); ``` ### 多频道 [#多频道-5] 本节提供多频道中常用功能的示例代码。 #### 默认在两个频道发布流 [#默认在两个频道发布流-5] 例如: - 在 `channel1` 发布麦克风和摄像头采集的流。 - 在 `channel2` 发布屏幕共享流。 **v2.x & v3.x** 不支持单进程同时在两个频道发布音视频流,所以需要通过多进程分别创建引擎。 1. 进程 1 发布摄像头流。 ```cpp m_rtcEngine->setClientRole(CLIENT_ROLE_BROADCASTER); m_rtcEngine->enableVideo(); m_rtcEngine->joinChannel(accessToken, channelId, "", uid); ``` 2. 进程 2 发布屏幕共享流。 ```cpp m_rtcEngine->setClientRole(CLIENT_ROLE_BROADCASTER); m_rtcEngine->joinChannel(accessToken, channelId, "", uid); m_rtcEngine->startScreenCaptureByDisplayId((int)info.sourceId, regionRect, capParam); ``` **v4.x** 支持单进程直接在多个频道内发布音视频流。 1. 发布摄像头流。 ```cpp ChannelMediaOptions options; options.channelProfile = CHANNEL_PROFILE_LIVE_BROADCASTING; options.clientRoleType = CLIENT_ROLE_BROADCASTER; options.autoSubscribeAudio = true; options.autoSubscribeVideo = true; options.publishCameraTrack = true; m_rtcEngine->joinChannel(APP_TOKEN, szChannelId, 0, options); ``` 2. 发布屏幕共享流。 ```cpp // 指定待分享的屏幕 agora::rtc::Rectangle rc; ScreenCaptureParameters scp; scp.frameRate = 15; scp.bitrate = 0; HWND hWnd = ::GetDesktopWindow(); RECT destop_rc; ::GetWindowRect(hWnd, &destop_rc); scp.dimensions.width = destop_rc.right - destop_rc.left; scp.dimensions.height = destop_rc.bottom - destop_rc.top; m_rtcEngine->startScreenCaptureByScreenRect(rc, rc, scp); // 加入多频道 ChannelMediaOptions options; options.channelProfile = CHANNEL_PROFILE_LIVE_BROADCASTING; options.clientRoleType = CLIENT_ROLE_BROADCASTER; // 如果是加入同一频道,则不必重复订阅音频流 options.autoSubscribeAudio = false; // 如果是加入同一频道,则不必重复订阅视频流 options.autoSubscribeVideo = false; // ex 频道不发布摄像头流 options.publishCameraTrack = false; // ex 频道不发布麦克风流 options.publishMicrophoneTrack = false; // ex 频道发布屏幕共享流 options.publishScreenTrack = true; agora::rtc::RtcConnection connection; connection.channelId = szChannelId; // 自定义 uid connection.localUid = screenId; m_rtcEngine->joinChannelEx(APP_TOKEN, connection, options, &eventHandlerScreen); ``` ### 屏幕共享 [#屏幕共享-5] 本节提供屏幕共享的示例代码。 #### 集成方式 [#集成方式-5] **v2.x & v3.x** 直接调用屏幕共享方法,无需集成屏幕共享插件。 **v4.x** 需在调用屏幕共享方法之前集成如下屏幕共享插件: - Android: `AgoraScreenShareExtension.aar` 和 `libagora_screen_capture_extension.so` - iOS/macOS: `AgoraReplayKitExtension.xcframework` - Windows: `libagora_screen_capture_extension.dll` #### 实现方法 [#实现方法-5] **v2.x & v3.x** - Android:[屏幕共享介绍](/zh-CN/realtime-media/rtc/build/video/screen-share)及[示例代码](/zh-CN/realtime-media/rtc/build/video/screen-share),[示例项目](https://github.com/Shengwang-Community/API-Examples/blob/legacy/Android/APIExample/app/src/main/java/io/agora/api/example/examples/advanced/MultiProcess.java) - iOS:[屏幕共享介绍](/zh-CN/realtime-media/rtc/build/video/screen-share)及[示例代码](/zh-CN/realtime-media/rtc/build/video/screen-share) - Windows:[屏幕共享介绍](/zh-CN/realtime-media/rtc/build/video/screen-share)及[实现方法](/zh-CN/realtime-media/rtc/build/video/screen-share) - macOS:[屏幕共享介绍](/zh-CN/realtime-media/rtc/build/video/screen-share)及[实现方法](/zh-CN/realtime-media/rtc/build/video/screen-share),[示例项目](https://github.com/Shengwang-Community/API-Examples/tree/legacy/macOS/APIExample/Examples/Advanced/ScreenShare) **v4.x** - Android:[屏幕共享](/zh-CN/realtime-media/rtc/build/video/screen-share),[示例项目](https://github.com/Shengwang-Community/API-Examples/blob/main/Android/APIExample/app/src/main/java/io/agora/api/example/examples/advanced/SwitchCameraScreenShare.java) - iOS:[屏幕共享](/zh-CN/realtime-media/rtc/build/video/screen-share),[示例项目](https://github.com/Shengwang-Community/API-Examples/tree/main/iOS/APIExample/Agora-ScreenShare-Extension) - Windows:[屏幕共享](/zh-CN/realtime-media/rtc/build/video/screen-share),[示例项目](https://github.com/Shengwang-Community/API-Examples/blob/main/windows/APIExample/APIExample/Advanced/ScreenShare/AgoraScreenCapture.cpp) - macOS:[屏幕共享](/zh-CN/realtime-media/rtc/build/video/screen-share),[示例项目](https://github.com/Shengwang-Community/API-Examples/tree/main/macOS/APIExample/Examples/Advanced/ScreenShare) ### 自定义采集 [#自定义采集-5] 如果你在 v2.x 或 v3.x 使用了自采集功能,例如通过视频自采集使用第三方美颜,声网推荐你在 v4.x 使用功能完善且更易用的 SDK 采集。 :::info[信息] v4.x 完善了 SDK 的视频模块并在 Android 上支持了 Texture 格式。一般情况下,声网推荐用户在升级后使用 SDK 采集。在特殊场景下,例如用户需要统一对接不同厂商的 SDK,则可沿用原有自采集方案。v4.x 的 SDK 采集相对于自采集有如下优势: - 易用性高:用户不需要处理视频采集、机型适配、采集 Profile 策略,最大程度降低 App 代码复杂度并减少因采集导致的问题。此外,SDK 采集可以更好地避免音画不同步的问题。 - 问题调查成本低:SDK 支持上传采集分辨率、帧率、美颜耗时等数据,声网后台会进行数据分析,从而快速、清晰地定位丢帧等问题原因。 - 维护成本低:SDK 采集有研发团队持续迭代优化,QA 测试也比较完善。自采集插件主要是重要问题修复,缺乏持续迭代。 - 问题修复速度快:采集策略可以配置下发,部分机型问题可以快速修复。 - 其他须知:MediaIO 相关的 API 在 v4.x 中已删除,需要改用 Push 模式。 ::: 在设置视频采集的过程中,你可能会有如下疑问: Q: `stopPreview`、`enableLocalVideo`、`muteLocalVideoStream` 有什么区别? A: 三个 API 区别如下: - `stopPreview` 用于停止本地预览,不会停止本地视频采集或发布本地视频流。 - `enableLocalVideo(false)` 用于停止本地视频采集。例如,App 切后台需要停止视频采集的情况。 - `muteLocalVideoStream(true)` 用于停止发布本地视频流。例如,App 希望保持占用摄像头但停止发布视频流的情况。 Q: 推荐在什么时机注册原始数据回调? A: 用户在主播角色下调用 `joinChannel` 时会自动启动摄像头,所以建议用户在初始化引擎后直接调用 `registerVideoFrameObserver`。 ## 升级前版本为 v4.0.0 Preview 或 v4.0.0 Beta [#升级前版本为-v400-preview-或-v400-beta-5] #### 中断性变化 [#中断性变化-5] - 删除了 `AUDIO_SCENARIO_TYPE` 中的 `AUDIO_SCENARIO_HIGH_DEFINITION`,改用功能一致的 `AUDIO_SCENARIO_GAME_STREAMING`。 - 修改了 `option` 命名,明确了对于 microphone track 的控制定义。将 `ChannelMediaOptions` 中的 `publishAudioTrack` 变更为 `publishMicrophoneTrack`。 - 为了丰富多路流功能的多样性,在视频流相关的回调事件中增加了视频源类型参数。例如:`onFirstLocalVideoFrame`、`onFirstLocalVideoFramePublished`、`onVideoSizeChanged`、`onVideoPublishStateChanged`、`onLocalVideoStats`、`onLocalVideoStateChanged`。 - 旁路推流 API 优化: - 为降低旁路推流集成难度,该版本优化了推流 API 设计,并改善了推流客户端和服务端内部对网络问题的处理机制。你可以通过如下方法体验优化后的旁路推流功能: - `startRtmpStreamWithoutTranscoding`: 开始非转码推流。与旧推流方法 `addPublishStreamUrl(false)` 作用相同。 - `startRtmpStreamWithTranscoding`: 开始 CDN 直播推流并设置转码属性。与依次调用旧推流方法 `setLiveTranscoding`、`addPublishStreamUrl(true)` 的作用相同。 - `updateRtmpTranscoding`: 更新转码属性。与非首次调用旧推流方法 `setLiveTranscoding` 的作用相同。 - `stopRtmpStream`: 结束 CDN 直播推流。与旧推流方法 `removePublishStreamUrl` 作用相同。 - (仅 Android 平台)`onRtmpStreamingStateChanged` 回调中的所有参数类型改为 Int 类型。 - 该版本废弃 `addPublishStreamUrl`、`setLiveTranscoding`、`removePublishStreamUrl` 这三个旧推流方法,声网推荐你使用新的推流方法,并参考[旁路推流](/zh-CN/realtime-media/media-push)更新你的业务代码逻辑。 - 删除 `startAudioMixing` 中的 `replace`(Bool 类型)参数。`startAudioMixing` 默认发送麦克风音频和媒体播放器音频的混音,如果需要停止发送麦克风音频,你可以根据是否要继续录音,调用以下方法: - 需要录音:调用 `updateChannelMediaOptions` 将 `publishMicrophoneTrack` 设置为 `false`,此时麦克风仍然打开。 - 不需要录音:调用 `enableLocalAudio` 关闭麦克风。 - (仅 Android 平台)`onRemoteAudioStateChanged` 回调中的所有参数类型改为 Int 类型。 #### 行为变更 & 新增 API [#行为变更--新增-api-5] - `IAudioFrameObserver` 新增回调 `getObservedAudioFramePosition`、`getRecordAudioParams`、`getPlaybackAudioParams`、`getMixedAudioParams`。 - 屏幕共享采用插件方式,详见[屏幕共享](/zh-CN/realtime-media/rtc/build/video/screen-share)。 - `enableVirtualBackground` 方法新增 `SegmentationProperty` 和 `segProperty` 参数。 ## 参考信息 [#参考信息-5] 下表展示一些常用 API 在不同版本的区别: 音视频流控制 角色与预览 本地采集 | 常用 API | muteLocalAudioStream | muteLocalVideoStream | | --- | --- | --- | | v2.x & v3.x | 带 `options` 参数的 `joinChannel` 方法会覆盖 `muteLocalAudioStream` 的设置。 | 带 `options` 参数的 `joinChannel` 方法会覆盖 `muteLocalVideoStream` 设置。 | | v4.0.0 Preview 或 v4.0.0 Beta | 功能等同于更新发布流控制 `ChannelMediaOptions.publishAudioTrack`。如果频道内主播调用该方法并将参数设置为 `false` 则会打开麦克风。 | 等同于更新发布流控制 `ChannelMediaOptions.publishCameraTrack`。 | | v4.x | [after-migrate-android-ios-macos-windows-electron-rn-flutter-unity-html-0-3-1 details](#table-slot-after-migrate-android-ios-macos-windows-electron-rn-flutter-unity-html-0-3-1-5) | [after-migrate-android-ios-macos-windows-electron-rn-flutter-unity-html-0-3-2 details](#table-slot-after-migrate-android-ios-macos-windows-electron-rn-flutter-unity-html-0-3-2-5) | **after-migrate-android-ios-macos-windows-electron-rn-flutter-unity-html-0-3-1 details** - 加入频道前后调用该方法都会生效。 - 网络控制 `muteLocalAudioStream` 和发布流控制 `ChannelMediaOptions` 相互独立:如果设置 `publishMicrophoneTrack` 为 `true`, `muteLocalAudioStream` 为 `true`,则仍然不发送音频。 **after-migrate-android-ios-macos-windows-electron-rn-flutter-unity-html-0-3-2 details** - 加入频道前后调用该方法都会生效。 - 网络控制 `muteLocalVideoStream` 和发布流控制 `ChannelMediaOptions` 相互独立:如果设置 `publishCameraTrack` 为 `true`,`muteLocalVideoStream` 为 `true`, 仍然不发送视频。 | 常用 API | setClientRole | startPreview | | --- | --- | --- | | v2.x & v3.x | 同 v4.x(不支持多路上行流,不能同时在多频道中设置为主播)。 | 同 v4.x。 | | v4.0.0 Preview 或 v4.0.0 Beta | `setClientRole` 会受到 `muteLocalAudioStream` 和 `muteLocalVideoStream` 的影响。例如,如果先调用 `muteLocalAudioStream(true)` 和 `muteLocalVideoStream(true)`, 再调用 `setClientRole` 为主播,主播仍然不能发流。 | 需要主动调用 `startPreview`/`stopPreview`,以开启/关闭本地视图。 | | v4.x | [after-migrate-android-ios-macos-windows-electron-rn-flutter-unity-html-1-3-1 details](#table-slot-after-migrate-android-ios-macos-windows-electron-rn-flutter-unity-html-1-3-1-5) | 加入频道时,主播角色发布摄像头采集的视频流时,会自动开启本地视图。如果 App 主动调用 `startPreview`,则离开频道时也需要主动调用 `stopPreview` 以关闭本地视图。 | **after-migrate-android-ios-macos-windows-electron-rn-flutter-unity-html-1-3-1 details** - `setClientRole` 优先级高于 `enableLocalAudio`/`enableLocalVideo`。 - 如果在加入频道前调用该方法,SDK 会先记录该状态。 - 如果进频道后切换用户角色为主播,会根据 `enableLocalAudio`/`enableLocalVideo` 的状态,打开媒体采集并自动发布。 - 如果切换用户角色为观众,则会关闭采集并停止发布。 - 在多频道场景中,用户可以在每个频道都切换为主播角色,从而进行发流。在频道中,通过 `updateChannelMediaOptionsEx` 控制流发布。 | 常用 API | enableLocalAudio | enableLocalVideo | | --- | --- | --- | | v2.x & v3.x | 同 v4.x | 同 v4.x | | v4.0.0 Preview 或 v4.0.0 Beta | [after-migrate-android-ios-macos-windows-electron-rn-flutter-unity-html-2-2-1 details](#table-slot-after-migrate-android-ios-macos-windows-electron-rn-flutter-unity-html-2-2-1-5) | [after-migrate-android-ios-macos-windows-electron-rn-flutter-unity-html-2-2-2 details](#table-slot-after-migrate-android-ios-macos-windows-electron-rn-flutter-unity-html-2-2-2-5) | | v4.x | [after-migrate-android-ios-macos-windows-electron-rn-flutter-unity-html-2-3-1 details](#table-slot-after-migrate-android-ios-macos-windows-electron-rn-flutter-unity-html-2-3-1-5) | [after-migrate-android-ios-macos-windows-electron-rn-flutter-unity-html-2-3-2 details](#table-slot-after-migrate-android-ios-macos-windows-electron-rn-flutter-unity-html-2-3-2-5) | **after-migrate-android-ios-macos-windows-electron-rn-flutter-unity-html-2-2-1 details** - 主播角色调用(包括频道内和频道外)会打开/关闭麦克风。 - 观众角色调用返回错误码。 - 如果在频道内调用,还会更新发布流控制 `ChannelMediaOptions.publishAudioTrack`。 **after-migrate-android-ios-macos-windows-electron-rn-flutter-unity-html-2-2-2 details** - 主播角色调用(包括频道内和频道外)会打开/关闭摄像头。 - 观众角色调用返回错误码。 - 如果在频道内调用,还会更新发布流控制 `ChannelMediaOptions.publishCameraTrack`。 **after-migrate-android-ios-macos-windows-electron-rn-flutter-unity-html-2-3-1 details** - 如果在频道外调用,不会打开/关闭麦克风,且加入频道后会自动打开/关闭麦克风。 - 如果在频道内调用,会打开/关闭麦克风。 **after-migrate-android-ios-macos-windows-electron-rn-flutter-unity-html-2-3-2 details** - 如果在频道外调用,不会打开/关闭摄像头,且加入频道后会自动打开/关闭摄像头。 - 如果在频道内调用,会打开/关闭摄像头。