ApsaraVideo VOD:Basic features

Configure a playback source

AVPVidAuthSource *authSource = [[AVPVidAuthSource alloc] init];
authSource.vid = @"Vid"; // Required. The video ID.
authSource.playAuth = @"<yourPlayAuth>"; // Required. The playback credential. To obtain a playback credential, call the GetVideoPlayAuth operation in ApsaraVideo VOD.
authSource.region = @"Access region"; // This parameter is deprecated in ApsaraVideo Player SDK V5.5.5.0 or later. If you use ApsaraVideo Player SDK V5.5.5.0 or later, the player automatically parses the region information. If you use ApsaraVideo Player SDK V5.5.5.0 or earlier, this parameter is required. Specify the ID of the region in which ApsaraVideo VOD is activated for this parameter. Default value: cn-shanghai.
// authSource.authTimeout = 3600; // The validity period of the playback URL. Unit: seconds. Default value: 3600. If you have configured a validity period for signed URLs in the ApsaraVideo VOD console, the configuration of this parameter takes precedence. If you leave this parameter empty, the default value 3600 is used. The validity period must be longer than the actual duration of the video. Otherwise, the playback URL expires before the playback is complete.

// If you have enabled parameter pass-through for HLS encryption in the ApsaraVideo VOD console and the default parameter name is MtsHlsUriToken, you need to set the config parameter and pass it to the VID. For more information, see the following code.
// If you have not enabled parameter pass-through for HLS encryption in the ApsaraVideo VOD console, you do not need to integrate the following code.
VidPlayerConfigGenerator* vp = [[VidPlayerConfigGenerator alloc] init];
[vp setHlsUriToken:yourMtsHlsUriToken];
authSource.playConfig = [vp generatePlayerConfig];

[self.player setAuthSource:authSource];

AVPVidStsSource *source = [[AVPVidStsSource alloc] init];
source.vid = @"Vid"; // Required. The video ID.
source.region = @"Access region"; // Required. The region in which ApsaraVideo VOD is activated. Default value: cn-shanghai.
source.securityToken = @"<yourSecurityToken>"; // Required. The STS token. To generate an STS token, call the AssumeRole operation in STS.
source.accessKeySecret = @"<yourAccessKeySecret>"; // Required. The AccessKey secret that is generated when the temporary STS token is issued. To generate the AccessKey secret, call the AssumeRole operation in STS.
source.accessKeyId = @"<yourAccessKeyId>"; // Required. The AccessKey ID that is generated when the temporary STS token is issued. To generate the AccessKey ID, call the AssumeRole operation in STS.
// source.authTimeout = 3600; // The validity period of the playback URL. Unit: seconds. Default value: 3600. If you have configured a validity period for signed URLs in the ApsaraVideo VOD console, the configuration of this parameter takes precedence. If you leave this parameter empty, the default value 3600 is used. The validity period must be longer than the actual duration of the video. Otherwise, the playback URL expires before the playback is complete.
// If you have enabled parameter pass-through for HLS encryption in the ApsaraVideo VOD console and the default parameter name is MtsHlsUriToken, you need to set the config parameter and pass it to the VID. For more information, see the following code.
// If you have not enabled parameter pass-through for HLS encryption in the ApsaraVideo VOD console, you do not need to integrate the following code.
VidPlayerConfigGenerator* vp = [[VidPlayerConfigGenerator alloc] init];
[vp setHlsUriToken:yourMtsHlsUriToken];
source.playConfig = [vp generatePlayerConfig];
// Configure the playback source.
[self.player setStsSource:source]

AVPUrlSource *urlSource = [[AVPUrlSource alloc] urlWithString:url]; // Required. The playback URL. The URL can be generated by ApsaraVideo VOD or a third-party service. You can also use the path of a local video.
[self.player setUrlSource:urlSource]; 

Control the playback

The ApsaraVideo Player SDK for iOS lets you manage media playback. For example, you can start or pause playback, or begin playback from a specific point in time.

Prepare the player

[self.player prepare];

Start the playback

[self.player start];

Start the playback from a specific point in time

