API reference - ApsaraVideo VOD - Alibaba Cloud Documentation Center

AliPlayerWidget provides a comprehensive set of APIs for controlling the player's behavior. AliPlayerWidgetController exposes these APIs to support features such as playback control, status queries, and data updates.

Common APIs

Configuration and initialization

API name	Description
`configure`	Configures the data source and initializes the player.
`prepare`	Manually triggers the player preparation process.
`destroy`	Destroys the player instance and releases all associated resources.

Playback control

API name	Description
`play`	Starts video playback.
`pause`	Pauses playback.
`stop`	Stops playback and resets the player.
`seek`	Seeks to a specified playback position.
`togglePlayState`	Toggles the playback state between playing and paused.
`replay`	Replays the video. Typically used to restart playback after it finishes.

Playback properties

API name	Description
`setSpeed`	Sets the playback speed.
`setVolume`	Sets the volume.
`setVolumeWithDelta`	Adjusts the volume by a specified delta.
`setBrightness`	Sets the screen brightness. (The developer must implement the underlying logic.)
`setBrightnessWithDelta`	Adjusts the screen brightness by a specified delta. (The developer must implement the underlying logic.)
`setLoop`	Sets whether the video loops.
`setMute`	Sets whether the player is muted.
`setMirrorMode`	Sets the mirror mode, such as horizontal or vertical mirroring.
`setRotateMode`	Sets the rotation angle, such as 90° or 180°.
`setScaleMode`	Sets the scaling mode, such as stretch or crop.

Video quality switching

API name	Description
`selectTrack`	Switches the video quality.

Thumbnails

API name	Description
`requestThumbnailBitmap`	Requests a thumbnail for a specified timestamp.

Other features

Note

These APIs have been moved to AliPlayerWidgetGlobalSetting. Use them directly:

Version number: AliPlayerWidgetGlobalSetting.kWidgetVersion.
Clear caches: AliPlayerWidgetGlobalSetting.clearCaches().

Event notifications

AliPlayerWidgetController provides a series of ValueNotifier objects that deliver real-time notifications for player state changes and user interactions.

Playback state management

Notifier	Description
`playStateNotifier`	Notifies of changes to the playback state (e.g., playing, paused, or stopped).
`playErrorNotifier`	Notifies of playback errors, providing an error code and message.
`isRenderedNotifier`	Notifies when the first frame is rendered.

Playback progress management

Notifier	Description
`currentPositionNotifier`	Notifies of the current playback position in real time, in milliseconds.
`bufferedPositionNotifier`	Notifies of the buffering progress, indicating the range of cached content.
`totalDurationNotifier`	Notifies of the video's total duration, which can be used to calculate progress or display the video length.

Volume and brightness control

Notifier	Description
`volumeNotifier`	Notifies of volume changes. The level ranges from 0.0 to 1.0.
`brightnessNotifier`	Notifies of screen brightness changes. The level ranges from 0.0 to 1.0.
`speedNotifier`	Notifies of changes to the playback speed.

Playback property states

Notifier	Description
`isLoopNotifier`	Notifies of changes to the loop status.
`isMuteNotifier`	Notifies of changes to the mute status.
`mirrorModeNotifier`	Notifies of changes to the mirror mode.
`rotateModeNotifier`	Notifies of changes to the rotation angle.
`scaleModeNotifier`	Notifies of changes to the scaling mode.

Video quality and thumbnails

Notifier	Description
`currentTrackInfoNotifier`	Notifies of changes to the current video quality (e.g., SD, HD, or UHD) and provides details after a switch.
`trackInfoListNotifier`	Provides a list of all available video quality tracks.
`thumbnailNotifier`	Notifies of the thumbnail loading status, which allows for real-time previews when seeking.

Subtitles

Notifier	Description
`subtitleNotifier`	Notifies of changes to external subtitle information.
`subtitleTrackIndexNotifier`	Notifies of changes to the index of the current subtitle track.
`isSubtitleVisibleNotifier`	Notifies of changes to subtitle visibility.

Other states

Notifier	Description
`videoSizeNotifier`	Notifies of changes to the video dimensions.
`snapFileStateNotifier`	Notifies of changes to the snapshot file state.
`downloadStateNotifier`	Notifies of changes to the download state.

Usage

To update the UI or execute logic in real time, use a ValueListenableBuilder to listen for changes from a ValueNotifier.

// Listen for playback errors
ValueListenableBuilder<Map<int?, String?>?>(
  valueListenable: _controller.playErrorNotifier,
  builder: (context, error, _) {
    if (error != null) {
      final errorCode = error.keys.firstOrNull;
      final errorMsg = error.values.firstOrNull;
      return Text("Playback error: [$errorCode] $errorMsg");
    }
    return const SizedBox.shrink();
  },
);

API documentation

For detailed API documentation and usage instructions, see the official documentation on Pub:

Official source: API reference on pub.dev.
Domestic mirror: API reference on pub.flutter-io.cn.

The official documentation provides detailed descriptions for each API, including parameters, return values, and additional usage examples.