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

若您遇到的问题本文未提及，请提交工单或者联系七牛技术支持同学协助解决。

横屏连麦的设置

需要设置 videoOrientation 为 AVCaptureVideoOrientationLandscapeRight 或 AVCaptureVideoOrientationLandscapeLeft，注意对应手机的实际旋转方向，然后设置 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 实现。

SDK 对接第三方美颜的处理

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

具体实现， v4.0 以下版本可参考 牛互动 下的

- (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 和 QNCameraVideoTrack.startCapture方法进行 Camera 采集的关闭和开启操作。

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

服务端合流需要七牛官网注册实名后的账号，在 portal 上创建应用，对应应用来编辑配置的合流信息，其中包括是否启用转推、是否只合成音频、合流输出尺寸大小、合流输出帧率和码率、填充模式以及转推流名。具体说明，可参见服务端合流文档。

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

客户端合流则是调用代码实现，需要配置 QNTranscodingLiveStreamingConfig ，生成 QNTranscodingLiveStreamingTrack ，然后调用 setTranscodingLiveStreamingID 实现。

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

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

不需要合流时，服务端合流直接关闭启用转推，客户端则需要调用 stopLiveStreamingWithTranscoding 来停止合流，收到 didStopLiveStreamingWith 回调代表停止合流转推成功。

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

房间内连麦的最大人数

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

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

房间内本地发生重连时，房间状态会变更为 QNConnectionStateReconnecting，此时 SDK 会自动重连，内部进行循环重试，当一直无法重连成功且无任何报错信息时，可通过调用 leave 离开房间。

合流失败后是否会重连

不会重连，但会触发合流错误的回调 didErrorLiveStreaming

是否支持 APP Extension 方式的录屏

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

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

不支持，需要先停止原来的视频发布 unpublish，设置新的参数后重新发布 publish。

混音格式支持

混音功能分为背景音乐混音和多音效混音两种。

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

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

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

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

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

上架 AppStore 审核失败

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

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

创建 QNCameraVideoTrack 指定编码分辨率配置 videoEncodeSize 时，需要同步设置预览分辨率 videoFormat，保证预览分辨率的宽高大于编码分辨率的宽高，否则设置不生效。

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

如果运行后程序 crash，报错信息标识动态库无法找到 image not found，说明 SDK 没有正常 Embed，可以按接入文档流程重新引入一次。

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

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

RTCVideoEncoderH264 报错 -12902

当使用默认 videoEncodeSize，但实际预览画面尺寸会动态改变时，会复现该报错，原因是 videoEncodeSize 默认与预览画面尺寸一致，当预览画面尺寸动态更改时，编码尺寸 videoEncodeSize 也一直随之改动，导致编码报错。

此时，需要对 videoEncodeSize 设置固定值，不随预览画面尺寸动态更改。

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

请先检查 startLiveStreamingWithTranscoding 创建合流转推是否成功，是否存在 streamID 或 publishUrl 为 nil。

正确做法应该在创建合流转推成功的回调 didTranscodingTracksUpdated 中，实现合流转推布局 setTranscodingLiveStreamingID 的更新。