iOS播放器常见问题

问题现象：使用5.4.7.1及之后版本的播放器时，出现如下报错。

解决方法：

• 请先确认您是否已申请License授权并在已配置License，5.4.7.1及之后版本播放器SDK需要配置License之后才能正常使用，具体操作，请参见License说明。

  说明

  当您使用组件化、多工程维护的代码工程，且已根据License说明配置好License后，如果使用AliListPlayer播放，仍然报错License is invalid!!!，则建议您使用5.5.0.0及以上版本的播放器SDK。

• 请确认您配置的License是否正确，判断方法请参见如何判断License是否正确。

问题现象：使用iOS Xcode14打包APP并提交到App Store审核时出现包含bitcode的错误，报错示例如下：

 ITMS-90482: Invalid Executable - The executable 'xxx.app/Frameworks/alivcffmpeg.framework/alivcffmpeg' contains bitcode.

处理方法：您可以通过xcrun bitcode_strip手动去除对应的framework的bitcode。如下示例中，${framework_path}是framework的二进制文件路径。

xcrun bitcode_strip ${framework_path} -r -o ${framework_path}

问题现象：当使用iOS Xcode14打包APP并提交到App Store审核时出现使用curl的错误，报错示例如下：

ITMS-90338: Non-public API usage - The app references non-public symbols in Frameworks/AliyunPlayer.framework/AliyunPlayer: _curl_multi_poll, _curl_multi_wakeup. If method names in your source code match the private Apple APIs listed above, altering your method names will help prevent this app from being flagged in future submissions. In addition, note that one or more of the above APIs may be located in a static library that was included with your app. If so, they must be removed. For further information, visit the Technical Support Information at http://developer.apple.com/support/technical/

处理方法：

• 如果您的项目中只集成了播放器SDK（AliPlayerSDK_iOS），则建议您升级到5.4.9.2以上版本。

• 如果您的项目中既集成了播放器SDK（AliPlayerPartSDK_iOS），同时还集成了短视频SDK，则建议播放器SDK升级到5.4.9.2以上版本，alivcffmpeg（QuCore-ThirdParty）升级到4.3.6版本，短视频SDK升级到3.26以上版本。

问题现象：当使用iOS Xcode14打包APP并提交到App Store审核时出现非公开方法的错误，报错示例如下：

问题现象：当使用iOS Xcode14打包APP并提交到App Store审核时出现引入mpf_filter.framework、vfi_filter.framework等插帧、锐化后处理插件相关的错误，报错示例如下：

处理方法：

• 如果您的工程中没有使用到报错提及的插件，则建议您删除报错的插件，不仅不会影响播放器的能力，还可以减小包的体积。

• 如果您的工程中必须使用报错提及的插件，则可以暂时在该framework路径下的Info.plist文件中的"Bundle identifier"键值对中，将值字符串中的"_"手动去掉，然后再进行编译构建工程。

• 可升级至5.5.2.0及以上版本，已修正命名。

处理方法：您可以在工程中适当的位置，进行统一设置AVAudioSession。例如：将应用的音频会话配置为播放类别，并允许与其他应用混音。再如，将应用的音频会话配置为PlayAndRecord类别，用于录制+播放的场景。如果操作过程中有任何错误，错误信息将被存储在err变量中。

[[AVAudioSession sharedInstance] setCategory:AVAudioSessionCategoryPlayback withOptions:AVAudioSessionCategoryOptionMixWithOthers error:&err];

同时，在阿里云iOS播放器SDK侧通过自定义设置AVAudioSession的代理，不使用SDK内部定义好的AVAudioSession逻辑，从而规避阿里云iOS播放器SDK侧可能造成的音频抢占风险。阿里云iOS播放器SDK侧的配置示例如下：

1. 设置代理。

   [AliPlayer setAudioSessionDelegate:self];

2. 设置代理的监听。

   return TRUE表示SDK内部不再对AVAudioSession进行设置。

   #pragma mark CicadaAudioSessionDelegate
   - (BOOL)setActive:(BOOL)active error:(NSError **)outError
   {
       return YES;
   }
   
   - (BOOL)setCategory:(NSString *)category withOptions:(AVAudioSessionCategoryOptions)options error:(NSError **)outError
   {
         return YES;
   }
   
   - (BOOL)setCategory:(AVAudioSessionCategory)category mode:(AVAudioSessionMode)mode routeSharingPolicy:(AVAudioSessionRouteSharingPolicy)policy options:(AVAudioSessionCategoryOptions)options error:(NSError **)outError
   {
       return YES;
   }

