ApsaraVideo VOD:iOS Player FAQ

License-related issues

Resolve invalid or expired license issues in License FAQ.

Common issues across platforms

• For platform-independent issues, check Cross-platform player FAQs.

• Experienced developers can also troubleshoot playback errors independently.

Errors occur when you package an app with Xcode 14 and submit it to the App Store for review

Bitcode-related errors

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

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

cURL-related errors

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/

Errors about non-public APIs

Solution: This is a warning from Xcode 14 builds and typically does not affect the release if the project builds successfully. If the app cannot be released, use Xcode 13.

Errors related to post-processing plugins such as mpf_filter.framework and vfi_filter.framework for frame interpolation and sharpening

After I integrate ApsaraVideo Player SDK for iOS, can I debug and run my app on an Xcode emulator?

ApsaraVideo Player SDK for iOS does not support emulators. Use a physical iPhone to debug and run your app.

How to get the current playback progress

AVPConfig *config = [self.player getConfig];
config.positionTimerIntervalMs = 100; // Change the callback interval. Unit: ms.
[self.player setConfig:config];

/**
 @brief: The callback for the current playback position.
 @param player: The player pointer.
 @param position: The current playback position.
 */
- (void)onCurrentPositionUpdate:(AliPlayer*)player position:(int64_t)position {
    // The current playback progress.
    long currentPosition = position;
}

How to get the width and height of a video

The progress bar jumps back after a seek operation

Cause: The player uses inaccurate seek by default. After a seek operation, the player starts playback from a keyframe near the seek point.

Solution: Switch to the accurate seek mode.

How to switch between accurate and inaccurate seek modes

// Switch to inaccurate seek.
[self.player seekToTime:1000 seekMode:AVP_SEEKMODE_INACCURATE];
// Switch to accurate seek.
[self.player seekToTime:1000 seekMode:AVP_SEEKMODE_ACCURATE];

The progress bar still jumps back after I switch to the accurate seek mode

Cause: Accurate seek takes longer than inaccurate seek. If the distance from the seek point to the nearest keyframe is too large and exceeds the maximum interval for accurate seek, the ApsaraVideo Player SDK automatically switches to inaccurate seek. This causes the progress bar to jump back.

// Unit: ms.
[self.player setMaxAccurateSeekDelta:10000];

Error during video caching: encrypt check fail

Caching works the same as downloading. With secure download enabled, the encryption verification file must match the app information. Download the file from Offline download and add it to the SDK. Follow the steps in Video download, otherwise caching or downloading fails.

Obtain audio and video source data

// Set the rendering callback.
self.player.renderingDelegate = self;

// Listen for the rendering callback.
- (BOOL)onRenderingFrame:(CicadaFrameInfo*) frameInfo {
    if (frameInfo.frameType == Cicada_FrameType_Video) { // Underlying video data.

    } else if (frameInfo.frameType == Cicada_FrameType_Audio) { // Underlying audio data.

    }
    return NO;
}

How do I get the pixels of each video frame in the player?

ApsaraVideo Player SDK for iOS: You can obtain the pixels by listening for the onRenderingFrame callback.

player.renderingDelegate = self;


#pragma mark CicadaRenderingDelegate
- (BOOL)onRenderingFrame:(CicadaFrameInfo*) frameInfo{
    if(frameInfo.frameType==Cicada_FrameType_Video){
        // Video
        NSLog(@"receive HW frame:%p pts:%ld foramt %d", frameInfo.video_pixelBuffer, frameInfo.pts, CVPixelBufferGetPixelFormatType(frameInfo.video_pixelBuffer));

    } else if (frameInfo.frameType==Cicada_FrameType_Audio){
        // Audio
    }
    return NO;
}

Adaptive bitrate switching logic

Custom retry logic

The SDK retries failed network operations twice by default with a 15-second timeout. If all retries fail, the Error callback fires.

AVPConfig *config = [self.player getConfig];
config.networkRetryCount = 0; // Set the number of retries. In this example, the value is set to 0.
[self.player setConfig:config];

