实时音视频

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

    迁移指南

    最近更新时间:2021-11-05 18:24:48

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

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

    改动简介

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

    优化实时音视频管理方式

    在 4.x 版本 SDK 中,我们提供了 QNRTCQNRTCClient 两个类来替代 QNRTCEnvQNRTCEngine 来进行 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 及之前的版本,初始化操作需要同时调用 QNRTCEnvQNRTCEngine 的相关方法,示例代码如下:

    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 版本混音通过 QNAudioMixer 来实现,示例代码如下:

    QNAudioMixer audioMixer = mMicrophoneAudioTrack.createAudioMixer(filePath, new QNAudioMixerListener()); // 创建混音控制器
    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