实时音视频

    • 实时音视频 > 使用指南 > Android >迁移指南

    迁移指南

    最近更新时间: 2023-04-21 12:56:19

    QNRTC Android SDK v4.x 是基于 v3.x 版本开发的全量重构版本，简化了接口调用逻辑，提高了接口的易用性，提供了更友好的事件监听机制。

    • 由于 QNRTC Android SDK v4.x 向下不兼容，因此，如果您是老版本用户并希望升级到最新版本以获得更好的用户体验，可参考本文提供的升级指南进行迁版本升级。
    • 老版本文档可查看 3.x 及之前版本的相关文档。

    改动简介

    4.x 版本优化了 SDK 接口调用逻辑，主要改动如下：

    优化实时音视频管理方式

    在 4.x 版本 SDK 中，我们提供了 QNRTC 和 QNRTCClient 两个类来替代 QNRTCEnv 和 QNRTCEngine 来进行 SDK 的初始化、Track 的创建以及房间的管理等操作。其中：

    • QNRTC 主要负责处理 SDK 的初始化以及本地音视频 Track 的创建采集等房间无关的操作。
    • QNRTCClient 主要负责处理房间的加入、离开，音视频 Track 的发布、订阅等房间交互相关的操作。

    上述管理方式的改动将影响到 SDK 的主要交互流程，若您需要升级，可以参考当前使用指南部分的核心场景使用姿势，分模块进行更新。

    优化音视频 Track 的定义及使用方式

    区别于 3.x 版本所有 Track 均使用 QNTrackInfo，在 4.x 版本 SDK 中，我们细化了音视频 Track 的分类，基于不同类型的 Track 提供了不同的控制接口，新版本的 Track 对本地 Track 和远端 Track 做了区分，继承结构定义如下：

    注意：本地仅支持创建一路音频 Track，重复创建音频 Track 将会返回 null。

    4.x 版本除了对音视频 Track 的结构进行了调整，还将部分 Track 的操作接口从 QNRTCEngine 移到了 Track 上，包括采集、渲染、美颜以及音视频回调监听的设置等。更详细接口定义请参考对应的 API 文档。

    优化事件监听接口

    v4.x 细化了不同场景下的事件监听，移除了 QNRTCEngineEventListener 回调监听。新版本事件监听定义如下：

    核心步骤迁移详解

    为了更方便您的版本迁移，本部分详细介绍了新老版本针对通话核心步骤的不同处理方式。

    初始化

    3.x 及之前的版本，初始化操作需要同时调用 QNRTCEnv 和 QNRTCEngine 的相关方法，示例代码如下：

    QNRTCEnv.init(getApplicationContext()); // 初始化 SDK 运行环境，建议在 Application 中调用
QNRTCSetting setting = new QNRTCSetting(); // 创建并初始化 SDK 相关配置
mEngine = QNRTCEngine.createEngine(getApplicationContext(), setting, new QNRTCEngineEventListener()); // 创建 QNRTCEngine 对象

    4.x 版本，初始化操作仅需通过 QNRTC 即可实现，示例代码如下：

    QNRTCSetting setting = new QNRTCSetting(); // 创建并初始化 SDK 相关配置
QNRTC.init(this, setting, new QNRTCEventListener()); // 初始化

    实现差异：

    • 4.x 版本 SDK 移除了 QNRTCEnv.init 的操作，仅需通过 QNRTC.init 即可完成初始化操作。

    更详细的 4.x 版本初始化使用方式可参考初始化使用指南

    加入房间

    3.x 及之前的版本，通过 QNRTCEngine.joinRoom 的方式加入房间，示例代码如下：

    mEngine.joinRoom(mRoomToken); // 加入房间

// 加入房间成功后会触发如下回调
interface QNRTCEngineEventListener {
  @Override
  public void onRoomStateChanged(QNRoomState state) {
    if (state == QNRoomState.CONNECTED) {
      // 成功加入房间
    }
  }
}

    4.x 版本加入房间首先需要创建 QNRTCClient 对象，再通过 QNRTCClient.join 的方式加入房间，示例代码如下：

    mClient = QNRTC.createClient(new QNClientEventListener()); // 创建 QNRTCClient 对象，并设置房间事件监听函数