/**
 @brief: The callback for player events.
 @param player: The player pointer.
 @param eventWithString: The player event type.
 @param description: The description of the player event.
 @see AVPEventType
 */
-(void)onPlayerEvent:(AliPlayer*)player eventWithString:(AVPEventWithString)eventWithString description:(NSString *)description {
    if (eventWithString == EVENT_PLAYER_NETWORK_RETRY) { // Network error. A retry is required.
        // TODO: Add the processing logic.
    }
}

A 403 error is reported and playback of an HLS stream fails after local caching is configured

Symptom: Playing an HLS (M3U8) stream with VidAuth and local caching enabled fails with a 403 error.

Cause: If you exit before the video is fully cached, the player reuses expired VidAuth credentials on the next playback attempt, causing a 403 error.

Solution: In SDK V5.5.4.0 and later, set the AVPConfig.enableStrictAuthMode field to control the authentication mode for HLS streams with authentication parameters. Defaults to false.

• Non-strict authentication (false): Authentication is cached. If only part of the media was cached previously, the player uses the cached authentication to request non-cached parts. If the URL authentication validity period is short, or playback resumes long after pausing, authentication may expire. Combine with the auto-refresh playback sources feature to handle expired authentication during resume.

• Strict authentication (true): Authentication is not cached. Authentication occurs on every startup, causing startup failure without network connectivity.

Audio preemption prevents ApsaraVideo Player SDK for iOS from playing videos

Symptom: When your project uses both ApsaraVideo Player SDK and other audio controls, playback issues such as no sound or video stuttering occur.

Cause: The AVAudioSession in iOS is a singleton. Without unified configuration across multiple audio controls, audio preemption can prevent video playback.

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

A stack crash that points to the SDK occurs when ApsaraVideo Player SDK for iOS is running

Does ApsaraVideo Player SDK for iOS support downloading while playing?

No. The SDK supports local caching, which downloads videos during playback for later offline use. However, it does not support playing cached files stored in a separate file directory.

Does ApsaraVideo Player SDK for iOS support getting the buffering progress of a video?

Yes. ApsaraVideo Player SDK for iOS supports obtaining the buffering speed, real-time rendering frame rate, audio and video bitrates, and network download bitrate. Get playback information.

A crash occurs while the player is running

A crash related to program initialization or preloading occurs when ApsaraVideo Player SDK V5.4.6.0 is running

Upgrade the ApsaraVideo Player SDK to a version later than V5.4.7.1. To maintain the stability of V5.4.6.0, you can also use the hotfix version pod 5.4.6.0-25587639.

How to enable full-screen playback

ApsaraVideo Player SDK for iOS does not provide an API for full-screen playback. You need to implement this feature based on the system. The ApsaraVideo Player SDK for iOS demo for versions 5.5.0.0 and later is adapted to the full-screen method of iOS 16.0 and later.

UIInterfaceOrientation orientation = UIInterfaceOrientationLandscapeLeft; // Rotate to full screen
......

// For iOS 16.0 and later
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(@"Screen rotation error:%@", [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(@"Screen rotation error:%@", exception.reason);
  } @finally {
  }
} else { // For systems earlier than iOS 16.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];
}

Black bars appear during video playback

Audio plays but no video is displayed, and the log reports "log[AFVTBDecoder] :IOS8VT: throw frame"

Stuttering and audio-video desynchronization occur during RTS stream pulling on an iOS client

Solution: Integrate the latest ultra-low latency component of the player. Implement RTS stream pulling on an iOS client.

When an iOS app is in the background or not started, audio plays but no video is displayed if the user enters the app through a notification.

- (AliPlayer *)aliPlayer{
    if (!_aliPlayer && UIApplicationStateActive == [[UIApplication sharedApplication] applicationState]) {
        _aliPlayer = [[AliPlayer alloc] init];
        _aliPlayer.scalingMode =  AVP_SCALINGMODE_SCALEASPECTFIT;
        _aliPlayer.rate = 1;
        _aliPlayer.delegate = self;
        _aliPlayer.playerView = self.playerView;
    }
    return _aliPlayer;
}

When a live stream is played, the log reports a standard error: "-5, IO error (Input/Output (I/O))"

