ApsaraVideo VOD:Basic features of ApsaraVideo Player SDK for iOS

Prepare for playback

Call the prepare method to prepare the video for playback.

[self.player prepare];

The onPlayerEvent callback with AVPEventPrepareDone is invoked when preparation is complete.

Start playback

Call the start method to begin playing the video:

[self.player start];

Pause playback

Call the pause method to pause the video:

[self.player pause];

Resume playback

Call the start method to resume playback after pausing:

[self.player start];

Seek to a specific position

Call seekToTime to jump to a specific position. This method is useful when users drag the progress bar or resume playback from a saved position.

// Seek to a specific position (in milliseconds)
// Accurate seek
[self.player seekToTime:position seekMode:AVP_SEEKMODE_ACCURATE];
// Inaccurate seek
[self.player seekToTime:position seekMode:AVP_SEEKMODE_INACCURATE];

Seek modes:

• Accurate seek (AVP_SEEKMODE_ACCURATE): Seeks to the exact position. Slower but more precise.

• Inaccurate seek (AVP_SEEKMODE_INACCURATE): Seeks to the nearest keyframe. Faster but less precise.

Start playback from a specific position

To start playback from a specific position (rather than seeking during playback), call setStartTime before calling prepare:

// Set the start time for the next prepare call (in milliseconds).
// This setting is only valid for the immediately following prepare call. The start time is automatically cleared after prepare is called.
// seekMode: accurate seek (AVP_SEEKMODE_ACCURATE) or inaccurate seek (AVP_SEEKMODE_INACCURATE).
[self.player setStartTime:time seekMode:seekMode];

Stop playback

Call the stop method to stop playback:

[self.player stop];

Destroy the player

You can destroy the player synchronously or asynchronously to release resources.

// Synchronous destroy. Blocks until player resources are released. Automatically calls stop.
[self.player destroy];
// Asynchronous destroy. Returns immediately. Automatically calls stop.
[self.player destroyAsync];

Recommendations:

• Use destroyAsync if you need fast UI response times.

• Do not perform any operations on the player object during asynchronous destruction.

• You do not need to call stop before destroyAsync because the destruction process includes an asynchronous stop operation.

Set the player delegate

Implement the AVPDelegate protocol in your view controller to receive player callbacks.

Important: Implement the onError and onPlayerEvent callbacks to handle errors and monitor playback state changes.

@interface SimplePlayerViewController ()<AVPDelegate>
@end
- (void)viewDidLoad {
    self.player = [[AliPlayer alloc] init];
    self.player.playerView = self.avpPlayerView.playerView;
    self.player.delegate = self;
    //...
}
/**
 @brief Delegate callback for player errors.
 @param player The player instance.
 @param errorModel Contains the error details.
 */
- (void)onError:(AliPlayer*)player errorModel:(AVPErrorModel *)errorModel {
    // Handle the error (e.g., show an alert) and stop playback.
}
/**
 @brief Delegate callback for player events.
 @param player The player instance.
 @param eventType The type of the event. See AVPEventType.
 */
-(void)onPlayerEvent:(AliPlayer*)player eventType:(AVPEventType)eventType{
    switch(eventType){
        case AVPEventPrepareDone:{
            // Triggered when the media has been prepared and is ready to play.
        }
            break;
        case AVPEventAutoPlayStart:
            // Triggered when autoplay begins.
            break;
        case AVPEventFirstRenderedStart:
            // Triggered when the first frame is rendered.
            break;
        case AVPEventCompletion:
            // Triggered when playback completes.
            break;
        case AVPEventLoadingStart:
            // Triggered when buffering starts.
            break;
        case AVPEventLoadingEnd:
            // Triggered when buffering finishes.
            break;
        case AVPEventSeekEnd:
            // Triggered when a seek operation completes.
            break;
        case AVPEventLoopingStart:
            // Triggered when a new loop begins.
            break;
        default:
            break;
    }
}
/**
 @brief Callback for the current playback position.
 @param player The player instance.
 @param position The current playback position in milliseconds.
 */
- (void)onCurrentPositionUpdate:(AliPlayer*)player position:(int64_t)position {
    // Update the progress bar.
}
/**
 @brief Callback for the current buffered position.
 @param player The player instance.
 @param position The current buffered position in milliseconds.
 */
- (void)onBufferedPositionUpdate:(AliPlayer*)player position:(int64_t)position {
    // Update the buffer progress indicator.
}
/**
 @brief Callback for when track information is ready.
 @param player The player instance.
 @param info An array of AVPTrackInfo objects for the available streams.
 */
- (void)onTrackReady:(AliPlayer*)player info:(NSArray<AVPTrackInfo*>*)info {
    // Retrieve information for available bitrates/tracks.
}
/**
 @brief Callback for when a subtitle should be displayed.
 @param player The player instance.
 @param index The index of the subtitle entry.
 @param subtitle The subtitle text to be displayed.
 */