mClient.join(mRoomToken); // 加入房间

// 加入房间成功后会触发如下回调
interface QNClientEventListener {
  @Override
  public void onConnectionStateChanged(QNConnectionState state, @Nullable QNConnectionDisconnectedInfo info) {
    if (state == QNConnectionState.CONNECTED) {
      // 成功加入房间
    }
  }
}

    实现差异：

    • 4.x 版本移除了 QNRTCEngine 的接口调用，使用 QNRTCClient 进行房间的相关操作
    • 4.x 版本房间连接状态监听回调改为 QNClientEventListener.onConnectionStateChanged，监听事件包括加入房间成功、失败以及成功离开房间等

    更详细的 4.x 版本房间管理使用方式可参考房间管理使用指南

    创建本地 Track

    3.x 及之前的版本，通过 QNRTCEngine 创建本地 Track，示例代码如下：

    // 创建本地音频 Track
mLocalAudioTrack = mEngine.createTrackInfoBuilder()
        .setSourceType(QNSourceType.AUDIO)
        .create();

// 创建本地 Camera 视频 Track
mLocalVideoTrack = mEngine.createTrackInfoBuilder()
        .setSourceType(QNSourceType.VIDEO_CAMERA)
        .setTag(UserTrackView.TAG_CAMERA)
        .setVideoPreviewFormat(new QNVideoFormat(videoWidth, videoHeight, fps)) // 设置采集参数，不设置采用 QNRTCSetting 的采集配置
        .setVideoEncodeFormat(new QNVideoFormat(videoWidth, videoHeight, fps)) // 设置编码参数，不设置采用 QNRTCSetting 的编码配置
        .create();

    4.x 版本通过 QNRTC 创建本地 Track，示例代码如下：

    // 创建本地音频 Track
mMicrophoneAudioTrack = QNRTC.createMicrophoneAudioTrack();

// 创建本地 Camera 视频 Track
QNCameraVideoTrackConfig cameraVideoTrackConfig = new QNCameraVideoTrackConfig("TAG_CAMERA")
        .setVideoCaptureConfig(QNVideoCaptureConfigPreset.CAPTURE_640x480)
        .setVideoEncoderConfig(new QNVideoEncoderConfig(encoderW, encoderH, encoderFPS, encoderBitrate))
mCameraVideoTrack = QNRTC.createCameraVideoTrack(cameraVideoTrackConfig);

    实现差异：

    • 4.x 版本移除了 QNRTCEngine 创建 Track 的接口，改用 QNRTC 相关接口创建
    • 4.x 版本 Track 相关的配置通过 QNCameraVideoTrackConfig 或者 QNMicrophoneAudioTrackConfig 等类似 Config 实现，创建时不传该参数则使用 SDK 提供的默认配置。3.x 版本需要在 QNTrackInfoBuilder 中传入，不传则使用 QNRTCSetting 中的配置。

    更详细的 4.x 版本音视频采集使用方式可参考音视频采集使用指南

    Track 的使用

    3.x 及之前的版本对 Track 的大部分操作都由 QNRTCEngine 来实现，这里以部分功能举例，示例代码如下：

    // 开启 Camera Track 内置美颜并设置美颜参数
QNBeautySetting beautySetting = new QNBeautySetting(0.5f, 0.5f, 0.5f); // 美颜参数配置类
beautySetting.setEnable(true); // 开启美颜
mEngine.setBeauty(beautySetting); // 设置美颜参数

mEngine.startCapture(); // 开启 Camera Track 采集
mEngine.stopCapture(); // 停止 Camera Track 采集

// 静默本地 Track
mLocalAudioTrack.setMuted(true); // 设置静默状态
mEngine.muteTracks(Collections.singletonList(mLocalAudioTrack)); // 更新静默状态

mEngine.setLocalAudioRecordVolume(1.0f); // 设置本地音频采集音量

    4.x 版本对 Track 的操作都由对应的 Track 来实现，示例代码如下：

    // 开启 Camera Track 内置美颜并设置美颜参数
