Advanced features

Advanced feature verification

Set the listener at application startup or before making any player API calls:

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

[AliPrivateService setOnPremiumLicenseVerifyCallback:premiumVeryfyCallback];

Here, AVPPremiumBizType is an advanced feature enumeration. When you use an advanced feature, the player verifies the license and returns the result through this callback. If isValid is false, errorMsg contains the reason for the failure.

Playback

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

//--------------View usage-------------
// For the player's view, set a clear background color.
@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 asset that matches the alpha mode.
AVPUrlSource *source = [[AVPUrlSource alloc] urlWithString:@"https://alivc-player.oss-cn-shanghai.aliyuncs.com/video/business_needs_sample/alpha_channel/alpha_left.mp4"];
[self.player setUrlSource:source];

// Optional: If you encounter visual artifacts after playback completes, 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 Specifies the video render type. Valid values: 0 (default renderer) and 1 (mixed renderer). Default: 0.
 */
@property(nonatomic, assign) int videoRenderType;

AVPConfig *config = [self.player getConfig];
// Enable Metal rendering.
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 (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.
    }
}

H.265 adaptive playback

// The application layer should maintain a dictionary to map original URLs to their backup URLs.
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 to a specific stream.
[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) {
        // The video track has changed.
    }
    // etc
}

AVPConfig *config = [self.player getConfig];
config.maxAllowedAbrVideoPixelNumber = 921600; // Set the maximum pixel count for ABR to 921600 (1280 * 720). This ensures that the player only switches to definitions with a pixel count less than or equal to this value.
[self.player setConfig:config];

Snapshot

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

Preview

The ApsaraVideo Player SDK for iOS supports a preview feature when configured with ApsaraVideo VOD. The SDK supports both VidSts and VidAuth playback. VidAuth is the recommended method. For more information, see Preview videos.

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

Set Referer

// Get the configuration.
AVPConfig *config = [self.player getConfig];
// Set the Referer.
config.referer = referer;
....// Other settings.
// Apply the configuration to the player.
[self.player setConfig:config];

User-Agent

// Get the current configuration.
AVPConfig *config = [self.player getConfig];
// Set the User-Agent.
config.userAgent = userAgent;
//... other settings
// Apply the configuration to the player.
[self.player setConfig:config];

Configure network retry count and timeout

// Get the configuration.
AVPConfig *config = [self.player getConfig];
// Set the network timeout in milliseconds.
config.networkTimeout = 5000;
// Set the maximum number of retries. The retry interval is determined by networkTimeout. A value of 0 disables retries, allowing the application to implement its own retry policy. The default is 2.
config.networkRetryCount = 2;
//... Other settings
// Apply the configuration to the player.
[self.player setConfig:config];

Cache and latency control

// Retrieve the configuration.
AVPConfig *config = [self.player getConfig];
// The maximum latency in milliseconds. Note: This parameter is for live streaming only. If latency becomes high, the Player SDK synchronizes frames to keep it within this limit.
config.maxDelayTime = 5000;
// The maximum duration (in milliseconds) of data that the player can buffer.
config.maxBufferDuration = 50000;
// The high buffer duration in milliseconds. When network conditions are poor, the player stops loading data once the buffer reaches this duration.
config.highBufferDuration = 3000;
// The startup buffer duration in milliseconds. A smaller value results in a faster startup speed but may cause stuttering shortly after playback starts.
config.startBufferDuration = 500;
// Other settings.
// Apply the configuration to the player.
[self.player setConfig:config];

Set HTTP header

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

Picture-in-picture

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 code examples demonstrate common interactions between the Picture-in-Picture (PiP) and player windows. They cover displaying playback controls such as pause, play, fast-forward, and rewind, and implementing the replay logic. For a complete reference to the delegate methods, see the AliPlayerPictureInPictureDelegate.h header file, located in AliyunPlayer.framework within the SDK folder of the player SDK demo.

1. Set the Picture-in-Picture delegate.

   /**
   * @brief Sets the delegate for Picture-in-Picture events.
   */
   -(void) setPictureinPictureDelegate:(id<AliPlayerPictureInPictureDelegate>)delegate;
   
   
   // Set the Picture-in-Picture delegate.
   [self.player setPictureinPictureDelegate:self];

