ApsaraVideo VOD:Advanced features

Configure playback

Enable list playback for short videos

ApsaraVideo Player SDK for iOS provides a full-fledged list playback feature for short videos. The SDK uses features such as preloading to minimize the startup time of short videos. We recommend that you do not enable this feature for long videos.

Play videos that have transparency configurations

Description

ApsaraVideo Player SDK supports rendering of videos with alpha channels to play dynamic gift videos with a transparent background. This way, you can view the dynamic effects of gifts without blocking the live video content when someone is streaming. This significantly improves the viewing and interactive experience.

Limits

You can use ApsaraVideo MediaBox SDK V6.8.0 or later and ApsaraVideo Player SDK V6.9.0 or later to render videos with transparency.

Benefits

You can use MP4 videos with transparency as gift effects. This improves the performance of dynamic effects and video compatibility, reduces the video size, and simplifies development. This also optimizes the viewing experience of the gift effects and improves user experience. Using MP4 videos with transparency as gift effects has the following benefits:

1. Higher video quality: You can use MP4 videos to display the dynamic gift effects in the original quality, such as the original image details and colors. Compared with other video formats such as APN or IXD, MP4 can display the dynamic effect in the original quality intended by the designers.

2. Smaller video size: Compared with other video formats such as APNG or IXD, MP4 reduces file sizes in a more efficient way. This accelerates loading and reduces the consumption of network bandwidth.

3. Better compatibility: MP4 is a general video format that is widely supported on various devices and browsers. You can play MP4 videos that are used as gift effects on mainstream devices.

4. Higher development efficiency: The solution of using MP4 videos as gift effects requires simple development. Instead of studying and developing complex parsing and rendering logic, developers can focus on the implementation of other features to improve development efficiency.

/**
 @brief The rendering mode of the alpha channel. You can place the alpha channel at the top, bottom, left side, or right side of the video material. By default, the value is set to None.
 @see AVPAlphaRenderMode
 */
/****
 @brief Set a rendering mode. Support alpha at right, left, top and bottom. Default value is none.
 @see AVPAlphaRenderMode
 */
@property(nonatomic) AVPAlphaRenderMode alphaRenderMode;

//--------------Configure the view-------------
// Specify clearColor for the view.
@property (weak, nonatomic) IBOutlet UIView *mediaPlayerView;
[self.aliplayerview setBackgroundColor:UIColor.clearColor];

//-----------Configure AliPlayer-----------
// Set the alpha mode.
[self.aliplayer setAlphaRenderMode:AVP_RENDERMODE_ALPHA_AT_LEFT];
// Specify the material that corresponds to the alpha mode.
AVPUrlSource *source = [[AVPUrlSource alloc] urlWithString:@"https://alivc-player.oss-cn-shanghai.aliyuncs.com/video/%E4%B8%9A%E5%8A%A1%E9%9C%80%E6%B1%82%E6%A0%B7%E6%9C%AC/alpha%E9%80%9A%E9%81%93/alpha_left.mp4"];
[self.aliplayer setUrlSource:source];

// Optional. If a connection error occurs when the playback of videos in a player instance is complete, you can clear the view.
#pragma mark -- AVPDelegate
- (void)onPlayerEvent:(AliPlayer *)player eventType:(AVPEventType)eventType {
    switch (eventType) {
        case AVPEventCompletion:
        {
            [player clearScreen];
        }
            break;
        //...
    }
}

[self.aliplayer setAutoPlay: YES];
[self.aliplayer prepare];

/**
 @ brief The video rendering type. 0 specifies the default renderer and 1 specifies the mixed renderer. Default value: 0.
 */
/****
 @brief video renderType, 0 means default render; 1 means mixed render.
 */
@property(nonatomic, assign) int videoRenderType;

AVPConfig *config = [self.player getConfig];
// Use the Metal framework to render videos.
config.videoRenderType = 1;
[self.player setConfig:config];
[self.player prepare];

Configure external subtitles

ApsaraVideo Player SDK for iOS allows you to add, turn on, and turn off external subtitles that are in the SubRip Subtitle (SRT) format, SubStation Alpha (SSA) format, Advanced SubStation Alpha (ASS) format, or Web Video Text Track (WebVTT) format. Sample code:

1. Create a view that displays the subtitles.

   You must create different views for subtitles in different formats.

   // Initialize the custom subTitleLabel view.
   UILabel *subTitleLabel = [[UILabel alloc] initWithFrame:frame];
   // Add the subTitleLabel view to a custom superView, which is the parent view of the custom user interface.
   [superView addSubview:subTitleLabel];