// position indicates the point in time from which you want to play the video. Unit: milliseconds. Use seekMode to specify the accurate seeking mode or the inaccurate seeking mode.
// Use the accurate seeking mode.
[self.player seekToTime:position seekMode:AVP_SEEKMODE_ACCURATE];
// Use the inaccurate seeking mode.
[self.player seekToTime:position seekMode:AVP_SEEKMODE_INACCURATE];

// Set the start time (in milliseconds) for the next prepare call. This setting takes effect only for the next prepare call.
// After prepare is called, this value is automatically cleared. If you do not call this method again before the next prepare call, the video starts from the beginning.
// seekMode can be set to accurate or inaccurate mode.
[self.player setStartTime:time seekMode:seekMode];

Pause playback

[self.player pause];

Resume playback

[self.player start];

Stop playback

[self.player stop];

Destroy the player

// Synchronously destroys the player. The system automatically calls the stop operation.
[self.player destroy];
// Asynchronously destroys the player. The system automatically calls the stop operation.
[self.player destroyAsync];

Monitor player status

The ApsaraVideo Player SDK for iOS lets you configure listeners and monitor player status.

Configure listeners

@interface SimplePlayerViewController ()<AVPDelegate>
@end
- (void)viewDidLoad {
    self.player = [[AliPlayer alloc] init];
    self.player.playerView = self.avpPlayerView.playerView;
    self.player.delegate = self;
    //...
}
/**
 @brief The callback for an invalid delegate.
 @param player The pointer of the player.
 @param errorModel The description of player errors. For more information, see the definition of AliVcPlayerErrorModel.
 */
- (void)onError:(AliPlayer*)player errorModel:(AVPErrorModel *)errorModel {
    // Indicates that an error occurred and the playback stopped.
}
/**
 @brief The callback for player events.
 @param player The pointer of the player.
 @param eventType The event type of the player. For more information, see the definition of AVPEventType.
 */
-(void)onPlayerEvent:(AliPlayer*)player eventType:(AVPEventType)eventType{
    switch(eventType){
        case AVPEventPrepareDone:{
            // The player is prepared.
        }
            break;
        case AVPEventAutoPlayStart:
            // The autoplay starts.
            break;
        case AVPEventFirstRenderedStart:
            // The appearance of the first frame.
            break;
        case AVPEventCompletion:
            // The completion of playback.
            break;
        case AVPEventLoadingStart:
            // The buffering starts.
            break;
        case AVPEventLoadingEnd:
            // The buffering is complete.
            break;
        case AVPEventSeekEnd:
            // The seeking is complete.
            break;
        case AVPEventLoopingStart:
            // The start of loop playback.
            break;
        default:
            break;
    }
}
/**
 @brief The callback for the current playback position.
 @param player The pointer of the player.
 @param position The current playback position.
 */
- (void)onCurrentPositionUpdate:(AliPlayer*)player position:(int64_t)position {
    // Updates the playback progress.
}
/**
 @brief The callback for the buffer position.
 @param player The pointer of the player.
 @param position The current buffer position.
 */
- (void)onBufferedPositionUpdate:(AliPlayer*)player position:(int64_t)position {
    // Updates the buffering progress.
}
/**
 @brief The callback for obtaining the track information.
 @param player The pointer of the player.
 @param info The array of track information. For more information, see AVPTrackInfo.
 */
- (void)onTrackReady:(AliPlayer*)player info:(NSArray<AVPTrackInfo*>*)info {
    // Obtain the information about different bitrates.
}
/**
 @brief The callback to display the subtitle.
 @param player The pointer of the player.
 @param index The index number for the subtitle.
 @param subtitle The string of the subtitle.
 */
- (void)onSubtitleShow:(AliPlayer*)player index:(int)index subtitle:(NSString *)subtitle {
    // Obtain the subtitle for display.
}
/**
 @brief The callback to hide the subtitle.
 @param player The pointer of the player.
 @param index The index number for the subtitle.
 */
- (void)onSubtitleHide:(AliPlayer*)player index:(int)index {
    // Hide the subtitles.
}
/**
 @brief The callback for snapshot capture.
 @param player The pointer of the player.
 @param image The image.
 */