当您在使用iOS播放器SDK时出现指向SDK的堆栈崩溃，您可以通过如下方法解决：

1. 若您使用的iOS播放器SDK不是最新版本，建议您升级至最新版本。iOS播放器SDK在不断的推出新版本优化提升稳定性，最新版SDK的获取，请参见播放器SDK。

2. 如果升级到最新版本后仍然出现相关崩溃，建议您将全量崩溃信息提供给阿里云技术支持。获取技术支持，请参见获取技术支持。

播放器SDK默认每500 ms回调一次播放进度。您可以修改回调间隔时间，通过将间隔时间缩短，以更高频率地获取当前播放进度，示例代码如下：

AVPConfig *config = [self.player getConfig];
config.positionTimerIntervalMs = 100; // 修改回调间隔时间，单位：ms。
[self.player setConfig:config];

/**
 @brief：视频当前播放位置回调。
 @param player：播放器player指针。
 @param position：视频当前播放位置。
 */
- (void)onCurrentPositionUpdate:(AliPlayer*)player position:(int64_t)position {
    // 当前播放进度。
    long currentPosition = position;
}

可通过如下三种方式进行获取：

• 方式一：通过iOS播放器AliPlayer实例执行完prepare方法，当处于准备完成状态后（AVPEventPrepareDone），可以直接获取AliPlayer实例的宽（width）和高（height）。

  -(void)onPlayerEvent:(AliPlayer*)player eventType:(AVPEventType)eventType {
      if (eventType == AVPEventPrepareDone) {
        NSLog(@"视频的宽:%d，高:%d", player.width, player.height);
      }
  }

• 方式二：通过监听视频大小变化回调的方法，直接返回视频的宽（width）和高（height）。

  - (void)onVideoSizeChanged:(AliPlayer*)player width:(int)width height:(int)height rotation:(int)rotation {
      NSLog(@"视频的宽:%d，高:%d", width, height);
  }

• 方式三：通过监听获取track信息回调的方法，根据info数组返回的AVPTrackInfo，获取视频的宽（videoWidth）和高（videoHeight）。

  说明

  监听获取track信息回调，由于是从网络请求，其成功获取到视频的宽高信息依赖网络质量，建议使用方式一和方式二的方法获取视频的宽高信息更为可靠。

  - (void)onTrackReady:(AliPlayer*)player info:(NSArray<AVPTrackInfo*>*)info {
      for (int i=0; i<info.count; i++) {
        AVPTrackInfo *trackInfo = info[i];
        NSLog(@"视频的宽：%d，高：%d", trackInfo.videoWidth, trackInfo.videoHeight);
    }
  }

可通过以下步骤排查问题产生原因：

1. 确认crash是否产生在播放器SDK。

   查看是否有带AliyunPlayer前缀的崩溃堆栈，如果有，则说明问题产生在播放器SDK。

2. 升级至最新版播放器SDK并验证，确认问题是否已经修复。

3. 如果问题依然存在，请准备相关的崩溃文件（包含全部线程）、崩溃日志、崩溃场景等信息，如何获取问题日志。

实现方法示例如下：

UIInterfaceOrientation orientation = UIInterfaceOrientationLandscapeLeft; // 要旋转为全屏
......