2. Configure listeners for subtitles.

   // The callback is invoked when an external subtitle is added.
   - (void)onSubtitleExtAdded:(AliPlayer*)player trackIndex:(int)trackIndex URL:(NSString *)URL {}
   // The callback is invoked when the subtitle header information is obtained.
   - (void)onSubtitleHeader:(AliPlayer *)player trackIndex:(int)trackIndex Header:(NSString *)header{}
   // The callback is invoked when the subtitle is displayed.
   - (void)onSubtitleShow:(AliPlayer*)player trackIndex:(int)trackIndex subtitleID:(long)subtitleID subtitle:(NSString *)subtitle {
    subTitleLabel.text =subtitle;
    subTitleLabel.tag =subtitleID;
   }
   // The callback is invoked when the subtitle is hid.
   - (void)onSubtitleHide:(AliPlayer*)player trackIndex:(int)trackIndex subtitleID:(long)subtitleID{
     [subTitleLabel removeFromSuperview];
   }

3. Add subtitles.

   [self.player addExtSubtitle:URL];

4. Switch subtitles.

   [self.player selectExtSubtitle:trackIndexenable:YES];

Enable audio-only playback

AVPConfig *config = [self.player getConfig];
config.disableVideo = YES;
[self.player setConfig:config];

Switch between hardware decoding and software decoding

// Enable hardware decoding. By default, hardware decoding is enabled.
self.player.enableHardwareDecoder = YES;

-(void)onPlayerEvent:(AliPlayer*)player eventWithString:(AVPEventWithString)eventWithString description:(NSString *)description {
    if (eventWithString == EVENT_SWITCH_TO_SOFTWARE_DECODER) {
        // Switch to software decoding.
    }
}

H.265 adaptive playback

// Create a map on the application layer to store the primary stream URLs and secondary stream URLs as key-value pairs. The system queries the corresponding secondary URL based on the primary stream URL during switching.
NSString* getBackupUrlCallback(AVPBizScene scene, AVPCodecType codecType, NSString* oriurl){
    NSMutableDictionary *globalMap = [AliPlayerViewController getGlobalBackupUrlMap];
    NSString *backupUrl = globalMap[oriurl];
    return backupUrl; 
}

[AliPlayerGlobalSettings setAdaptiveDecoderGetBackupURLCallback:getBackupUrlCallback];

Adaptive bitrate streaming

AVPMediaInfo *info = [self.player getMediaInfo];
NSArray<AVPTrackInfo*>* tracks = info.tracks;

// Switch to the required bitrate.
[self.player selectTrack:track.trackIndex];
// Enable adaptive bitrate streaming.
[self.player selectTrack:SELECT_AVPTRACK_TYPE_VIDEO_AUTO];

- (void)onTrackChanged:(AliPlayer*)player info:(AVPTrackInfo*)info {
    if (info.trackType == AVPTRACK_TYPE_VIDEO) {
        // video changed
    }
    // etc
}

Manage snapshot jobs

// Configure the callback for snapshot capture.
- (void)onCaptureScreen:(AliPlayer *)player image:(UIImage *)image {
    // Process the snapshot.
}
// Capture a snapshot of the current video image.
aliyunVodPlayer.snapshot();

Configure video preview

ApsaraVideo Player SDK for iOS integrates specific configurations of ApsaraVideo VOD to support previews of videos. Only VidSts sources and VidAuth sources can be previewed. We recommend that you preview only VidAuth sources in ApsaraVideo VOD. For more information about how to configure and use the preview feature, see Configure the preview feature.

AVPVidStsSource *source = [[AVPVidStsSource alloc] init];
....
VidPlayerConfigGenerator* vp = [[VidPlayerConfigGenerator alloc] init];
[vp setPreviewTime:20];// Set the preview duration to 20s.
source.playConfig = [vp generatePlayerConfig];// Configure the settings for the player.
...

Set the referer

// Obtain the configuration information.
AVPConfig *config = [self.player getConfig];
// Set the referer.
config.referer = referer;
....// Configure other settings.
// Configure the settings for the player.
[self.player setConfig:config];

Specify the User-Agent

// Obtain the configuration information.
AVPConfig *config = [self.player getConfig];
// Specify the User-Agent header.
config.userAgent = userAgent;
....// Configure other settings.
// Configure the settings for the player.
[self.player setConfig:config];

Specify the network timeout period and number of retries

