实时音视频

  • 实时音视频 > 使用指南 > iOS >v4.x 迁移指南

    v4.x 迁移指南

    最近更新时间: 2022-06-07 23:23:16

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

    升级指南

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

    改动简介

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

    优化实时音视频管理方式

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

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

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

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

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

    注意:本地仅支持创建一路音频 Track,重复创建会返回 nil。

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

    优化事件监听接口

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


    核心步骤迁移详解

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

    初始化

    3.x 及之前的版本,初始化操作需要调用 QNRTCEngine 的相关方法,示例代码如下:

    QNRTCConfiguration *configuration = [QNRTCConfiguration defaultConfiguration]; // 创建并初始化 SDK 默认配置
    QNRTCEngine *engine = [[QNRTCEngine alloc] initWithConfiguration:configuration];// 创建 QNRTCEngine 对象
    

    4.x 版本,初始化操作直接通过 QNRTC 类方法即可实现,示例代码如下:

    QNRTCConfiguration *configuration = [QNRTCConfiguration defaultConfiguration]; // 创建并初始化 SDK 默认配置
    [QNRTC configRTC:configuration]; // QNRTC 初始化
    QNRTCClient *rtcClient = [QNRTC createRTCClient]; // 创建 QNRTCClient
    

    实现差异:

    • 4.x 版本 SDK 直接通过 QNRTC.init 即可完成初始化操作。

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

    加入房间

    3.x 及之前的版本,通过 - (void)joinRoomWithToken:(NSString *)token; 的方式加入房间,示例代码如下:

    [rtcEngine joinRoomWithToken:roomToken]; // 加入房间
    
    // 加入房间成功后会触发如下回调
    - (void)RTCEngine:(QNRTCEngine *)engine roomStateDidChange:(QNConnectionState)roomState {
        if (state == QNConnectionStateConnected) {
    		// 成功加入房间
        }
    }
    

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

    rtcClient = [QNRTC createRTCClient]; // 创建 QNRTCClient 对象,并设置房间事件监听函数
    [rtcClient join:roomToken]; // 加入房间
    
    // 加入房间成功后会触发如下回调
    - (void)RTCClient:(QNRTCClient *)client didConnectionStateChanged:(QNConnectionState)state disconnectedInfo:(QNConnectionDisconnectedInfo *)info {
        if (state == QNConnectionStateConnected) {
    		// 成功加入房间
        }
    }
    

    实现差异:

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

    创建本地 Track

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

    // 创建本地音频 Track
    QNTrackInfo *audioInfo = [[QNTrackInfo alloc] initWithSourceType:QNRTCSourceTypeAudio master:YES bitrateBps:self.audioBitrate * 1000];
    
    // 创建本地 Camera 视频 Track
    QNTrackInfo *videoInfo = [[QNTrackInfo alloc] initWithSourceType:QNRTCSourceTypeCamera master:YES bitrateBps:self.videoBitrate * 1000 videoEncodeSize:self.videoEncodeSize];
    

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

    // 创建本地音频 Track
    QNMicrophoneAudioTrack *microphoneAudioTrack = [QNRTC createMicrophoneAudioTrack];
    
    // 创建本地 Camera 视频 Track
    QNCameraVideoTrackConfig *cameraVideoTrackConfig = [QNRTC createCameraVideoTrack];
    

    实现差异:

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

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

    Track 的使用

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

    // 开启 Camera Track 内置美颜并设置美颜参数
    [rtcEngine setBeautifyModeOn:YES]; // 开启美颜
    [rtcEngine setBeautify:0.5]; // 设置美颜参数
    [rtcEngine setWhiten:0.5]; // 设置美白参数
    [rtcEngine setRedden:0.5]; // 设置红润参数
    
    [rtcEngine startCapture]; // 开启 Camera Track 采集
    [rtcEngine stopCapture]; // 停止 Camera Track 采集
    
    // 静默本地 Track
    [rtcEngine muteAudio:YES]; // 设置音频静默状态
    [rtcEngine muteVideo:YES]; // 设置视频静默状态
    

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

    // 开启 Camera Track 内置美颜并设置美颜参数
    [cameraVideoTrack setBeautifyModeOn:YES]; // 开启美颜
    [cameraVideoTrack setBeautify:0.5]; // 设置美颜参数
    [cameraVideoTrack setWhiten:0.5]; // 设置美白参数
    [cameraVideoTrack setRedden:0.5]; // 设置红润参数
    
    [cameraVideoTrack startCapture]; // 开启 Camera Track 采集
    [cameraVideoTrack stopCapture]; // 停止 Camera Track 采集
    
    // 静默本地 Track
    [localAudio updateMute:YES]; // 设置音频静默状态
    [localVideo updateMute:YES]; // 设置视频静默状态
    
    [microphoneAudioTrack setVolume:0.8]; // 设置麦克风采集音量
    

    实现差异:

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

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

    发布本地 Track

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

    // 发布本地 Track
    [rtcEngine publishTracks:tracks];
    
    // 发布成功后,会触发 QNRTCEngineDelegate.didPublishLocalTracks 回调
    - (void)RTCEngine:(QNRTCEngine *)engine didPublishLocalTracks:(NSArray<QNTrack *> *)tracks {
    	// 回调发布成功的 Track 列表
    }
    

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

    // 发布本地 Track
    [rtcClient publish:tracks completeCallback:^(BOOL onPublished, NSError *error) {
    	if (onPublished) {
    		// Track 发布成功
    	} else {
    		// Track 发布失败
    	}
    }];
    

    实现差异:

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

    订阅远端 Track

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

    rtcEngine.autoSubscribe = YES; // 设置是否自动订阅远端 Track,默认开启
    [rtcEngine subscribeTracks:tracks]; // 手动订阅场景下,订阅远端 Track
    
    // 订阅成功后,会触发 QNRTCEngineDelegate.didSubscribedRemoteVideoTracks 回调
    - (void)RTCEngine:(QNRTCEngine *)engine didSubscribedRemoteVideoTracks:(NSArray<QNRemoteVideoTrack *> *)videoTracks audioTracks:(NSArray<QNRemoteAudioTrack *> *)audioTracks ofUserID:(NSString *)userID {
    	// 回调订阅成功的 Track 列表
    }
    

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

    rtcClient.autoSubscribe = YES; // 设置是否自动订阅远端 Track,默认开启
    [rtcClient subscribe:tracks]; // 手动订阅场景下,订阅远端 Track,支持可变参数
    
    // 订阅成功后,会触发 QNRTCClientDelegate.didSubscribedRemoteVideoTracks 回调
    - (void)RTCClient:(QNRTCClient *)client didSubscribedRemoteVideoTracks:(NSArray<QNRemoteVideoTrack *> *)videoTracks audioTracks:(NSArray<QNRemoteAudioTrack *> *)audioTracks ofUserID:(NSString *)userID {
    	// 回调订阅成功的 Track 列表
    }
    

    实现差异:

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

    CDN 转推

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

    // 创建并配置单路转推任务,配置步骤省略
    QNForwardStreamConfiguration *forwardConfig = [QNForwardStreamConfiguration alloc] init];
    
    [rtcEngine createForwardJobWithConfiguration:forwardConfig]; // 开始单路转推任务
    [rtcEngine stopForwardJobWithJobId:forwardConfig.jobId]; // 停止单路转推任务
    
    // 创建并配置合流转推任务,配置步骤省略
    QNMergeStreamConfiguration *mergeConfig = [QNMergeStreamConfiguration alloc] init];
    [rtcEngine createMergeStreamJobWithConfiguration:mergeConfig; // 开始合流转推任务
    [rtcEngine setMergeStreamLayouts:layouts jobId:mergeConfig.jobId]; // 更新合流布局
    [rtcEngine removeMergeStreamLayouts:layouts jobId:mergeConfig.jobId]; // 移除合流布局
    [rtcEngine stopMergeStreamWithJobId:mergeConfig.jobId]; // 停止合流转推任务
    
    // 创建成功后会触发 QNRTCEngineDelegate 的相关回调
    - (void)RTCEngine:(QNRTCEngine *)engine didCreateForwardJobWithJobId:(NSString *)jobId {
    	// 回调创建成功的单路转推 job id
    }
    
    - (void)RTCEngine:(QNRTCEngine *)engine didCreateMergeStreamWithJobId:(NSString *)jobId {
    	// 回调创建成功的合流转推 job id
    }
    

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

    // CDN 转推相关回调
    - (void)RTCClient:(QNRTCClient *)client didStartLiveStreamingWith:(NSString *)streamID {
    	// 对应 streamID 的单路/合流转推任务开始转推
    }
    
    - (void)RTCClient:(QNRTCClient *)client didStopLiveStreamingWith:(NSString *)streamID {
    	// 对应 streamID 的单路/合流转推任务已停止转推
    }
    
    - (void)RTCClient:(QNRTCClient *)client didTranscodingTracksUpdated:(BOOL)success withStreamID:(NSString *)streamID {
    	// 合流布局更改时触发此回调
    }
    
    - (void)RTCClient:(QNRTCClient *)client didErrorLiveStreamingWith:(NSString *)streamID errorInfo:(QNLiveStreamingErrorInfo *)errorInfo {
    	// 转推任务出错时触发此回调
    }
    
    // 创建并配置单路转推任务,配置步骤省略
    QNDirectLiveStreamingConfig *directLiveStreamingConfig = [[QNDirectLiveStreamingConfig alloc] init];
    [rtcClient startLiveStreamingWithDirect:directLiveStreamingConfig]; // 开始单路转推任务
    [rtcClient stopLiveStreamingWithDirect:directLiveStreamingConfig]; // 停止单路转推任务
    
    // 创建并配置合流转推任务,配置步骤省略
    QNTranscodingLiveStreamingConfig *transcodingLiveStreamingConfig = [[QNTranscodingLiveStreamingConfig alloc] init];
    [rtcClient startLiveStreamingWithTranscoding:transcodingLiveStreamingConfig]; // 开始合流转推任务
    [rtcClient setTranscodingLiveStreamingID:transcodingLiveStreamingConfig.streamID withTracks:transcodingTracks]; // 更新合流布局
    [rtcClient removeTranscodingLiveStreamingID:transcodingLiveStreamingConfig.streamID withTracks:transcodingTracks]; // 移除合流布局
    [rtcClient stopLiveStreamingWithTranscoding:transcodingLiveStreamingConfig]; // 停止合流转推任务
    

    实现差异:

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

    离开房间

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

    [rtcEngine leaveRoom]; // 离开房间
    

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

    [rtcClient leave]; // 离开房间
    

    实现差异:

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