Added #

• Quality List Stream: Added qualitiesStream to track changes in available video qualities

  • Stream emits List<NativeVideoPlayerQuality> whenever quality list changes
  • Useful for updating UI when qualities are loaded or changed
  • Follows the same pattern as other property streams
  • Example usage in custom_video_overlay.dart demonstrates reactive quality selector updates

• Automatic Orientation Restoration: Enhanced FullscreenManager with intelligent orientation tracking

  • Automatically saves current orientation preferences when entering fullscreen
  • Restores original orientations when exiting fullscreen (no manual setup required)
  • Added setPreferredOrientations() helper method as optional drop-in replacement for SystemChrome.setPreferredOrientations()
  • Added preferredOrientations parameter to NativeVideoPlayerController for easy orientation configuration
  • Supports per-controller orientation preferences (e.g., portrait-only apps can specify this when creating the controller)

• Tap-to-Hide Overlay: Enhanced custom overlay interaction

  • Tapping on visible overlay now hides it (in addition to the auto-hide timer)
  • Tapping on hidden overlay shows it (existing behavior)
  • Interactive elements (buttons, sliders) are unaffected and work normally
  • Uses HitTestBehavior.deferToChild for proper gesture handling

Fixed #

• Stream Disposal Race Condition: Fixed "Bad state: Cannot add new events after calling close" error
  • Added _isDisposed flag to prevent state updates after disposal
  • Added isClosed checks before adding events to all stream controllers
  • Improved disposal order: now cancels event subscriptions before closing stream controllers
  • Added double-disposal guard to prevent errors from multiple dispose calls
  • Affects: bufferedPositionController, durationController, playerStateController, positionController, speedController, isPipEnabledController, isPipAvailableController, isAirplayAvailableController, isAirplayConnectedController, isFullscreenController, qualityChangedController, and qualitiesController

Changed #

• Custom Video Overlay: Refactored to use streams instead of control events
  • Now uses bufferedPositionStream for reactive buffer position updates
  • Now uses qualitiesStream for reactive quality list updates
  • Reduced dependency on control event polling
  • Improved code organization and separation of concerns
  • Added dart:async import for StreamSubscription support

Documentation #

• Updated NativeVideoPlayerController documentation with preferredOrientations usage examples
• Updated FullscreenManager documentation explaining automatic orientation tracking
• Added comprehensive explanation of auto quality feature and buffer health thresholds

Added #

• HDR Control: Added enableHDR parameter to NativeVideoPlayerController

  • Defaults to false to prevent washed-out/too-white video appearance on HDR content
  • Set to true to enable HDR playback when desired
  • Applies to both iOS and Android platforms
  • ExoPlayer automatically handles tone-mapping to SDR when HDR is disabled

• AirPlay Connection State Tracking: Enhanced AirPlay monitoring with connection state

  • Added isAirplayConnected property to NativeVideoPlayerState
  • Added isAirplayConnected getter to NativeVideoPlayerController
  • Added isAirplayConnectedStream for real-time connection state updates
  • New PlayerControlState events: airPlayConnected and airPlayDisconnected
  • Allows UI to respond to active AirPlay streaming state

• Convenience State Getters: Added direct property access to controller state

  • speed - Current playback speed
  • isPipEnabled - Current Picture-in-Picture state
  • isPipAvailable - PiP device availability
  • isAirplayAvailable - AirPlay device availability
  • isAirplayConnected - Active AirPlay connection state

Fixed #

• Android Picture-in-Picture Media Session: Fixed media info not displaying correctly in PiP mode
  • Media session now properly updates when entering PiP mode (manual, automatic, and exit)
  • Ensures notification and lock screen controls show correct title, subtitle, and artwork
  • Applies to all PiP entry/exit scenarios: manual start/stop and automatic transitions

Changed #

• Enhanced NativeVideoPlayerState model with isAirplayConnected property
• Updated event handling to process AirPlay connection state changes
• Improved Android PiP lifecycle to ensure media session consistency

Added #

• Individual Property Streams: Added dedicated broadcast streams for convenient property monitoring

  • bufferedPositionStream - Stream of buffered position changes
  • durationStream - Stream of duration changes
  • playerStateStream - Stream of player state changes (playing, paused, buffering, etc.)
  • positionStream - Stream of playback position changes
  • speedStream - Stream of playback speed changes
  • isPipEnabledStream - Stream of Picture-in-Picture state changes
  • isPipAvailableStream - Stream of Picture-in-Picture availability changes
  • isAirplayAvailableStream - Stream of AirPlay availability changes
  • isFullscreenStream - Stream of fullscreen state changes
  • qualityChangedStream - Stream of quality changes
  • Streams only emit when values actually change (no duplicate emissions)
  • All streams are broadcast streams allowing multiple listeners

• Toggle Picture-in-Picture: Added togglePictureInPicture() method for easy PiP toggling

  • Automatically checks current PiP state and enters/exits accordingly
  • Returns bool indicating success/failure of the operation
  • Follows the same pattern as toggleFullScreen() for consistency

