aliplayer_widget

[7.14.0] - Strategy System, i18n, UI Theme & Slot System Enhancement

New Features

• Strategy System
  • Pluggable strategy architecture with custom strategy registration for playback behavior control.
  • Built-in first frame optimization and stutter detection strategies, ready to use out of the box.
  • Built-in resume play strategy that automatically resumes playback when the app returns to foreground.
• Internationalization (i18n) System
  • Built-in Chinese and English support, auto-syncs with system language.
  • Runtime language switching without restart.
  • Custom language pack registration (e.g., Japanese, Korean) by implementing PlayerTranslations interface.
  • Translation override mechanism to modify built-in text.
  • Integrates with Flutter's LocalizationsDelegate for seamless MaterialApp integration.
• UI Theme System
  • Production-ready UI design with unified design tokens (colors, fonts, sizes, spacing via PlayerStyles).
  • Custom skin support via assetsPath parameter — replace all player icons with your own assets.
• UI Enhancements
  • Redesigned player UI with production-ready visuals, no additional UI restoration needed.
• Player Configuration
  • Android view type configuration support (AndroidViewType).
  • Optimized playback experience for different scenarios.

Improvements

• Fullscreen Optimization
  • Refactored fullscreen to single-instance architecture for better stability and resource management.
  • Simplified fullscreen toggle logic with landscape top bar layout optimization.
• Slot System
  • Slots now support custom ordering and insertion at any level, making UI orchestration more flexible.
  • Slot builder signature simplified to single parameter (BuildContext context).
  • overlays parameter deprecated, unified migration to slot system.

Documentation Updates

• Added custom configuration guide.
• Clarified flutter_aliplayer dependency version requirements.
• Added strategy system documentation.

Example Updates

• Added internationalization (i18n) demo page.
• Added short-video right-side action buttons overlay example.
• Added watermark slot example.
• Added resume play strategy example.

[7.12.2] - Slot Builder Controller Parameter & Fullscreen Improvements

New Features

• Slot Builder Controller Parameter for Fullscreen Support

  • Introduced SlotWidgetBuilderWithController type that passes the current AliPlayerWidgetController instance to slot builders.
  • Enables custom slot UI to correctly control the player in fullscreen mode.
  • The new signature: Widget Function(BuildContext context, AliPlayerWidgetController controller).
  • Backward Compatible: Old single-parameter SlotWidgetBuilder is still supported but deprecated. Automatic signature detection ensures seamless migration.

• Custom Configuration Callbacks

  • Added OnGlobalInitCallback via AliPlayerWidgetGlobalSetting.setOnGlobalInit, called after global initialization for custom global settings (e.g., setOption).
  • Added OnPlayerConfigCallback via AliPlayerWidgetData.onPlayerConfig, called before prepare() for per-instance player configuration (e.g., setConfig, setOption). Supports async operations (FutureOr<void>).
  • Enables customers to configure player APIs not directly exposed by AliPlayerWidget within the best-practice configuration flow.

Improvements

• Simplified Fullscreen Toggle Logic
  • Refactored fullscreen toggle logic for better maintainability.
  • Unified system UI handling across portrait and landscape modes.

Bug Fixes

• Documentation Language Switching
  • Fixed case-insensitive language switching in the documentation site.

Documentation Updates

• README Simplification

  • Removed inline code examples from README.md and README-EN.md, directing users to the Quick Start Guide for complete implementation details.
  • Improved example READMEs with structured scenario descriptions (core features, implementation points, execution effects).

• Quick Start Guide Enhancement

  • Updated to use recommended VidAuth video source instead of URL-based source.
  • Added const constructors for better performance.

• Core Components Restructure

  • Reorganized with numbered sections for improved readability and navigation.

• Video Source Documentation

  • Reordered to highlight VidAuth as the recommended playback method.
  • Clarified the advantages and use cases of each video source type.

• Global Configuration Clarification

  • Emphasized default optimal settings.
  • Clarified usage notes for custom configuration scenarios.

[7.12.1] – Fine-Grained Slot Element Control

New Features

• SlotType.centerDisplay: Control visibility of volume, brightness, and speed indicators
• SlotType.playState: Control visibility of error icon and error message
• SlotType.seekThumbnail: Control visibility of thumbnail image and time text
• SlotType.playControl: Disable specific gesture interactions

Notes