// Obtain the configuration information.
AVPConfig *config = [self.player getConfig];
// Set the network timeout period. Unit: milliseconds.
config.networkTimeout = 5000;
// Specify the maximum number of retries that can be performed after a network timeout occurs. The retry interval is equal to the timeout period that is specified for the NetworkTimeout parameter. The NetworkRetryCount parameter specifies the number of retries. A value of 0 indicates no retry. The application determines the number of retries. Default value: 2.
config.networkRetryCount = 2;
....// Configure other settings.
// Configure the settings for the player.
[self.player setConfig:config];

Control the buffer and latency.

// Query the configuration information.
AVPConfig *config = [self.player getConfig];
// Specify the maximum latency. Note: This parameter is valid only for live streaming. If the latency exceeds the maximum limit, ApsaraVideo Player SDK synchronizes frames to ensure that the latency does not exceed the limit. 
config.maxDelayTime = 5000;
// Specify the maximum buffer duration. Unit: milliseconds. This parameter specifies the maximum buffer duration for the player to load data at a time. 
config.maxBufferDuration = 50000;
// Specify the peak buffer duration. Unit: milliseconds. This parameter specifies the peak buffer duration. After the peak buffer duration elapses, the player stops loading data if the network conditions are poor. 
config.highBufferDuration = 3000;
// Set the startup buffer duration Unit: milliseconds. A smaller value indicates a shorter startup loading duration. In this case, the player may enter the loading status soon after the playback starts. 
config.startBufferDuration = 500;
// Configure other settings.
// Configure the settings for the player.
[self.player setConfig:config];

Configure HTTP headers

// Obtain the configuration information.
AVPConfig *config = [self.player getConfig];
// Define a header.
NSMutableArray *httpHeaders = [[NSMutableArray alloc] init];
// Configure a host when you use Alibaba Cloud HTTPDNS. 
[httpHeaders addObject:@"Host:example.com"];
// Configure the headers.
config.httpHeaders = httpHeaders;
....// Configure other settings.
// Configure the settings for the player.
[self.player setConfig:config];

Configure PiP

Enable the PiP feature

- (void)onPlayerEvent:(AliPlayer *)player eventType:(AVPEventType)eventType {
    switch (eventType) {
        case AVPEventPrepareDone:
        {
            [self.player setPictureInPictureEnable:YES];
        }
            break;
        default:
            break;
    }
}

Set the PiP delegate

The following sample code provides an example on how to pause, play, fast forward, fast backward, and replay videos in PiP mode and the interactions between the floating window and the player view. For more information about how to configure the PiP delegate, see the header file AliPlayerPictureInPictureDelegate.h of AliyunPlayer.framework in the directory of the demo for ApsaraVideo Player SDK for iOS. For more information about how to download the demo, see SDK overview and download.

1. Set up the PiP delegate to receive event callbacks.

   [self.player setPictureinPictureDelegate:self];