// iOS 16.0以上的系统
if (@available(iOS 16.0, *)) {
    @try {
            NSArray *array = [[[UIApplication sharedApplication] connectedScenes] allObjects];
      UIWindowScene *ws = (UIWindowScene *)array[0];
        Class GeometryPreferences = NSClassFromString(@"UIWindowSceneGeometryPreferencesIOS");
      id geometryPreferences = [[GeometryPreferences alloc]init];
      UIInterfaceOrientationMask orientationMask = UIInterfaceOrientationMaskLandscapeRight;
      if (orientation == UIInterfaceOrientationPortrait) {
          orientationMask = UIInterfaceOrientationMaskPortrait;
      }
      [geometryPreferences setValue:@(orientationMask) forKey:@"interfaceOrientations"];
      SEL sel_method = NSSelectorFromString(@"requestGeometryUpdateWithPreferences:errorHandler:");
      void (^ErrorBlock)(NSError *err) = ^(NSError *err){
            NSLog(@"屏幕旋转出错:%@", [err debugDescription]);
      };
      if ([ws respondsToSelector:sel_method]) {
          (((void (*)(id, SEL,id,id))[ws methodForSelector:sel_method])(ws, sel_method,geometryPreferences,ErrorBlock));
      }
  } @catch (NSException *exception) {
      NSLog(@"屏幕旋转出错:%@", exception.reason);
  } @finally {
  }
} else { // iOS16.0以下的系统
  if ([[UIDevice currentDevice] respondsToSelector:@selector(setOrientation:)]) {
      SEL selector = NSSelectorFromString(@"setOrientation:");
      NSInvocation *invocation = [NSInvocation invocationWithMethodSignature:[UIDevice instanceMethodSignatureForSelector:selector]];
      [invocation setSelector:selector];
      [invocation setTarget:[UIDevice currentDevice]];
      [invocation setArgument:&Orientation atIndex:2];
      invocation invoke];
  }
  [[UIApplication sharedApplication]setStatusBarOrientation:orientation animated:YES];
}

可通过以下步骤排查问题产生原因：

1. 检查视频源本身是否存在黑边问题。

2. 可通过如下接口调节播放器的缩放模式。

   /*
   AVP_SCALINGMODE_SCALEASPECTFILL：按比例填充，画面会有裁剪。
   AVP_SCALINGMODE_SCALEASPECTFIT：按比例缩放，会有黑边。
   AVP_SCALINGMODE_SCALETOFILL：不按比例填充，画面会变形。
   */
   self.player.scalingMode = AVP_SCALINGMODE_SCALETOFILL;

3. 若缩放模式依然无法满足需求，则可以调节设置self.player.playerView的自定义View的宽和高（通过修改self.player.playerView的frame实现）。

可通过以下步骤排查问题产生原因：

1. 使用其他播放器播放，检查视频是否是纯音频。

2. 使用其他播放器播放时播放正常且出现视频源长宽变化，则可以设置成软解码方式，设置方法如下：

   player.enableHardwareDecoder = NO

V5.4.5.0及之前版本的播放器SDK不支持使用列表播放器AliListPlayer播放HLS（m3u8）格式的视频。从V5.4.5.0之后版本开始支持播放HLS（m3u8）格式的视频，但是需要开启本地缓存，开启本地缓存的方法请参见本地缓存。

解决方法：

1. 在Xcode中开启后台采集数据功能。示例如下：

2. 如果实现了程序前后台监听方法，则需要注释掉相关的暂停、重新播放方法。

   // 添加检测APP进入后台的观察者
   [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(applicationEnterBackground) name: UIApplicationWillResignActiveNotification object:nil];
   // APP从后台进入前台时会调用该方法
   [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(applicationDidBecomeActive) name: UIApplicationDidBecomeActiveNotification object:nil];
   
   // 需注释掉的暂停方法
   - (void)applicationEnterBackground {
      // [self.player pause];
   }
   // 需注释掉的重新播放方法
   - (void)applicationDidBecomeActive {
      // [self.player start];
   }

切换seek模式的示例代码如下：

//切换为非精准seek。
[self.player seekToTime:1000 seekMode:AVP_SEEKMODE_INACCURATE];
//切换为精准seek。
[self.player seekToTime:1000 seekMode:AVP_SEEKMODE_ACCURATE];

解决方法：可以通过接口设置精准seek的最大间隔，将精准seek的最大间隔调大，降低精准seek被切换成非精准seek的频率，以提高seek精准度，但当seek的点距离关键帧间隔太长时，耗时也将更长，请根据业务特点合理设置精准seek的最大间隔。示例代码如下：

//单位：ms。
[self.player setMaxAccurateSeekDelta:100];

可以在onPlayerEvent回调中，获取缓存失败的原因。onPlayerEvent回调的示例代码如下：

