ApsaraVideo VOD:Custom configuration

Key concepts

Three-level configuration system

AliPlayerKit's configuration system has three levels:

┌─────────────────────────────────────────────────────────┐
│              1. Global Configuration (OnGlobalInitBlock)              │
│         Executes once at app launch, affecting all player instances                │
├─────────────────────────────────────────────────────────┤
│              2. Model Configuration (AliPlayerModel)                 │
│         Sets playback parameters via properties each time configure: is called               │
├─────────────────────────────────────────────────────────┤
│           3. Player Configuration (onPlayerConfigBlock)               │
│       Provides a callback to the underlying player before prepare each time configure: is called          │
└─────────────────────────────────────────────────────────┘

Global configuration

Use cases

• Set global options, such as the global log level

• Enable HTTP/2 multiplexing

• Configure a global DNS resolution strategy

• Implement other global behaviors that must take effect before any player instances are created

How it works

• Register a callback block by using +[AliPlayerKit setOnGlobalInitBlock:].

• The callback is triggered once after +setup completes its internal initialization.

• After execution, the system sets the block to nil, and it will not trigger again.

• At this point, the underlying SDK is ready, and you can safely call global APIs.

Usage

In application:didFinishLaunchingWithOptions:, register the callback before you call +setup:

- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    // 1. Register the global custom configuration callback.
    //    This must be called before setup.
    [AliPlayerKit setOnGlobalInitBlock:^{
        // Example: Enable HTTP/2 multiplexing.
        [AliPlayerFactory setOption:ALLOW_H2_MULTIPLEX value:1];

        // Example: Set the global log level.
        // [AliPlayerFactory setLogLevel:AF_LOG_LEVEL_INFO];
    }];

    // 2. Initialize the SDK. This triggers the callback registered above
    //    after internal initialization is complete.
    [AliPlayerKit setup];

    return YES;
}

Configuration sequence

application:didFinishLaunchingWithOptions:
    │
    ├── [AliPlayerKit setOnGlobalInitBlock:block]   ← Register callback
    │
    └── [AliPlayerKit setup]
            │
            ├── [GlobalManager setup]    ← Initialize underlying SDK
            │
            ├── sInitialized = YES
            │
            └── block()                  ← Trigger global config callback (once only)

Usage notes

Player configuration

Use cases

• Customize the buffering strategy (for example, maxBufferDuration and highBufferDuration).

• Set Referer hotlink protection.

• Configure HTTP headers.

• Set instance-level options.

• Access other player interfaces not directly exposed by AliPlayerKit.

How it works

• Set a callback block on the AliPlayerModel.onPlayerConfigBlock property.

• The callback is triggered every time [controller configure:model] is called.

• The callback executes after setDataSource: and before prepare.

• The callback parameter is the underlying player instance, which conforms to the MediaPlayer protocol.

Usage

When building AliPlayerModel, set onPlayerConfigBlock:

VideoSource *source = [VideoSource urlSourceWithUrl:@"https://example.com/video.mp4"];
AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];

// Set the instance-level custom configuration callback
model.onPlayerConfigBlock = ^(id<MediaPlayer> player) {
    // Example 1: Customize the buffering strategy
    AVPConfig *config = [player getConfig];
    config.maxBufferDuration = 50000;       // Max buffer duration: 50s
    config.highBufferDuration = 3000;       // High watermark: 3s
    config.startBufferDuration = 500;       // Start buffer duration: 500ms
    [player setConfig:config];

    // Example 2: Set Referer hotlink protection
    AVPConfig *refConfig = [player getConfig];
    refConfig.referer = @"https://your-domain.com";
    [player setConfig:refConfig];

    // Example 3: Set an instance-level option
    // [player setOption:key value:value];
};

// Configure and play the video
[controller configure:model];

Configuration sequence

[controller configure:model]
    │
    ├── lifecycleStrategy.acquire()             ← Get player instance
    │
    ├── [mediaPlayer setDataSource:model]       ← Configure video source
    │
    ├── model.onPlayerConfigBlock(mediaPlayer)  ← Trigger player config callback
    │
    ├── [strategyManager start/reset]           ← Start strategy system
    │
    └── [mediaPlayer prepare]                   ← Start preparing for playback

Usage notes

Built-in configuration items

AliPlayerKit global configuration

By using the methods of the AliPlayerKit class, you can directly set the built-in configuration options:

AliPlayerModel player configuration

Instance-level configuration items set by the AliPlayerModel property:

AliPlayerController runtime configuration

Configurations that are dynamically adjusted at runtime by AliPlayerController:

Configuration priority

Priority rules

If the same item is configured at multiple levels, the settings are applied in the following order of precedence:

Player configuration (onPlayerConfigBlock) > AliPlayerModel properties > Global configuration > SDK default values

Configuration scope

Configuration example

Code example

// ===== Global configuration (in AppDelegate, once only) =====
- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    // Global custom configuration
    [AliPlayerKit setOnGlobalInitBlock:^{
        // Enable HTTP/2 multiplexing
        [AliPlayerFactory setOption:ALLOW_H2_MULTIPLEX value:1];
    }];

    // Initialize
    [AliPlayerKit setup];

    // Global built-in configuration (must be called after setup)
    [AliPlayerKit setLogLevel:LogLevelWarn];
    [AliPlayerKit enableConsoleLog:YES];

    return YES;
}

// ===== Player configuration (in the player view controller, for each playback) =====
- (void)startPlayback {
    VideoSource *source = [VideoSource urlSourceWithUrl:videoUrl];
    AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];

    // Model property configuration
    model.sceneType = SceneTypeVOD;
    model.videoTitle = @"Awesome Video";
    model.coverUrl = coverImageUrl;
    model.autoPlay = YES;
    model.hardwareDecode = YES;
    model.startTime = resumePosition; // Resume from last position

    // Instance-level custom configuration (for the underlying SDK)
    model.onPlayerConfigBlock = ^(id<MediaPlayer> player) {
        AVPConfig *config = [player getConfig];
        config.maxBufferDuration = 50000;
        config.highBufferDuration = 3000;
        config.startBufferDuration = 500;
        config.referer = @"https://your-domain.com";
        [player setConfig:config];
    };

    [_controller configure:model];
}

API quick reference

Global configuration API

Player configuration API

Related files

For a complete list of APIs, see the API Reference.

FAQ

Configuration execution order

Global configuration is executed once at application startup (in +setup ), and player configuration is executed during each configure: call before prepare. The two do not interfere with each other.

Default behavior

AliPlayerKit includes built-in configurations based on best practices, making it suitable for most use cases without requiring custom configuration.

Asynchronous operations in callbacks

This is not recommended. Callbacks are executed synchronously, which means the player will not continue to execute prepare until the callback is complete. If you perform a time-consuming operation in the callback, it will block the player's startup process.

Changing video source in callbacks

This is not recommended. The video source is already set by using setDataSource: before the callback. Modifying it in the callback may cause unexpected behavior. The player configuration callback should only be used to set playback parameters, such as the buffering strategy and Referer.

Calling setOnGlobalInitBlock: after setup

It will not take effect. The +setup method uses dispatch_once to ensure that it is executed only once. If a Block is set after the +setup method is called, the Block will never be triggered.

Log configuration timing

setLogLevel: and enableConsoleLog: must be called after +setup, because they operate directly on the LogHub singleton. However, setOnGlobalInitBlock: must be set before +setup.