2. Configure the PiP delegate.

   1. Add a global variable to manage the status change of the player.

      // Listen for the PiP pause event.
      @property (nonatomic, assign) BOOL isPipPaused;
      // Listen for newStatus to determine whether the playback status of the player is changed.
      @property (nonatomic, assign) AVPStatus currentPlayerStatus;
      // Configure the PiP controller in the callback that indicates the PiP feature is enabled. Set the controller to nil before you end the playback in PiP mode. We recommend that you configure the PiP controller.
      @property (nonatomic, weak) AVPictureInPictureController *pipController;
      // Listen for the playback progress event. Set currentPosition to the position that is returned in the callback of the current playback progress.
      @property(nonatomic, assign) int64_t currentPosition;

      Note

      You must use the weak or assign modifier for pipController. If you use the assign modifier, make sure that you set the correct variables to null.

   2. Update the status of the PiP controller when you listen for the onPlayerStatusChanged event.

      - (void)onPlayerStatusChanged:(AliPlayer*)player oldStatus:(AVPStatus)oldStatus newStatus:(AVPStatus)newStatus {
          self.currentPlayerStatus = newStatus;
      
        if (_pipController) {
           [self.pipController invalidatePlaybackState];
         }
      }

   3. Update the status of the PiP controller when you listen for the onPlayerEvent event.

      - (void)onPlayerEvent:(AliPlayer*)player eventType:(AVPEventType)eventType {
          if (eventType == AVPEventCompletion) {
            if (_pipController) {
             self.isPipPaused = YES; // Pause the playback in PiP mode after the playback ends.
             [self.pipController invalidatePlaybackState];
          }
        } else if (eventType == AVPEventSeekEnd) {
          // The seeking is complete.
            if (_pipController) {
             [self.pipController invalidatePlaybackState];
          }
        }
      }

   4. Configure listeners.

      • Listen to the callback returned when the playback in PiP mode is about to start.

        /**
         @ brief The callback returned when the playback in PiP mode starts.
         @param pictureInPictureController indicates the PiP controller.
         */
        - (void)pictureInPictureControllerWillStartPictureInPicture:(AVPictureInPictureController *)pictureInPictureController {
            if (!_pipController) {
             self.pipController = pictureInPictureController;
          }
            self.isPipPaused = !(self.currentPlayerStatus == AVPStatusStarted);
          [pictureInPictureController invalidatePlaybackState];
        }

      • Listen to the callback returned when the playback in PiP mode is about to stop.

        /**
         @ brief The callback returned when the playback in PiP mode is about to stop.
         @param pictureInPictureController indicates the PiP controller.
         */
        - (void)pictureInPictureControllerWillStopPictureInPicture:(AVPictureInPictureController *)pictureInPictureController {
            self.isPipPaused = NO;
          [pictureInPictureController invalidatePlaybackState];
        }

      • Listen to the callback returned after the playback in PiP mode stops and use the delegate to enable the player UI.

        /**
         @ brief The callback returned after the playback in PiP mode stops.
         @param pictureInPictureController indicates the PiP controller.
         @ param Set completionHandler to YES to stop playback in PiP mode and enable the player UI.
         */
        - (void)pictureInPictureController:(AVPictureInPictureController *)pictureInPictureController restoreUserInterfaceForPictureInPictureStopWithCompletionHandler:(void (^)(BOOL restored))completionHandler {
            if (_pipController) {
              _pipController = nil;
          }
          completionHandler(YES);
        }

      • Listen to the callback of the duration limits of videos that can be played in PiP mode.

        /**
         @ brief The callback of the duration limits of videos that can be played in PiP mode.
         @param pictureInPictureController indicates the PiP controller.
         @ return The duration limits of videos that can be played in PiP mode.
         */
         - (CMTimeRange)pictureInPictureControllerTimeRangeForPlayback:(nonnull AVPictureInPictureController *)pictureInPictureController layerTime:(CMTime)layerTime{
            Float64 current64 = CMTimeGetSeconds(layerTime);
        
            Float64 start;
            Float64 end;
        
            if (currentPosition <= self.player.duration) {
                double curPostion = self.currentPosition / 1000.0;
                double duration = self.player.duration / 1000.0;
                double interval = duration - curPostion;
                start = current64 - curPostion;
                end = current64 + interval;
                CMTime t1 = CMTimeMakeWithSeconds(start, layerTime.timescale);
                CMTime t2 = CMTimeMakeWithSeconds(end, layerTime.timescale);
                return CMTimeRangeFromTimeToTime(t1, t2);
            } else {
                return CMTimeRangeMake(kCMTimeNegativeInfinity, kCMTimePositiveInfinity);
            }
        }

      • Listen to the callback returned when the status of playback in PiP mode is changed.

        /**
         @ brief The callback returned when the status of playback in PiP mode is changed. The UI changes when the playback status changes.
         @param pictureInPictureController indicates the PiP controller.
         @ return The playback status in PiP mode.
         */
        - (BOOL)pictureInPictureControllerIsPlaybackPaused:(nonnull AVPictureInPictureController *)pictureInPictureController{
            return self.isPipPaused;
        }

        Note

        This callback is invoked before a video enters the PiP mode. The video enters the PiP mode only when false is returned in the callback.

      • Listen to the callback returned when a fast forward or fast backward operation is performed during playback in PiP mode and synchronize the playback progress to the player.

        /**
         @ brief The callback returned when a fast forward or fast backward operation is performed during playback in PiP mode.
         @param pictureInPictureController indicates the PiP controller.
         @ param skipInterval indicates the interval by which the video is skipped forward or backward.
         @ param Call completionHandler to end the fast forward or fast backward operation.
         */
         - (void)pictureInPictureController:(nonnull AVPictureInPictureController *)pictureInPictureController skipByInterval:(CMTime)skipInterval completionHandler:(nonnull void (^)(void))completionHandler {
            int64_t skipTime = skipInterval.value / skipInterval.timescale;
            int64_t skipPosition = self.currentPosition + skipTime * 1000;
            if (skipPosition < 0) {
                skipPosition = 0;
            } else if (skipPosition > self.player.duration) {
                skipPosition = self.player.duration;
            }
            [self.player seekToTime:skipPosition seekMode:AVP_SEEKMODE_INACCURATE];
            [pictureInPictureController invalidatePlaybackState];
        }

      • Listen to the callback returned when the playback in PiP mode is paused or started.

        /**
         @ brief The callback that is returned when the playback in PiP mode is paused or started.
         @param pictureInPictureController indicates the PiP controller.
         @ param playing indicates whether the video is being played in PiP mode.
         */
        - (void)pictureInPictureController:(nonnull AVPictureInPictureController *)pictureInPictureController setPlaying:(BOOL)playing {
            if (!playing){
              [self.player pause];
              self.isPipPaused = YES;
            } else {
              // If you want to replay a video after the playback ends, run the following code that starts with if.
              if (self.currentPlayerStatus == AVPStatusCompletion) {
                 [self.player seekToTime:0 seekMode:AVP_SEEKMODE_ACCURATE];
              }
        
              [self.player start];
              self.isPipPaused = NO;
          }
          [pictureInPictureController invalidatePlaybackState];
        }