When you play a live stream, use the default values for the cache and latency control settings (startBufferDuration, highBufferDuration, and maxBufferDuration in AVPConfig). Do not customize these settings. Verify your configuration against Configure cache and latency control.

After I pause playback, navigate away, and then return to resume playback, an audio-related error is reported in the log: "Deactivating an audio session that has running I/O." or "All I/O should be stopped or paused prior to deactivating the audio session."

Symptom: On the video playback page, you pause playback and navigate to another page that has audio. When you return, you cannot resume playback, and an audio-related error such as "Deactivating an audio session that has running I/O." or "All I/O should be stopped or paused prior to deactivating the audio session." is reported in the log.

Solution: Check for conflicts in audio settings (AudioSession properties). For example, when you exit another page with audio, the audio resources may not be released in time (the related recording or audio playback is not stopped promptly).

An error occurs when AliListPlayer is used to play an HLS (m3u8) video

An unsupported protocol error occurs when you play an ARTC stream

Cause 1: The bridge layer between the player and the RTS component (AlivcArtc) and the RTS component (RtsSDK) are not integrated, even though the ApsaraVideo Player SDK is integrated.

Solution: For information about how to integrate the components, see Implement RTS stream pulling on an iOS client.

Cause 2: The version of the bridge layer between the player and the RTS component (AlivcArtc) is inconsistent with the version of the player.

Solution: The bridge layer (AlivcArtc) and the player must have the same version number. Implement RTS stream pulling on an iOS client.

If a video is transcoded into multiple definitions, which definition does the ApsaraVideo Player SDK play by default?

The SDK plays the first available definition in this order: FD, LD, SD, HD, 2K, 4K, OD. Definition.

How to specify the default definition for video playback

// The following code provides an example of playback using VidSts.
AVPVidStsSource *stsSource = [[AVPVidStsSource alloc] init];
stsSource.vid = @"<vid>";
stsSource.accessKeyId = @"<accessKeyId>";
stsSource.securityToken = @"<securityToken>";
stsSource.accessKeySecret = @"<accessKeySecret>";
stsSource.quality = @""; // The expected definition for playback. Valid values: FD, LD, SD, HD, 2K, 4K, and OD.
stsSource.forceQuality = NO; // Specifies whether to forcibly play the video in the expected definition. NO: The video is not forcibly played in the expected definition. The player searches for definitions in the default order and plays the video in the first definition that it finds. YES: The video is forcibly played in the expected definition. If the expected definition is not found, the video is not played.

If a definition has multiple streams, which stream does the ApsaraVideo Player SDK play?

If a definition has multiple streams, the ApsaraVideo Player SDK plays the latest stream.

How to configure a video to be played without a watermark but downloaded with a watermark?

Transcode the video into multiple definitions. Play the definition without a watermark and download the definition with a watermark.

Landscape mode does not take effect

ApsaraVideo Player SDK for iOS does not provide a method to implement landscape mode. You need to implement this feature based on the iOS system API. When you implement landscape mode, make sure to properly set the frame of aliplayer.playerView.

How to obtain logs

Submit logs when requesting Alibaba Cloud technical support to expedite issue resolution.

1. Obtain the logs.

   Set the log level to LOG_LEVEL_TRACE before obtaining logs. Obtain SDK logs.

2. Provide the generated logs to Alibaba Cloud technical support.

   Get technical support.

After the local cache is enabled, the multi-rate (HLS) video misses the cache.

Problem phenomenon: The local cache has been turned on and preloaded according to the document, but the progress of seeking back to the cache missed during playback, or the playback cannot continue after the network is disconnected, or the cache file check returns that it does not exist, or the cache directory is empty after the preload is turned off.

Cause of the problem: In the multi-bit rate (HLS) scenario, if a certain stream is not explicitly selected during playback, the player plays in ABR (adaptive bit rate) mode, and the data in ABR mode does not fall on the disk, so no local cache is generated. Only after the selectTrack is explicitly called to select a certain code stream, the selected data will be cached to the local. If the selectTrack is not called (or the incoming SELECT_AVPTRACK_TYPE_VIDEO_AUTO), it will be processed according to ABR.