• This feature only works with default slot UI
• If a slotBuilders is configured for a slot, hiddenSlotElements for that slot will not take effect
• PlayControlElements is used to disable gesture interactions, not hide UI elements.

[7.12.0] – Custom Back Press Callback & Documentation Improvements

🚀 New Feature: Custom Back Press Callback

In previous versions, AliPlayerWidget handled the system back button event by default. However, many use cases—such as showing an exit confirmation or navigating to a specific route—require developers to intercept and customize this behavior, which wasn’t possible before. To address this, we’ve added a new onBackPressed callback parameter to AliPlayerWidget, giving you full control over the back press behavior.

How it works:

• The onBackPressed callback is triggered whenever the user presses the back button while the player is active.
• Return true → Event is handled; default navigation (Navigator.pop()) is prevented.
• Return false or null → Default behavior (Navigator.pop()) is executed.

Enable advanced use cases like:

• ✅ Showing a confirmation dialog before exiting full-screen playback
• ✅ Navigating to a specific route (e.g., home feed) instead of simply popping the current screen
• ✅ Implementing custom back-stack logic tailored for short-video or immersive viewing scenarios

Example usage:

AliPlayerWidget(
  onBackPressed: () {
    // Show exit confirmation
    showDialog(...);
    return true; // Handled — don't pop
  },
)

feat: upgrade version to 7.11.0; remove VidAuthPlay page and consolid…

[7.10.0] – Local JWT Play Authentication & Kernel SDK Update

New Features

Local JWT Play Authentication (JWTPlayAuth)

• Introduced support for locally signed playback credentials using JWT (JSON Web Token). The client’s AppServer can now generate a JWT-based play token using the PlayKey, which is then validated by the on-demand streaming service.
• This enhancement improves security and flexibility by enabling offline or edge-side credential generation without requiring real-time authentication calls to external services.

Updates

Kernel SDK Updated to v7.10.0

• Upgraded the underlying kernel SDK to version 7.10.0, incorporating performance improvements, bug fixes, and compatibility enhancements for the new JWTPlayAuth feature.

[7.9.1] – Slot System for Full UI Customization & Documentation Restructure

Improvements

Synchronized UI Slots During Portrait-to-Fullscreen Transition

• Ensured consistent slot state and rendering when switching from vertical (portrait) mode to fullscreen (landscape) mode.
• Custom or disabled slots (e.g., top bar, bottom controls, overlay) now correctly persist their configuration across orientation changes.
• Eliminates UI flickering or unexpected reversion to default components during rotation, providing a smoother and more predictable customization experience—especially critical for short-video and mobile-first scenarios.

Brightness Control View Hidden by Default

• The built-in brightness adjustment UI (typically shown in center feedback during swipe gestures) has been hidden starting from this version.
• Rationale: Official system-level brightness control APIs are not uniformly supported across Android/iOS versions and OEM skins. Exposing this feature as a built-in component risks compatibility issues, inconsistent behavior, or app rejection on certain platforms.
• Customization Path: Developers requiring brightness control may implement it via the center feedback slot using platform-specific plugins or third-party packages, giving full control over compatibility and UX.

[7.9.0] – Slot System for Full UI Customization & Documentation Restructure

New Features

Slot-Based UI Customization System
Introduced a powerful slot system to enable fine-grained, component-level customization of the player UI:

• Provides dedicated slots for key UI regions such as:
  • Top bar, bottom bar, play controls
  • Cover image, subtitles, setting menu
  • Center feedback (volume/brightness/seek), seek thumbnail, play state display
  • Overlay layer for custom business widgets (e.g., like/share/comment, badges, watermarks)
• Each slot can be:
  • Left as default (built-in UI)
  • Replaced with a custom builder
  • Explicitly disabled (hidden) when not needed
• Enables easy creation of different player themes (minimal, classic, short-video style, etc.) and injection of business-specific UI without modifying core player logic.

Overlay Slot Unification

Consolidated all overlay-related customization into a dedicated overlays slot, unifying floating UI components under the new slot mechanism. This provides a clearer and more extensible way to manage all overlay elements on top of the video surface.

Improvements

Backward-Compatible Overlay Usage
Existing usage of the overlays parameter remains fully supported to ensure compatibility with older integrations. Internally, overlays are now unified with the slot-based architecture, simplifying future UI extensions and maintenance.