- (void)onSubtitleShow:(AliPlayer*)player index:(int)index subtitle:(NSString *)subtitle {
    // Get and display the subtitle text.
}
/**
 @brief Callback for when a subtitle should be hidden.
 @param player The player instance.
 @param index The index of the subtitle entry that was shown.
 */
- (void)onSubtitleHide:(AliPlayer*)player index:(int)index {
    // Hide the subtitle.
}
/**
 @brief Callback for a screen capture request.
 @param player The player instance.
 @param image The captured screenshot as a UIImage.
 */
- (void)onCaptureScreen:(AliPlayer *)player image:(UIImage *)image {
    // Preview or save the captured image.
}
/**
 @brief Callback for when a track change is complete.
 @param player The player instance.
 @param info The AVPTrackInfo object for the new, active track.
 */
- (void)onTrackChanged:(AliPlayer*)player info:(AVPTrackInfo*)info {
    // Notification that the bitrate/track has changed.
}

Listen for player state changes

The onPlayerStatusChanged callback is invoked when the player state changes:

- (void)onPlayerStatusChanged:(AliPlayer*)player oldStatus:(AVPStatus)oldStatus newStatus:(AVPStatus)newStatus {
    switch (newStatus) {
    case AVPStatusIdle:{
           // Player is idle
        }
 break;
        case AVPStatusInitialzed:{
           // Player is initialized
        }
 break;
        case AVPStatusPrepared:{
           // Player prepared
        }
 break;
        case AVPStatusStarted:{
           // Playback started
        }
 break;
case AVPStatusPaused:{
           // Playback paused
        }
 break;
case AVPStatusStopped:{
           // Playback stopped
        }
 break;
case AVPStatusCompletion:{
           // Playback completed
        }
 break;
case AVPStatusError:{
           // Player error occurred
        }
 break;
        default:
            break;
    }
}

Scaling modes

The SDK supports three scaling modes:

// Scale to fit the view while maintaining the aspect ratio (letterboxing).
self.player.scalingMode = AVP_SCALINGMODE_SCALEASPECTFIT;
// Scale to fill the view while maintaining the aspect ratio (cropping).
self.player.scalingMode = AVP_SCALINGMODE_SCALEASPECTFILL;
// Stretch to fill the view. The aspect ratio is not maintained. Image distortion may occur.
self.player.scalingMode = AVP_SCALINGMODE_SCALETOFILL;

Rotation

Rotate the video clockwise by a specified angle:

// No rotation
self.player.rotateMode = AVP_ROTATE_0;
// Rotate 90 degrees clockwise
self.player.rotateMode = AVP_ROTATE_90;
// Rotate 180 degrees clockwise
self.player.rotateMode = AVP_ROTATE_180;
// Rotate 270 degrees clockwise
self.player.rotateMode = AVP_ROTATE_270;

Mirroring

Call setMirrorMode to mirror the video. The SDK supports horizontal and vertical mirroring:

// No mirroring
self.player.mirrorMode = AVP_MIRRORMODE_NONE;
// Horizontal mirroring
self.player.mirrorMode = AVP_MIRRORMODE_HORIZONTAL;
// Vertical mirroring
self.player.mirrorMode = AVP_MIRRORMODE_VERTICAL;

Playback progress

The current playback position is returned in the onCurrentPositionUpdate callback:

- (void)onCurrentPositionUpdate:(AliPlayer*)player position:(int64_t)position {
// position is in milliseconds
NSString *position = [NSString stringWithFormat:@"%lld, position"];
}

Total duration

Retrieve the total duration of the video after it has been loaded (e.g., after the AVPEventPrepareDone event):

-(void)onPlayerEvent:(AliPlayer*)player eventType:(AVPEventType)eventType {
  switch (eventType) {
    case AVPEventPrepareDone: {
      if (self.player.duration >= 0) {
       NSString *duration  = self.player.duration;
      }
    }
      break;
    default:
      break;
  }
}

Actual playback duration

Retrieve the actual playback duration in real time. This value excludes the time when playback is paused or buffering.

 NSString *duration = [player getPlayedDuration];

Buffering progress

The current buffering progress is returned in the onBufferedPositionUpdate callback:

- (void)onBufferedPositionUpdate:(AliPlayer*)player position:(int64_t)position {
    NSString *bufferPosition = position;
}

Real-time rendering and bitrate metrics

Obtain the rendering frame rate, audio and video bitrate, and network downstream bitrate in real time.

// Video rendering frame rate. Returns a float value.
[self.player getOption:AVP_OPTION_RENDER_FPS]
// Video bitrate. Returns a float value in bit/s.
[self.player getOption:AVP_OPTION_VIDEO_BITRATE]
// Audio bitrate. Returns a float value in bit/s.
[self.player getOption:AVP_OPTION_AUDIO_BITRATE]
// Network downstream bitrate. Returns a float value in bit/s.
[self.player getOption:AVP_OPTION_DOWNLOAD_BITRATE]

Adjust the volume