QNBeautySetting beautySetting = new QNBeautySetting(0.5f, 0.5f, 0.5f); // 美颜参数配置类
beautySetting.setEnable(true); // 开启美颜
mCameraVideoTrack.setBeauty(mBeautySetting); // 设置美颜参数

mCameraVideoTrack.startCapture(); // 开启 Camera Track 采集
mCameraVideoTrack.stopCapture(); // 停止 Camera Track 采集

mMicrophoneAudioTrack.setMuted(true); // 静默本地 Track

mMicrophoneAudioTrack.setVolume(1.0f); // 设置本地音频采集音量

    实现差异：

    • 4.x 版本将 Track 相关操作接口都移交给对应的 Track 来实现，移除了 QNRTCEngine 的相关调用

    上述示例代码仅展示了部分功能的示例，更多 Track 相关的接口使用请参考对应的 Track 接口文档

    发布本地 Track

    3.x 及之前的版本发布 Track 通过 QNRTCEngine 来实现，示例代码如下：

    // 发布本地 Track
mEngine.publishTracks(mLocalTrackList);

// 发布成功后，会触发 QNRTCEngineEventListener.onLocalPublished 回调
interface QNRTCEngineEventListener {
  @Override
  public void onLocalPublished(List<QNTrackInfo> trackInfoList) {
    // 回调发布成功的 Track 列表
  }
}

    4.x 版本发布 Track 通过 QNRTCClient 来实现，示例代码如下：

    // 发布本地 Track
mClient.publish(new QNPublishResultCallback() {
  @Override
  public void onPublished() {
    // Track 发布成功
  }

  @Override
  public void onError(int errorCode, String errorMessage) {
    // Track 发布失败
  }
}, mCameraVideoTrack, mMicrophoneAudioTrack);

    实现差异：

    更详细的 4.x 版本发布和订阅使用方式可参考发布和订阅使用指南

    订阅远端 Track

    3.x 及之前的版本订阅 Track 通过 QNRTCEngine 来实现，示例代码如下：

    mEngine.setAutoSubscribe(true); // 设置是否自动订阅远端 track，默认开启
mEngine.subscribeTracks(trackList); // 手动订阅场景下，订阅远端 Track

// 订阅成功后，会触发 QNRTCEngineEventListener.onSubscribed 回调
interface QNRTCEngineEventListener {
  @Override
  public void onSubscribed(String remoteUserId, List<QNTrackInfo> trackInfoList) {
    // 回调订阅成功的 Track 列表
  }
}

    4.x 版本订阅 Track 通过 QNRTCClient 来实现，示例代码如下：

    mClient.setAutoSubscribe(true); // 设置是否自动订阅远端 track，默认开启
mClient.subscribe(trackList); // 手动订阅场景下，订阅远端 track，支持可变参数

// 订阅成功后，会触发 QNClientEventListener.onSubscribed 回调
interface QNClientEventListener {
  @Override
  public void onSubscribed(String remoteUserID, List<QNRemoteAudioTrack> remoteAudioTracks, List<QNRemoteVideoTrack> remoteVideoTracks) {
    // 回调订阅成功的 Track 列表
  }
}

    实现差异：

    更详细的 4.x 版本发布和订阅使用方式可参考发布和订阅使用指南

    CDN 转推

    3.x 及之前的版本 CDN 转推通过 QNRTCEngine 来实现，示例代码如下：

    // 创建并配置单路转推任务，配置步骤省略
QNForwardJob forwardJob = new QNForwardJob();
mEngine.createForwardJob(forwardJob); // 开始单路转推任务
mEngine.stopForwardJob(forwardJob.getForwardJobId()); // 停止单路转推任务

// 创建并配置合流转推任务，配置步骤省略
QNMergeJob mergeJob = new QNMergeJob();
mEngine.createMergeJob(mergeJob); // 开始合流转推任务
mEngine.setMergeStreamLayouts(addedTrackOptions, mergeJob.getMergeJobId()); // 更新合流布局
mEngine.removeMergeStreamLayouts(removedTrackOptions, mergeJob.getMergeJobId()); // 移除合流布局
mEngine.stopMergeStream(mergeJob.getMergeJobId()); // 停止合流转推任务

