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.

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.

新功能

• 策略系统
  • 提供可插拔的策略架构，支持自定义注册策略来控制播放行为。
  • 内置首帧优化策略和卡顿检测策略，开箱即用。
  • 内置后台恢复播放策略，应用回到前台时自动恢复播放。
• 国际化（i18n）系统
  • 内置中英文支持，自动跟随系统语言。
  • 支持运行时动态切换语言，无需重启。
  • 实现 PlayerTranslations 接口即可注册自定义语言包（如日语、韩语等）。
  • 支持覆盖内置翻译文案。
  • 与 Flutter LocalizationsDelegate 无缝集成，可直接接入 MaterialApp。
• UI 主题系统
  • 提供完整的 UI 设计规范，统一的设计 Token（颜色、字号、尺寸、间距，通过 PlayerStyles 引用）。
  • 通过 assetsPath 参数支持自定义皮肤，一键替换全套播放器图标。
• UI 增强
  • 全新播放器 UI 设计与还原，可直接使用，无需客户再还原 UI。
• 播放器配置
  • 支持 Android 端 View 类型配置（AndroidViewType）。
  • 优化不同场景下的播放体验。

优化

• 全屏优化
  • 全屏重构为单实例架构，提升稳定性和资源管理效率。
  • 全屏切换逻辑简化，横屏顶栏布局适配优化。
• 插槽系统
  • 插槽支持自定义排序与任意层级插入，UI 编排更灵活。
  • 插槽 Builder 签名简化为单参数 (BuildContext context)。
  • overlays 参数已废弃，统一迁移至插槽系统管理。

文档更新

• 新增自定义配置指南文档。
• 补充 flutter_aliplayer 依赖版本说明。
• 新增策略系统使用文档。

示例更新

• 新增国际化（i18n）示例页面。
• 新增短视频右侧互动按钮叠加层示例。
• 新增水印插槽示例。
• 新增后台恢复播放策略示例。