Call volume to change the volume. Valid values range from 0 to 2, where 1 is the original volume. Values greater than 1 amplify the audio and may introduce noise. We recommend that you do not set the volume to a value greater than 1.

// Set the volume. Valid values: 0 to 2.
self.player.volume = 1.0f;
// Get the current volume.
self.player.volume

Mute the video

Mute or unmute the audio:

self.player.muted = YES;

VidAuth or VidSts-based playback

If you use VidAuth or VidSts for VOD playback, the SDK automatically retrieves video definitions from ApsaraVideo VOD. No additional configuration is required.

- (void)onTrackReady:(AliPlayer*)player info:(NSArray<AVPTrackInfo*>*)info {
    for (int i=0; i<info.count; i++) {
        AVPTrackInfo* track = [info objectAtIndex:i];
        switch (track.trackType) {
            case AVPTRACK_TYPE_VIDEO: {
                int trackBitrate = track.trackBitrate;
            }
                break;
        }
    }
}

[self.player selectTrack:index];

- (void)onTrackChanged:(AliPlayer*)player info:(AVPTrackInfo*)info {
 // Definition switched.
}

AVPConfig *config = [self.player getConfig];
config.selectTrackBufferMode = 1;
[self.player setConfig:config];

UrlSource-based live streaming

For details, see Standard live stream playback.

Supported stream types

You can switch audio tracks in the following stream types. The switching behavior varies based on the stream type.

Get available audio tracks

The onSubTrackReady callback is invoked when audio track information is available:

  // onSubTrackReady. Typically triggered before the AVPEventPrepareDone event.
- (void)onSubTrackReady:(AliPlayer*)player info:(NSArray<AVPTrackInfo*>*)info {
    // Call getSubMediaInfo after this callback is triggered. Calling it before this callback returns an empty result.
    AVPMediaInfo* subMediaInfo = [player getSubMediaInfo];
    // Iterate through available audio tracks
    for (int i=0; i<subMediaInfo.tracks.count; i++) {
    	AVPTrackInfo* track = [mediaInfo.tracks objectAtIndex:i];
        // Find the target audio track from the track list.
    }
}

Switch the audio track

Call the selectTrack method to switch to a different audio track:

[self.player selectTrack:myTrack.trackIndex accurate:YES]

Method 1: View logs in the development tool console

This method is suitable for scenarios where you can reproduce the issue locally.

1. Enable logging and set the log level:

   // Enable SDK logging
   [AliPlayer setEnableLog:YES];
   // Set the log level (default: LOG_LEVEL_INFO). Use LOG_LEVEL_TRACE for detailed troubleshooting.
   [AliPlayer setLogCallbackInfo:LOG_LEVEL_INFO callbackBlock:nil];

2. Enable frame-level logging (optional):

   // Enable frame-level logging for detailed troubleshooting
   // 0 = disabled, 1 = enabled
   [AliPlayer setLogOption:FRAME_LEVEL_LOGGING_ENABLED value:value];

   Note

   Frame-level logging generates a large volume of logs and is primarily used for troubleshooting playback issues.

3. Collect logs:

   Option A: View logs in the console

   After reproducing the issue, retrieve the logs from your development tool console, such as XCode.

   Option B: Write logs to a file

   Set the full path for your log file within the application's sandbox.

   NSArray *paths =NSSearchPathForDirectoriesInDomains(NSDocumentDirectory,NSUserDomainMask, YES);
   NSString *documentDirectory = [paths objectAtIndex:0];
   // Define your custom log file path. For example, create a file named 'xxxx.log'.
   NSString *logFilePath = [documentDirectory stringByAppendingPathComponent:@"xxxx.log"];

   Redirect logs to a custom file in the app's sandbox:

   freopen([logFilePath cStringUsingEncoding:NSASCIIStringEncoding],"a+", stdout);
   freopen([logFilePath cStringUsingEncoding:NSASCIIStringEncoding],"a+", stderr);

   After reproducing the issue, retrieve the .log file from the custom directory.

Method 2: Set LogCallback to receive logs programmatically

Use this method when you cannot reliably reproduce the issue on your device. The callback exports logs to your application's log channel.

1. Enable logging and set the log level.

   // Enable SDK logging
   [AliPlayer setEnableLog:YES];
   // Set the log level. Default value: LOG_LEVEL_INFO. For troubleshooting, set it to LOG_LEVEL_TRACE.
   [AliPlayer setLogCallbackInfo:LOG_LEVEL_INFO callbackBlock:^(AVPLogLevel logLevel, NSString *strLog) {
    NSLog(@"strLog:%@", strLog);
   }];

2. Collect logs:

   After reproducing the issue, the logs are automatically forwarded to your app's logging system.

Troubleshooting

References

• Advanced features: Learn about advanced features such as Picture-in-Picture (PiP), time shifting, and adaptive bitrate streaming.

• API reference: Explore the complete API reference for the ApsaraVideo Player SDK for iOS.

• Mobile error codes: Refer to this topic for troubleshooting.