SDK 升级后的 API 设置

声网支持将 RTC SDK 从 2.x、3.x、4.0.0 Preview 或 4.0.0 Beta 版本升级到 4.x 版本，升级步骤以及版本间的变更介绍见迁移指南。

本文介绍在 SDK 升级后需要修改 API 以及相关实现代码的场景，以帮助你顺利完成迁移。

信息

如无特别说明，本文 API 名称均以 C++ 为例，平台均以 Windows 为例。

升级前版本为 2.x 或 3.x

如果你已经在 v2.x 或 v3.x 中用到了本节介绍的功能和场景，可参考对应示例更新 App 代码。

单频道

本节提供单频道中常用功能的示例代码。

初始化引擎

v2.x & v3.x

• Android: 实现互动直播及示例项目
• iOS: 实现互动直播及示例项目
• Windows: 实现互动直播及示例项目
• macOS: 实现互动直播及示例项目

v4.x

• Android: 实现音视频互动及示例项目
• iOS: 实现音视频互动及示例项目
• Windows: 实现音视频互动及示例项目
• macOS: 实现音视频互动及示例项目

默认发布麦克风和摄像头采集的的音视频流

v2.x & v3.x

C++

// 通过 muteLocalAudioStream 和 muteLocalVideoStream 控制是否发流
// true 为暂停发布音频流，false 为继续发布音频流
m_rtcEngine->muteLocalAudioStream(false);
// true 为暂停发布视频流，false 为继续发布视频流
m_rtcEngine->muteLocalVideoStream(false);

v4.x

C++

// 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);

将视频源从摄像头切换为共享的屏幕

v2.x & v3.x

C++

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

C++

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 视频

v2.x & v3.x 需要独立进程并通过 MediaPlayer Kit 实现，详见媒体播放器组件（3.x）。

v4.x 初始化 MediaPlayer。

1. 发布麦克风和摄像头采集的流

   C++

   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. 切换为发布媒体播放器的音视频流

   C++

   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);

多频道

本节提供多频道中常用功能的示例代码。

默认在两个频道发布流

例如：

• 在 channel1 发布麦克风和摄像头采集的流。
• 在 channel2 发布屏幕共享流。

v2.x & v3.x 不支持单进程同时在两个频道发布音视频流，所以需要通过多进程分别创建引擎。

1. 进程 1 发布摄像头流。

   C++

   m_rtcEngine->setClientRole(CLIENT_ROLE_BROADCASTER);
   m_rtcEngine->enableVideo();
   m_rtcEngine->joinChannel(accessToken, channelId, "", uid);

2. 进程 2 发布屏幕共享流。

   C++

   m_rtcEngine->setClientRole(CLIENT_ROLE_BROADCASTER);
   m_rtcEngine->joinChannel(accessToken, channelId, "", uid);
   m_rtcEngine->startScreenCaptureByDisplayId((int)info.sourceId, regionRect, capParam);

v4.x 支持单进程直接在多个频道内发布音视频流。

1. 发布摄像头流。

   C++

   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. 发布屏幕共享流。

   C++

   // 指定待分享的屏幕
   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);

屏幕共享

本节提供屏幕共享的示例代码。

集成方式

v2.x & v3.x 直接调用屏幕共享方法，无需集成屏幕共享插件。

v4.x 需在调用屏幕共享方法之前集成如下屏幕共享插件：

• Android: AgoraScreenShareExtension.aar 和 libagora_screen_capture_extension.so
• iOS/macOS: AgoraReplayKitExtension.xcframework
• Windows: libagora_screen_capture_extension.dll

实现方法

v2.x & v3.x

• Android：屏幕共享介绍及示例代码，示例项目
• iOS：屏幕共享介绍及示例代码
• Windows：屏幕共享介绍及实现方法
• macOS：屏幕共享介绍及实现方法，示例项目

v4.x

• Android：屏幕共享，示例项目
• iOS：屏幕共享，示例项目
• Windows：屏幕共享，示例项目
• macOS：屏幕共享，示例项目

自定义采集

如果你在 v2.x 或 v3.x 使用了自采集功能，例如通过视频自采集使用第三方美颜，声网推荐你在 v4.x 使用功能完善且更易用的 SDK 采集。

信息

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

中断性变化

• 删除了 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 这三个旧推流方法，声网推荐你使用新的推流方法，并参考旁路推流更新你的业务代码逻辑。
• 删除 startAudioMixing 中的 replace（Bool 类型）参数。startAudioMixing 默认发送麦克风音频和媒体播放器音频的混音，如果需要停止发送麦克风音频，你可以根据是否要继续录音，调用以下方法：
  • 需要录音：调用 updateChannelMediaOptions 将 publishMicrophoneTrack 设置为 false，此时麦克风仍然打开。
  • 不需要录音：调用 enableLocalAudio 关闭麦克风。
• （仅 Android 平台）onRemoteAudioStateChanged 回调中的所有参数类型改为 Int 类型。

行为变更 & 新增 API

• IAudioFrameObserver 新增回调 getObservedAudioFramePosition、getRecordAudioParams、getPlaybackAudioParams、getMixedAudioParams。
• 屏幕共享采用插件方式，详见屏幕共享。
• enableVirtualBackground 方法新增 SegmentationProperty 和 segProperty 参数。

参考信息

下表展示一些常用 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	加入频道前后调用该方法都会生效。 网络控制 muteLocalAudioStream 和发布流控制 ChannelMediaOptions 相互独立：如果设置 publishMicrophoneTrack 为 true， muteLocalAudioStream 为 true，则仍然不发送音频。	加入频道前后调用该方法都会生效。 网络控制 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	setClientRole 优先级高于 enableLocalAudio/enableLocalVideo。 如果在加入频道前调用该方法，SDK 会先记录该状态。 如果进频道后切换用户角色为主播，会根据 enableLocalAudio/enableLocalVideo 的状态，打开媒体采集并自动发布。 如果切换用户角色为观众，则会关闭采集并停止发布。 在多频道场景中，用户可以在每个频道都切换为主播角色，从而进行发流。在频道中，通过 updateChannelMediaOptionsEx 控制流发布。	加入频道时，主播角色发布摄像头采集的视频流时，会自动开启本地视图。如果 App 主动调用 startPreview，则离开频道时也需要主动调用 stopPreview 以关闭本地视图。

常用 API	enableLocalAudio	enableLocalVideo
v2.x & v3.x	同 v4.x	同 v4.x
v4.0.0 Preview 或 v4.0.0 Beta	主播角色调用（包括频道内和频道外）会打开/关闭麦克风。 观众角色调用返回错误码。 如果在频道内调用，还会更新发布流控制 ChannelMediaOptions.publishAudioTrack。	主播角色调用（包括频道内和频道外）会打开/关闭摄像头。 观众角色调用返回错误码。 如果在频道内调用，还会更新发布流控制 ChannelMediaOptions.publishCameraTrack。
v4.x	如果在频道外调用，不会打开/关闭麦克风，且加入频道后会自动打开/关闭麦克风。 如果在频道内调用，会打开/关闭麦克风。	如果在频道外调用，不会打开/关闭摄像头，且加入频道后会自动打开/关闭摄像头。 如果在频道内调用，会打开/关闭摄像头。