[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.

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., setPlayConfig, 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.

新功能

• 插槽 Builder 支持控制器参数（全屏适配）

  • 新增 SlotWidgetBuilderWithController 类型，将当前 AliPlayerWidgetController 实例传递给插槽 Builder。
  • 使自定义插槽 UI 在全屏模式下也能正确控制播放器。
  • 新签名：Widget Function(BuildContext context, AliPlayerWidgetController controller)。
  • 向后兼容：旧的单参数 SlotWidgetBuilder 仍然支持但已标记废弃，自动签名检测确保平滑迁移。

• 自定义配置回调

  • 新增 OnGlobalInitCallback，通过 AliPlayerWidgetGlobalSetting.setOnGlobalInit 设置，在全局初始化完成后调用，可用于自定义全局设置（如 setOption）。
  • 新增 OnPlayerConfigCallback，通过 AliPlayerWidgetData.onPlayerConfig 设置，在 prepare() 前调用，用于单实例播放器配置（如 setPlayConfig、setOption）。支持异步操作（FutureOr<void>）。
  • 使客户可以在最佳实践配置流程中配置 AliPlayerWidget 未直接透出的播放器 API。

优化

• 全屏切换逻辑简化
  • 重构全屏切换逻辑，提升可维护性。
  • 统一横竖屏模式下的系统 UI 处理。

Bug 修复

• 文档语言切换
  • 修复文档站的大小写不敏感语言切换问题。

文档更新

• README 精简

  • 从 README.md 和 README-EN.md 中移除内联代码示例，引导用户查看快速开始指南获取完整实现细节。
  • 优化示例 README，采用结构化场景描述（核心功能、实现要点、执行效果）。

• 快速开始指南增强

  • 更新为推荐使用 VidAuth 视频源而非基于 URL 的方式。
  • 添加 const 构造函数以提升性能。

• 核心组件文档重构

  • 使用编号章节重新组织，提升可读性和导航体验。

• 视频源文档

  • 调整顺序，突出 VidAuth 为推荐的播放方式。
  • 明确各视频源类型的优势和使用场景。

• 全局配置说明

  • 强调默认最优设置。
  • 明确自定义配置场景的使用注意事项。

[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.

New Features

• Fine-Grained Slot Element Visibility Control (hiddenSlotElements)
  • 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.

新功能

• 细粒度插槽元素可见性控制（hiddenSlotElements）
  • SlotType.centerDisplay：控制音量、亮度、速度指示器的可见性
  • SlotType.playState：控制错误图标和错误信息的可见性
  • SlotType.seekThumbnail：控制缩略图和时间文本的可见性
  • SlotType.playControl：禁用特定手势交互

注意事项

• 此功能仅对默认插槽 UI 生效
• 若某个插槽已配置 slotBuilders，则该插槽的 hiddenSlotElements 不会生效
• PlayControlElements 用于禁用手势交互，而非隐藏 UI 元素。

[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
  },
)

Update

• Kernel SDK Updated to v7.12.0

New Features

• Custom Back Press Callback (onBackPressed)
  • Added onBackPressed callback parameter to AliPlayerWidget, allowing developers to fully customize back button behavior.
  • The callback is invoked when the user presses the back button.
  • Return true to indicate the event was handled and prevent default behavior.
  • Return false or null to execute the default Navigator.pop() behavior.
  • This enables scenarios such as:
    • Showing confirmation dialogs before exiting
    • Navigating to specific routes instead of simple pop
    • Implementing custom back stack management in short-video scenarios

Documentation Updates

• Core Components Documentation Enhancement

版本更新

• 内核 SDK 升级至 v7.12.0

新功能

• 自定义返回按钮回调（onBackPressed）
  • 在 AliPlayerWidget 中新增 onBackPressed 回调参数，允许开发者完全自定义返回按钮行为。
  • 当用户按下返回按钮时触发回调。
  • 返回 true 表示事件已处理，阻止默认行为。
  • 返回 false 或 null 执行默认的 Navigator.pop() 行为。
  • 支持以下场景：
    • 退出前显示确认对话框
    • 导航到指定路由而非简单 pop
    • 在短视频场景中实现自定义返回栈管理

文档更新

• 核心组件文档增强

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

Update

• Kernel SDK Updated to v7.11.0
• remove VidAuthPlay page and consolidate into long video page

版本更新

• 内核 SDK 升级至 v7.11.0
• 移除 VidAuthPlay 页面，合并至长视频页面

[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.

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.

新功能

• 本地 JWT 播放鉴权（JWTPlayAuth）
  • 支持使用 JWT（JSON Web Token）本地签发播放凭证。客户端 AppServer 可使用 PlayKey 生成 JWT 播放令牌，由点播服务验证。
  • 通过支持离线或边缘侧凭证生成（无需实时调用外部鉴权服务），提升安全性和灵活性。

版本更新

• 内核 SDK 升级至 v7.10.0
• 升级底层内核 SDK 至 7.10.0 版本，包含性能改进、Bug 修复和对 JWTPlayAuth 新特性的兼容性增强。

[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.

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.

优化

• 竖屏转全屏 UI 插槽同步

  • 确保从竖屏切换到全屏（横屏）模式时插槽状态和渲染的一致性。
  • 自定义或禁用的插槽（如顶栏、底部控件、叠加层）在方向切换时正确保持其配置。
  • 消除旋转时的 UI 闪烁或意外回退到默认组件的问题，提供更流畅、更可预测的定制体验——对短视频和移动优先场景尤为关键。

• 亮度控制视图默认隐藏

  • 从此版本起，内置亮度调节 UI（通常在滑动手势时在中央反馈区域显示）默认隐藏。
  • 原因：官方系统级亮度控制 API 在不同 Android/iOS 版本和 OEM 定制系统中支持不一致。将此功能作为内置组件暴露可能导致兼容性问题、行为不一致或在某些平台被拒绝。
  • 自定义路径：需要亮度控制的开发者可通过中央反馈插槽使用平台特定插件或第三方包实现，完全控制兼容性和用户体验。

[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.

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
  • Each slot can be:
    • Left as default (built-in UI)
    • Replaced with a custom builder
    • Explicitly disabled (hidden) when not needed
  • The slot system makes it easy to:
    • Create different player themes (minimal, classic, short-video style, etc.)
    • Inject business-specific UI (e.g., like/share/comment, custom badges, watermarks)
    • Combine multiple UI behaviors without modifying core player logic.
• Overlay Slot Unification
  • Consolidated overlay-related customization into a dedicated overlay slot, so custom floating UI components are now part of the unified slot mechanism.
  • Provides a clearer and more extensible way to manage all overlay elements on top of the video surface.

Improvements

• Backward-Compatible Overlay Usage
  • Existing overlays parameter usage remains supported to ensure compatibility with older integrations.
  • Internally, overlays and slots are now unified under the new slot-based architecture, making future UI extensions easier to maintain.
• Documentation Restructure (docs/ Directory)
  • Reorganized documentation into modular topics under docs/, including (but not limited to):
    • Integration Guide
    • Quick Start
    • Core Components
    • API Reference
    • Advanced Features (e.g., video source types, overlays/slot system)
  • README (EN & CN) is now lighter and mainly acts as an entry point, linking to these dedicated documents instead of embedding all details directly.

新功能

• 基于插槽的 UI 定制系统 引入强大的插槽系统，实现播放器 UI 的细粒度、组件级定制：

  • 为关键 UI 区域提供专用插槽：
    • 顶栏、底栏、播放控件
    • 封面图、字幕、设置菜单
    • 中央反馈（音量/亮度/进度）、拖拽缩略图、播放状态展示
    • 叠加层（用于自定义业务组件）
  • 每个插槽支持：
    • 保持默认（内置 UI）
    • 使用自定义 Builder 替换
    • 显式禁用（隐藏）
  • 插槽系统使以下操作变得简单：
    • 创建不同播放器主题（极简、经典、短视频风格等）
    • 注入业务 UI（如点赞/分享/评论、自定义徽章、水印）
    • 组合多种 UI 行为而无需修改核心播放器逻辑。

• 叠加层插槽统一

  • 将叠加层相关定制整合到专用叠加层插槽中，使自定义浮层 UI 组件成为统一插槽机制的一部分。
  • 提供更清晰、更具扩展性的方式来管理视频表面之上的所有叠加元素。

优化

• 向后兼容的叠加层使用

  • 现有 overlays 参数用法继续支持，确保与旧集成的兼容性。
  • 内部已将叠加层和插槽统一到新的基于插槽的架构下，使未来 UI 扩展更易维护。

• 文档重构（docs/ 目录）

  • 将文档重新组织为 docs/ 下的模块化主题，包括（但不限于）：
    • 集成指南
    • 快速开始
    • 核心组件
    • API 参考
    • 高级功能（如视频源类型、叠加层/插槽系统）
  • README（中英文）现在更轻量，主要作为入口点，链接到这些专门文档而非直接嵌入所有细节。

[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.

新功能

• 外挂字幕支持 新增全面的外挂字幕支持，包括：

  • 显示/隐藏外挂字幕的切换按钮
  • 可自定义的显示逻辑和定位
  • 专用 SubtitleBuilder 和配置移至 AliPlayerWidgetData
  • 优化渲染性能和代码结构

• 高级场景类型 UI 控制 引入新场景类型实现细粒度 UI 行为：

  • SceneType.minimal：仅视频画面，无任何 UI 元素
  • SceneType.restricted：禁用所有控件和手势，用于安全或受限播放场景

• 增强媒体操作：下载、截图与直播刷新 实现关键用户操作能力：

  • 视频下载：支持下载点播内容，包括鉴权的 VID 类型源（VidSts/VidAuth）
  • 播放器内截图：在播放期间捕获并保存当前视频帧（支持点播和直播）
  • 直播流刷新：专用刷新按钮，在遇到网络或播放问题时重新加载直播流

• TraceId 播放追踪 在 AliPlayerWidget 中新增 traceId 支持，实现端到端视频播放追踪和诊断。

• 多清晰度点播播放逻辑 扩展播放逻辑以更好地处理多清晰度点播（VOD）内容。

优化

• 播放器视图默认值更新 将 Android 端默认播放器视图类型更改为 AliPlayerViewTypeForAndroid.textureview，以提升兼容性和性能。

• 文档增强

  • 在 README 中新增集成架构图（Integration.png、Integration_en.png）
  • 修订使用示例以使用现代 videoSource API
  • 废弃 videoUrl 和 AliPlayerWidgetData.fromUrl，改用 videoSource

破坏性变更

• 建议全局配置初始化 为确保存储路径正确设置和平台特定行为（如 Android 外部存储 vs iOS 沙盒），建议在应用生命周期早期初始化 AliPlayerWidgetGlobalSetting。

  迁移建议： 请参考 example/main.dart 中建议的 initializeGlobalSettings() 实现，该方法根据平台智能配置缓存和文件目录：

  /// 初始化 aliplayer_widget 全局设置，包括存储路径。
  /// 在应用启动时调用一次。
  Future<void> initializeGlobalSettings() async {
    await AliPlayerWidgetGlobalSetting.setupConfig();
    // ...（平台特定路径逻辑如示例所示）
    AliPlayerWidgetGlobalSetting.setStoragePaths(cachePath: ..., filesPath: ...);
  }
  

  未初始化全局设置可能导致目录缺失、缓存错误或播放失败。此变更确保正确的文件管理和平台合规性。

• 废弃的控制器方法 以下 AliPlayerWidgetController 方法现已废弃，将在未来版本中移除：

  • getWidgetVersion() → 使用 AliPlayerWidgetGlobalSetting.kWidgetVersion
  • clearCaches() → 使用 AliPlayerWidgetGlobalSetting.clearCaches()

  Widget 版本已更新为 7.8.0。

注意：此版本显著增强了字幕能力，引入了强大的基于场景的 UI 控制，并在存储和文件管理方面提供了更大的灵活性。围绕缓存和版本 API 的破坏性变更需要少量迁移。建议需要外挂字幕、安全播放模式或可自定义存储路径的应用升级。

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.

新功能

• 屏幕常亮支持 新增屏幕常亮功能，防止视频播放期间设备屏幕变暗或锁定。 此功能对长视频内容、直播和教育类视频应用尤为实用。

优化

• 修改横竖屏切换方式，切换方向时不再包含导航栏。
• 集成解码器选择功能，允许根据需求选择软解码或硬解码进行播放。

Bug 修复

• 修复基于 URL 视频源的 RTMP/ARTC 流播放 解决了 URL 格式视频源无法正确播放 RTMP/ARTC 格式流的问题。 此更新确保不同播放场景下对各种流媒体协议的更好兼容性。

注意：此版本增强了播放可靠性，改善了流媒体使用场景下的用户体验。建议需要 RTMP/ARTC 支持和屏幕常亮行为的应用升级。

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.

新功能

• 多视频源支持：新增对各类视频源类型的兼容，支持以下播放方式：

  • 直接 URL 播放公开可访问的视频。
  • VID+STS 基于令牌的播放，用于安全访问和增强控制。
  • VID+Auth 基于鉴权的播放，用于简化授权场景。

  此增强确保开发者能够满足不同使用场景（如点播、直播和安全媒体分发）中的多样化播放需求。

优化

• 简化视频源配置，使开发者更轻松地动态切换不同播放模式。
• 更新示例项目以演示所有支持的视频源类型的集成，为实现提供全面参考。

文档更新

• 扩展 README 文档，包含配置和使用各视频源类型的详细指南。
• 添加集成 URL、VID+STS 和 VID+Auth 播放模式的代码示例，确保采用这些功能的开发者有清晰的参考。

注意：此版本专注于增强视频源灵活性和改善开发者体验。建议需要多源播放支持的项目升级。

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.

Bug 修复

• 解决 pub.dev 合规性相关问题，确保更顺畅的包发布和集成。
  • 处理元数据和依赖相关警告。
  • 改进包验证以满足 pub.dev 质量标准。

新功能

• 引入业务标识符支持，允许开发者为播放器实例打上自定义标识，便于追踪和分析。

  • 此功能增强了在复杂多场景应用中监控和管理播放器使用的能力。

• 在示例项目中添加视频源切换功能，支持播放期间在不同视频源之间无缝切换。

  • 此更新提供了动态源管理的实际演示，增强了示例项目对开发者的灵活性。

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.

性能改进

• 增强 PageView 滚动性能，显著减少切换时的卡顿。
• 优化 UI 渲染，使交互更流畅、响应更迅速。

Bug 修复

• 修复某些设备上 PageView 滚动时的视频加载延迟问题。
• 解决全屏模式切换时的 UI 布局问题。

注意：此版本专注于 UI 性能优化。建议升级以获得更流畅的体验。

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.

文档更新

• README 增强
  • 改善 README 文档的清晰度和结构，提升可读性。
  • 新增在多场景应用中集成 AliPlayerWidget 的额外指导（如点播、直播、短视频）。

无功能性变更

此版本仅专注于改善文档，不包含任何功能性变更或 Bug 修复。所有功能和 API 与 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

功能

• 核心播放器功能

  • 实现基本视频播放能力，包括播放、暂停、停止和拖拽操作。
  • 通过 setRate() 方法支持多种播放速率。
  • 集成亮度和音量控制，支持增量调节。

• 控制器架构

  • 开发 AliPlayerWidgetController 作为播放器交互的主接口。
  • 实现多种通知器，包括：
    • mirrorModeNotifier
    • isMuteNotifier
    • scaleModeNotifier
    • isLoopNotifier
    • speedNotifier
    • trackInfoListNotifier
    • thumbnailNotifier

• 事件处理系统

  • 建立全面的播放器事件回调机制：
    • 视频尺寸变化检测
    • 加载状态通知（开始、进度、结束）
    • 拖拽完成事件
    • 播放位置追踪

UI 组件

• 设置菜单面板

  • 创建可自定义的设置菜单，支持可见性控制。
  • 实现设置项构建器，用于动态配置选项。

• 叠加层系统

  • 引入灵活的叠加层系统，允许自定义组件定位在播放器之上。
  • 支持多个叠加元素和绝对定位。

技术实现

• 平台集成

  • 实现平台亮度检测，自动适配主题模式。
  • 开发健壮的播放器实例初始化和销毁流程。

• 数据管理

  • 创建 AliPlayerWidgetData 类用于管理视频源信息。
  • 支持包括点播和直播在内的多种媒体源。

文档

• 提供完整的 README 文档，包括：
  • 快速开始指南
  • 核心组件描述
  • 自定义说明
  • 常见用例代码示例