2. Add properties and implement the delegate methods.

   1. Add properties to your view controller to manage the state of the player and the Picture-in-Picture window.

      #import "YourUIViewController.h"
      #import <AliyunPlayer/AliyunPlayer.h>
      
      @interface YourUIViewController () <AVPDelegate, AliPlayerPictureInPictureDelegate>
      // The player instance.
      @property (nonatomic, strong) AliPlayer *player;
      // The container view for the player.
      @property (nonatomic, strong) UIView *playerView;
      // Tracks whether the Picture-in-Picture window is paused.
      @property (nonatomic, assign) BOOL isPipPaused;
      // Tracks the current playback status of the player, updated by the onPlayerStatusChanged:oldStatus:newStatus: callback.
      @property (nonatomic, assign) AVPStatus currentPlayerStatus;
      // A weak reference to the picture-in-picture controller. This is set in the pictureInPictureControllerWillStartPictureInPicture: callback and should be set to nil before the view controller is deallocated. Using a weak reference is recommended.
      @property (nonatomic, weak) AVPictureInPictureController *pipController;
      // Tracks playback progress, updated by the 'position' parameter in the playback progress callback.
      @property (nonatomic, assign) int64_t currentPosition;
      
      @end

      Note

      The pipController property must be declared with a weak or assign attribute to prevent retain cycles. If you use assign, manually set the property to nil at the appropriate time.

   2. In your onPlayerStatusChanged: delegate method, notify the picture-in-picture controller to update its state.

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

   3. In your onPlayerEvent: delegate method, update the Picture-in-Picture state in response to playback events.

      - (void)onPlayerEvent:(AliPlayer*)player eventType:(AVPEventType)eventType {
          if (eventType == AVPEventCompletion) {
            if (_pipController) {
             self.isPipPaused = YES; // When playback finishes, set the PiP state to paused.
             [self.pipController invalidatePlaybackState];
          }
        } else if (eventType == AVPEventSeekEnd) {
          // The seek operation is complete.
            if (_pipController) {
             [self.pipController invalidatePlaybackState];
          }
        }
      }

   4. Implement the delegate methods.

      • Implement the callback for when Picture-in-Picture is about to start.

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

      • Implement the callback for when Picture-in-Picture is about to stop.

        /**
         @brief Tells the delegate that Picture-in-Picture is about to stop.
         @param pictureInPictureController The picture-in-picture controller.
         */
        - (void)pictureInPictureControllerWillStopPictureInPicture:(AVPictureInPictureController *)pictureInPictureController {
            self.isPipPaused = NO;
          [pictureInPictureController invalidatePlaybackState];
        }

      • Implement the callback to restore the UI before Picture-in-Picture stops.

        /**
         @brief Tells the delegate to restore the user interface before Picture-in-Picture stops.
         @param pictureInPictureController The picture-in-picture controller.
         @param completionHandler A completion handler to call with YES to allow the system to complete the restoration.
         */
        - (void)pictureInPictureController:(AVPictureInPictureController *)pictureInPictureController restoreUserInterfaceForPictureInPictureStopWithCompletionHandler:(void (^)(BOOL restored))completionHandler {
            if (_pipController) {
              _pipController = nil;
          }
          completionHandler(YES);
        }

      • Implement the callback that provides the playable time range.

        /**
         @brief Asks the delegate for the current playable time range.
         @param pictureInPictureController The picture-in-picture 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);
            }
        }

      • Implement the callback that reports whether playback is paused.

        /**
         @brief Asks the delegate whether playback is currently paused.
         @param pictureInPictureController The picture-in-picture controller.
         @return A Boolean value indicating whether playback is paused.
         */
        - (BOOL)pictureInPictureControllerIsPlaybackPaused:(nonnull AVPictureInPictureController *)pictureInPictureController{
            return self.isPipPaused;
        }

        Note

        This callback is invoked before Picture-in-Picture starts. It must return false at this point for the PiP window to launch. Returning true prevents Picture-in-Picture from starting.

      • Implement the callback to handle skip forward and skip backward actions from the Picture-in-Picture controls.

        /**
         @brief Tells the delegate that the user has requested to skip forward or backward.
         @param pictureInPictureController The picture-in-picture controller.
         @param skipInterval The time interval to skip.
         @param completionHandler A completion handler that you must call after the seek 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];
        }

      • Implement the callback to handle play and pause actions from the Picture-in-Picture controls.

        /**
         @brief Tells the delegate that the user has toggled the play/pause button.
         @param pictureInPictureController The picture-in-picture controller.
         @param playing A Boolean value indicating whether playback should start.
         */
        - (void)pictureInPictureController:(nonnull AVPictureInPictureController *)pictureInPictureController setPlaying:(BOOL)playing {
            if (!playing){
              [self.player pause];
              self.isPipPaused = YES;
            } else {
              // Tip: If you want the play button to restart the video after playback completes, add the following block.
              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

Picture-in-picture is out-of-app by default. To implement in-app picture-in-picture, first call the following interface to check if picture-in-picture is active:

/**
 @brief Tells the delegate whether picture-in-picture is enabled.
 @param pictureInPictureController The picture-in-picture controller reporting its state.
 @param isEnable `YES` if picture-in-picture is enabled; `NO` otherwise.
 */
- (void)pictureInPictureControllerIsPictureInPictureEnable:(nullable AVPictureInPictureController *)pictureInPictureController isEnable:(BOOL)isEnable;

To disable automatic startup and switch to manual activation while picture-in-picture is running, use the following sample code:

- (void) pictureInPictureControllerIsPictureInPictureEnable:(nullable AVPictureInPictureController *) pictureInPictureController isEnable:(BOOL) isEnable
{
    if (isEnable && pictureInPictureController) {
        _pipController = pictureInPictureController;
        // Disable 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 {
        // Stop pip.
        [_pipController stopPictureInPicture];
    }
}

// Set the output audio channel using an AVPOutputAudioChannel enumeration value.
// AVP_AUDIO_CHANNEL_NONE: Plays the original audio channels from the input source. This is the default value.
// AVP_AUDIO_CHANNEL_LEFT: Plays only the left audio channel.
// AVP_AUDIO_CHANNEL_RIGHT: Plays only the right audio channel.
self.player.outputAudioChannel = AVP_AUDIO_CHANNEL_NONE;

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

// The parameter is an 8-digit hexadecimal value in ARGB format (alpha, red, green, blue).
// For example, 0x0000ff00 represents green.
[self.player setVideoBackgroundColor:0x0000ff00]

/**
 @brief Play a video by using the video ID and playback credential (PlayAuth). For more information, see: https://www.alibabacloud.com/help/en/vod/user-guide/use-playback-credentials-to-play-videos
 @param source An AVPVidAuthSource object.
 @see AVPVidAuthSource
 */
- (void)setAuthSource:(AVPVidAuthSource*)source;

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

// Set to 1 to enable background decoding or 0 to disable it. Default: 0.
[self.player setOption:ALLOW_DECODE_BACKGROUND valueInt:1];

// Replace x.x.x with the version of your Player SDK.
pod 'AliPlayerSDK_iOS_VVC_CODEC_PLUGIN', 'x.x.x'

// Replace x.x.x with the version of your all-in-one SDK.
pod 'AliVCSDK_Standard/AliPlayerSDK_iOS_VVC_CODEC', 'x.x.x'

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

/**
 @brief Sets the callback for VidAuth source expiration notifications.

 This callback is triggered when the player detects that the current VidAuth source has expired. A VidAuth source expires if its PlayAuth or playback URL has expired.
 You can refresh the VidAuth source in this callback and pass the new object via the `callback` parameter to ensure smooth playback.

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

/**
 @protocol AVPSourceRefreshCallback
 @brief A protocol for handling the results of a source refresh, which you must implement.

 This protocol notifies your application when the player requests a source refresh, such as when a resource
 has expired or needs to be updated. The methods in this protocol are called to provide the refresh results,
 including success or failure.

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

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

 This method indicates that the refresh operation has been successfully completed. You must pass
 the updated `newSource` back to the player so that it can load the new 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. You can use `errorMsg` to capture failure
 details and handle the error accordingly.
 */
- (void)onError:(NSString *)errorMsg;

@end

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

        // ------------------- Start of user implementation -------------------
        // Call your custom function to retrieve a new PlayAuth from your app server.
        // clinetGetPlayAuthFunction is a sample function name. Replace it with your actual implementation.
        [self clinetGetPlayAuthFunction:vidAuth.vid success:^(NSString* newPlayAuth){
            // 1. In the success callback, after retrieving the new credential:
            [vidAuth setPlayAuth:newPlayAuth];
            // 2. Pass the updated source object back to the player via the SDK's callback.
            [callback onSuccess:vidAuth];
        } failure:^(NSString* errorMsg) {
            // In the failure callback.
            // errorMsg contains details about the error.
            [callback onError:errorMsg];
        }];
        // ------------------- End of user implementation -------------------
    }
}];