Configure an alternative RTS URL

// Specify downgradeUrl.
AVPUrlSource *urlSource = [[AVPUrlSource alloc] urlWithString:downgradeUrl];
// Optional. Configure playback degradation.
AVPConfig *config = [self.player getConfig];
// Specify an alternative RTS URL.
[self.player enableDowngrade:urlSource config:config];

Enable RTS playback degradation

// 1 indicates that the RTS playback degradation feature is enabled and 0 indicates that the RTS playback degradation feature is disabled. Hardware decoding is enabled by default.
[AliPlayerGlobalSettings setOption:ALLOW_PRE_RENDER valueInt:1];

// Specify AVPOutputAudioChannel to switch the audio channel. Default value: AVP_AUDIO_CHANNEL_NONE.
// Specify AVP_AUDIO_CHANNEL_NONE to use the audio channel settings of the input file.
// Specify AVP_AUDIO_CHANNEL_LEFT to use the left audio channel for playback.
// Specify AVP_AUDIO_CHANNEL_RIGHT to use the right audio channel for playback.
self.aliplayer.outputAudioChannel = AVP_AUDIO_CHANNEL_NONE;

/**
 @ brief Set the background color of the video.
 @param color  the color
 */
/****
 @brief Set video background color
 @param color  the color
 */
-(void) setVideoBackgroundColor:(UIColor *)color;

// The value must be an 8-bit hexadecimal string, in which every 2 characters indicate a factor in the following sequence: R (red), G (green), B (blue), and A (alpha transparency).
// For example, 0x00ff00ff indicates green.
[aliPlayer setVideoBackgroundColor:0x00ff00ff]

/**
 @brief Play videos based on the VID and playAuth. For more information, visit https://www.alibabacloud.com/help/en/vod/user-guide/use-playback-credentials-to-play-videos.
 @param source The playback source type is AVPVidAuthSource.
 @see AVPVidAuthSource
 */
- (void)setAuthSource:(AVPVidAuthSource*)source;

VidPlayerConfigGenerator* gen = [[VidPlayerConfigGenerator alloc]init];
// Specify the playDomain parameter. For more information, visit https://www.alibabacloud.com/help/en/vod/developer-reference/api-vod-2017-03-21-getplayinfo.
//https://www.alibabacloud.com/help/zh/vod/developer-reference/api-vod-2017-03-21-getplayinfo
[gen addVidPlayerConfigByStringValue:@"playDomain" value: @"com.xxx.xxx"];
[source setPlayConfig:[gen generatePlayerConfig]];
[self.player setAuthSource:source]:

// 1 indicates that backend decoding is enabled and 0 indicates that backend decoding is not enabled. Default value: 0.
[self.player setOption:ALLOW_DECODE_BACKGROUND valueInt:1];

Performance

Configure pre-rendering

[player setOption:ALLOW_PRE_RENDER valueInt:1];

Configure local caching

ApsaraVideo Player SDK for iOS allows you to cache videos during playback. This reduces the startup time, accelerates the seeking process, reduces the playback latency, and saves your traffic during loop playback.

Enable local caching

/**
 * Enable local caching. After this feature is enabled, a media file is cached on your device. 
 * @param enable: specifies whether to enable the video preload feature. Valid values: true and false. true indicates that the local caching feature is enabled and false indicates that the local caching feature is disabled. Default value: false. 
 * @param maxBufferMemoryKB: This parameter is deprecated in V5.4.7.1 and later. 
 * @param localCacheDir: Required. The directory of the cached file, which is an absolute path. 
 */
[AliPlayerGlobalSettings enableLocalCache:true maxBufferMemoryKB:1024 localCacheDir:@""];