Solution: Ensure that preloading and playback use the same definition and the same playback address, and explicitly select the code stream during playback.

1. In the preloading stage, the local cache is enabled to initiate preloading on the code stream of the specified definition.

2. The playback phase calls the selectTrack after the onPlayerEvent receives the preparation completion event (AVPEventPrepareDone), and selects the same definition as the preload; setUrlSource(AVPUrlSource) uses the same playback address as the preload, and then prepare and start.

3. If the starting bit rate is inconsistent with the default bit rate, the buffering will be triggered. It is recommended to set the starting bit rate to reduce the switching jam.

Playing a locally downloaded HLS (m3u8) file results in the error “No such file or directory.”

Problem phenomenon: After HLS is downloaded offline, play the local address and report No such file or directory (no file found). This problem may not be necessary and is easier to reproduce in scenarios such as multi-page fast switching (fast sliding).

Cause of the problem: HLS offline download usually only downloads ts slices and m3u8 of one of the definitions (e.g. 540p) in order to save space, but the locally saved master m3u8 still retains the records of all definitions (e.g. 1080p/720p/540p/360p) as they are. During playback, if the downloaded definition is not specified before prepare, the player will try to request other definition parts that do not exist locally according to the default/adaptive logic, thus reporting that the file cannot be found. A common cause is the omission of a call with specified clarity, or the timing of the call later than prepare.

Solution:

1. The setDefaultResolution is called before the prepare, specifying the same definition as the offline download.

2. Ensure that all playback portals are set with default definition, including fast sliding, multi-instance multiplexing, preload switching and other branches to avoid missing a 1 path.

3. The getCurrentTrack can be used to verify whether the actual starting definition is the downloaded definition.

Audio and video misalignment occurs after video switching, or the same video is repeatedly played and misses the cache.

Problem phenomenon: After the local cache is turned on, when switching videos (such as switching the number of sets), there is a dislocation of sound and picture (the screen is a new video and the sound is still the previous video), or the same video is repeatedly played without hitting the cache; After clearing the cache, it returns to normal.

Cause of the problem: After the local cache is enabled, the player uses the Hash returned by the setCacheUrlHashCallback callback as the unique cache identifier of each playback address (iOS implements this callback through the C function pointer). If the callback does not ensure that "the same playback address always returns the same hash, different content returns different hash", it will lead to cache key mismatch: different content hits the same cache (shown as audio and picture misalignment), or the same address each time the hash is different and cannot hit the cache.

Solution:

1. The callback must stably return the same hash for the same playback address, and different media must return different hashes.

2. For example, in order to remove the authentication parameter to improve the hit rate, only hash is calculated after the authentication parameter is removed for the playback address (m3u8/mp4); The keyURL of encrypted m3u8 does not need to be authenticated, otherwise the keys of different videos will hit the same cache and cause playback failure-it can be handled differently by domain name in the callback.

3. If the same file has both HTTP and HTTPS addresses, the protocol can be unified or the hash can be calculated after the protocol header is removed.

For details, please refer Advanced features.

Authentication failed when playing Alibaba Cloud private encrypted video

Problem phenomenon: When playing a video encrypted by Alibaba Cloud video (private encryption), the authentication fails or cannot be played.

Cause of the problem: alibaba cloud video encryption (private encryption) is decrypted by the interaction between the player and the server, and playback must be started through vid playback. If you use the on-demand AVPUrlSource to directly transfer the playback address to play (common private encryption), the authentication and decryption cannot be completed, which fails.

Solution:

1. Private encrypted videos are played on iOS through on-demand AVPVidAuthSource(VidAuth) or AVPVidStsSource(VidSts). If the output stream is mixed with non-private encrypted streams, you can set the encryption type to AliyunVoDEncryption to filter private encrypted streams.

2. Note: Only "License private encryption" supports on-demand AVPUrlSource playback (MP4 must be spliced at the end of the URL etavirp_nuyila=1,HLS can directly use the original URL in the corresponding supported version), ordinary private encryption is not applicable.

For details, please refer Play an encrypted video.