Documentation Restructure (docs/ Directory)

Reorganized documentation into modular, topic-focused guides under docs/, including:

• Integration Guide
• Quick Start
• Core Components
• API Reference
• Advanced Features (e.g., video source types, overlays/slot system)
  The main README (EN & CN) is now lighter and serves primarily as an entry point, linking to these dedicated documents instead of embedding all details inline.

Practical Examples

Added comprehensive usage examples in example/lib/pages/slot/slot_demo_page.dart, demonstrating:

• Implementation of modern, classic, and minimalist UI styles
• Customization of top bar, bottom bar, and play control slots
• External player control via Notifier from outside the widget tree
• Scene-adaptive behavior across vod, live, listPlayer, restricted, and minimal modes

Example snippets:

// Hide top and bottom bars for a clean look
AliPlayerWidget(controller, slotBuilders: {
  SlotType.topBar: null,
  SlotType.bottomBar: null,
});

// Add custom business overlay
AliPlayerWidget(controller, slotBuilders: {
  SlotType.overlays: (context) => MyLikeShareButtons(),
});

// Fully branded UI
AliPlayerWidget(controller, slotBuilders: {
  SlotType.topBar: (context) => MyAppTopBar(),
  SlotType.bottomBar: (context) => MyAppBottomBar(),
  SlotType.settingMenu: null, // hide settings
});

Breaking Changes

Deprecation of Legacy overlays Parameter
The standalone overlays parameter in AliPlayerWidget is now deprecated in favor of the unified slot system (SlotType.overlays). While still functional for backward compatibility, new code should use slotBuilders exclusively. The legacy parameter will be removed in a future release.

Note: The playerSurface slot handles core video rendering. Customizing it is not recommended, as it may cause playback instability.

This release empowers developers to build highly tailored player experiences while maintaining clean separation from core logic. Combined with the restructured documentation and practical examples, the slot system significantly lowers the barrier to advanced UI customization. Upgrading is recommended for any app requiring branded, minimal, or feature-rich player interfaces.

[7.8.0] - External Subtitle Support, Advanced Scene Control, and Enhanced Media Operations

New Features

• External Subtitle Support
  Added comprehensive support for external subtitles, including:
• Toggle button to show/hide external subtitles
• Customizable display logic and positioning
• Dedicated SubtitleBuilder and configuration moved to AliPlayerWidgetData
• Optimized rendering performance and code structure

Advanced Scene Types for UI Control

Introduced new scene types to enable fine-grained UI behavior:

• SceneType.minimal: Surface-only playback with no UI elements
• SceneType.restricted: Disables all controls and gestures for secure or limited playback scenarios

Enhanced Media Operations: Download, Screenshot & Live Refresh

Implemented key user-facing media control capabilities:

• Video Download: Support for downloading VOD content, including authenticated VID-based sources (VidSts/VidAuth)
• In-Player Screenshot: Capture and save the current video frame during playback (supports both VOD and live)
• Live Stream Refresh: Dedicated refresh button to reload live streams when encountering network or playback issues

Playback Tracking with Trace ID

Added traceId support in AliPlayerWidget to enable end-to-end video playback tracking and diagnostics.

Multi-Definition VOD Playback Logic

Expanded playback logic to better handle multi-definition Video-on-Demand (VOD) content.

Improvements

Player View Default Update
Changed default player view type on Android to AliPlayerViewTypeForAndroid.textureview for improved compatibility and performance.

Documentation Enhancements

• Updated README with integration diagrams (Integration.png, Integration_en.png)
• Revised usage examples to use the modern videoSource API
• Deprecated videoUrl and AliPlayerWidgetData.fromUrl in favor of videoSource

Breaking Changes

Recommended Global Configuration Initialization
To ensure proper storage path setup and platform-specific behavior (e.g., Android external storage vs. iOS sandbox), it is recommended to initialize AliPlayerWidgetGlobalSetting early in your application lifecycle.

Migration Suggestion: Please refer to example/main.dart for the suggested initializeGlobalSettings() implementation, which intelligently configures cache and file directories based on the platform:

/// Initialize aliplayer_widget global settings, including storage paths.
/// Call this once at app startup.
Future<void> initializeGlobalSettings() async {
  await AliPlayerWidgetGlobalSetting.setupConfig();
  // ... (platform-specific path logic as shown in example)
  AliPlayerWidgetGlobalSetting.setStoragePaths(cachePath: ..., filesPath: ...);
}