/**
 @brief Configure settings for clearing cached files. 
 @ param expireMin: This parameter is deprecated in V5.4.7.1 and later. 
 @param maxCapacityMB: the maximum cache size. Unit: MB. By default, the maximum size of cached data is 20 GB. If the specified maximum size is exceeded, the system deletes cached files based on the point in time when the file is cached until the size of the cached data is less than or equal to the specified maximum size. During this process, the system preferentially deletes the earliest files that are cached. 
 @param freeStorageMB: the minimum idle space of the disk. Unit: MB. Default value: 0. If the idle space of the disk is less than the specified minimum space, the system deletes cached files based on the point in time when the file is cached until the idle space of the disk is greater than or equal to the specified minimum space. During this process, the system preferentially deletes the earliest files that are cached. 
 */
[AliPlayerGlobalSettings setCacheFileClearConfig:0 maxCapacityMB:0 freeStorageMB:0];

/**
 * Obtain the callback for the URL hash value of the video file and use it as the unique ID of the URL. 
 */

// You must run the function and set the function pointer to setCacheUrlHashCallback.
static NSString *CaheUrlHashHandle(NSString *url) {
    return @"xxx";
}

[AliPlayerGlobalSettings setCacheUrlHashCallback:&CaheUrlHashHandle];

Enable or disable local caching for a single URL

// Obtain the configuration information.
AVPConfig *config = [self.player getConfig];
// Configure whether to enable local caching for the playback URL. Default value: true. When local caching is enabled in AliPlayerGlobalSettings and the value of this parameter is true, the local caching for the URL takes effect. If the value of this parameter is false, the local caching for the URL is disabled. 
config.enableLocalCache = false;
....// Configure other settings.

// Configure the settings for the player.
[self.player setConfig:config];

[AliPlayerGlobalSettings enableLocalCache:true];

Configure large cache

You can set the maximum buffer duration to cache video data in the memory during playback, which improves the playback performance and experience. If the maximum buffer duration is set too large, the buffer consumes excessive memory. You can use the large cache feature to cache video in files, which reduces memory usage and further improves player performance.

When mMaxBufferDuration is greater than 50,000 ms, you can enable local caching to automatically trigger large cache. Perform the following steps:

1. Enable the global local caching feature.

   By default, the video preload feature is disabled. To use this feature, you must enable it. You can call enableLocalCache in the AliPlayerGlobalSettings class to enable local caching. For more information about the sample code, see the Enable local caching section of the Advanced features topic.

2. Enable local caching for a URL.

   For more information about the sample code, see Enable or disable local caching for a single URL in Configure local caching.

3. Enable large cache. Sample code:

   [AliPlayerGlobalSettings enableBufferToLocalCache:true];

Configure video preload

ApsaraVideo Player SDK for iOS supports video preload, which is an upgrade of the local caching feature. The video preload feature allows you to specify the maximum size of memory that can be occupied by cached videos. This helps reduce the startup duration.

[AliPlayerGlobalSettings enableNetworkBalance:false];

1. Enable the local caching feature. For more information, see the Configure local caching section of this topic.

2. Obtain an AliMediaLoader instance.

   The AliMediaLoader instance is a singleton object. You can create only one AliMediaLoader instance regardless of the number of times for which you obtain the instance.

   [AliMediaLoader shareInstance];

3. Configure the AliMediaLoader instance.

   Note

   If you call prepare in player and mediaLoader.load at the same time, an Application Not Responding (ANR) error may occur. This is because the system must traverse all local files for both operations. We recommend that you start loading after the onPrepared callback is fired in player.

   // Configure listeners and start to load video files. 
   // url: the URL of the video file.  duration: the loading duration. Unit: milliseconds. 
   [[AliMediaLoader shareInstance] load:obj.url duration:1000];
   // Configure a callback delegate.
   [[AliMediaLoader shareInstance] setAliMediaLoaderStatusDelegate:self];
   
   @protocol AliMediaLoaderStatusDelegate <NSObject>
   @optional
   
   /**
    @brief The callback that is invoked when an error occurs.
    @ param url The URL.
    @param code The error code.
    @ param msg The error description.
    */
   - (void)onError:(NSString *)url code:(int64_t)code msg:(NSString *)msg;
   
   /**
    @ brief The callback that is invoked when the loading is complete.
    @ param url The URL.
    */
   - (void)onCompleted:(NSString *)url;
   
   /**
    @ brief The callback that is invoked when the loading is canceled.
    @ param url The URL.
    */
   - (void)onCanceled:(NSString *)url;
   
   @end

4. Optional: Delete the loaded video files.

   You can delete the loaded video files to reduce occupied space. ApsaraVideo Player SDK for iOS does not provide a method to delete the loaded video files. You must delete the video files in the corresponding directory in your application.

Dynamic preloading

The dynamic preloading feature allows you to manage cache of the video that is being played and videos that are preloaded. You can also control the number of videos that can be preloaded. This helps maintain a balance between playback experience and cost.