Changed #

• Enhanced State Model: Extended NativeVideoPlayerState with new properties

  • Added speed property to track playback speed
  • Added isPipEnabled property to track current PiP state
  • Added isPipAvailable property to track PiP device availability
  • Added isAirplayAvailable property to track AirPlay device availability
  • Updated copyWith(), operator==, and hashCode to include new properties

• Improved Event Handling: Enhanced event processing to update state properties

  • Quality changes now update state and emit to quality stream
  • Speed changes now update state and emit to speed stream
  • PiP state changes (both platform view and MainActivity events) now update state and emit to PiP streams
  • PiP availability changes now update state and emit to availability stream
  • AirPlay availability changes now update state and emit to AirPlay stream

Documentation #

• Added comprehensive documentation for individual property streams in README
• Added usage examples showing how to use streams vs event listeners
• Updated API Reference section with new streams and toggle method
• Added dedicated Streams subsection in API Reference documenting all 10 available streams
• Updated Picture-in-Picture section with togglePictureInPicture() usage examples

Note #

• The original event listeners (addActivityListener, addControlListener) continue to work as before
• Users can choose between using dedicated streams or event listeners based on their use case
• Stream controllers are properly disposed in the dispose() method to prevent memory leaks

Improved #

• Enhanced Player Disposal and Cleanup: Improved SharedPlayerManager on both iOS and Android platforms
  • Added stopAllViewsForController() method to properly stop playback and clear player from all views when disposing
  • Enhanced iOS disposal to pause player and clear current item before removing
  • Enhanced Android disposal to stop playback and clear active views
  • Improved logging for better debugging of player lifecycle
  • Better cleanup of view references when controller is disposed

Changed #

• Code formatting improvements across the codebase to comply with Dart style guidelines
• Improved readability with better line formatting in NativeVideoPlayerController

Fixed #

• Critical Controller Disposal Bug: Fixed incomplete resource cleanup in NativeVideoPlayerController.dispose() method

  • Added proper cleanup of PiP event subscription (Android global listener)
  • Added cleanup of AirPlay listeners (availability and connection handlers)
  • Added cleanup of platform view contexts map
  • Added cleanup of overlay builder and fullscreen callback references
  • Fixed memory leaks by ensuring all event handlers and subscriptions are properly cancelled

• Android Player Reinitialization Issue: Fixed critical bug where Android players could not be reinitialized after disposal

  • Fixed VideoPlayerMethodHandler.handleDispose() to properly remove player from SharedPlayerManager
  • Added controllerId parameter to VideoPlayerMethodHandler constructor
  • Now properly releases ExoPlayer, notification handler, and clears PiP settings on disposal
  • Android players can now be disposed and recreated just like iOS players

Changed #

• Enhanced VideoPlayerMethodChannel with new dispose() method that calls native platform disposal
• Updated Flutter controller dispose() to call native cleanup via method channel
• Improved disposal flow to ensure both Flutter and native resources are properly cleaned up

Documentation #

• Updated dispose() method documentation to reflect proper disposal of both Flutter and native platform resources

Improved #

• Android Media Info Management: Refactored VideoPlayerNotificationHandler and VideoPlayerObserver for improved media information management
  • Enhanced media session and notification updates to occur consistently when playback starts
  • Improved user experience in both normal playback and Picture-in-Picture modes
  • Cleaned up code for better readability and maintainability
  • Enhanced logging for better debugging capabilities

Fixed #

• iOS Automatic Picture-in-Picture for Shared Controllers: Fixed critical issue where automatic PiP would not work correctly when multiple views share the same controller (e.g., list view + detail view scenario)
  • Fixed race condition where multiple views observing the same shared player would compete for PiP control
  • Added primary view tracking to ensure only the most recently active view can trigger automatic PiP
  • Fixed automatic PiP not working for videos started with native controls (non-programmatic playback)
  • Improved SharedPlayerManager to properly handle PiP state transfers between views with the same controller ID
  • Added isPrimaryView() and getPrimaryViewId() methods to prevent observer conflicts

Changed #

• Enhanced observer logic to detect when playback starts via native controls and automatically set the view as primary
• Improved logging for debugging PiP state transitions across multiple views

Fixed #

• Fixed Dart formatting issues in native_video_player_controller.dart and fullscreen_manager.dart to comply with pub.dev static analysis requirements

Added #

• WASM compatibility: Package now supports Web Assembly (WASM) runtime
  • Implemented conditional imports using dart:io only on native platforms
  • Added PlatformUtils class for platform detection without direct dart:io dependency
  • Exported PlatformUtils for users who need platform-agnostic code

Changed #

• Replaced direct Platform checks with PlatformUtils in fullscreen manager and controller
• Code formatting improvements across all files

Fixed #

• Updated iOS podspec version to match package version (0.2.1)

Added #