/**
 @brief Sets the callback for URL source expiration notifications.

 This callback is triggered when the player detects that the current URL source has expired.
 You can refresh the URL source in this callback and return the new URL source via the `callback` parameter to ensure continuous playback.

 @note For more information about how to configure URL signing, see the Alibaba Cloud documentation:
 https://www.alibabacloud.com/help/en/vod/user-guide/configure-url-signing
 
 @param callback The callback block triggered when the URL source expires.
 You can 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 the results of a source refresh, which you must implement.

 This protocol notifies your application when the player requests a source refresh, such as when a resource
 has expired or needs to be updated. The methods in this protocol are called to provide the refresh results,
 including success or failure.

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

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

 This method indicates that the refresh operation has been successfully completed. You must pass
 the updated `newSource` back to the player so that it can load the new 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. You can use `errorMsg` to capture failure
 details and handle the error accordingly.
 */
- (void)onError:(NSString *)errorMsg;

@end

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

        // Check if the URL 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 authentication parameters: the authKey and the expiration time.
        // Use the authKey class member if it is valid.
        NSString *key = (self.authKey.length > 0) ? self.authKey : @"";
        if (!NOT_EMPTY(key)) {
            [callback onError:@"REFRESH_ERROR:key fail"];
            return;
        }       
        
        // Use the validTime class member if it is valid; otherwise, use a default value.
        NSTimeInterval validTime = (self.validTime > 0) ? self.validTime : 3600; // Default: 3600 seconds.
        NSTimeInterval newExpireTime = [[NSDate date] timeIntervalSince1970] + validTime;

         // 3. Generate a new signed URL with CdnAuthUtil (Method 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