- (void)onCaptureScreen:(AliPlayer *)player image:(UIImage *)image {
    // Preview and save the snapshot.
}
/**
 @brief The callback that indicates that the track is switched.
 @param player The pointer of the player.
 @param info The information about the switching after the switching is complete. For more information, see AVPTrackInfo.
 */
- (void)onTrackChanged:(AliPlayer*)player info:(AVPTrackInfo*)info {
    // Send a notification about the result of switching the bitrate.
}

Monitor playback status

- (void)onPlayerStatusChanged:(AliPlayer*)player oldStatus:(AVPStatus)oldStatus newStatus:(AVPStatus)newStatus {
    switch (newStatus) {
    case AVPStatusIdle:{
           // The player is idle.
        }
 break;
        case AVPStatusInitialzed:{
           // The player is initialized.
        }
 break;
        case AVPStatusPrepared:{
           // The player is prepared.
        }
 break;
        case AVPStatusStarted:{
           // The player is playing a media stream.
        }
 break;
case AVPStatusPaused:{
           // The playback is paused.
        }
 break;
case AVPStatusStopped:{
           // The playback is stopped.
        }
 break;
case AVPStatusCompletion:{
           // The completion of playback.
        }
 break;
case AVPStatusError:{
           // A playback error occurs.
        }
 break;
        default:
            break;
    }
}

Specify the display mode

The ApsaraVideo Player SDK for iOS lets you configure display settings for playback. For example, you can specify how video images are scaled, rotated, or mirrored.

Padding

// Scale in the video to fit the view. The aspect ratio of the video is maintained.
self.player.scalingMode = AVP_SCALINGMODE_SCALEASPECTFIT;
// Scale out the video to fill the view. The aspect ratio of the video is maintained.
self.player.scalingMode = AVP_SCALINGMODE_SCALEASPECTFILL;
// Stretch the video to fill the view. The aspect ratio of the video is not maintained. If the aspect ratios of the video and the view are different, image distortion may occur.
self.player.scalingMode = AVP_SCALINGMODE_SCALETOFILL;

Rotation

// Set the rotation angle to 0° in the clockwise direction.
self.player.rotateMode = AVP_ROTATE_0;
// Set the rotation angle to 90° in the clockwise direction.
self.player.rotateMode = AVP_ROTATE_90;
// Set the rotation angle to 180° in the clockwise direction.
self.player.rotateMode = AVP_ROTATE_180;
// Set the rotation angle to 270° in the clockwise direction.
self.player.rotateMode = AVP_ROTATE_270;

Mirroring

// Specify no mirroring for the video images.
self.player.mirrorMode = AVP_MIRRORMODE_NONE;
// Specify horizontal mirroring for the video images.
self.player.mirrorMode = AVP_MIRRORMODE_HORIZONTAL;
// Specify vertical mirroring for the video images.
self.player.mirrorMode = AVP_MIRRORMODE_VERTICAL;

Obtain information about the playback

The ApsaraVideo Player SDK for iOS lets you obtain playback information, such as the current playback progress, video duration, and buffering progress.

Obtain the current playback progress

- (void)onCurrentPositionUpdate:(AliPlayer*)player position:(int64_t)position {
// The position parameter indicates the current playback position. Unit: milliseconds.
NSString *position = [NSString stringWithFormat:@"%lld, position"];
}

Obtain the video duration

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

Obtain the actual playback duration

 NSString *duration = [player getPlayedDuration];

Obtain the buffering progress

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

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

// Obtain the current frame rate for video rendering. The returned data is of the FLOAT data type.
[self.player getOption:AVP_OPTION_RENDER_FPS]
// Obtain the current video bitrate. The returned data is of the FLOAT data type. Unit: bit/s.
[self.player getOption:AVP_OPTION_VIDEO_BITRATE]
// Obtain the current audio bitrate. The returned data is of the FLOAT data type. Unit: bit/s.
[self.player getOption:AVP_OPTION_AUDIO_BITRATE]
// Obtain the current network downlink bitrate. The returned data is of the FLOAT data type. Unit: bit/s.
[self.player getOption:AVP_OPTION_DOWNLOAD_BITRATE]

