SDK 升级后的 API 设置

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

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

升级前版本为 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

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

v4.x

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

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

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，详见媒体播放器组件（4.x）。

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

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

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 发布摄像头流。

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

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

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

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

1. 发布摄像头流。

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

// 指定待分享的屏幕
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 采集。

v2.x & v3.x

• Android：
  • 自定义音频采集及示例项目
  • 自定义视频采集及示例项目：
    • PushExternalVideo（Push 方式）
    • SwitchExternalVideo（MediaIO 方式）
• iOS：
  • 自定义音频采集及示例项目：
    • CustomAudioSource
    • ExternalAudio
  • 自定义视频采集及示例项目：
    • CustomVideoSourcePush（Push 方式）
    • CustomVideoSourceMediaIO（MediaIO 方式）
• Windows：
  • 自定义音频采集及示例项目
  • 自定义视频采集及示例项目：
    • CustomVideoCapture（Push 方式）
    • MediaIOCustomVideoCaptrue（MediaIO 方式）
• macOS：
  • 自定义音频采集及示例项目：
    • CustomAudioSource
    • ExternalAudio
  • 自定义视频采集及示例项目：
    • CustomVideoSourcePush（Push 方式）
    • CustomVideoSourceMediaIO（MediaIO 方式）

v4.x

• Android：
  • 自定义音频采集及示例项目
  • 自定义视频采集及示例项目：
    • PushExternalVideo（Push方式）
    • MultiVideoSourceTracks（Video Track 方式）
• iOS：
  • 自定义音频采集及示例项目
  • 自定义视频采集及示例代码：
    • CustomVideoSourcePush（Push方式）
    • CustomVideoSourcePushMulti（Video Track 方式）
• Windows：
  • 自定义音频采集及示例项目
  • 自定义视频采集及示例项目
• macOS：
  • 自定义音频采集及示例项目
  • 自定义视频采集及示例项目

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

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