// x.x.x must match the version of the player SDK.
pod 'AliPlayerSDK_iOS_AUDIO_ENHANCE_FILTER', 'x.x.x'

[player setFilterValid:@"audioEnhance" valid:YES];  // Enable
[player setFilterValid:@"audioEnhance" valid:NO];   // Disable

AVPFilterConfig *filterConfig = [[AVPFilterConfig alloc] init];
AVPFilter *filterItem = [[AVPFilter alloc] initWithTarget:@"audioEnhance"];
AVPFilterOptions *opts = [[AVPFilterOptions alloc] init];
// Surround sound
[opts setOptions:@"enable_surround" value:@YES];
[opts setOptions:@"surround_effect_type" value:@"3DSurround"]; // The type must be set when you first enable surround sound.
// Dialogue enhancement
[opts setOptions:@"enable_dialoguenhance" value:@YES];
[opts setOptions:@"dialoguenhance_voice" value:@(1.0)]; // Range: 1.0 to 10.0. The voice level must be set when you first enable dialogue enhancement.
// Volume normalization
[opts setOptions:@"enable_normalizer" value:@YES];

[filterItem setOptions:opts];
[filterConfig addFilter:filterItem];
[player setFilterConfig:filterConfig];

AVPFilterOptions *opts = [[AVPFilterOptions alloc] init];
[opts setOptions:@"enable_surround" value:@YES];
[opts setOptions:@"surround_effect_type" value:@"3DSurround"]; // The type can only be set when enabling surround sound for the first time. It is ignored on subsequent calls because the filter is already initialized.
[player updateFilterConfig:@"audioEnhance" options:opts];

Performance

Set a player scene

Setting a player scene automatically applies the optimal parameters for that scenario, such as buffer settings and feature toggles. Custom parameters that you set with the setConfig method override the scene defaults.

API example

/**
 @brief Sets the player scene.
 @param scene The player scene.
 @see AVPScene
 */