Failure to initialize global settings may result in missing directories, cache errors, or playback failures. This change ensures proper file management and platform compliance.

Deprecated Controller Methods

The following methods in AliPlayerWidgetController are now deprecated and will be removed in a future release:

○ getWidgetVersion() → Use AliPlayerWidgetGlobalSetting.kWidgetVersion
○ clearCaches() → Use AliPlayerWidgetGlobalSetting.clearCaches()
Note: This release significantly enhances subtitle capabilities, introduces powerful scene-based UI control, and provides greater flexibility in storage and file management. The breaking changes around cache and version APIs require minor migration. Upgrading is recommended for apps needing external subtitles, secure playback modes, or customizable storage paths.

New Features

• External Subtitle Support
  Added comprehensive support for external subtitles, including:
  • Toggle button to show/hide external subtitles
  • Customizable display logic and positioning
  • Dedicated SubtitleBuilder and configuration moved to AliPlayerWidgetData
  • Optimized rendering performance and code structure
• Advanced Scene Types for UI Control
  Introduced new scene types to enable fine-grained UI behavior:
  • SceneType.minimal: Surface-only playback with no UI elements
  • SceneType.restricted: Disables all controls and gestures for secure or limited playback scenarios
• Enhanced Media Operations: Download, Screenshot & Live Refresh Implemented key user-facing media control capabilities:
  • Video Download: Support for downloading VOD content, including authenticated VID-based sources (VidSts/VidAuth)
  • In-Player Screenshot: Capture and save the current video frame during playback (supports both VOD and live)
  • Live Stream Refresh: Dedicated refresh button to reload live streams when encountering network or playback issues
• Playback Tracking with Trace ID
  Added traceId support in AliPlayerWidget to enable end-to-end video playback tracking and diagnostics.
• Multi-Definition VOD Playback Logic
  Expanded playback logic to better handle multi-definition Video-on-Demand (VOD) content.

Improvements

• Player View Default Update
  Changed default player view type on Android to AliPlayerViewTypeForAndroid.textureview for improved compatibility and performance.

• Documentation Enhancements

  • Updated README with integration diagrams (Integration.png, Integration_en.png)
  • Revised usage examples to use the modern videoSource API
  • Deprecated videoUrl and AliPlayerWidgetData.fromUrl in favor of videoSource

Breaking Changes

• Recommended Global Configuration Initialization To ensure proper storage path setup and platform-specific behavior (e.g., Android external storage vs. iOS sandbox), it is recommended to initialize AliPlayerWidgetGlobalSetting early in your application lifecycle.

  Migration Suggestion: Please refer to example/main.dart for the suggested initializeGlobalSettings() implementation, which intelligently configures cache and file directories based on the platform:

  /// Initialize aliplayer_widget global settings, including storage paths.
  /// Call this once at app startup.
  Future<void> initializeGlobalSettings() async {
    await AliPlayerWidgetGlobalSetting.setupConfig();
    // ... (platform-specific path logic as shown in example)
    AliPlayerWidgetGlobalSetting.setStoragePaths(cachePath: ..., filesPath: ...);
  }
  

  Failure to initialize global settings may result in missing directories, cache errors, or playback failures. This change ensures proper file management and platform compliance.

• Deprecated Controller Methods
  The following methods in AliPlayerWidgetController are now deprecated and will be removed in a future release:

  • getWidgetVersion() → Use AliPlayerWidgetGlobalSetting.kWidgetVersion
  • clearCaches() → Use AliPlayerWidgetGlobalSetting.clearCaches()

  Widget version has been updated to 7.8.0 as part of this change (included in 7.8.0 release).

Note: This release significantly enhances subtitle capabilities, introduces powerful scene-based UI control, and provides greater flexibility in storage and file management. The breaking changes around cache and version APIs require minor migration. Upgrading is recommended for apps needing external subtitles, secure playback modes, or customizable storage paths.

New Features

• Screen Keep-On Support
  Added screen keep-on functionality to prevent the device screen from dimming or locking during video playback.
  This feature is especially useful for long-form content, live streaming, and educational video applications.

Improvements

• The method for switching between portrait and landscape modes has been modified. Now, the navigation bar will not be included when switching orientations.
• The functionality to select a decoder has been integrated, allowing you to choose between software decoding or hardware decoding for playback based on your needs.