Specify the volume

You can adjust the player volume or configure the mute mode for playback.

Adjust the volume

// Set the volume to a real number from 0 to 2.
self.player.volume = 1.0f;
// Obtain the volume.
self.player.volume

Configure the mute mode

self.player.muted = YES;

Set the playback speed

// Playback speeds ranging from 0.5x to 5x are supported. Common playback speeds are multiples of 0.5x, such as 0.5x, 1x, and 1.5x.
self.player.rate = 1.0f;

Multiple Resolution Settings

Configure UrlSource-based live streaming

For more information, see Standard live streaming playback.

Configure VidAuth- or VidSts-based playback

If you use VidAuth or VidSts to play on-demand videos, no additional settings are required. The ApsaraVideo Player SDK for iOS automatically retrieves video definitions from ApsaraVideo VOD. The SDK lets you retrieve video definitions and switch between them. This feature is not supported for UrlSource-based playback.

Query the definition

After the video is loaded, you can retrieve its definitions. You can retrieve the bitrates from the trackBitrate parameter nested under the info parameter in the onTrackReady callback.

- (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;
        }
    }
}

Switch Resolution

Call the selectTrack method and specify the index corresponding to the definition you want to switch to. You can obtain the index from the TrackInfo parameter.

[self.player selectTrack:index];

Resolution Switching Notifications

The onTrackChanged callback is invoked after the video definition is switched.

- (void)onTrackChanged:(AliPlayer*)player info:(AVPTrackInfo*)info {
 // Switching completed
}

Quick switching

After you enable Quick Switch mode, every manual call to selectTrack returns a quick response.

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

Enable loop playback

self.player.loop = YES;

- (void)onPlayerEvent:(AliPlayer*)player eventType:(AVPEventType)eventType {
    switch (eventType) {
        case AVPEventLoopingStart:
            break;
    }
}

Switch audio tracks

The iOS Player SDK enables you to switch audio tracks when watching videos with multilingual dubbing, so you can select your preferred dubbing language.

Examples

1. Configure callbacks.

     // The onSubTrackReady callback is typically triggered before the prepare callback.
   - (void)onSubTrackReady:(AliPlayer*)player info:(NSArray<AVPTrackInfo*>*)info {
       // Call getSubMediaInfo to proactively retrieve the corresponding MediaInfo. You can call this method only after receiving the onSubTrackReady callback; otherwise, it returns nil.
       AVPMediaInfo* subMediaInfo = [player getSubMediaInfo];
       // Traverse the tracks.
       for (int i=0; i<subMediaInfo.tracks.count; i++) {
       	AVPTrackInfo* track = [mediaInfo.tracks objectAtIndex:i];
           // Retrieve the corresponding track.
       }
   }

2. Switch to the desired audio track.

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

Thumbnail Usage

Before you use the thumbnail feature in the ApsaraVideo Player SDK, ensure that thumbnails are configured for the video. To generate thumbnails, go to the ApsaraVideo VOD console, create a snapshot template, and select Image Sprite as Snapshot Type. Create a workflow to process the video based on the snapshot template. Then, the sprite snapshot is created for the video. For more information, see Video snapshots. The following sample code provides an example on how to use the thumbnail feature in the ApsaraVideo Player SDK:

/**
 Specifies whether a thumbnail is configured for the track. No thumbnail is displayed if you do not configure a thumbnail.
 */
@property (nonatomic,assign)BOOL trackHasThumbnai;

/**
 Create a custom view that displays thumbnails.
 */
@property (nonatomic,strong)UIImageView *thumbnaiView;

/**
  onPrepare
 */