-(void) setPlayerScene:(AVPScene)scene;

Player scenes

typedef enum _AVPScene {
    /**
     * No specific scene is set.
     */
    SceneNone,
    /**
     * Long video scene, suitable for videos over 30 minutes.
     */
    SceneLong,
    /**
     * Medium video scene, suitable for videos between 5 and 30 minutes.
     */
    SceneMedium,
    /**
     * Short video scene, suitable for videos up to 5 minutes.
     */
    SceneShort,
    /**
     * Live streaming scene.
     */
    SceneLive,
    /**
     * RTS live scene.
     */
    SceneRTSLive
} AVPScene;

Usage

// 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 cache

The Alibaba Cloud Player SDK for iOS provides a local cache feature. This feature improves startup speed and seek speed, reduces stuttering, and saves network traffic during repeated playback.

Enable local cache

/**
 * Enables the local cache. When enabled, content is cached to local files.
 * @param enable A boolean value that specifies whether to enable the local cache. true: enabled, false: disabled. Default value: false.
 * @param maxBufferMemoryKB This parameter is deprecated in v5.4.7.1 and later and has no effect.
 * @param localCacheDir The directory for local cache files. You must specify an absolute path.
 */
[AliPlayerGlobalSettings enableLocalCache:true maxBufferMemoryKB:1024 localCacheDir:@""];

/**
 @brief Configures the automatic cleanup of local cache files.
 @param expireMin This parameter is deprecated in v5.4.7.1 and later and has no effect.
 @param maxCapacityMB The maximum cache size in MB. Default value: 20 GB. During cleanup, if the total cache size exceeds this limit, the oldest cache items are deleted one by one until the total size is within the limit.
 @param freeStorageMB The minimum free disk space in MB. Default value: 0. During cleanup, if the available disk space is less than this value, cache files are deleted one by one until the free space is equal to or greater than this value, or until all cached files are deleted.
 */
[AliPlayerGlobalSettings setCacheFileClearConfig:0 maxCapacityMB:0 freeStorageMB:0];

/**
 * A callback to get the hash value of a URL. This value is used as the unique ID for the URL. You must ensure that each URL has a unique hash value.
 */

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

[AliPlayerGlobalSettings setCacheUrlHashCallback:&CaheUrlHashHandle];

Enable or disable cache for a URL

// Get the configuration.
AVPConfig *config = [self.player getConfig];
// Specifies whether to enable local caching for the playback URL. Default value: true.
// To enable local caching for this URL, both this setting and the global setting in AliPlayerGlobalSettings must be enabled.
// If this is set to false, local caching is disabled for this URL.
config.enableLocalCache = false;
....// Other settings

// Apply the configuration to the player.
[self.player setConfig:config];

[AliPlayerGlobalSettings enableLocalCache:true];

Preloading

The Alibaba Cloud Player SDK for iOS provides a preloading feature, which is an enhancement to the local cache. Preloading downloads a portion of a video into the cache before playback begins, improving startup speed.

[AliPlayerGlobalSettings enableNetworkBalance:false];

1. Enable the local cache feature as described in Local cache.

2. Set the data source.

   VidAuth (recommended)

   AVPVidAuthSource* vidAuthSource = [[AVPVidAuthSource alloc] init];
   [vidAuthSource setVid:@"your_video_id"]; // Required. The video ID.
   [vidAuthSource setPlayAuth:@"<yourPlayAuth>"]; // Required. The playback credential. You must call the GetVideoPlayAuth operation of ApsaraVideo for VOD to generate the credential.
   [vidAuthSource setRegion:@"your_region"]; // This parameter is deprecated in SDK v5.5.5.0 and later. The player automatically parses the region. For earlier versions, this parameter is required and defaults to cn-shanghai.
   [vidAuthSource setQuality:@"AUTO"]; // "AUTO" enables adaptive bitrate streaming.

   VidSts

   AVPVidStsSource* vidStsSource = [[AVPVidStsSource alloc] init];
   [vidStsSource setVid: @""]; // Required. The video ID.
   [vidStsSource setRegion:@""]; // Required. The region where ApsaraVideo VOD is activated. Default value: cn-shanghai.
   [vidStsSource setSecurityToken: @"<yourSecurityToken>"]; // Required. The STS security token. You must call the AssumeRole API operation of STS to obtain the token.
   [vidStsSource setAccessKeySecret: @"<yourAccessKeySecret>"]; // Required. The AccessKey secret of the temporary STS AccessKey pair. You must call the AssumeRole API operation of STS to obtain the AccessKey secret.
   [vidStsSource setAccessKeyId: @"<yourAccessKeyId>"]; // Required. The AccessKey ID of the temporary STS AccessKey pair. You must call the AssumeRole API operation of STS to obtain the AccessKey ID.
   [vidStsSource setQuality:@""]; // "AUTO" specifies adaptive bitrate streaming.

   UrlSource

   NSString* url = @"your_playback_url"; // Required. The playback URL. It can be a third-party VOD URL or a playback URL from ApsaraVideo for VOD.
   AVPUrlSource* urlSource = [[AVPUrlSource alloc]urlWithString:url];

