ApsaraVideo VOD:Strategy system

Built-in strategies

The system includes the following recommended strategies out of the box:

Usage

Using default strategies

Built-in strategies run automatically without any configuration:

final data = AliPlayerWidgetData(
  videoSource: videoSource,
);
controller.configure(data);

Replacing a built-in strategy

To retrieve runtime data, replace a default built-in strategy by registering a new instance with the same name using the register() method. This allows you to provide callbacks:

controller.strategyManager
  ..register(FirstFrameStrategy(
    onPrepared: (cost) {
      print('Time to prepare: ${cost.inMilliseconds}ms');
    },
    onFirstFrame: (cost) {
      print('Time to first frame: ${cost.inMilliseconds}ms');
    },
  ))
  ..register(StutterDetectStrategy(
    onStutterDetected: (info) {
      print('Stutters: ${info.stutterCount}, Stutter Rate: ${(info.stutterRate * 100).toStringAsFixed(1)}%');
    },
  ));

Registering a custom strategy

Register a custom strategy instance with a unique name using register() to extend the player's behavior:

controller.strategyManager.register(ResumePlayStrategy(
  onPositionSaved: (position) {
    print('Position saved: ${position.inSeconds}s');
  },
));

Managing strategies

Use strategyManager to remove strategies at runtime:

// Remove a strategy by name
controller.strategyManager.unregister('MyCustomStrategy');

// Remove all strategies
controller.strategyManager.clear();

Custom strategy development

Extending BasePlayerStrategy

Create a custom strategy by extending BasePlayerStrategy. The framework automatically manages the listener lifecycle:

class MyCustomStrategy extends BasePlayerStrategy {
  @override
  String get name => 'MyCustomStrategy';

  @override
  void onStart(AliPlayerWidgetController controller) {
    // Subscribe to notifiers with listen(). The framework automatically cleans them up in onStop.
    listen<int>(controller.playStateNotifier, (state) {
      // Handle playback state changes
    });

    listen<Duration>(controller.currentPositionNotifier, (position) {
      // Handle playback position changes
    });
  }

  @override
  void onReset() {
    // Reset internal state when the video source changes (the strategy remains active)
  }
}

Lifecycle methods

Callback safety mechanism

Strategies typically use callbacks to report data externally, for example, to notify the UI of updates. When a strategy is stopped, the associated UI might have already been disposed. To prevent potential issues, the framework provides two layers of protection:

class ResumePlayStrategy extends BasePlayerStrategy {
  final void Function(Duration)? onPositionSaved;

  @override
  void onStop() {
    super.onStop();
    _savePosition();
  }

  void _savePosition() {
    // Persistence always runs (for data safety)
    storage.save(position);

    // Safely trigger the external callback with notify() (skipped if stopped)
    notify(onPositionSaved, position);
  }
}

Data sources and state signals

A strategy is essentially the basic organizational unit of business logic. Because it involves business logic, it inevitably involves data acquisition and processing. A strategy obtains a complete reference to the controller in onStart and can obtain the required data through various methods.

Observable state signals

Strategies subscribe to ValueNotifier objects on the controller by using the listen() method:

Other data sources

Strategies can also get data from any public API on the controller:

If the data you need does not have a corresponding Notifier, you can:

class MyCustomStrategy extends BasePlayerStrategy {
  late AliPlayerWidgetController _controller;

  @override
  String get name => 'MyCustomStrategy';

  @override
  void onStart(AliPlayerWidgetController controller) {
    _controller = controller;

    // Method 1: Use an existing Notifier to trigger an active query in the callback.
    listen<int>(controller.playStateNotifier, (state) {
      // When the playback state changes, actively query the current playback position.
      controller.getCurrentPosition().then((pos) {
        // ...handle business logic
      });
    });

    // Method 2: Read configuration information directly.
    final videoSource = controller.widgetData?.videoSource;
    // ...execute different logic based on the video source type.
  }
}

How the strategy system works

The strategy system operates through the following mechanisms:

1. Automatic registration: The StrategyManager registers recommended built-in strategies by default upon creation.

2. Lifecycle binding: Strategies are started with the controller's configure() method and destroyed with the destroy() method.

3. Exception isolation: An exception in one strategy does not affect the operation of other strategies.

4. Callback safety: The framework uses an isActive flag to ensure that external callbacks are not triggered after a strategy has stopped.

Practical example

See example/lib/pages/strategy/strategy_demo_page.dart for a complete example of using the strategy system, including a full implementation of a custom strategy for resuming playback.

The strategy system lets you encapsulate business concerns into independent strategies, which you can combine flexibly for different scenarios.