ApsaraVideo VOD:Advanced features

Verify professional capabilities

You can set the listener when the application starts or before you call any player API operations.

void premiumVeryfyCallback(AVPPremiumBizType biztype, bool isValid, NSString* errorMsg) {
    NSLog(@"onPremiumLicenseVerifyCallback: %d, isValid: %d, errorMsg: %@", biztype, isValid, errorMsg);
}

[AliPrivateService setOnPremiumLicenseVerifyCallback:premiumVeryfyCallback];

AVPPremiumBizType is an enumeration type for premium features. When a related feature is used, the player validates the feature and returns the result through this callback. If isValid is false, errorMsg contains the specific reason.

Playback

/**
 @brief Alpha rendering mode. Supports alpha at the right, left, top, and bottom. The default value is none.
 @see AVPAlphaRenderMode
 */
@property(nonatomic) AVPAlphaRenderMode alphaRenderMode;

//--------------View usage-------------
// For View, you need to set clearColor.
@property (weak, nonatomic) IBOutlet UIView *mediaPlayerView;
[self.aliplayerview setBackgroundColor:UIColor.clearColor];

//-----------AliPlayer usage-----------
// Set the alpha mode.
[self.player setAlphaRenderMode:AVP_RENDERMODE_ALPHA_AT_LEFT];
// Set the material corresponding 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.player setUrlSource:source];

// Optional: If there is a connection issue after a single instance playback is complete, you can clear the screen.
#pragma mark -- AVPDelegate
- (void)onPlayerEvent:(AliPlayer *)player eventType:(AVPEventType)eventType {
    switch (eventType) {
        case AVPEventCompletion:
        {
            [player clearScreen];
        }
            break;
        //...
    }
}

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

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

AVPConfig *config = [self.player getConfig];
// Use the Metal rendering method.
config.videoRenderType = 1;
[self.player setConfig:config];
[self.player prepare];

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

// Enable hardware decoding. This is enabled by default.
self.player.enableHardwareDecoder = YES;

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

Adaptive H.265 playback

// The application layer maintains a map that stores all key-value pairs of original URLs and backup URLs. When switching, query the backup URL in the map based on the original URL.
NSString* getBackupUrlCallback(AVPBizScene scene, AVPCodecType codecType, NSString* oriurl){
    NSMutableDictionary *globalMap = [AliPlayerViewController getGlobalBackupUrlMap];
    NSString *backupUrl = globalMap[oriurl];
    return backupUrl; 
}

[AliPlayerGlobalSettings setAdaptiveDecoderGetBackupURLCallback:getBackupUrlCallback];

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

// Switch the 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
}

AVPConfig *config = [self.player getConfig];
config.maxAllowedAbrVideoPixelNumber = 921600; // Set the maximum number of pixels for ABR definition to 921600 (width × height = 1280 × 720), so that the number of pixels for the definition that ABR can switch to is less than or equal to this value.
[self.player setConfig:config];

Take snapshots

// Snapshot callback.
- (void)onCaptureScreen:(AliPlayer *)player image:(UIImage *)image {
    // Process the snapshot.
}
// Take a snapshot of the current playback screen.
[self.player snapShot];

Preview

ApsaraVideo Player SDK for iOS, in conjunction with ApsaraVideo VOD configurations, can implement a preview feature. It supports both VidSts and VidAuth (recommended for ApsaraVideo VOD) playback methods. For more information about how to configure and use the preview feature, see Preview videos.

AVPVidStsSource *source = [[AVPVidStsSource alloc] init];
....
VidPlayerConfigGenerator* vp = [[VidPlayerConfigGenerator alloc] init];
[vp setPreviewTime:20]; // 20-second preview.
source.playConfig = [vp generatePlayerConfig]; // Set for the playback source.
...

Set the Referer

// First, get the configuration.
AVPConfig *config = [self.player getConfig];
// Set the Referer.
config.referer = referer;
....// Other settings.
// Set the configuration for the player.
[self.player setConfig:config];

Set the User-Agent

// First, get the configuration.
AVPConfig *config = [self.player getConfig];
// Set the User-Agent.
config.userAgent = userAgent;
....// Other settings.
// Set the configuration for the player.
[self.player setConfig:config];

Configure network retry time and count

// First, get the configuration.
AVPConfig *config = [self.player getConfig];
// Set the network timeout in milliseconds.
config.networkTimeout = 5000;
// Set the number of retry attempts on timeout. The interval for each retry is networkTimeout. networkRetryCount=0 means no retries, and the retry policy is determined by the app. The default value is 2.
config.networkRetryCount = 2;
....// Other settings.
// Set the configuration for the player.
[self.player setConfig:config];

Configure caching and latency control

// First, get the configuration.
AVPConfig *config = [self.player getConfig];
// Maximum latency. Note: This is effective for live streaming. When the latency is high, the player SDK will perform frame synchronization to ensure the latency is within this range.
config.maxDelayTime = 5000;
// Maximum buffer duration in milliseconds. The player loads at most this duration of buffered data each time.
config.maxBufferDuration = 50000;
// High buffer duration in milliseconds. When data is being loaded due to poor network conditions, if the loaded buffer duration reaches this value, the loading state ends.
config.highBufferDuration = 3000;
// Start buffer duration in milliseconds. The shorter this time is set, the faster the first frame loads. It may also cause the player to enter a loading state soon after playback starts.
config.startBufferDuration = 500;
// Other settings.
// Set the configuration for the player.
[self.player setConfig:config];