/**
 @brief：播放器事件回调。
 @param player：播放器player指针。
 @param eventWithString：播放器事件类型。
 @param description：播放器事件说明。
 @see AVPEventType
 */
-(void)onPlayerEvent:(AliPlayer*)player eventWithString:(AVPEventWithString)eventWithString description:(NSString *)description {
    if (eventWithString == EVENT_PLAYER_CACHE_SUCCESS) { // 边播边缓存成功。

    } else if (eventWithString == EVENT_PLAYER_CACHE_ERROR) { // 边播边缓存失败。
        NSString *errorMsg = description;
    }
}

常见的失败原因如下：

• CacheConfig中设置的大小和时长与视频不匹配导致缓存失败。

• 在播放过程中，stop或者seek到buffer外导致缓存失败。

获取音视频源数据的示例代码如下：

// 设置渲染回调。
self.player.renderingDelegate = self;

// 监听渲染回调。
- (BOOL)onRenderingFrame:(CicadaFrameInfo*) frameInfo {
    if (frameInfo.frameType == Cicada_FrameType_Video) { // 底层视频数据。

    } else if (frameInfo.frameType == Cicada_FrameType_Audio) { // 底层音频数据。

    }
    return NO;
}

当开启自动码率切换，即调用了[self.player selectTrack:SELECT_AVPTRACK_TYPE_VIDEO_AUTO];接口后，播放器SDK内部会统计当前网速，当10秒内网速达到下一个码率时，就会切换到下一个码率。若10秒内网速未达到下一个码率，则不切换。

• 从高码率切换到低码率的场景，当10秒内网速达到下一个码率时，会将已缓存的高码率内容播放完成后才切换。

• 从低码率切换到高码率的场景，当10秒内网速达到下一个码率时，会直接切换。

可以自定义重试逻辑，当触发重试时，将重试事件通知到外部，由外部决定具体的重试逻辑。示例代码如下：

AVPConfig *config = [self.player getConfig];
config.networkRetryCount = 0; // 设置重试次数，此处以设置为0为例。
[self.player setConfig:config];

/**
 @brief：播放器事件回调。
 @param player：播放器player指针。
 @param eventWithString：播放器事件类型。
 @param description：播放器事件说明。
 @see AVPEventType
 */
-(void)onPlayerEvent:(AliPlayer*)player eventWithString:(AVPEventWithString)eventWithString description:(NSString *)description {
    if (eventWithString == EVENT_PLAYER_NETWORK_RETRY) { // 网络失败，需要重试。
        // TODO做相应的逻辑处理。
    }
}

可通过以下步骤排查报错原因：

1. 检查3个SDK（AliPlayerSDK_iOS、AliPlayerSDK_iOS_ARTC、RtsSDK）是否全部都已集成。

   使用阿里云播放器播放RTS流，需要集成3个SDK：AliPlayerSDK_iOS、AliPlayerSDK_iOS_ARTC、RtsSDK。集成操作可参见阿里云播放器SDK集成Native RTS SDK实现说明。

2. 检查Native RTS SDK（RtsSDK）和阿里云播放器SDK（AliPlayerSDK_iOS）的版本是否配套。

   Native RTS SDK和阿里云播放器SDK有版本配套关系，需要集成对应的版本，版本配套关系请参见SDK下载。

3. 检查AliPlayerSDK_iOS和AliPlayerSDK_iOS_ARTC的版本是否一致，需保持一致。

示例代码如下：

//以VidSts播放方式为例。
AVPVidStsSource *stsSource = [[AVPVidStsSource alloc] init];
stsSource.vid = @"<vid>";
stsSource.accessKeyId = @"<accessKeyId>";
stsSource.securityToken = @"<securityToken>";
stsSource.accessKeySecret = @"<accessKeySecret>";
stsSource.quality = @""; // 期望播放的清晰度，取值为FD、LD、SD、HD、2K、4K、OD。
stsSource.forceQuality = NO; // 是否强制使用期望播放的清晰度播放。NO：不强制使用期望的清晰度播放，按播放器SDK的默认清晰度播放顺序查找播放；YES：强制使用设置的期望清晰度播放，如果找不到期望播放的清晰度就不播放。