// Enable the dynamic preloading feature and use the default configurations.
[self.listPlayer setScene:AVP_SHORT_VIDEO];

// Configure the baseline preload duration.
// Set the preload duration to 1,000 milliseconds.
AVPPreloadConfig *config = [[AVPPreloadConfig alloc] init];
config.preloadDuration = 1000;
[self.listPlayer updatePreloadConfig:config];

Configure the number of videos that can be preloaded. Forward and backward are supported.
// 1 specifies the number of videos that can be preloaded forwards and 3 specifies the number of videos that can be preloaded backwards.
[self.listPlayer setPreloadCount:1 nextCount:3];

// Configure the decreasing offset for dynamic preloading.
[self.listPlayer enableStrategy:AVP_STRATEGY_DYNAMIC_PRELOAD enable:true];
[self.listPlayer setStrategyParam:AVP_STRATEGY_DYNAMIC_PRELOAD strategyParam:@"{\"algorithm\": \"sub\",\"offset\": \"200\"}"];

typedef enum AVPMultiBitratesMode : NSUInteger {
    /**
     * The default bitrate for playback and preloading.
     */
    /****
     * default mode, play and preload default bitrate of a stream
     */
    AVPMultiBitratesMode_Default = 0,
    /**
     * The preloading mode in which the first frame performance has a higher priority. In this case, the preloaded video is played by default.
     */
    /****
     * First frame cost (FC) priority, decrease first frame cost. only play bitrate of the hls stream which has been preloaded.
     */
    AVPMultiBitratesMode_FCPrio = 1,
    /**
     * The preloading mode in which the first frame performance and playback smoothness have the same priority. In this case, the same bitrate is used before and after you call the moveToNext method to switch videos.
     */
    /****
     * First frame and play smooth, play the same bitrate before and after moveToNext
     */
    AVPMultiBitratesMode_FC_AND_SMOOTH = 2,
    /**
     * The preloading mode in which the playback smoothness has a higher priority. In this case, the bitrate of the last video is used by default.
     */
    /****
     * Play Smooth priority, play the same bitrate before and after moveToNext.
     */
    AVPMultiBitratesMode_SmoothPrio = 3,
} AVPMultiBitratesMode;

// Specify the multi-bitrate preloading mode.
[self.listPlayer->SetMultiBitratesMode(preLoadMode)];

// Optional. Set the starting bitrate.
[self.listPlayer setDefaultBandWidth:defaultBandWidth];

// Optional. In the onPrepared callback, specify the abr mode.
-(void)onPlayerEvent:(AliPlayer*)player eventType:(AVPEventType)eventType {
    switch (eventType) {
        case AVPEventPrepareDone: {
            [self.listPlayer selectTrack:-1];
        }
            break;
        case AVPEventFirstRenderedStart: {
        }
            break;
        default:
            break;
    }
}

Query the download speed

- (void)onCurrentDownloadSpeed:(AliPlayer *)player speed:(int64_t)speed{
  intspeed_=speed;
}

Configure the network

// Enable the enhanced HTTPDNS feature.
[AliPlayerGlobalSettings enableEnhancedHttpDns:YES];
// Optional. Add an HTTPDNS pre-resolved domain name.
[[AliDomainProcessor shareInstance] addPreResolveDomain:@"player.***alicdn.com"];

[AliPlayerGlobalSettings setUseHttp2:true];

// Specify the domain parameter in the host[:port] format. Separate multiple domain names with semicolons (;). The port parameter is optional.
// Specify global settings.
// Add or delete TCP connections. If you specify an empty string, no TCP connections are created.
[AliPlayerGlobalSettings setOption:SET_PRE_CONNECT_DOMAIN value: @"domain1;domain2"];

Configure video download

ApsaraVideo Player SDK for iOS allows you to download videos to local devices for offline playback. The normal download and secure download modes are supported.

• Normal download: Videos that are downloaded in normal download mode are not encrypted by Alibaba Cloud and can be played by third-party players.

• Secure download: Videos that are downloaded in secure download mode are encrypted by Alibaba Cloud. You cannot use third-party players to play the downloaded videos. You can use only ApsaraVideo Player to play them.

Usage notes

• You can only download videos that are played based on VidSts or VidAuth.

• To use the video download feature, you must enable the feature and configure the download mode in the ApsaraVideo VOD console. For more information, see Configure download settings.

• Resumable download is supported.

Procedure