Set HTTP headers

// First, get the configuration.
AVPConfig *config = [self.player getConfig];
// Define the header.
NSMutableArray *httpHeaders = [[NSMutableArray alloc] init];
// For example, when using HTTPDNS, you need to set the Host.
[httpHeaders addObject:@"Host:example.com"];
// Set the header.
config.httpHeaders = httpHeaders;
....// Other settings.
// Set the configuration for the player.
[self.player setConfig:config];

Picture-in-Picture (PiP)

Enable PiP

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

Set the PiP delegate

The following section provides only some common code examples for interactions between the Picture-in-Picture (PiP) window and the player window. These examples include the logic for the pause, play, fast forward, and fast backward buttons in the PiP window, and for replaying. For details about the delegate methods, see the content of the AliPlayerPictureInPictureDelegate.h header file in the AliyunPlayer.framework of the SDK folder in the Player SDK Demo.

1. Set the PiP delegate.

   /**
   * @brief Set the PiP delegate.
   */
   -(void) setPictureinPictureDelegate:(id<AliPlayerPictureInPictureDelegate>)delegate;
   
   
   // Set the PiP delegate.
   [self.player setPictureinPictureDelegate:self];

2. Add variables and implement the delegate interface.

   1. Add global variables to control the player's state changes.

      #import "YourUIViewController.h"
      #import <AliyunPlayer/AliyunPlayer.h>
      
      @interface YourUIViewController () <AVPDelegate, AliPlayerPictureInPictureDelegate>
      // Player instance.
      @property (nonatomic, strong) AliPlayer *player;
      // Player view container.
      @property (nonatomic, strong) UIView *playerView;
      // Listen for whether PiP is currently paused.
      @property (nonatomic, assign) BOOL isPipPaused;
      // Listen for the current playback status of the player, set through the newStatus callback of the playback event status change listener.
      @property (nonatomic, assign) AVPStatus currentPlayerStatus;
      // Set the PiP controller. Set it in the callback method that is invoked before PiP starts. You must actively set it to nil when the page is about to be destroyed. We recommend setting this.
      @property (nonatomic, weak) AVPictureInPictureController *pipController;
      // Listen for the current playback progress of the player. Set currentPosition to the value of the position parameter in the callback for the current video playback position.
      @property (nonatomic, assign) int64_t currentPosition;
      
      @end

      Note

      pipController must be modified with weak or assign. If you use assign, pay attention to when the variable is set to null.

   2. When you listen to the playback event status change callback interface, you must actively call the following method to update the relevant status of the PiP controller.

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

   3. When you listen to the playback event callback interface, you must actively call the following method to update the relevant status of the PiP controller.

      - (void)onPlayerEvent:(AliPlayer*)player eventType:(AVPEventType)eventType {
          if (eventType == AVPEventCompletion) {
            if (_pipController) {
             self.isPipPaused = YES; // After playback ends, change the PiP status to paused.
             [self.pipController invalidatePlaybackState];
          }
        } else if (eventType == AVPEventSeekEnd) {
          // Seeking is complete.
            if (_pipController) {
             [self.pipController invalidatePlaybackState];
          }
        }
      }

   4. Set listeners.

      • Listen for the callback that is invoked before PiP starts.

        /**
         @brief PiP is about to start.
         @param pictureInPictureController The PiP controller.
         */
        - (void)pictureInPictureControllerWillStartPictureInPicture:(AVPictureInPictureController *)pictureInPictureController {
            if (!_pipController) {
             self.pipController = pictureInPictureController;
          }
            self.isPipPaused = !(self.currentPlayerStatus == AVPStatusStarted);
          [pictureInPictureController invalidatePlaybackState];
        }

      • Listen for the callback that is invoked before PiP stops.

        /**
         @brief PiP is about to stop.
         @param pictureInPictureController The PiP controller.
         */
        - (void)pictureInPictureControllerWillStopPictureInPicture:(AVPictureInPictureController *)pictureInPictureController {
            self.isPipPaused = NO;
          [pictureInPictureController invalidatePlaybackState];
        }

      • Listen for the callback that is invoked to restore the user interface before PiP stops.

        /**
         @brief Tells the delegate to restore the user interface before PiP stops.
         @param pictureInPictureController The PiP controller.
         @param completionHandler Call and pass YES to allow the system to finish restoring the player user interface.
         */
        - (void)pictureInPictureController:(AVPictureInPictureController *)pictureInPictureController restoreUserInterfaceForPictureInPictureStopWithCompletionHandler:(void (^)(BOOL restored))completionHandler {
            if (_pipController) {
              _pipController = nil;
          }
          completionHandler(YES);
        }

      • Listen for the callback that sets the playable time range in PiP mode.

        /**
         @brief Notifies the PiP controller of the current playable time range.
         @param pictureInPictureController The PiP controller.
         @return The current playable time range.
         */
         - (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 for the callback that indicates whether the video is paused in PiP mode.

        /**
         @brief Reflects the paused or playing state on the UI.
         @param pictureInPictureController The PiP controller.
         @return Paused or playing.
         */
        - (BOOL)pictureInPictureControllerIsPlaybackPaused:(nonnull AVPictureInPictureController *)pictureInPictureController{
            return self.isPipPaused;
        }

        Note

        This callback is triggered before PiP starts. Make sure that the return value of this callback is false at this time. Otherwise, PiP cannot be activated.

      • Listen for the callback that is invoked when the user taps the fast-forward or rewind button in PiP mode and synchronize the player status.

        /**
         @brief The user taps the fast-forward or rewind button.
         @param pictureInPictureController The PiP controller.
         @param skipInterval The time interval for fast-forwarding or rewinding.
         @param completionHandler A closure that must be called to indicate that the seeking operation is complete.
         */
         - (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 for the callback that is invoked when the user taps the pause or play button in PiP mode.

        /**
         @brief The user taps the pause button in PiP mode.
         @param pictureInPictureController The PiP controller.
         @param playing Whether the video is playing.
         */
        - (void)pictureInPictureController:(nonnull AVPictureInPictureController *)pictureInPictureController setPlaying:(BOOL)playing {
            if (!playing){
              [self.player pause];
              self.isPipPaused = YES;
            } else {
              // Recommendation: If the PiP playback is complete and needs to be replayed, you can additionally execute the code in the following if statement.
              if (self.currentPlayerStatus == AVPStatusCompletion) {
                 [self.player seekToTime:0 seekMode:AVP_SEEKMODE_ACCURATE];
              }
        
              [self.player start];
              self.isPipPaused = NO;
          }
          [pictureInPictureController invalidatePlaybackState];
        }

In-app Picture-in-Picture

When you use the PiP feature, it is an out-of-app PiP by default. To implement in-app PiP, you can first use the following API operation to determine whether the PiP feature is enabled:

/**
 @brief Indicates whether PiP is enabled.
 @param pictureInPictureController The PiP controller.
 @param isEnable Whether PiP is enabled.
 */
- (void)pictureInPictureControllerIsPictureInPictureEnable:(nullable AVPictureInPictureController *)pictureInPictureController isEnable:(BOOL)isEnable;

When the PiP feature is enabled, you can disable the automatic start of PiP and manually control the feature's activation. The following code provides an example:

- (void) pictureInPictureControllerIsPictureInPictureEnable:(nullable AVPictureInPictureController *) pictureInPictureController isEnable:(BOOL) isEnable
{
    if (isEnable && pictureInPictureController) {
        _pipController = pictureInPictureController;
        // close pip auto start
        if (@available(iOS 15.0, *)) {
            _pipController.canStartPictureInPictureAutomaticallyFromInline = false;
        }
    } else {
        _pipController = NULL;
    }
}

- (void) switchPip:(bool) enable {
    if (_pipController == nil) {
        return;
    }
    if (enable) {
        // start pip
        [_pipController startPictureInPicture];
    } else {
        // close pip
        [_pipController stopPictureInPicture];
    }
}

// Set the AVPOutputAudioChannel enumeration value to switch the sound channel.
// AVP_AUDIO_CHANNEL_NONE: Do not specify a sound channel. Play with the input source's sound channel. This is the default value.
// AVP_AUDIO_CHANNEL_LEFT: Switch to the left sound channel for playback.
// AVP_AUDIO_CHANNEL_RIGHT: Switch to the right sound channel for playback.
self.player.outputAudioChannel = AVP_AUDIO_CHANNEL_NONE;

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

// The parameter is 8-bit hexadecimal data. The 8-bit data is divided into groups of two, representing A (alpha transparency), R (red), G (green), and B (blue) in order.
// For example, 0x0000ff00 represents green.
[self.player setVideoBackgroundColor:0x0000ff00]

/**
 @brief Play using VID + PlayAuth. For more information, see https://www.alibabacloud.com/help/en/vod/user-guide/use-playback-credentials-to-play-videos
 @param source The input type of AVPVidAuthSource.
 @see AVPVidAuthSource
 */
- (void)setAuthSource:(AVPVidAuthSource*)source;

VidPlayerConfigGenerator* gen = [[VidPlayerConfigGenerator alloc]init];
// Add the playDomain field. For fields that can be added, see
// https://www.alibabacloud.com/help/en/vod/developer-reference/api-vod-2017-03-21-getplayinfo
[gen addVidPlayerConfigByStringValue:@"playDomain" value: @"com.xxx.xxx"];
[source setPlayConfig:[gen generatePlayerConfig]];
[self.player setAuthSource:source]:

// A value of 1 enables background decoding. A value of 0 disables background decoding. The default value is 0.
[self.player setOption:ALLOW_DECODE_BACKGROUND valueInt:1];

// x.x.x should be consistent with the version number of ApsaraVideo Player SDK.
pod 'AliPlayerSDK_iOS_VVC_CODEC_PLUGIN', 'x.x.x'

// x.x.x should be consistent with the version number of the All-in-One SDK you are using.
pod 'AliVCSDK_Standard/AliPlayerSDK_iOS_VVC_CODEC', 'x.x.x'

[AliPlayerGlobalSettings enableCodecPlugin:@"vvc" valid:true];

/**
 @brief Set the callback for VidAuth source expiration notification.

 This method is triggered when the player detects that the current VidAuth source has expired.
 You can refresh the VidAuth source within the callback and use the `callback` to return the updated VidAuth source,
 ensuring uninterrupted and smooth video playback.

 @param callback The callback block triggered when the VidAuth source expires.
 Use this callback to provide a valid `VidAuth` object to update the player.
 */
-(void)setOnVidAuthExpiredCallback:(void (^)(id expiredSource, id<AVPSourceRefreshCallback> callback))callback;

/**
 @protocol AVPSourceRefreshCallback
 @brief A protocol for handling playback source refresh results, which developers need to implement.

 This protocol notifies developers when the player requests playback source refresh, such as when a resource
 has expired or needs updating. The methods in this protocol are called to provide the refresh results to the developer,
 including success or failure.

 @note This protocol applies to URL source, VidAuth source, and similar scenarios requiring refresh logic.
 */
@protocol AVPSourceRefreshCallback <NSObject>

/**
 @brief Called by the player when the refresh operation succeeds.
 
 @param newSource The new playback source object containing the updated information.

 This method indicates that the refresh operation has been successfully completed. Developers need to pass
 the updated `newSource` back to the player so that it can load the latest resource.
 */
- (void)onSuccess:(id)newSource;

/**
 @brief Called by the player when the refresh operation fails.
 
 @param errorMsg A string describing the reason for the failure.

 This method indicates that the refresh operation has failed. Developers can use `errorMsg` to capture failure
 details and handle subsequent processing accordingly.
 */
- (void)onError:(NSString *)errorMsg;

@end

[self.player setOnVidAuthExpiredCallback:^(id expiredSource, id<AVPSourceRefreshCallback> callback) {
    // Get AVPVidAuthSource
    if ([expiredSource isKindOfClass:[AVPVidAuthSource class]]) {

        // ------------------- Start of user implementation -------------------
        // Call your self-implemented function that obtains a new PlayAuth from your app server.
        // clinetGetPlayAuthFunction is an example function name. Replace it with your own implementation.
        [self clinetGetPlayAuthFunction:vid success:^(NSString* newPlayAuth){
            // 1. Callback for successfully obtaining a new credential.
            [vidAuth setPlayAuth:newPlayAuth];
            // 2. Pass the updated object back to the player through the SDK's callback.
            [callback onSuccess:vidAuth];
        } failure:^(NSString* errorMsg) {
            // Callback for failing to obtain a new credential.
            // errorMsg contains detailed error information.
            [callback onError:errorMsg];
        }];
        // ------------------- End of user implementation -------------------
    }
}];

/**
 @brief Set the callback for URL source expiration notification.

 This method is triggered when the player detects that the current URL source has expired.
 You can refresh the URL source within the callback and use the `callback` to return the updated URL source,
 ensuring uninterrupted video playback.

 @note For information about configuring the URL signing mechanism, see the official Alibaba Cloud documentation:
 https://www.alibabacloud.com/help/zh/vod/user-guide/configure-url-signing?spm=a2c4g.11186623.0.0.560c4140fGh8MW
 
 @param callback The callback block triggered when the URL source expires.
 Use this callback to provide a valid `URLSource` object to update the player.
 */
-(void)setOnURLSourceExpiredCallback:(void (^)(id expiredSource, id<AVPSourceRefreshCallback> callback))callback;

/**
 @protocol AVPSourceRefreshCallback
 @brief A protocol for handling playback source refresh results, which developers need to implement.

 This protocol notifies developers when the player requests playback source refresh, such as when a resource
 has expired or needs updating. The methods in this protocol are called to provide the refresh results to the developer,
 including success or failure.

 @note This protocol applies to URL source, VidAuth source, and similar scenarios requiring refresh logic.
 */
@protocol AVPSourceRefreshCallback <NSObject>

/**
 @brief Called by the player when the refresh operation succeeds.
 
 @param newSource The new playback source object containing the updated information.

 This method indicates that the refresh operation has been successfully completed. Developers need to pass
 the updated `newSource` back to the player so that it can load the latest resource.
 */
- (void)onSuccess:(id)newSource;

/**
 @brief Called by the player when the refresh operation fails.
 
 @param errorMsg A string describing the reason for the failure.

 This method indicates that the refresh operation has failed. Developers can use `errorMsg` to capture failure
 details and handle subsequent processing accordingly.
 */
- (void)onError:(NSString *)errorMsg;

@end

[self.player setOnURLSourceExpiredCallback:^(id expiredSource, id<AVPSourceRefreshCallback> callback) {
    // Get AVPUrlSource
    if ([expiredSource isKindOfClass:[AVPUrlSource class]]) {
        AVPUrlSource *expiredUrlSource = (AVPUrlSource *)expiredSource;
        NSString *expiredUrl = [expiredUrlSource.playerUrl absoluteString];

        // Check if it contains auth_key
        if (![expiredUrl containsString:@"auth_key="]) {
            return;
        }

        // 1. Extract the original URL from the expired URL
        NSRange authKeyQuestionRange = [expiredUrl rangeOfString:@"?auth_key="];
        NSRange authKeyAmpersandRange = [expiredUrl rangeOfString:@"&auth_key="];

        NSInteger authKeyIndex = NSNotFound;
        if (authKeyQuestionRange.location != NSNotFound) {
            authKeyIndex = authKeyQuestionRange.location;
        } else if (authKeyAmpersandRange.location != NSNotFound) {
            authKeyIndex = authKeyAmpersandRange.location;
        }

        NSString *originalUrl = nil;
        if (authKeyIndex != NSNotFound) {
            originalUrl = [expiredUrl substringToIndex:authKeyIndex];
        } else {
            // If auth_key is not found, assume the entire URL is the original URL
            originalUrl = expiredUrl;
        }

        // 2. Prepare new signing parameters: authKey and expiration time
        // If the class member authKey is valid, use authKey
        NSString *key = (self.authKey.length > 0) ? self.authKey : @"";
        if (!NOT_EMPTY(key)) {
            [callback onError:@"REFRESH_ERROR:key fail"];
            return;
        }       
        
        // If the class member validTime is valid, use validTime; otherwise, use the default value
        NSTimeInterval validTime = (self.validTime > 0) ? self.validTime : 3600; // Default is 3600 seconds
        NSTimeInterval newExpireTime = [[NSDate date] timeIntervalSince1970] + validTime;

         // 3. Use CdnAuthUtil to generate a new signed URL (Type A)
        NSString *newAuthUrl = [CdnAuthUtil aAuthWithUri:originalUrl key:key exp:newExpireTime];
        AVPUrlSource *resultSource = [[AVPUrlSource alloc] urlWithString:newAuthUrl];

        // 4. Handle the callback
        if (newAuthUrl) {
            [callback onSuccess:resultSource];
        } else {
            [callback onError:@"REFRESH_ERROR:refresh fail"];
        }
    }
}];

#import "CdnAuthUtil.h"
#import <CommonCrypto/CommonDigest.h>

@implementation CdnAuthUtil

#pragma mark - Auth Method A
+ (NSString *)aAuthWithUri:(NSString *)uri key:(NSString *)key exp:(NSTimeInterval)exp {
    NSDictionary *components = [self matchUri:uri];
    if (!components) return nil;

    NSString *scheme = components[@"scheme"];
    NSString *host = components[@"host"];
    NSString *path = components[@"path"];
    NSString *args = components[@"args"];

    NSString *rand = @"0";
    NSString *uid = @"0";

    NSString *sstring = [NSString stringWithFormat:@"%@-%lld-%@-%@-%@", path, (long long)exp, rand, uid, key];
    NSString *hashvalue = [self md5sum:sstring];
    NSString *authKey = [NSString stringWithFormat:@"%lld-%@-%@-%@", (long long)exp, rand, uid, hashvalue];

    if (args.length > 0) {
        return [NSString stringWithFormat:@"%@%@%@%@&auth_key=%@", scheme, host, path, args, authKey];
    } else {
        return [NSString stringWithFormat:@"%@%@%@%@?auth_key=%@", scheme, host, path, args, authKey];
    }
}

#pragma mark - Private Helper: MD5
+ (NSString *)md5sum:(NSString *)src {
    const char *cStr = [src UTF8String];
    unsigned char result[CC_MD5_DIGEST_LENGTH];
    CC_MD5(cStr, (unsigned int)strlen(cStr), result);

    NSMutableString *hexString = [NSMutableString string];
    for (int i = 0; i < CC_MD5_DIGEST_LENGTH; i++) {
        [hexString appendFormat:@"%02x", result[i]];
    }
    return hexString.copy;
}

#pragma mark - Private Helper: Regex Match
+ (NSDictionary *)matchUri:(NSString *)uri {
    NSError *error = nil;
    NSRegularExpression *regex = [NSRegularExpression regularExpressionWithPattern:@"^(https?://)?([^/?]+)(/[^?]*)?(\\?.*)?$"
                                  options:0
                                  error:&error];
    if (error) {
        NSLog(@"Regex error: %@", error.localizedDescription);
        return nil;
    }

    NSTextCheckingResult *match = [regex firstMatchInString:uri
                                   options:0
                                   range:NSMakeRange(0, uri.length)];
    if (!match) return nil;

    __block NSString *scheme = nil, *host = nil, *path = nil, *args = nil;

    void (^setStringFromRange)(NSInteger, NSString**) = ^(NSInteger idx, NSString **outStr) {
        NSRange range = [match rangeAtIndex:idx];
        if (range.location != NSNotFound && range.length > 0) {
            *outStr = [uri substringWithRange:range];
        } else {
            *outStr = nil;
        }
    };

    setStringFromRange(1, &scheme);
    setStringFromRange(2, &host);
    setStringFromRange(3, &path);
    setStringFromRange(4, &args);

    // Handle default values
    if (!scheme) scheme = @"http://";
    if (!path) path = @"/";

    return @{
        @"scheme": scheme,
        @"host": host,
        @"path": path,
        @"args": args ?: @""
        };
}
@end

Performance

Set the playback scenario

Setting a playback scenario automatically configures optimal parameters, such as buffer settings and feature toggles, based on the scenario. This setting is also compatible with custom parameter settings that are configured using the setConfig interface. Custom settings take precedence.

API example

/**
 @brief Set player scene.
 @param scene Player scene.
 @see AVPScene
 */
-(void) setPlayerScene:(AVPScene)scene;

Playback scenarios

typedef enum _AVPScene {
    /**
     * Scene: None
     */
    SceneNone,
    /**
     * Long video scene: applicable to videos longer than 30 minutes
     */
    SceneLong,
    /**
     * Medium video scene: applicable to videos between 5 and 30 minutes
     */
    SceneMedium,
    /**
     * Short video scene: applicable to videos between 0 seconds and 5 minutes
     */
    SceneShort,
    /**
     * Live streaming scene
     */
    SceneLive,
    /**
     * RTS live scene
     */
    SceneRTSLive
} AVPScene;

Usage instructions

// Set the short video scene.
[self.player setPlayerScene:SceneShort];

// Set the medium video scene.
[self.player setPlayerScene:SceneMedium]; 

// Set the long video scene.
[self.player setPlayerScene:SceneLong];  

// Set the live streaming scene.
[self.player setPlayerScene:SceneLive];   

Pre-rendering

[self.player setOption:ALLOW_PRE_RENDER valueInt:1];

Local caching

ApsaraVideo Player SDK for iOS provides a local caching feature. This feature improves the first frame loading speed, seek speed, and reduces stuttering when users play a video repeatedly. It also helps save traffic.

Enable local caching

/**
 * Enable local caching. After enabling, videos will be cached to local files.
 * @param enable: Local caching feature switch. true: enable, false: disable. Default is false.
 * @param maxBufferMemoryKB: Deprecated since V5.4.7.1, has no effect.
 * @param localCacheDir: Must be set. The directory for local cache files, must be an absolute path.
 */
[AliPlayerGlobalSettings enableLocalCache:true maxBufferMemoryKB:1024 localCacheDir:@""];

/**
 @brief Settings for automatic clearing of local cache files.
 @param expireMin: Deprecated since V5.4.7.1, has no effect.
 @param maxCapacityMB: Maximum cache capacity in megabytes. Default is 20 GB. During cleanup, if the total cache capacity exceeds this size, the oldest cache files will be deleted one by one, sorted by the last access time of the cache item, until the total capacity is less than or equal to the maximum capacity.
 @param freeStorageMB: Minimum free disk space in megabytes. Default is 0. During cleanup, similar to maximum cache capacity, if the current disk space is less than this value, cache files will also be deleted one by one according to the rule until the free storage is greater than or equal to this value or all caches are cleared.
 */
[AliPlayerGlobalSettings setCacheFileClearConfig:0 maxCapacityMB:0 freeStorageMB:0];

/**
 * Callback to get the hash value of the loaded URL, used as a unique ID for the URL. It must be ensured that each URL is unique.
 */

// You need to implement this function yourself and pass the function pointer to setCacheUrlHashCallback.
static NSString *CaheUrlHashHandle(NSString *url) {
    return @"xxx";
}

[AliPlayerGlobalSettings setCacheUrlHashCallback:&CaheUrlHashHandle];

Enable or disable local caching for a single URL

// First, get the configuration.
AVPConfig *config = [self.player getConfig];
// Whether to enable local caching for the playback URL. The default value is true. When local caching is enabled in AliPlayerGlobalSettings, and local caching is also enabled here (set to true), local caching for this URL will take effect. If set to false here, local caching for this URL is disabled.
config.enableLocalCache = false;
....// Other settings.

// Set the configuration for the player.
[self.player setConfig:config];

[AliPlayerGlobalSettings enableLocalCache:true];

Preloading

ApsaraVideo Player SDK for iOS provides a preloading feature, which is an upgrade to the local caching feature. By setting the memory size that is occupied by the video cache, you can further improve the first frame loading speed of the video.

[AliPlayerGlobalSettings enableNetworkBalance:false];

1. Enable the local caching feature. For more information, see Local caching.

2. Set the data source.

   VidAuth (recommended)

   AVPVidAuthSource* vidAuthSource = [[AVPVidAuthSource alloc] init];
   [vidAuthSource setVid:@"Vid information"]; // Required. The video ID.
   [vidAuthSource setPlayAuth:@"<yourPlayAuth>"]; // Required. The playback credential. You need to call the GetVideoPlayAuth API operation of ApsaraVideo VOD to generate it.
   [vidAuthSource setRegion:@"Access region"]; // For player SDKs V5.5.5.0 and later, this parameter is deprecated. You do not need to set the region; the player will automatically parse it. For player SDKs earlier than V5.5.5.0, this parameter is required. The access region of ApsaraVideo VOD, default is cn-shanghai.
   [vidAuthSource setQuality:@"Selected definition"]; // "AUTO" represents adaptive bitrate.

   VidSts

   AVPVidStsSource* vidStsSource = [[AVPVidStsSource alloc] init];
   [vidStsSource setVid: @"Vid information"]; // Required. The video ID.
   [vidStsSource setRegion:@"Access region"]; // Required. The access region of ApsaraVideo VOD, default is cn-shanghai.
   [vidStsSource setSecurityToken: @"<yourSecurityToken>"]; // Required. The STS token. You need to call the AssumeRole API operation of STS to generate it.
   [vidStsSource setAccessKeySecret: @"<yourAccessKeySecret>"]; // Required. The AccessKey secret of the temporary STS AccessKey pair. You need to call the AssumeRole API operation of STS to generate it.
   [vidStsSource setAccessKeyId: @"<yourAccessKeyId>"]; // Required. The AccessKey ID of the temporary STS AccessKey pair. You need to call the AssumeRole API operation of STS to generate it.
   [vidStsSource setQuality:@"Selected definition"]; // "AUTO" represents adaptive bitrate.

   UrlSource

   NSString* url = @"Playback URL"; // Required. The playback URL, which can be a third-party VOD URL or a playback URL in ApsaraVideo VOD.
   AVPUrlSource* urlSource = [[AVPUrlSource alloc]urlWithString:url];

3. Set task parameters.

   Note

   This applies only to multi-bitrate videos. You can set only one of setDefaultBandWidth, setDefaultResolution, or setDefaultQuality.

   AVPPreloadConfig *config = [[AVPPreloadConfig alloc]init];
   // Set the preload bitrate for multi-bitrate streams.
   [config setDefaultBandWidth:400000];
   // Set the preload resolution for multi-bitrate streams.
   [config setDefaultResolution:640 * 480];
   // Set the preload quality for multi-bitrate streams.
   [config setDefaultQuality:@"FD"];
   // Set the preload duration.
   [config setDuration:1000];

4. Add a task listener.

   Expand to view code

   @interface YourViewController () <OnPreloadListener>
   
   @property(nonatomic,strong) AliMediaLoaderV2* vodMedialoader; // Preloader
   @property(nonatomic,strong) AVPVidAuthSource* vidSource; // vidAuth data source
   @property(nonatomic,strong) AVPUrlSource* urlSource; // url data source
   @property(nonatomic,strong) AVPVidStsSource* vidStsSource; // vidSts data source
   
   @end
   
   @implementation YourViewController
   
   - (void)onCompleted:(NSString *)taskId urlOrVid:(NSString *)urlOrVid {
       NSLog(@"Current task (%@) completed:%@", taskId,urlOrVid);
   }
   
   - (void)onError:(NSString *)taskId urlOrVid:(NSString *)urlOrVid errorModel:(AVPErrorModel *)errorModel {
       NSLog(@"An exception occurred:%@", urlOrVid);
   }
   
   - (void)onCanceled:(NSString *)taskId urlOrVid:(NSString *)urlOrVid {
       NSLog(@"Task canceled:%@", urlOrVid);
   }
   
   @end

5. Build a task and add it to the MediaLoaderV2 instance to start preloading.

   VidAuth (recommended)

   // Build the preload task.
   AVPPreloadTask* mPreloadTask = [[AVPPreloadTask alloc]initWithVidAuthSource:vidAuthSource preloadConfig:config];
   // Get the MediaLoaderV2 instance.
   AliMediaLoaderV2* vodMedialoader = [AliMediaLoaderV2 shareInstance];
   // Add the task and start preloading.
   NSString* taskId = [vodMedialoader addTask:mPreloadTask listener:self];

   VidSts

   // Build the preload task.
   AVPPreloadTask* mPreloadTask = [[AVPPreloadTask alloc]initWithVidStsSource:vidStsSource preloadConfig:config];
   // Get the MediaLoaderV2 instance.
   AliMediaLoaderV2* vodMedialoader = [[AliMediaLoaderV2 alloc]init];
   // Add the task and start preloading.
   NSString* taskId = [vodMedialoader addTask:mPreloadTask listener:self];

   UrlSource

   // Build the preload task.
   AVPPreloadTask* mPreloadTask = [[AVPPreloadTask alloc]initWithUrlSource:urlSource preloadConfig:config];
   // Get the MediaLoaderV2 instance.
   AliMediaLoaderV2* vodMedialoader = [[AliMediaLoaderV2 alloc]init];
   // Add the task and start preloading.
   NSString* taskId = [vodMedialoader addTask:mPreloadTask listener:self];

6. Optional: Manage tasks.

   [vodMedialoader cancelTask:taskId]; // Cancel the preload task with the specified task ID.
   [vodMedialoader pauseTask:taskId]; // Pause the preload task with the specified task ID.
   [vodMedialoader resumeTask:taskId]; // Resume the preload task with the specified task ID.

7. Optional: Delete loaded files.

   You can delete loaded files as needed to save space. ApsaraVideo Player SDK for iOS does not provide a deletion interface. You need to delete the files in the loading directory in the app.

Dynamic preloading

The dynamic preloading policy allows integrators to control both the cache of the currently playing video and the number and cache of preloaded videos, balancing the playback experience with cost overhead for business needs.

// Enable recommended configuration and dynamic preloading.
[self.listPlayer setScene:AVP_SHORT_VIDEO];

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

// Configure the number of preloads, supporting both directions.
// 1 is the number of preloads backward, 3 is the number of preloads forward.
[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 {
    /**
     * Default mode, play and preload default bitrate of a stream.
     */
    AVPMultiBitratesMode_Default = 0,
    /**
     * First frame cost (FC) priority, decrease first frame cost. only play bitrate of the hls stream which has been preloaded.
     */
    AVPMultiBitratesMode_FCPrio = 1,
    /**
     * Balance first frame and play smooth, play the same bitrate before and after moveToNext.
     */
    AVPMultiBitratesMode_FC_AND_SMOOTH = 2,
    /**
     * Play Smooth priority, play the same bitrate before and after moveToNext.
     */
    AVPMultiBitratesMode_SmoothPrio = 3,
} AVPMultiBitratesMode;

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

// (Optional) Select the starting bitrate.
[self.listPlayer setDefaultBandWidth:defaultBandWidth];

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

Get the download speed

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

Network features

// Enable enhanced HTTPDNS.
[AliPlayerGlobalSettings enableEnhancedHttpDns:YES];
// Optional: Add a domain name for HTTPDNS pre-resolution.
[[AliDomainProcessor shareInstance] addPreResolveDomain:@"player.***alicdn.com"];

[AliPlayerGlobalSettings setUseHttp2:true];

// The domain format is host[:port], where port is optional. Multiple domain names are separated by semicolons (;).
// Global settings
// The full interface uses the current string each time it is set (more - add, less - delete). An empty string stops pre-connection.
[AliPlayerGlobalSettings setOption:SET_PRE_CONNECT_DOMAIN value: @"domain1;domain2"];

Video download

ApsaraVideo Player SDK for iOS provides a video download feature for ApsaraVideo VOD. This feature allows users to cache videos locally for viewing with ApsaraVideo Player. The SDK offers two download methods: standard download and secure download.

• Standard download: The downloaded video data is not encrypted by Alibaba Cloud. Users can play it with third-party players.

• Secure download: The downloaded video data is encrypted by Alibaba Cloud. Third-party players cannot play the data. The data can be played only using ApsaraVideo Player.

Usage notes

• The video download feature is supported only for VidSts and VidAuth methods.

• To use the video download feature of the player, you need to enable and configure the download mode in the ApsaraVideo VOD console. For more information, see Offline download.

• Video download supports resumable downloads.

Procedure

1. Optional: Configure the encryption verification file for secure download. This is required only for secure download, not for standard download.

   Note

   Make sure that the configured encryption verification file is consistent with the app information. Otherwise, the video download fails.

   If you set the download method to secure download, you must configure the key file that is generated in the ApsaraVideo VOD console into the player SDK for decryption and verification during video download and playback. For more information about how to generate the key file, see Enable secure download.

   We recommend that you configure the key file once in the Application. The following code provides an example:

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

2. Create and set up the downloader.

   The following code provides an example:

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

3. Set event listeners.

   The downloader provides multiple event listeners. The following code provides an example:

   -(void)onPrepared:(AliMediaDownloader *)downloader mediaInfo:(AVPMediaInfo *)info {
       // The download item is successfully prepared.
   }
   -(void)onError:(AliMediaDownloader *)downloader errorModel:(AVPErrorModel *)errorModel {
       // A download error occurred.
   }
   -(void)onDownloadingProgress:(AliMediaDownloader *)downloader percentage:(int)percent {
       // Download progress percentage.
   }
   -(void)onProcessingProgress:(AliMediaDownloader *)downloader percentage:(int)percent {
       // Processing progress percentage.
   }
   -(void)onCompletion:(AliMediaDownloader *)downloader {
       // The download is successful.
   }

4. Prepare the download source.

   You can use the prepare method to prepare the download source. Both VidSts and VidAuth methods are supported. The following code provides an example:

   • VidSts

     // Create VidSts.
     AVPVidStsSource* stsSource = [[AVPVidStsSource alloc] init];
     stsSource.region = @"Access region"; // The access region of ApsaraVideo VOD. Default is cn-shanghai.
     stsSource.vid = @"Vid information"; // The video ID.
     stsSource.securityToken = @"<yourSecurityToken>"; // The STS token. You need to call the AssumeRole API operation of STS to generate it.
     stsSource.accessKeySecret = @"<yourAccessKeySecret>"; // The AccessKey secret of the temporary STS AccessKey pair. You need to call the AssumeRole API operation of STS to generate it.
     stsSource.accessKeyId = @"<yourAccessKeyId>"; // The AccessKey ID of the temporary STS AccessKey pair. You need to call the AssumeRole API operation of STS to generate it.
     
     // If you have enabled HLS standard encryption parameter pass-through in the VOD console, and the default parameter name is MtsHlsUriToken, you need to set the config and pass it into the vid, as shown below.
     // If you have not enabled HLS standard encryption parameter pass-through in the VOD console, you do not need to integrate the following code.
     VidPlayerConfigGenerator* vp = [[VidPlayerConfigGenerator alloc] init];
     [vp setHlsUriToken:yourMtsHlsUriToken];
     stsSource.playConfig = [vp generatePlayerConfig];
     // Prepare the download source.
     [downloader prepareWithVid:stsSource];

   • VidAuth

     // Create VidAuth.
     AVPVidAuthSource *authSource = [[AVPVidAuthSource alloc] init];
     authSource.vid = @"Vid information"; // The video ID.
     authSource.playAuth = @"<yourPlayAuth>"; // The playback credential. You need to call the GetVideoPlayAuth API operation of ApsaraVideo VOD to generate it.
     authSource.region = @"Access region"; // For player SDKs V5.5.5.0 and later, this parameter is deprecated. You do not need to set the region; the player will automatically parse it. For player SDKs earlier than V5.5.5.0, this parameter is required. The access region of ApsaraVideo VOD, default is cn-shanghai.
     // If you have enabled HLS standard encryption parameter pass-through in the VOD console, and the default parameter name is MtsHlsUriToken, you need to set the config and pass it into the vid, as shown below.
     // If you have not enabled HLS standard encryption parameter pass-through in the VOD console, you do not need to integrate the following code.
     VidPlayerConfigGenerator* vp = [[VidPlayerConfigGenerator alloc] init];
     [vp setHlsUriToken:yourMtsHlsUriToken];
     authSource.playConfig = [vp generatePlayerConfig];
     // Prepare the download source.
     [downloader prepareWithVid:authSource];

   Note

   If you have enabled HLS standard encryption parameter pass-through in the VOD console, and the default parameter name is MtsHIsUriToken (for more information, see HLS standard encryption parameter pass-through), please set the MtsHIsUriToken value into the VOD source as shown in the code above.

5. After successful preparation, select a download item.

   After the preparation is successful, the onPrepared method is called back. The returned TrackInfo contains information such as the definition of each video stream. You can select a track to download. The following code provides an example:

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

6. Update the download source and start the download.

   To prevent VidSts and VidAuth from expiring, we recommend that you update the download source information before you start the download. The following code provides an example:

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

7. After the download succeeds or fails, release the downloader.

   After the download is successful, you can call destroy to release the downloader.

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

Encrypted video playback

ApsaraVideo VOD supports HLS encryption, Alibaba Cloud proprietary cryptography, and DRM encryption. Live streaming videos support only DRM encryption. For more information about encrypted playback, see Encrypted video playback.

Native RTS playback

ApsaraVideo Player SDK for iOS integrates the Native RTS SDK to implement the native low-latency live streaming feature. For more information, see Implement RTS stream pulling on iOS.

References

• API reference

• Mobile client error codes

• FAQ for ApsaraVideo Player for iOS