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

gpt: [实时音视频](https://developer.qiniu.com/rtc) > 使用指南 > 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 及之前版本的相关文档](https://doc.qnsdk.com/rtn/ios)。
>

## 改动简介

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

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

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

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

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

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

区别于 3.x 版本所有 [Track](https://developer.qiniu.com/rtc/quick_start/9909/the-rtc-
basic-concept#track) 均使用 `QNTrackInfo`，在 4.x 版本 SDK 中，我们细化了音视频 Track
的分类，基于不同类型的 Track 提供了不同的控制接口，新版本的 Track 对本地 Track 和远端 Track 做了区分，继承结构定义如下：

  * [QNTrack](https://developer.qiniu.com/rtc/api/8851/QNTrack-iOS)
    * [QNLocalTrack](https://developer.qiniu.com/rtc/api/8847/QNLocalTrack-iOS)
      * [QNLocalAudioTrack](https://developer.qiniu.com/rtc/api/8854/QNLocalAudioTrack-iOS)
        * [QNMicrophoneAudioTrack](https://developer.qiniu.com/rtc/api/8855/QNMicrophoneAudioTrack-iOS)
        * [QNCustomAudioTrack](https://developer.qiniu.com/rtc/api/8856/QNCustomAudioTrack-iOS)
      * [QNLocalVideoTrack](https://developer.qiniu.com/rtc/api/8849/QNLocalVideoTrack-iOS)
        * [QNCameraVideoTrack](https://developer.qiniu.com/rtc/api/8852/QNCameraVideoTrack-iOS)
        * [QNCustomVideoTrack](https://developer.qiniu.com/rtc/api/8853/QNCustomVideoTrack-iOS)
        * [QNScreenVideoTrack](https://developer.qiniu.com/rtc/api/8850/QNScreenVideoTrack-iOS)
    * [QNRemoteTrack](https://developer.qiniu.com/rtc/api/8857/QNRemoteTrack-iOS)
      * [QNRemoteAudioTrack](https://developer.qiniu.com/rtc/api/8859/QNRemoteAudioTrack-iOS)
      * [QNRemoteVideoTrack](https://developer.qiniu.com/rtc/api/8858/QNRemoteVideoTrack-iOS)

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

4.x 版本除了对音视频 [Track](https://developer.qiniu.com/rtc/quick_start/9909/the-rtc-
basic-concept#track) 的结构进行了调整，还将部分 Track 的操作接口从 `QNRTCEngine` 移到了 Track
上，包括采集、渲染、美颜以及音视频回调监听的设置等。更详细接口定义请参考对应的 API 文档。

### 优化事件监听接口

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

  * [QNRTCClientDelegate:](https://developer.qiniu.com/rtc/api/9248/QNRTCClientDelegate) 核心回调接口，定义了房间相关的回调事件，包括房间连接状态、用户加入离开状态等
  * [QNCameraTrackVideoDataDelegate:](https://developer.qiniu.com/rtc/api/9252/QNCameraTrackVideoDataDelegate) 视频数据帧回调接口
  * [QNMicrophoneAudioTrackDataDelegate:](https://developer.qiniu.com/rtc/api/89267/QNMicrophoneAudioTrackDataDelegate) 音频数据帧回调接口
  * [QNAudioMixerDelegate:](https://developer.qiniu.com/rtc/api/9251/QNAudioMixerDelegate) 混音相关回调接口，监听混音状态、进度等事件
  * [QNRemoteTrackDelegate](https://developer.qiniu.com/rtc/api/9265/QNRemoteTrackDelegate) 音视频 Track 信息变化监听接口，监听是否静默
  * [QNRemoteTrackVideoDataDelegate](https://developer.qiniu.com/rtc/api/9253/QNRemoteTrackVideoDataDelegate) 视频 Track 信息变化监听接口，监听大小流切换

* * *

## 核心步骤迁移详解

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

### 初始化

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

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

4.x 版本，初始化操作直接通过 [QNRTC](https://developer.qiniu.com/rtc/api/8834/QNRTC-iOS)
类方法即可实现，示例代码如下：

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

实现差异：

  * 4.x 版本 SDK 直接通过 [QNRTC.init](https://developer.qiniu.com/rtc/api/8834/QNRTC-iOS#init%5B1/2%5D) 即可完成初始化操作。

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

### 加入房间

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

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

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

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

实现差异：

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

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

### 创建本地 Track

3.x 及之前的版本，通过 `QNRTCEngine` 创建本地
[Track](https://developer.qiniu.com/rtc/quick_start/9909/the-rtc-basic-
concept#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](https://developer.qiniu.com/rtc/api/8834/QNRTC-iOS) 创建本地
[Track](https://developer.qiniu.com/rtc/quick_start/9909/the-rtc-basic-
concept#track)，示例代码如下：

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

实现差异：

  * 4.x 版本移除了 `QNRTCEngine` 创建 Track 的接口，改用 [QNRTC](https://developer.qiniu.com/rtc/api/8834/QNRTC-iOS) 相关接口创建
  * 4.x 版本 Track 相关的配置通过 [QNCameraVideoTrackConfig](https://developer.qiniu.com/rtc/api/8844/QNCameraVideoTrackConfig-iOS) 或者 [QNMicrophoneAudioTrackConfig](https://developer.qiniu.com/rtc/api/8837/QNMicrophoneAudioTrackConfig-iOS) 等类似 Config 实现，创建时不传该参数则使用 SDK 提供的默认配置。3.x 版本需要在 `QNTrackInfo` 初始化配置中传入，不传则使用默认配置。

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

### Track 的使用

3.x 及之前的版本对 [Track](https://developer.qiniu.com/rtc/quick_start/9909/the-rtc-
basic-concept#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](https://developer.qiniu.com/rtc/quick_start/9909/the-rtc-
basic-concept#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](https://developer.qiniu.com/rtc/quick_start/9909/the-rtc-
basic-concept#track) 通过 `QNRTCEngine` 来实现，示例代码如下：

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

4.x 版本发布 [Track](https://developer.qiniu.com/rtc/quick_start/9909/the-rtc-
basic-concept#track) 通过
[QNRTCClient](https://developer.qiniu.com/rtc/api/8836/QNRTCClient-iOS)
来实现，示例代码如下：

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

实现差异：

  * 4.x 版本通过 [QNRTCClient.publish](https://developer.qiniu.com/rtc/api/8836/QNRTCClient-iOS#publish%5B1/2%5D) 来实现本地 Track 的发布，移除了 `QNRTCEngine` 的相关调用
  * 4.x 版本发布结果回调改为了 [QNPublishResultCallback](https://developer.qiniu.com/rtc/api/9254/QNTypeDefines#QNPublishResultCallback)，可在 [QNRTCClient.publish](https://developer.qiniu.com/rtc/api/8836/QNRTCClient-iOS#publish%5B2/2%5D) 中传入，移除了 `QNRTCEngineDelegate.didPublishLocalTracks` 回调

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

### 订阅远端 Track

3.x 及之前的版本订阅 [Track](https://developer.qiniu.com/rtc/quick_start/9909/the-rtc-
basic-concept#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](https://developer.qiniu.com/rtc/quick_start/9909/the-rtc-
basic-concept#track) 通过
[QNRTCClient](https://developer.qiniu.com/rtc/api/8836/QNRTCClient-iOS)
来实现，示例代码如下：

    
    
    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 版本通过 [QNRTCClient.subscribe](https://developer.qiniu.com/rtc/api/8836/QNRTCClient-iOS#subscribe) 来实现对 Track 的订阅，移除了 `QNRTCEngine` 的相关调用
  * 4.x 版本订阅结果通过 [QNRTCClientDelegate.didSubscribedRemoteVideoTracks](https://developer.qiniu.com/rtc/api/9248/QNRTCClientDelegate#didSubscribedRemoteVideoTracks) 回调，移除了 `QNRTCEngineDelegate` 相关的回调

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

### 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](https://developer.qiniu.com/rtc/api/8836/QNRTCClient-iOS)
来实现，示例代码如下：

    
    
    // 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 版本通过 [QNDirectLiveStreamingConfig](https://developer.qiniu.com/rtc/api/8861/QNDirectLiveStreamingConfig-iOS) 代替 `QNForwardStreamConfiguration` 实现单路转推的配置；通过 [QNTranscodingLiveStreamingConfig](https://developer.qiniu.com/rtc/api/8862/QNTranscodingLiveStreamingConfig-iOS) 代替 `QNMergeStreamConfiguration` 实现合流转推的配置；通过 [QNTranscodingLiveStreamingTrack](https://developer.qiniu.com/rtc/api/8862/QNTranscodingLiveStreamingConfig-iOS) 代替 `QNMergeStreamLayout` 实现合流布局的控制
  * 4.x 版本通过 [QNRTCClientDelegate](https://developer.qiniu.com/rtc/api/9248/QNRTCClientDelegate) 代替 `QNRTCEngineDelegate` 相关方法来实现 CDN 转推状态的监听

更详细的 4.x 版本 CDN 转推使用方式可参考 [CDN
转推使用指南](https://developer.qiniu.com/rtc/development_guidelines/9260/publish-
and-subscribe-iOS)

### 离开房间

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

    
    
    [rtcEngine leaveRoom]; // 离开房间
    

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

    
    
    [rtcClient leave]; // 离开房间
    

实现差异：

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

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