human: 如何处理七牛云的实时音视频迁移指南

gpt: [实时音视频](https://developer.qiniu.com/rtc) > 使用指南 > Windows >迁移指南

#  迁移指南

最近更新时间: 2022-03-24 15:05:01

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

# 升级指南

>   * **由于 QNRTC Windows SDK v5.x 向下不兼容**
> ，因此，如果您是老版本用户并希望升级到最新版本以获得更好的用户体验，可参考本文提供的升级指南进行迁版本升级。
>   * 老版本文档可查看 [3.x 及之前版本的相关文档](https://doc.qnsdk.com/rtn/windows)。
>

## 改动简介

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

### 优化实时音视频管理方式

在 5.x 版本 SDK 中，我们提供了 [QNRTC](https://developer.qiniu.com/rtc/api/9445/QNRTC) 和
[QNRTCClient](https://developer.qiniu.com/rtc/api/9446/QNRTCClient) 两个类来替代
`QNRoomInterface` 、 `QNVideoInterface` 和 `QNAudioInterface` 来进行 SDK 的初始化、track
的创建以及房间的管理等操作。其中：

  * [QNRTC](https://developer.qiniu.com/rtc/api/9445/QNRTC) 主要负责处理 SDK 的初始化以及本地音视频 track 的创建采集等房间无关的操作。
  * [QNRTCClient](https://developer.qiniu.com/rtc/api/9446/QNRTCClient) 主要负责处理房间的加入、离开，音视频 track 的发布、订阅等房间交互相关的操作。

上述管理方式的改动将影响到 SDK 的主要交互流程，若您需要升级，可以参考 [RTC v5.x
使用指南](https://developer.qiniu.com/rtc/development_guidelines/9544/guidelines-
windows) 的使用姿势分模块进行更新。

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

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

  * [QNTrack](https://developer.qiniu.com/rtc/api/9445/QNTrack)
    * [QNLocalTrack](https://developer.qiniu.com/rtc/api/9422/QNLocalTrack)
      * [QNLocalAudioTrack](https://developer.qiniu.com/rtc/api/9420/QNLocalAudioTrack)
        * [QNMicrophoneAudioTrack](https://developer.qiniu.com/rtc/api/9433/QNMicrophoneAudioTrack)
        * [QNCustomAudioTrack](https://developer.qiniu.com/rtc/api/9409/QNCustomAudioTrack)
      * [QNLocalVideoTrack](https://developer.qiniu.com/rtc/api/9424/QNLocalVideoTrack)
        * [QNCameraVideoTrack](https://developer.qiniu.com/rtc/api/9404/QNCameraVideoTrack)
        * [QNCustomVideoTrack](https://developer.qiniu.com/rtc/api/9412/QNCustomVideoTrack)
        * [QNScreenVideoTrack](https://developer.qiniu.com/rtc/api/9448/QNScreenVideoTrack)
    * [QNRemoteTrack](https://developer.qiniu.com/rtc/api/9440/QNRemoteTrack)
      * [QNRemoteAudioTrack](https://developer.qiniu.com/rtc/api/9438/QNRemoteAudioTrack)
      * [QNRemoteVideoTrack](https://developer.qiniu.com/rtc/api/9443/QNRemoteVideoTrack)

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

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

### 优化事件监听接口

v5.x 细化了不同场景下的事件监听，移除了 `QNRoomListener`、`QNVideoListener` 和 `QNAudioListener`
回调监听。新版本事件监听定义如下：

  * [QNClientEventListener:](https://developer.qiniu.com/rtc/api/9407/QNClientEventListener) 核心回调接口，定义了房间相关的回调事件，包括房间连接状态、用户加入离开状态等
  * [QNPublishResultCallback:](https://developer.qiniu.com/rtc/api/9435/QNPublishResultCallback) 核心回调接口，定义了 Publish 结果的回调事件
  * [QNLocalAudioFrameListener:](https://developer.qiniu.com/rtc/api/9419/QNLocalAudioFrameListener) 本地音频数据帧回调接口
  * [QNLocalVideoFrameListener:](https://developer.qiniu.com/rtc/api/9423/QNLocalVideoFrameListener) 本地视频数据帧回调接口
  * [QNRemoteAudioFrameListener:](https://developer.qiniu.com/rtc/api/9436/QNRemoteAudioFrameListener) 远端音频频数据帧回调接口
  * [QNRemoteVideoFrameListener:](https://developer.qiniu.com/rtc/api/9442/QNRemoteVideoFrameListener) 远端视频数据帧回调接口
  * [QNRemoteAudioMixedFrameListener:](https://developer.qiniu.com/rtc/api/9437/QNRemoteAudioMixedFrameListener) 远端音频数据混音后的回调
  * [QNLiveStreamingListener:](https://developer.qiniu.com/rtc/api/9418/QNLiveStreamingListener) CDN 转推相关回调接口，监听任务转推成功、合流布局更新等事件
  * [QNTrackInfoChangedListener:](https://developer.qiniu.com/rtc/api/9453/QNTrackInfoChangedListener) 音视频 track 信息变化监听接口，监听大小流切换、track 静默状态改变等事件

## 核心步骤迁移详解

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

### 初始化

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

    
    
        _rtc_room_interface = qiniu_v2::QNRoomInterface::ObtainRoomInterface();
        _rtc_room_interface->SetRoomListener(this);
        _rtc_video_interface = _rtc_room_interface->ObtainVideoInterface();
        _rtc_video_interface->SetVideoListener(this);
        _rtc_audio_interface = _rtc_room_interface->ObtainAudioInterface();
        _rtc_audio_interface->SetAudioListener(this);
    

5.x 版本，初始化操作仅需通过 [QNRTC](https://developer.qiniu.com/rtc/api/9445/QNRTC)
即可实现，示例代码如下：

    
    
      _rtc_client_ptr = QNRTC::CreateClient();
      _rtc_client_ptr->SetQNClientEventListener(this);
      _rtc_client_ptr->SetQNPublishResultCallback(this);
      _rtc_client_ptr->SetLiveStreamingListener(this);
    

更详细的 5.x
版本初始化使用方式可参考[初始化使用指南](https://developer.qiniu.com/rtc/development_guidelines/9545/user-
guidance-windows)

### 加入房间

3.x 及之前的版本，通过 `_rtc_room_interface->JoinRoom` 的方式加入房间，示例代码如下：

    
    
    _rtc_room_interface->JoinRoom(_room_token); // 加入房间
    
    // 加入房间成功后会触发如下回调
    void CRtcDemoV2::OnJoinResult(
      int error_code_, 
      const string& error_str_,
      const UserInfoList& user_list_,
      const TrackInfoList& tracks_list_,
      bool reconnect_flag_)
    {
    }
    

5.x 版本加入房间首先需要创建
[QNRTCClient](https://developer.qiniu.com/rtc/api/9446/QNRTCClient) 对象，再通过
[QNRTCClient.Join](https://developer.qiniu.com/rtc/api/9446/QNRTCClient#Join)
的方式加入房间，示例代码如下：

    
    
    _rtc_client_ptr->Join(_room_token); // 加入房间
    
    // 加入房间成功后会触发如下回调
    void CRtcDemoV2::OnConnectionStateChanged(qiniu::QNConnectionState state, const qiniu::QNConnectionDisconnectedInfo& info)
    {
        if (state == CONNECTED) {
            _wnd_status_bar.SetText(_T("登录成功！"), 1, 0);
        } 
    }
    

实现差异：

  * 5.x 版本移除了 `QNRoomInterface` 的接口调用，使用 [QNRTCClient](https://developer.qiniu.com/rtc/api/9446/QNRTCClient) 进行房间的相关操作
  * 5.x 版本房间连接状态监听回调改为 `QNClientEventListener.OnConnectionStateChanged`，监听事件包括加入房间成功、失败以及成功离开房间等

更详细的 5.x
版本房间管理使用方式可参考[房间管理使用指南](https://developer.qiniu.com/rtc/development_guidelines/9547/room-
management-windows)

### 创建本地 track

3.x 及之前的版本，通过 `CreateVideoTrackInfo` 和 `CreateAudioTrackInfo`创建本地
track，示例代码如下：

    
    
    // 创建本地音频 track
    auto audio_track = qiniu_v2::QNTrackInfo::CreateAudioTrackInfo(
                MICROPHONE_TAG,
                32000,
                false
            );
    
    // 创建本地 Camera 视频 track
    auto video_track_ptr = qiniu_v2::QNTrackInfo::CreateVideoTrackInfo(
                std::to_string(source_id),
                SCREENCASTS_TAG,
                GetDlgItem(IDC_STATIC_VIDEO_PREVIEW2)->m_hWnd,
                640,
                480,
                25,
                2000000,
                qiniu_v2::tst_ScreenCasts,
                false,
                _enable_simulcast
            );
    

5.x 版本通过 [QNRTC](https://developer.qiniu.com/rtc/api/9445/QNRTC) 创建本地
track，示例代码如下：

    
    
    // 创建本地音频 track
    QNMicrophoneAudioTrackConfig micro_info = { 32000,MICROPHONE_TAG };
    _microphone_audio_track_ptr = QNRTC::CreateMicrophoneAudioTrack(micro_info);
    
    // 创建本地 Camera 视频 track
    QNCameraVideoTrackConfig camera_info = { width,height,30,2000000,video_dev_id,CAMERA_TAG,m_hWnd,_enable_simulcast };
    _camera_track_ptr = QNRTC::CreateCameraVideoTrack(camera_info);
    

实现差异：

  * 5.x 版本移除了 `QNTrackInfo` 创建 track 的接口，改用 [QNRTC](https://developer.qiniu.com/rtc/api/9445/QNRTC) 相关接口创建
  * 5.x 版本 track 相关的配置通过 [QNCameraVideoTrackConfig](https://developer.qiniu.com/rtc/api/9406/QNCameraVideoTrackConfig) 或者 [QNMicrophoneAudioTrackConfig](https://developer.qiniu.com/rtc/api/9434/QNMicrophoneAudioTrackConfig) 等类似 Config 实现。

更详细的 5.x
版本音视频采集使用方式可参考[音视频采集使用指南](https://developer.qiniu.com/rtc/development_guidelines/9546/audio-
and-video-collection-windows)

### track 的使用

3.x 及之前的版本对 track 的大部分操作都由 `QNRoomInterface` 、 `QNVideoInterface` 和
`QNAudioInterface` 来实现，这里以部分功能举例，示例代码如下：

    
    
    // 静默本地 track
    _rtc_room_interface->MuteVideo(itor->GetTrackId(), true); // 设置静默状态
    
    _rtc_audio_interface->SetAudioVolume(unicode2utf(local_userid, pos / 100.0f); // 设置本地音频采集音量
    

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

    
    
    _microphone_audio_track_ptr->SetMuted(true); // 静默本地 track
    
    _microphone_audio_track_ptr->SetVolume(pos / 100.0f); // 设置本地音频采集音量
    

实现差异：

  * 5.x 版本将 track 相关操作接口都移交给对应的 track 来实现，移除了 `QNRoomInterface` 、 `QNVideoInterface` 和 `QNAudioInterface` 的相关调用

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

### 发布本地 track

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

    
    
    // 发布本地 track
    _rtc_room_interface->PublishTracks(track_list);
    
    // 发布成功后，会触发 QNRTCEngineEventListener.onLocalPublished 回调
    void CRtcDemoV2::OnPublishTracksResult(int error_code_, 
        const string& error_str_, const qiniu_v2::TrackInfoList& track_info_list_)
    {
    }
    

5.x 版本发布 track 通过
[QNRTCClient](https://developer.qiniu.com/rtc/api/9446/QNRTCClient)
来实现，示例代码如下：

    
    
    _rtc_client_ptr->Publish(track_list)；
    // 发布后，会触发 QNPublishResultCallback 回调
    class QNPublishResultCallback
    {
    public:
        /**
         * 发布成功后触发此回调
         */
        virtual void OnPublished() = 0;
    
        /**
         * 发布失败后触发此回调
         *
         * @param errorCode 错误码
         * @param errorMessage 错误消息
         */
        virtual void OnPublishError(int errorCode, const std::string& errorMessage) = 0;
    protected:
        ~QNPublishResultCallback() {}
    };
    

实现差异：

  * 5.x 版本通过 [QNRTCClient.Publish](https://developer.qiniu.com/rtc/api/9446/QNRTCClient#Publish) 来实现本地 track 的发布，移除了 `QNRoomInterface` 的相关调用
  * 5.x 版本发布结果回调改为了 [QNPublishResultCallback](https://developer.qiniu.com/rtc/api/9435/QNPublishResultCallback)，可在 [QNRTCClient.SetQNPublishResultCallback](https://developer.qiniu.com/rtc/api/9446/QNRTCClient#SetQNPublishResultCallback) 中传入，移除了 `QNRoomListener.OnPublishTracksResult` 回调

更详细的 5.x
版本发布和订阅使用方式可参考[发布和订阅使用指南](https://developer.qiniu.com/rtc/development_guidelines/9548/publish-
and-subscribe-windows)

### 订阅远端 track

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

    
    
    _rtc_room_interface->SubscribeTracks(sub_tracks_list); // 不支持自动订阅，需手动订阅订阅远端 track
    
    // 订阅成功后，会触发 QNRoomInterface.OnSubscribeTracksResult 回调
    void CRtcDemoV2::OnSubscribeTracksResult(int error_code_, 
        const std::string &error_str_, const qiniu_v2::TrackInfoList &track_info_list_)
    { 
    }
    

5.x 版本订阅 track 通过
[QNRTCClient](https://developer.qiniu.com/rtc/api/9446/QNRTCClient)
来实现，示例代码如下：

    
    
    _rtc_client_ptr->SetAutoSubscribe(true); // 设置是否自动订阅远端 track，默认关闭
    _rtc_client_ptr->Subscribe(trackList); // 手动订阅场景下，订阅远端 track，支持可变参数
    
    // 订阅成功后，会触发 QNClientEventListener.OnSubscribed 回调
    void CRtcDemoV2::OnSubscribed(
        const std::string& remoteUserID,
        const qiniu::RemoteAudioTrackList& remoteAudioTracks,
        const qiniu::RemoteVideoTrackList& remoteVideoTracks)
    {
    }
    

实现差异：

  * 5.x 版本通过 [QNRTCClient.Subscribe](https://developer.qiniu.com/rtc/api/9446/QNRTCClient#Subscribe) 来实现对 track 的订阅，移除了 `QNRoomInterface` 的相关调用
  * 5.x 版本订阅结果通过 [QNClientEventListener.OnSubscribed](https://developer.qiniu.com/rtc/api/9407/QNClientEventListener#OnSubscribed) 回调，移除了 `QNRoomInterface` 相关的回调

更详细的 5.x
版本发布和订阅使用方式可参考[发布和订阅使用指南](https://developer.qiniu.com/rtc/development_guidelines/9548/publish-
and-subscribe-windows)

### CDN 转推

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

    
    
    // 创建并配置单路转推任务，配置步骤省略
    _rtc_room_interface->CreateForwardJob(forwardInfo); // 开始单路转推任务
    _rtc_room_interface->StopForwardJob(_custom_forward_id, 0); // 停止单路转推任务
    
    // 创建并配置合流转推任务，配置步骤省略
    _rtc_room_interface->CreateMergeJob(job_desc, background, watermarks); // 开始合流转推任务
    _rtc_room_interface->SetMergeStreamlayouts(add_tracks_list, remove_tracks_list); // 更新、移除合流布局
    _rtc_room_interface->StopMergeStream(_custom_merge_id, 0); // 停止合流转推任务
    
    // 创建成功后会触发 QNRTCEngineEventListener 的相关回调
    void CRtcDemoV2::OnCreateForwardResult(
        const std::string& job_id_,
        int error_code_,
        const std::string& error_str_)
    {
    }
    
     void CRtcDemoV2::OnCreateMergeResult(
        const std::string& job_id_,
        int error_code_,
        const std::string& error_str_)
    {
    }
    

5.x 版本 CDN 转推通过
[QNRTCClient](https://developer.qiniu.com/rtc/api/9446/QNRTCClient)
来实现，示例代码如下：

    
    
    // 设置 CDN 转推状态监听
    _rtc_client_ptr->SetLiveStreamingListener(this)；
    
    // 创建并配置单路转推任务，配置步骤省略
    _rtc_client_ptr->StartLiveStreaming(forwardInfo); // 开始单路转推任务
    _rtc_client_ptr->StopLiveStreaming(forwardInfo); // 停止单路转推任务
    
    // 创建并配置合流转推任务，配置步骤省略
    _rtc_client_ptr->StartLiveStreaming(job_desc); // 开始合流转推任务
    _rtc_client_ptr->SetTranscodingLiveStreamingTracks(_custom_merge_id, add_tracks_list); // 更新合流布局
    _rtc_client_ptr->RemoveTranscodingLiveStreamingTracks(_custom_merge_id, remove_tracks_list); // 移除合流布局
    _rtc_client_ptr->StopLiveStreaming(job_desc); // 停止合流转推任务
    

实现差异：

  * 5.x 版本通过 [QNDirectLiveStreamingConfig](https://developer.qiniu.com/rtc/api/9414/QNDirectLiveStreamingConfig) 代替 `ForwardOptInfo` 实现单路转推的配置；通过 [QNTranscodingLiveStreamingConfig](https://developer.qiniu.com/rtc/api/9456/QNTranscodingLiveStreamingConfig) 代替 `MergeJob` 实现合流转推的配置；通过 [QNTranscodingLiveStreamingTrack](https://developer.qiniu.com/rtc/api/9458/QNTranscodingLiveStreamingTrack) 代替 `MergeOptInfo` 实现合流布局的控制
  * 5.x 版本通过 [QNLiveStreamingListener](https://developer.qiniu.com/rtc/api/9418/QNLiveStreamingListener) 代替 `QNRoomListener` 相关方法来实现 CDN 转推状态的监听

更详细的 5.x 版本 CDN 转推使用方式可参考 [CDN
转推使用指南](https://developer.qiniu.com/rtc/development_guidelines/9549/turn-the-
cdn-push-windows)

### 离开房间

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

    
    
    _rtc_room_interface->LeaveRoom(); // 离开房间
    

5.x 版本离开房间通过
[QNRTCClient](https://developer.qiniu.com/rtc/api/9446/QNRTCClient)
来实现，示例代码如下：

    
    
    _rtc_client_ptr->Leave(); // 离开房间
    

实现差异：

  * 5.x 版本通过 [QNRTCClient.Leave](https://developer.qiniu.com/rtc/api/9446/QNRTCClient#Leave) 来实现离开房间的操作，移除了 `QNRoomInterface` 的相关调用

以上内容是否对您有帮助？