- (void)onPlayerStatusChanged:(AliPlayer*)player oldStatus:(AVPStatus)oldStatus newStatus:(AVPStatus)newStatus {
  if(newStatus == AVPStatusPrepared){
       [self.player setThumbnailUrl:[URL];// Specify a thumbnail URL. You can obtain the thumbnail URL in the ApsaraVideo VOD console or by calling API operations.
       self.trackHasThumbnai = YES;
  }
}
/**
 The callback for changing the playback position on the progress bar.
 @param playerView playerView
 @param value: The playback position.
 */
- (void)AVPPlayerView:(AVPPlayerView *)playerView progressSliderValueChanged:(CGFloat)value {
    if (self.trackHasThumbnai) {
        [self.player getThumbnail:self.player.duration*value];
    }
}

/**
 @brief: The callback that is returned when the thumbnail is obtained.
 @param positionMs: The specified thumbnail position.
 @param fromPos: The playback position from which the thumbnail is used.
 @param toPos: The playback position at which the thumbnail is no longer used.
 @param image: The pointer for the thumbnail image. NSImage is used for macOS and UIImage is used for iOS.
 */
- (void)onGetThumbnailSuc:(int64_t)positionMs fromPos:(int64_t)fromPos toPos:(int64_t)toPos image:(id)image {
    self.thumbnaiView.hidden = NO;
    [self.thumbnaiView setImage:(UIImage *)image];
}

/**
 @brief: The callback that is returned when the thumbnail fails to be obtained.
 @param positionMs: The specified thumbnail position.
 */
- (void)onGetThumbnailFailed:(int64_t)positionMs {
    self.thumbnaiView.hidden = YES;
}

Obtain SDK logs

SDK logs are generated when you use the ApsaraVideo Player SDK. The logs contain detailed information such as request status, invocation results, and permission application results. You can debug code and troubleshoot problems by viewing the SDK logs to facilitate development. You can use one of the following methods to obtain SDK logs.

Method 1: Use the console of your development tool

This method captures logs on your local device. It is suitable for scenarios where you can reliably reproduce the error on your device.

1. Enable the logging feature and set the log level.

   // Enable the logging feature.
   [AliPlayer setEnableLog:YES];
   // Set the log level. Default value: LOG_LEVEL_INFO. To troubleshoot problems, set this parameter to LOG_LEVEL_TRACE.
   [AliPlayer setLogCallbackInfo:LOG_LEVEL_INFO callbackBlock:nil];

2. Configure frame-level logs.

   // Configure frame-level log printing.
   // Valid values of the value parameter: 0 and 1. A value of 0 indicates disabled. A value of 1 indicates enabled.
   [AliPlayer setLogOption:FRAME_LEVEL_LOGGING_ENABLED value:value];

   Note

   This feature is used in troubleshooting scenarios.

3. Collect logs.

   1. Method 1: View logs in the console of your development tool

      Reproduce the error and obtain the error log in the console of your development tool such as Xcode.

   2. Method 2: Export logs to a specific path

      1. After you enable the logging feature, specify a sandbox path in which error logs are stored before you create a player instance.

         NSArray *paths =NSSearchPathForDirectoriesInDomains(NSDocumentDirectory,NSUserDomainMask, YES);
         NSString *documentDirectory = [paths objectAtIndex:0];
         // logFilePath is a sample path. You can also create a .log file in the sandbox directory. For example, xxxx.log.
         NSString *logFilePath = [documentDirectory stringByAppendingPathComponent:@"xxxx.log"];

      2. Import the log data to the file that you specify.

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

      3. Reproduce the error and find the .log file in the path that you specified.

Method 2: Set LogCallback to receive ApsaraVideo Player SDK logs

This method uses the LogCallback method. It is suitable for scenarios where the error occurs on the client side but you cannot reliably reproduce the error and capture logs on your device. Call LogCallback to listen to the log export of the ApsaraVideo Player SDK and automatically export error logs to the log channel of your application.

1. Enable the logging feature and set the log level.

   // Enable the logging feature.
   [AliPlayer setEnableLog:YES];
   // Set the log level. Default value: LOG_LEVEL_INFO. To troubleshoot problems, set this parameter to LOG_LEVEL_TRACE.
   [AliPlayer setLogCallbackInfo:LOG_LEVEL_INFO callbackBlock:^(AVPLogLevel logLevel, NSString *strLog) {
    NSLog(@"strLog:%@", strLog);
   }];

2. Collect logs.

   After you reproduce the issue, logs are automatically output through your app's log channel to its log file.