• AirPlay Support (iOS): Complete AirPlay integration for streaming to Apple TV and AirPlay-enabled devices

  • isAirPlayAvailable() method to check for available AirPlay devices
  • showAirPlayPicker() method to display native AirPlay device picker
  • addAirPlayAvailabilityListener() to monitor when AirPlay devices become available/unavailable
  • addAirPlayConnectionListener() to track AirPlay connection state changes
  • Automatic detection of AirPlay-enabled devices on the network
  • Support for streaming video to multiple AirPlay receivers

• Custom Overlay Controls: Build your own video player UI on top of the native player

  • New overlayBuilder parameter in NativeVideoPlayer widget
  • Full access to controller state for custom UI implementations
  • Allows building custom controls while maintaining native video decoding performance
  • Example implementation in example/lib/widgets/custom_video_overlay.dart with:
    • Play/pause control
    • Progress slider with buffered position indicator
    • Speed controls (0.25x - 2.0x)
    • Quality selector for HLS streams
    • Fullscreen toggle
    • Volume control
    • AirPlay button (iOS)
    • Auto-hide functionality

• Dart-side Fullscreen Management: New FullscreenManager class for Flutter-based fullscreen

  • FullscreenVideoPlayer widget for fullscreen video playback in a Flutter overlay
  • enterFullscreen() and exitFullscreen() methods
  • System UI management (hide/show status bar and navigation bar)
  • Device orientation locking options
  • Fullscreen dialog helper for easy integration
  • Works alongside native fullscreen for maximum flexibility

• Buffered Position Tracking: Real-time buffered position updates

  • New bufferedPosition property in controller
  • Included in timeUpdated control events
  • Enables showing how much video has been preloaded
  • Perfect for showing secondary progress indicator in custom overlays

Improved #

• Enhanced controller state management with better activity and control state tracking
• Improved fullscreen state synchronization between native and Dart layers
• Better event listener management with separate activity and control listeners
• Enhanced example app with new video_with_overlay_screen.dart demonstrating custom controls
• Improved documentation with comprehensive AirPlay and custom overlay usage examples
• Better error handling and state validation throughout the player lifecycle

Documentation #

• Updated README with comprehensive sections on AirPlay and custom overlays
• Added example code for all new features

Fixed #

• Fixed Dart SDK constraint to use proper version range (>=3.9.0 <4.0.0) instead of exact version, allowing compatibility with all Dart 3.9.x and 3.x versions

Fixed #

• Fixed fullscreen exit handling on iOS when user dismisses by swiping down or tapping Done button
• Fixed iOS playback state preservation when exiting fullscreen (video now resumes playing if it was playing before)
• Fixed Android fullscreen button icon synchronization when fullscreen is toggled from Flutter code
• Fixed fullscreen event parsing to properly distinguish between entering and exiting fullscreen states
• Fixed shared player state synchronization by sending current playback state when new views attach

Improved #

• Standardized event naming by renaming videoLoaded to loaded across all platforms for consistency
• Enhanced Android fullscreen button to detect and correct icon desynchronization
• Improved shared player initial state callback mechanism to properly communicate loaded state with duration
• Better fullscreen state event notifications on Android with proper isFullscreen data
• Enhanced iOS fullscreen delegate handling with playback state restoration

Fixed #

• Fixed iOS player state tracking by observing timeControlStatus instead of relying only on item observers
• Fixed shared player initialization to properly handle existing players vs new players
• Fixed Android PiP event channel setup to only initialize on Android platform (prevents iOS errors)
• Fixed playback state synchronization when connecting to shared players
• Fixed unnecessary buffering/loading events for shared players during reattachment

Improved #

• Enhanced iOS player observer to distinguish between play/pause and buffering states
• Improved shared player management with better state tracking and event handling
• Enhanced Android player controls by hiding unnecessary buttons (next, previous, settings)
• Better error handling and logging throughout the player lifecycle

Fixed #

• Fixed Android package name to match plugin name (com.huddlecommunity.better_native_video_player)
• Fixed plugin registration in Android

Changed #

• Updated Flutter SDK constraint to 3.9.2
• Updated flutter_lints to 6.0.0

Added #

• Initial release of native_video_player plugin
• Native video playback using AVPlayerViewController (iOS) and ExoPlayer/Media3 (Android)
• HLS streaming support with adaptive quality selection
• Picture-in-Picture (PiP) mode on both platforms
• Native fullscreen playback
• Now Playing integration (Control Center on iOS, lock screen on Android)
• Background playback with media notifications
• Comprehensive playback controls:
  • Play/pause
  • Seek to position
  • Volume control
  • Playback speed adjustment (0.5x to 2.0x)
  • Quality selection for HLS streams
• Event streaming for player state changes
• Support for custom media info (title, subtitle, album, artwork)
• Configurable PiP behavior
• Native player controls toggle
• Example app demonstrating all features
• Comprehensive documentation and API reference

Platform Support #

• iOS 12.0+
• Android API 24+ (Android 7.0+)

Dependencies #

• Flutter SDK ^3.9.2
• iOS: AVFoundation framework
• Android: androidx.media3 1.5.0 (ExoPlayer, HLS, Session)