Custom configuration-ApsaraVideo VOD(VOD)-阿里云帮助中心

Custom configuration is an extension mechanism for AliPlayerKit. AliPlayerKit provides built-in configurations based on best practices, ensuring a high-quality experience in most scenarios without extra setup. If a player feature you need is not exposed through the AliPlayerKit interface, use custom configuration to call the underlying AliPlayer SDK APIs.

Prerequisites

To use custom configuration, you must call the native APIs of the flutter_aliplayer library directly. Although the aliplayer_widget package already includes this library as a dependency, we recommend declaring it explicitly in your project to ensure you can import and use its APIs correctly:

# pubspec.yaml
dependencies:
  aliplayer_widget: <latest_version>

  # Explicitly declare the dependency for custom configurations.
  flutter_aliplayer: <latest_version>

Configuration levels

AliPlayerWidget provides two levels of custom configuration with different degrees of granularity:

Level	API	Timing	Typical scenarios
global configuration	`AliPlayerWidgetGlobalSetting.setOnGlobalInit`	After the one-time global initialization is complete.	Global behaviors such as setOption and mediaLoader.
instance configuration	`AliPlayerWidgetData.onPlayerConfig`	Before `prepare()` is called for each player instance.	Instance-level behaviors such as setPlayConfig (buffering, Referer) and setOption.

Note

The underlying player SDK supports both global and instance configurations. AliPlayerWidget builds on this by providing best-practice defaults and these two callback entry points to access unexposed native APIs directly on the player instance.

Global configuration: setOnGlobalInit

Use cases

Set global options, such as the global log level.
Configure mediaLoader for custom media loading logic.
Set other global behaviors that must take effect before any player instances are created.

Usage

import 'package:aliplayer_widget/aliplayer_widget_lib.dart';
import 'package:flutter_aliplayer/flutter_aliplayer.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();

  // Register the global custom configuration callback (call before setupConfig).
  AliPlayerWidgetGlobalSetting.setOnGlobalInit(() {
    // Example: Set a global option.
    FlutterAliPlayerGlobalSettings.setOption(
      AliPlayerGlobalSettings.ENABLE_H2_MULTIPLEX, 1,
    );
  });

  // Initialize global settings (this triggers the registered callback internally after initialization).
  AliPlayerWidgetGlobalSetting.setupConfig();

  runApp(const MyApp());
}

Timing

The callback is triggered once, after the global initialization inside setupConfig() is complete. At this point, the underlying SDK is ready, and you can safely call its global APIs.

Notes

Call setOnGlobalInit before setupConfig() to ensure the callback is triggered.
The global configuration is applied only once. Subsequent calls to setupConfig() will not trigger the callback again.

Instance configuration: onPlayerConfig

Use cases

Customize the buffering strategy, such as setting maxBufferDuration and highBufferDuration.
Set the Referer for hotlinking protection.
Configure HTTP headers.
Set instance-level options.
Call other player APIs not directly exposed by AliPlayerWidget.

Usage

Pass the callback to the onPlayerConfig parameter when creating an AliPlayerWidgetData object:

final data = AliPlayerWidgetData(
  videoSource: videoSource,
  videoTitle: "Video Title",
  onPlayerConfig: (player) async {
    // Example 1: Customize the buffering strategy and Referer.
    var config = await player.getPlayConfig();
    config.maxBufferDuration = 50000;        // Maximum buffer duration: 50,000 ms (50s)
    config.highBufferDuration = 3000;        // High watermark for buffering: 3,000 ms (3s)
    config.startBufferDuration = 500;        // Buffer duration before playback starts: 500 ms
    config.referer = "https://your-domain.com";  // Set the Referer for hotlinking protection.
    await player.setPlayConfig(config);

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

// Configure and play.
controller.configure(data);

Timing

The callback is triggered before the player executes prepare(). At this point, the player instance has been created but has not yet started loading or playing media. This is the ideal time to apply custom configurations. The callback is triggered every time controller.configure(data) is called.

Notes

This callback can be an asynchronous operation (using async/await). The widget awaits its completion before executing prepare().
The player parameter is a native FlutterAliplayer instance, which allows you to call any of its native APIs.
This callback is triggered every time controller.configure(data) is called, making it suitable for dynamic configuration scenarios.

FAQ

Execution order of global and instance configurations

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

Default behavior

By default, AliPlayerWidget uses built-in configurations based on best practices. Custom configuration is optional and only required for advanced scenarios.