ApsaraVideo VOD：iOS播放器常見問題

問題現象：使用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：強制使用設定的期望清晰度播放，如果找不到期望播放的清晰度就不播放。