#  iOS 常见问题

最近更新时间: 2023-03-10 10:54:52

本文搜集并整理了 iOS 实时音视频 SDK 对接及使用过程中的常见问题

> 若您遇到的问题本文未提及，请[提交工单](https://support.qiniu.com/tickets/new)或者联系七牛技术支持同学协助解决。

# 配置使用

## 横屏连麦的设置

需要设置
[videoOrientation](https://developer.qiniu.com/rtc/api/8852/QNCameraVideoTrack-
iOS#videoOrientation) 为 `AVCaptureVideoOrientationLandscapeRight` 或
`AVCaptureVideoOrientationLandscapeLeft`，注意对应手机的实际旋转方向，然后设置
[videoEncodeSize](https://developer.qiniu.com/rtc/api/8844/QNCameraVideoTrackConfig-
iOS#videoEncodeSize) 为横屏尺寸，即宽大于高的横屏比例分辨率。

## 扬声器听筒切换

v2.1.0 之前的版本，没有暴露切换扬声器和听筒的方法，给 `QNRTCSession` 加个扩展，直接操作 `AVAudioSession` 实现切换：

    
    
    @interface QNRTCSession (AudioSession)
    - (void)overrideOutputAudioPortToSpeaker:(BOOL)enabled;
    @end
    

v4.0 之前的版本，通过 `QNRTCEngine` 调用如下 API 实现：

    
    
    - (void)setDefaultOutputAudioPortToSpeaker:(BOOL)defaultToSpeaker;
    

v4.0 及以上版本，通过 `QNRTC` 调用
[setAudioRouteToSpeakerphone](https://developer.qiniu.com/rtc/api/8834/QNRTC-
iOS#setAudioRouteToSpeakerphone) 实现。

## SDK 对接第三方美颜的处理

直接在摄像头采集的数据回调中，修改原来的 `CMSampleBufferRef`

具体实现， v4.0 以下版本可参考 [牛互动](https://github.com/pili-engineering/QNRTCLive-
iOS/blob/master/QNRTCLiveDemo/QNRTCLiveDemo/QNLiveViewController.m) 下的

    
    
    - (void)RTCEngine:(QNRTCEngine *)engine cameraSourceDidGetSampleBuffer:(CMSampleBufferRef)sampleBuffer；
    

v4.x 则在 `QNCameraVideoTrack` 下的

    
    
    - (void)cameraVideoTrack:(QNCameraVideoTrack *)cameraVideoTrack didGetSampleBuffer:(CMSampleBufferRef)sampleBuffer;
    

v5.x 则在 `QNLocalVideoTrack` 下的

    
    
    - (void)localVideoTrack:(QNLocalVideoTrack *)localVideoTrack didGetPixelBuffer:(CVPixelBufferRef)pixelBuffer;
    

## QNRTCKit 设置 SEI 以及 PLPLayerKit 解析 SEI 信息

`QNRTCKit` SDK 中调用本地视频 Track 发布 SEI：

    
    
    // v4.x
    - (void)sendSEI:(NSString *)videoSEI repeatNmuber:(NSNumber *)repeatNumber;
    
    // v5.x
    - (void)sendSEI:(NSString *)videoSEI uuid:(NSString *)uuid repeatNmuber:(NSNumber *)repeatNumber;
    

`PLPLayerKit` SDK 中实现代理回调：

    
    
    - (void)player:(PLPlayer *)player SEIData:(NSData *)SEIData ts:(int64_t)ts;
    

在该回调内部，解析 SEI 信息，将 `SEIData`转换成需要的 16进制字符串

    
    
    NSData *data = [SEIData subdataWithRange:NSMakeRange(19, SEIData.length - 19 - 1)];
    NSMutableString *hexString = [[NSMutableString alloc] initWithCapacity:[data length]];
    [data enumerateByteRangesUsingBlock:^(const void * _Nonnull bytes, NSRange byteRange, BOOL * _Nonnull stop) {
        unsigned char *dataBytes = (unsigned char *)bytes;
        for (NSInteger i = 0; i < byteRange.length; i++) {
            NSString *hexStr = [NSString stringWithFormat:@"%x", (dataBytes[i]) & 0xff];
            if ([hexStr length] == 2) {
                [hexString appendString:hexStr];
            } else {
                [hexString appendFormat:@"0%@", hexStr];
            }
        }
    }];
    

# 功能疑问

## 是否支持后台连麦

基于 iOS App 运行模式，仅支持退后台语音连麦，视频画面将保留退后台前的最后一帧。

若您有后台连麦的需求，请在工程 Info.plist 下配置 “Required background modes” 对应 “App plays audio
or streams audio/video using AirPlay” ，即设置音频模式，就可实现在应用退后台后，保持音频采集。

若您不需要后台连麦，可以在应用层监听
`UIApplicationDidEnterBackgroundNotification`、`UIApplicationDidBecomeActiveNotification`，分别调用
[QNCameraVideoTrack.stopCapture](https://developer.qiniu.com/rtc/kb/10078) 和
[QNCameraVideoTrack.startCapture](https://developer.qiniu.com/rtc/kb/10078)方法进行
Camera 采集的关闭和开启操作。

## 服务端与客户端合流配置的差异

服务端合流需要七牛官网注册实名后的账号，在 [portal](https://portal.qiniu.com/app)
上创建应用，对应应用来编辑配置的合流信息，其中包括是否启用转推、是否只合成音频、合流输出尺寸大小、合流输出帧率和码率、填充模式以及转推流名。具体说明，可参见[服务端合流文档](https://developer.qiniu.com/rtn/4399/the-
service-side-confluence)。

**注意：合流输出尺寸是整个流的画布大小！**

客户端合流则是调用代码实现，需要配置
[QNTranscodingLiveStreamingConfig](https://developer.qiniu.com/rtc/api/8862/QNTranscodingLiveStreamingConfig-
iOS) ，生成
[QNTranscodingLiveStreamingTrack](https://developer.qiniu.com/rtc/api/8863/QNTranscodingLiveStreamingTrack-
iOS) ，然后调用
[setTranscodingLiveStreamingID](https://developer.qiniu.com/rtc/api/8836/QNRTCClient-
iOS#setTranscodingLiveStreamingID) 实现。

`QNTranscodingLiveStreamingConfig` 是合流输出的配置，包括合流输出宽高、合流转推 url、流
id、帧率、码率、画面填充模式以及水印背景图片等。

`QNTranscodingLiveStreamingTrack` 是配置单个用户的，`frame` 包括了 x、y 坐标位置及宽高，`zOrder`
则决定了层次，一般 `zOrder` 为 0，有多个转推 Track 且有层次需求的，需要小心配置，不要覆盖。

不需要合流时，服务端合流直接关闭`启用转推`，客户端则需要调用
[stopLiveStreamingWithTranscoding](https://developer.qiniu.com/rtc/api/8836/QNRTCClient-
iOS#stopLiveStreamingWithTranscoding) 来停止合流，收到
[didStopLiveStreamingWith](https://developer.qiniu.com/rtc/api/9248/QNRTCClientDelegate#didStopLiveStreamingWith)
回调代表停止合流转推成功。

另外，存在管理员用户和普通用户，即 `admin` 和 `user`。拥有 `admin` 权限的主播，可以设置 `user` 权限主播的画面。

## 房间内连麦的最大人数

上行 50 人发布，下行随时可上麦人数在 1000 人，不过最多可发布的就是 50 人；单房间观众权限（不能直接发布）最多可订阅 1 万人，主播权限是
1000 人。

## 进入房间后发生重连时的重连逻辑

房间内本地发生重连时，房间状态会变更为
[QNConnectionStateReconnecting](https://developer.qiniu.com/rtc/api/9254/QNTypeDefines#QNConnectionState)，此时
SDK 会自动重连，内部进行循环重试，当一直无法重连成功且无任何报错信息时，可通过调用
[leave](https://developer.qiniu.com/rtc/api/8836/QNRTCClient-iOS#leave) 离开房间。

## 合流失败后是否会重连

不会重连，但会触发`合流错误的回调`
[didErrorLiveStreaming](https://developer.qiniu.com/rtc/api/9248/QNRTCClientDelegate#didErrorLiveStreaming)

## 是否支持 APP Extension 方式的录屏

不支持，`QNRTC` 在 Extension 模式下无法实现数据发布，直接在 APP 中用系统录屏 Replaykit 的
`RPScreenRecorder` 即可。

## 是否支持合流过程中修改发布的分辨率

不支持，需要先停止原来的视频发布
[unpublish](https://developer.qiniu.com/rtc/api/8836/QNRTCClient-
iOS#unpublish)，设置新的参数后重新发布
[publish](https://developer.qiniu.com/rtc/api/8836/QNRTCClient-iOS#publish)。

## 混音格式支持

混音功能分为[背景音乐混音](https://developer.qiniu.com/rtc/api/11930/QNAudioMusicMixer-
iOS)和[多音效混音](https://developer.qiniu.com/rtc/development_guidelines/11979/iOS-
audio-effect-mixer)两种。

两种混音场景均支持本地文件和在线文件，支持混合的音频格式为：aac、mp3、mp4、wav、m4r、caf、ogg、opus、m4a、flac

# 非预期问题

## 合流后没有视频帧或音频帧

检查 portal 后台连麦应用的设置，检查下宽高参数是否有设置为`奇数`，若存在改为`偶数`即可；没有音频，需要检查是否`静默`了音频发布。

## 合流后转推画面不符合预期

检查配置合流转推后台`画布`大小，客户端上`位置`是否对应，是否存在`多人`可配置合流画面位置导致。

## 上架 AppStore 审核失败

可能使用了`真机加模拟器`版本，或者携带了 `QNRTCKit` SDK 文件夹下的 `dsym` 文件。保证使用`仅真机`版本，且不携带 `dsym`
文件。

## 设置 QNCameraVideoTrack 的编码分辨率配置 videoEncodeSize 不生效

创建
[QNCameraVideoTrack](https://developer.qiniu.com/rtc/8852/QNCameraVideoTrack-
iOS) 指定编码分辨率配置
[videoEncodeSize](https://developer.qiniu.com/rtc/8844/QNCameraVideoTrackConfig-
iOS#videoEncodeSize) 时，需要同步设置预览分辨率
[videoFormat](https://developer.qiniu.com/rtc/8852/QNCameraVideoTrack-
iOS#videoFormat)，保证预览分辨率的宽高大于编码分辨率的宽高，否则设置不生效。

## 手动引入 SDK 时报错：动态库无法找到 image not found

如果运行后程序 crash，报错信息标识动态库无法找到 image not found，说明 SDK 没有正常
Embed，可以按[接入文档](https://developer.qiniu.com/rtc/8831/prepare-ios-
development#3)流程重新引入一次。

## 屏幕录制失败或者播放声音突然变小

需要检查下 App 层是否更改了 `AVAudioSession` 的 category 类型或 mode 模式，在使用 SDK
的过程中，请确保`AVAudioSession` 的 category 类型和 mode 模式分别是
`AVAudioSessionCategoryPlayAndRecord` 和
`AVAudioSessionModeVoiceChat`，否则可能出现屏幕录制失败（报错 -5833）、播放声音突然变小等非预期问题。

# 报错处理

## RTCVideoEncoderH264 报错 -12902

当使用默认
[videoEncodeSize](https://developer.qiniu.com/rtc/api/8844/QNCameraVideoTrackConfig-
iOS#videoEncodeSize)，但实际预览画面尺寸会动态改变时，会复现该报错，原因是 `videoEncodeSize`
默认与预览画面尺寸一致，当预览画面尺寸动态更改时，编码尺寸 `videoEncodeSize` 也一直随之改动，导致编码报错。

此时，需要对
[videoEncodeSize](https://developer.qiniu.com/rtc/api/8844/QNCameraVideoTrackConfig-
iOS#videoEncodeSize) 设置固定值，不随预览画面尺寸动态更改。

## 更新合流转推的布局发生报错 11013

请先检查
[startLiveStreamingWithTranscoding](https://developer.qiniu.com/rtc/api/8836/QNRTCClient-
iOS#startLiveStreamingWithTranscoding) 创建合流转推是否成功，是否存在
[streamID](https://developer.qiniu.com/rtc/api/8862/QNTranscodingLiveStreamingConfig-
iOS#streamID) 或
[publishUrl](https://developer.qiniu.com/rtc/api/8862/QNTranscodingLiveStreamingConfig-
iOS#publishUrl) 为 nil。

正确做法应该在创建合流转推成功的回调
[didTranscodingTracksUpdated](https://developer.qiniu.com/rtc/api/9248/QNRTCClientDelegate#didTranscodingTracksUpdated)
中，实现合流转推布局
[setTranscodingLiveStreamingID](https://developer.qiniu.com/rtc/api/8836/QNRTCClient-
iOS#setTranscodingLiveStreamingID) 的更新。

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

* __
* __
* __
* __
* __

文档反馈 (如有产品使用问题，请[ 提交工单](https://support.qiniu.com/tickets/category))

提交