3. Set task parameters.

   Note

   These parameters apply only to multi-bitrate videos. You need to set only one of setDefaultBandWidth, setDefaultResolution, and setDefaultQuality.

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

4. Add a task listener.

   Code example

   @interface YourViewController () <OnPreloadListener>
   
   @property(nonatomic,strong) AliMediaLoaderV2* vodMedialoader; // The preloader.
   @property(nonatomic,strong) AVPVidAuthSource* vidSource; // The VidAuth data source.
   @property(nonatomic,strong) AVPUrlSource* urlSource; // The UrlSource data source.
   @property(nonatomic,strong) AVPVidStsSource* vidStsSource; // The 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 error occurred: %@", urlOrVid);
   }
   
   - (void)onCanceled:(NSString *)taskId urlOrVid:(NSString *)urlOrVid {
       NSLog(@"Task canceled: %@", urlOrVid);
   }
   
   @end

5. Build the task, add it to the MediaLoaderV2 instance, and 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 ID.
   [vodMedialoader pauseTask:taskId];// Pause the preload task with the specified ID.
   [vodMedialoader resumeTask:taskId];// Resume the preload task with the specified ID.

7. Optional: Delete loaded files.

   To save space, you can delete cached files. Because the Alibaba Cloud Player SDK for iOS does not provide a deletion interface, you must manually delete files from the cache directory within your app.

Dynamic preloading

The dynamic preloading strategy lets you control caching for the current video and the number of videos to preload. This helps you balance the playback experience with cost.

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

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

// Configure the number of items to preload. This supports preloading in both directions.
// 1 is the number of previous items to preload, and 3 is the number of next items to preload.
[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 configuration. Plays and preloads the default bitrate.
     */
    AVPMultiBitratesMode_Default = 0,
    /**
     * Prioritizes a fast time to first frame. The player starts by playing the bitrate that has finished preloading.
     */
    AVPMultiBitratesMode_FCPrio = 1,
    /**
     * Balances a fast time to first frame with smooth playback. The player attempts to play the same bitrate before and after a `moveToNext` call.
     */
    AVPMultiBitratesMode_FC_AND_SMOOTH = 2,
    /**
     * Prioritizes smooth playback. The player attempts to start the next video at the same bitrate as the previous one.
     */
    AVPMultiBitratesMode_SmoothPrio = 3,
} AVPMultiBitratesMode;

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

// Optional: Select the startup bitrate.
[self.listPlayer setDefaultBandWidth:defaultBandWidth];

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

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]. The port is optional. Use semicolons (;) to separate multiple domain names.
// Global setting.
// This is an absolute setting. Each time you call this method, the new string replaces the previous one. An empty string disables pre-connection.
[AliPlayerGlobalSettings setOption:SET_PRE_CONNECT_DOMAIN value: @"domain1;domain2"];

Video download

The ApsaraVideo Player SDK for iOS lets you download ApsaraVideo VOD content for offline playback. The SDK offers two download modes: standard download and secure download.

• Standard download: The downloaded video data is not encrypted by Alibaba Cloud and can be played using third-party players.

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

Usage

• The video download feature is available only for VidSts and VidAuth sources.

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

• The video download feature supports resumable downloads.

Procedure