// 创建成功后会触发 QNRTCEngineEventListener 的相关回调
interface QNRTCEngineEventListener {
  @Override
  public void onCreateForwardJobSuccess(String forwardJobId) {
    // 回调创建成功的单路转推 job id
  }

  @Override
  public void onCreateMergeJobSuccess(String mergeJobId) {
    // 回调创建成功的合流转推 job id
  }
}

    4.x 版本 CDN 转推通过 QNRTCClient 来实现，示例代码如下：

    // 设置 CDN 转推状态监听
mClient.setLiveStreamingListener(new QNLiveStreamingListener() {
  @Override
  public void onStarted(String streamID) {
    // 对应 streamID 的转推任务开始转推
  }

  @Override
  public void onStopped(String streamID) {
    // 对应 streamID 的转推任务已停止转推
  }

  @Override
  public void onTranscodingTracksUpdated(String streamID) {
    // 合流布局更改时触发此回调
  }

  @Override
  public void onError(String streamID, QNLiveStreamingErrorInfo errorInfo) {
    // 转推任务出错时触发此回调
  }
};)

// 创建并配置单路转推任务，配置步骤省略
QNDirectLiveStreamingConfig directLiveStreamingConfig = new QNDirectLiveStreamingConfig();
mClient.startLiveStreaming(directLiveStreamingConfig); // 开始单路转推任务
mClient.stopLiveStreaming(directLiveStreamingConfig); // 停止单路转推任务

// 创建并配置合流转推任务，配置步骤省略
QNTranscodingLiveStreamingConfig transcodingLiveStreamingConfig = new QNTranscodingLiveStreamingConfig();
mClient.startLiveStreaming(transcodingLiveStreamingConfig); // 开始合流转推任务
mClient.setTranscodingLiveStreamingTracks(transcodingLiveStreamingConfig.getStreamID(), transcodingTracks); // 更新合流布局
mClient.removeTranscodingLiveStreamingTracks(transcodingLiveStreamingConfig.getStreamID(), transcodingTracks); // 移除合流布局
mClient.stopLiveStreaming(transcodingLiveStreamingConfig); // 停止合流转推任务

    实现差异：

    更详细的 4.x 版本 CDN 转推使用方式可参考 CDN 转推使用指南

    混音

    3.x 及之前的版本混音通过 QNAudioMixingManager 来实现，示例代码如下：

    QNAudioMixingManager audioMixingManager = mEngine.getAudioMusicMixingManager(); // 获取混音控制器
audioMixingManager.setAudioMixingListener(new QNAudioMixingListener()); // 设置混音状态监听
audioMixingManager.startAudioMixing("filePath", 0); // 开始混音
audioMixingManager.pauseAudioMixing(); // 暂停混音
audioMixingManager.resumeAudioMixing(); // 恢复混音
audioMixingManager.stopAudioMixing(); // 停止混音

    4.x 版本混音通过 QNAudioMusicMixer 来实现，示例代码如下：

    QNAudioMusicMixer audioMixer = mMicrophoneAudioTrack.createAudioMusicMixer(filePath, new QNAudioMusicMixerListener()); // 创建混音控制器
audioMixer.start(); // 开始混音
audioMixer.pause(); // 暂停混音
audioMixer.resume(); // 恢复混音
audioMixer.stop(); // 停止混音

    实现差异：

    更详细的 4.x 版本混音使用方式可参考背景音乐混音使用指南

    离开房间

    3.x 及之前的版本离开房间通过 QNRTCEngine 来实现，示例代码如下：

    mEngine.leaveRoom(); // 离开房间

    4.x 版本离开房间通过 QNRTCClient 来实现，示例代码如下：

    mClient.leave(); // 离开房间

    实现差异：

    • 4.x 版本通过 QNRTCClient.leave 来实现离开房间的操作，移除了 QNRTCEngine 的相关调用
    以上内容是否对您有帮助？
    • Qvm free helper
    Close