实时音视频

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

    迁移指南

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

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

    升级指南

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

    改动简介

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

    优化实时音视频管理方式

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

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

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

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

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

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

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

    优化事件监听接口

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

    核心步骤迁移详解

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

    初始化

    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 即可实现，示例代码如下：

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

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

    加入房间

    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 对象，再通过 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 进行房间的相关操作
    • 5.x 版本房间连接状态监听回调改为 QNClientEventListener.OnConnectionStateChanged，监听事件包括加入房间成功、失败以及成功离开房间等

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

    创建本地 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 创建本地 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 版本音视频采集使用方式可参考音视频采集使用指南

    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 来实现，示例代码如下：

    _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 版本发布和订阅使用方式可参考发布和订阅使用指南

    订阅远端 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 来实现，示例代码如下：

    _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 版本发布和订阅使用方式可参考发布和订阅使用指南

    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 来实现，示例代码如下：

    // 设置 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 版本 CDN 转推使用方式可参考 CDN 转推使用指南

    离开房间

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

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

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

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

    实现差异：

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