1. Optional: Configure the key file for secure download. This step is required only for secure download.

   Note

   Ensure that the information in the configured key file matches your app's information. Otherwise, the video download will fail.

   If you use the secure download mode, you must configure the ApsaraVideo Player SDK with the key file that you generated in the ApsaraVideo VOD console. This file is used for decryption and verification during video download and playback. For instructions on how to generate the key file, see Enable secure download.

   Perform this configuration only once in your application, as shown in the following example:

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

2. Create and configure 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 supports multiple event listeners. The following code provides an example:

   -(void)onPrepared:(AliMediaDownloader *)downloader mediaInfo:(AVPMediaInfo *)info {
       // A download item is successfully prepared.
   }
   -(void)onError:(AliMediaDownloader *)downloader errorModel:(AVPErrorModel *)errorModel {
       // An error occurred during download.
   }
   -(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.

   Call the prepare method to prepare the download source. VidSts and VidAuth sources are supported. The following code provides an example:

   • VidSts

     // Create a VidSts source.
     AVPVidStsSource* stsSource = [[AVPVidStsSource alloc] init];
     stsSource.region = @"your_region"; // Your ApsaraVideo VOD service region. Default value: cn-shanghai.
     stsSource.vid = @"your_video_id"; // The video ID.
     stsSource.securityToken = @"<yourSecurityToken>"; // The STS security token. To get this token, call the STS AssumeRole operation.
     stsSource.accessKeySecret = @"<yourAccessKeySecret>"; // The AccessKey secret of the temporary STS credential. To get this secret, call the STS AssumeRole operation.
     stsSource.accessKeyId = @"<yourAccessKeyId>"; // The AccessKey ID of the temporary STS credential. To get this ID, call the STS AssumeRole operation.
     
     // If you have enabled parameter pass-through for HLS encryption in the ApsaraVideo VOD console
     // and the default parameter name is MtsHlsUriToken, you must set the config and pass it to the VidSts source.
     // If this feature is not enabled, you can skip the following code.
     VidPlayerConfigGenerator* vp = [[VidPlayerConfigGenerator alloc] init];
     [vp setHlsUriToken:yourMtsHlsUriToken];
     stsSource.playConfig = [vp generatePlayerConfig];
     // Prepare the download source.
     [downloader prepareWithVid:stsSource];

   • VidAuth

     // Create a VidAuth source.
     AVPVidAuthSource *authSource = [[AVPVidAuthSource alloc] init];
     authSource.vid = @"your_video_id"; // The video ID.
     authSource.playAuth = @"<yourPlayAuth>"; // The playback credential. To get this credential, call the ApsaraVideo VOD GetVideoPlayAuth operation.
     authSource.region = @"your_region"; // Deprecated in ApsaraVideo Player SDK V5.5.5.0 and later because the player automatically parses the region.
     // Required for earlier versions.
     // Your ApsaraVideo VOD service region. Default value: cn-shanghai.
     // If you have enabled parameter pass-through for HLS encryption in the ApsaraVideo VOD console
     // and the default parameter name is MtsHlsUriToken, you must set the config and pass it to the VidAuth source.
     // If this feature is not enabled, you can skip 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 enable parameter pass-through for HLS encryption in the ApsaraVideo VOD console and the default parameter name is MtsHlsUriToken, you must set the MtsHlsUriToken value in the download source as shown in the code above. For more information, see parameter pass-through for HLS encryption.

5. Select a video track after the source is prepared.

   After the download source is prepared, the onPrepared method is called. The mediaInfo parameter of the callback contains information about each available video track, such as video quality. 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, to download the first track:
       [downloader selectTrack:[tracks objectAtIndex:0].trackIndex];
   }

6. Update the download source and start the download.

   To prevent VidSts and VidAuth credentials from expiring, we recommend updating the 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. Release the downloader after the download completes or fails.

   Call the destroy method to release the downloader.

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

Encrypted playback

ApsaraVideo VOD supports HLS standard encryption, Alibaba Cloud proprietary encryption, and DRM encryption. Live video supports only DRM encryption. For more information, see Encrypted playback.

Native RTS playback

The iOS player SDK integrates the Native RTS SDK to enable low-latency live streaming. For more information, see Implement RTS-based stream pulling on iOS.

References

• API reference

• Mobile error codes

• iOS player FAQ