Bug Fixes

• Fixed URL-based Video Source Playback for RTMP/ARTC Streams
  Resolved an issue where URL-formatted video sources were unable to play RTMP/ARTC format streams correctly.
  This update ensures better compatibility with various streaming protocols across different playback scenarios.

Note: This release enhances playback reliability and improves user experience for streaming use cases. Upgrading is recommended for apps requiring support for RTMP/ARTC and screen keep-on behavior.

New Features

• Multiple Video Source Support: Added compatibility for various video source types, enabling playback through:

  • Direct URL playback for publicly accessible videos.
  • VID+STS token-based playback for secure access and enhanced control.
  • VID+Auth authentication-based playback for simplified authorization scenarios.

  This enhancement ensures that developers can meet diverse playback requirements across different use cases, such as VOD (Video on Demand), live streaming, and secure media distribution.

Improvements

• Streamlined video source configuration to make it easier for developers to switch between different playback modes dynamically.
• Updated the example project to demonstrate the integration of all supported video source types, providing a comprehensive reference for implementation.

Documentation Updates

• Expanded the README documentation to include detailed guidance on configuring and utilizing each video source type.
• Added code examples for integrating URL, VID+STS, and VID+Auth playback modes, ensuring clarity for developers adopting these features.

Note: This release focuses on enhancing video source flexibility and improving developer experience. Upgrading is recommended for projects requiring multi-source playback support.

Bug Fixes

• Resolved issues related to pub.dev compliance, ensuring smoother package publication and integration.
  • Addressed metadata and dependency-related warnings.
  • Improved package validation to meet pub.dev quality standards.

New Features

• Introduced business identifier support, allowing developers to tag player instances with custom identifiers for better tracking and analytics.

  • This feature enhances the ability to monitor and manage player usage in complex multi-scenario applications.

• Added video source switching functionality to the example project, enabling seamless transitions between different video sources during playback.

  • This update provides a practical demonstration of dynamic source management and enhances the flexibility of the example project for developers.

Performance Improvements

• Enhanced PageView scrolling performance, significantly reducing lag during transitions.
• Optimized UI rendering for smoother interactions and improved responsiveness.

Bug Fixes

• Fixed video loading delays during PageView scrolling on certain devices.
• Resolved UI layout issues during full-screen mode transitions.

Note: This release focuses on UI performance optimization. Upgrading is recommended for a smoother experience.

Documentation Updates

• README Enhancements
  • Improved clarity and structure of the README documentation for better readability.
  • Included additional guidance on integrating AliPlayerWidget in multi-scenario applications (e.g., VOD, live streaming, short videos).

No Functional Changes

This release focuses solely on improving documentation and does not include any functional changes or bug fixes. All features and APIs remain consistent with version 7.0.0.

Features

• Core Player Functionality

  • Implemented basic video playback capabilities including play, pause, stop and seek operations.
  • Added support for multiple playback rates with setRate() method.
  • Integrated brightness and volume control with delta adjustments.

• Controller Architecture

  • Developed AliPlayerWidgetController as the main interface for player interactions.CHANGELOG.md
  • Implemented various notifiers including:
    • mirrorModeNotifier
    • isMuteNotifier
    • scaleModeNotifier
    • isLoopNotifier
    • speedNotifier
    • trackInfoListNotifier
    • thumbnailNotifier

• Event Handling System

  • Established comprehensive callback mechanisms for player events:
    • Video size change detection
    • Loading status notifications (begin, progress, end)
    • Seek completion events
    • Playback position tracking

UI Components

• Setting Menu Panel

  • Created customizable settings menu with visibility control.
  • Implemented setting items builder for dynamic configuration options.

• Overlay System

  • Introduced flexible overlay system allowing custom widgets to be positioned over the player.
  • Supports multiple overlay elements with absolute positioning.

Technical Implementation

• Platform Integration

  • Implemented platform brightness detection for automatic theme mode adjustment.
  • Developed robust initialization and destruction processes for player instances.

• Data Management

  • Created AliPlayerWidgetData class for managing video source information.
  • Supports various media sources including VOD and live streams.

Documentation

• Provided complete README documentation including:
  • Quick start guide
  • Core component descriptions
  • Customization instructions
  • Code examples for common use cases