需要访问旧版文档站？前往旧版文档官网首页。 (在新标签页打开)
声网文档中心

SDK 升级后的 API 设置

  • Android

更新时间不可用

查看实时互动 RTC 的 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

v4.x

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

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

多频道

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

加入多频道

v2.x & v3.x 单进程只能发布一路流。加入多频道后，同一时间只能在一个频道发布一路流，其他频道只能订阅流不能发布流。如果需要发布多路流，则需要开多个进程。详见：

v4.x 支持在单进程中加入多频道，并且同一时间可以在多个频道中发布音视频流。详见：

默认在两个频道发布流

例如：

  • 在 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

v4.x

自定义采集

如果你在 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 模式。

v2.x & v3.x

v4.x

在设置视频采集的过程中，你可能会有如下疑问：

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 在不同版本的区别：

常用 APImuteLocalAudioStreammuteLocalVideoStream
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， 仍然不发送视频。
表格内容超出当前宽度，可横向滚动查看更多列。
常用 APIsetClientRolestartPreview
v2.x & v3.x同 v4.x（不支持多路上行流，不能同时在多频道中设置为主播）。同 v4.x。
v4.0.0 Preview 或 v4.0.0 BetasetClientRole 会受到 muteLocalAudioStream 和 muteLocalVideoStream 的影响。例如，如果先调用 muteLocalAudioStream(true) 和 muteLocalVideoStream(true)， 再调用 setClientRole 为主播，主播仍然不能发流。需要主动调用 startPreview/stopPreview，以开启/关闭本地视图。
v4.x
  • setClientRole 优先级高于 enableLocalAudio/enableLocalVideo。
  • 如果在加入频道前调用该方法，SDK 会先记录该状态。
  • 如果进频道后切换用户角色为主播，会根据 enableLocalAudio/enableLocalVideo 的状态，打开媒体采集并自动发布。
  • 如果切换用户角色为观众，则会关闭采集并停止发布。
  • 在多频道场景中，用户可以在每个频道都切换为主播角色，从而进行发流。在频道中，通过 updateChannelMediaOptionsEx 控制流发布。
加入频道时，主播角色发布摄像头采集的视频流时，会自动开启本地视图。如果 App 主动调用 startPreview，则离开频道时也需要主动调用 stopPreview 以关闭本地视图。
表格内容超出当前宽度，可横向滚动查看更多列。
常用 APIenableLocalAudioenableLocalVideo
v2.x & v3.x同 v4.x同 v4.x
v4.0.0 Preview 或 v4.0.0 Beta
  • 主播角色调用（包括频道内和频道外）会打开/关闭麦克风。
  • 观众角色调用返回错误码。
  • 如果在频道内调用，还会更新发布流控制 ChannelMediaOptions.publishAudioTrack。
  • 主播角色调用（包括频道内和频道外）会打开/关闭摄像头。
  • 观众角色调用返回错误码。
  • 如果在频道内调用，还会更新发布流控制 ChannelMediaOptions.publishCameraTrack。
v4.x
  • 如果在频道外调用，不会打开/关闭麦克风，且加入频道后会自动打开/关闭麦克风。
  • 如果在频道内调用，会打开/关闭麦克风。
  • 如果在频道外调用，不会打开/关闭摄像头，且加入频道后会自动打开/关闭摄像头。
  • 如果在频道内调用，会打开/关闭摄像头。
表格内容超出当前宽度，可横向滚动查看更多列。

咨询电话

400 632 6626

上海声网科技有限公司

Copyright © 2026 声网保留所有权利