1. (Optional) Configure the security file for encryption verification. You must configure the security file only when you use the secure download mode.

   Note

   Make sure that the information in the security file for encryption verification matches the application information. Otherwise, the video download fails.

   If you use the secure download mode, you must configure the key file generated in the ApsaraVideo VOD console in ApsaraVideo Player SDK. The key file is used to decrypt and verify the video for download and playback. For more information about how to generate the key file, see Secure download.

   We recommend that you configure the key file only once. Sample code:

   NSString *encrptyFilePath = [[NSBundle mainBundle] pathForResource:@"encryptedApp" ofType:@"dat"];
   [AliPrivateService initKey:encrptyFilePath];

2. Create and set a video downloader.

   Sample code:

   AliMediaDownloader *downloader = [[AliMediaDownloader alloc] init];
   [downloader setSaveDirectory:self.downLoadPath];
   [downloader setDelegate:self];

3. Configure listeners.

   The download object provides multiple listeners. Sample code:

   -(void)onPrepared:(AliMediaDownloader *)downloader mediaInfo:(AVPMediaInfo *)info {
       // The listener for the preparation of the content to be downloaded.
   }
   -(void)onError:(AliMediaDownloader *)downloader errorModel:(AVPErrorModel *)errorModel {
       // The listener for a download error.
   }
   -(void)onDownloadingProgress:(AliMediaDownloader *)downloader percentage:(int)percent {
       // The listener for the download progress in percentage.
   }
   -(void)onProcessingProgress:(AliMediaDownloader *)downloader percentage:(int)percent {
       // The listener for the processing progress in percentage.
   }
   -(void)onCompletion:(AliMediaDownloader *)downloader {
       // The listener for a successful download.
   }

4. Prepare the download source.

   You can call the prepare method to prepare a download source. AVPVidStsSource and AVPVidAuthSource are supported. Sample code:

   • VidSts

     // Create the VidSts download source.
     AVPVidStsSource* stsSource = [[AVPVidStsSource alloc] init];
     stsSource.region = @"Access region"; // The region in which ApsaraVideo VOD is activated. Default value: cn-shanghai. 
     stsSource.vid = @"Video ID"; // The ID of the video. 
     stsSource.securityToken = @"<Your security token>"; // The STS token. To generate an STS token, call the AssumeRole operation in STS. 
     stsSource.accessKeySecret = @"<Your AccessKey secret>"; // The AccessKey secret that is generated when the temporary STS token is issued. To generate the AccessKey secret, call the AssumeRole operation in STS. 
     stsSource.accessKeyId = @"<Your AccessKey ID>"; // The AccessKey ID that is generated when the temporary STS token is issued. To generate the AccessKey ID, call the AssumeRole operation in STS. 
     // Prepare the download source.
     [downloader prepareWithVid:stsSource];

   • VidAuth

     // Add the VidAuth download source.
     AVPVidAuthSource *authSource = [[AVPVidAuthSource alloc] init];
     authSource.vid = @"Video ID";// The ID of the video. 
     authSource.playAuth = @"<Your playback credential>"; // The playback credential. To obtain the 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. 
     // Prepare the download source.
     [downloader prepareWithVid:authSource];

5. Select the content that you want to download from the prepared download source.

   After the download source is prepared, a callback is invoked by the onPrepared method. The value of the TrackInfo parameter indicates the information about video tracks such as video definitions. Select a track to download. Sample code:

   -(void)onPrepared:(AliMediaDownloader *)downloader mediaInfo:(AVPMediaInfo *)info {
       NSArray<AVPTrackInfo*>* tracks = info.tracks;
       // In this example, download the content of the first track.
       [downloader selectTrack:[tracks objectAtIndex:0].trackIndex];
   }

6. Update the download source and start the download.

   VidSts or VidAuth may expire before the download. Therefore, we recommend that you update the download source before you start the download. Sample code:

   // Update the download source.
   [downloader updateWithVid:vidSource]
   // Start the download.
   [downloader start];

7. Release the downloader after the download succeeds or fails.

   After the download succeeds, call the destroy method to release the downloader.

   [self.downloader destroy];
   self.downloader = nil;

Play encrypted videos

ApsaraVideo Player SDK for Android allows you to play on-demand videos encrypted based on HLS encryption, Alibaba Cloud proprietary cryptography, or digital rights management (DRM) encryption. The SDK allows you to play live streams encrypted only based on DRM encryption. For more information about how to play encrypted videos, see Play an encrypted video.

Configure Native RTS SDK

You can integrate ApsaraVideo Player SDK for iOS with Native RTS SDK to use the Real-Time Streaming (RTS) feature. For more information, see Native RTS SDK for iOS.

References

• API reference

• Error codes

• FAQ about ApsaraVideo Player SDK for iOS