Custom configuration

Use cases

• Set global options, such as the global log level.

• Enable HTTP/2 multiplexing.

• Configure global behaviors that must apply before any player instance is created.

How it works

• Register the callback by using AliPlayerKit.setOnGlobalInit().

• The callback is triggered after the internal global initialization in AliPlayerKit.init() is complete. It is executed only once.

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

Usage

In Application.onCreate(), register the callback before calling AliPlayerKit.init():

public class MyApplication extends Application {

    @Overridepublic void onCreate() {
        super.onCreate();

        // 1. Register the global custom configuration callback (call before init).
        AliPlayerKit.setOnGlobalInit(() -> {
            // Example: Enable HTTP/2 multiplexing.
            AliPlayerFactory.setOption(
                AliPlayerGlobalSettings.ENABLE_H2_MULTIPLEX, 1
            );
            // Example: Set the global log level.
            // AliPlayerFactory.setOption(...);
        });

        // 2. Initialize the SDK (this triggers the registered callback internally after initialization is complete).
        AliPlayerKit.init(this);
    }
}

Usage notes

Use cases

• Custom buffer policy (maxBufferDuration, highBufferDuration, etc.).

• Set the Referer for hotlink protection.

• Configure HTTP headers.

• Set instance-level options.

• Use other player APIs not directly exposed by AliPlayerKit.

How it works

• Use AliPlayerModel.Builder.onPlayerConfig() to pass in the callback.

• Triggered each time controller.configure(model) is called.

• The callback is executed after setDataSource() and before prepare().

• The callback parameter is an IMediaPlayer instance, which allows you to access all configuration capabilities of the underlying SDK.

Usage

When building the AliPlayerModel, pass the callback by using the onPlayerConfig() method:

AliPlayerModel model = new AliPlayerModel.Builder()
        .videoSource(videoSource)
        .onPlayerConfig(player -> {
            // Example 1: Customize buffering strategy and Referer
            PlayerConfig config = player.getPlayConfig();
            config.mMaxBufferDuration = 50000;                  // Max buffer duration: 50s
            config.mHighBufferDuration = 3000;                  // High-water mark buffer: 3s
            config.mStartBufferDuration = 500;                  // Startup buffer duration: 500ms
            config.mReferrer = "https://your-domain.com";       // Set Referer for hotlink protection
            player.setPlayConfig(config);

            // Example 2: Set an instance-level option
            player.setOption(AliPlayerGlobalSettings.ALLOW_PRE_RENDER, 1);
        })
        .build();

// Configure and start playback
controller.configure(model);

Usage notes

Global configuration sequence

Application.onCreate()
    │
    ├── AliPlayerKit.setOnGlobalInit(callback)   ← Register callback
    │
    └── AliPlayerKit.init(context)
            │
            ├── GlobalManager.initialize()    ← Underlying SDK initialization
            │
            └── callback.onGlobalInit()           ← Trigger global configuration callback (once only)

Instance configuration sequence

controller.configure(model)
    │
    ├── lifecycleStrategy.acquire()               ← Acquire player instance
    │
    ├── player.setDataSource(model)               ← Configure video source
    │
    ├── onPlayerConfig.onPlayerConfig(player)     ← Trigger instance configuration callback
    │
    └── player.prepare() / player.start()         ← Start playback

Complete lifecycle

┌──────────────────────────────────────────────────────────────────┐
│                       Application Startup                          │
│                                                                  │
│  setOnGlobalInit(callback)  ──→  init(context)                  │
│                                      │                           │
│                               GlobalManager                  │
│                                      │                           │
│                               callback.onGlobalInit() ← global configuration │
└──────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌──────────────────────────────────────────────────────────────────┐
│                      Player Instance Creation                    │
│                                                                  │
│  AliPlayerModel.Builder()                                        │
│      .videoSource(source)                                        │
│      .onPlayerConfig(callback)  ← Register instance configuration callback │
│      .build()                                                    │
│                                                                  │
│  controller.configure(model)                                     │
│      │                                                           │
│      ├── setDataSource(model)                                    │
│      ├── callback.onPlayerConfig(player)  ← instance configuration │
│      └── prepare() / start()                                     │
└──────────────────────────────────────────────────────────────────┘

Core interfaces

@FunctionalInterfacepublic interface OnGlobalInitCallback {
    /**
     * Configuration callback after global initialization is complete.
     */void onGlobalInit();
}

@FunctionalInterfacepublic interface OnPlayerConfigCallback {
    /**
     * Player custom configuration callback, called before prepare().
     *
     * @param player The player instance. Use this to access the underlying SDK's configuration capabilities.
     */void onPlayerConfig(@NonNull IMediaPlayer player);
}

Registration methods

Related files

Global and instance configuration order

The global configuration (setOnGlobalInit) is executed once when the application starts. The instance configuration (onPlayerConfig) is executed for each player instance before prepare(). These two configurations do not affect each other.

Omitting custom configurations

AliPlayerKit includes built-in best practices, so you can use it without any custom configuration in most scenarios.

Asynchronous operations in instance callback

This is not recommended. On Android, the callback is executed synchronously, and the execution of prepare() resumes only after 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 instance callback

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