better_native_video_player library
A Flutter plugin for native video playback on iOS and Android.
This plugin provides a native video player that uses AVPlayerViewController on iOS and ExoPlayer (Media3) on Android, offering features like:
- HLS streaming with quality selection
- Picture-in-Picture support
- AirPlay support with device name tracking (iOS)
- Fullscreen playback (native and Dart-based)
- Custom overlay widgets
- Now Playing integration (Control Center / lock screen)
- Background playback with media notifications
Classes
- AirPlayStateManager
- Global singleton manager for AirPlay state across all video player instances.
- BackgroundPlaybackGuard
- Pauses playback when the app is backgrounded and resumes it on return — for controllers that should NOT keep playing audio in the background.
- FullscreenManager
- Manages fullscreen state, system UI visibility, and device orientation
- FullscreenVideoPlayer
- A fullscreen video player widget that displays the video in fullscreen mode
- NativeVideoPlayer
- A native video player widget that wraps platform-specific video players (AVPlayerViewController on iOS, ExoPlayer on Android).
- NativeVideoPlayerAndroidBufferConfig
-
ExoPlayer
DefaultLoadControlparameters (Android only). - NativeVideoPlayerAudioTrack
- Represents an alternate audio track of the current media (multiple languages, audio description, commentary) — the audio counterpart of NativeVideoPlayerSubtitleTrack. Requested in issues #23 and #16.
- NativeVideoPlayerCache
- Warms the opt-in Android disk cache (NativeVideoPlayerConfig.androidEnableDiskCache) for upcoming videos.
- NativeVideoPlayerConfig
- Global, opt-in tuning knobs for the plugin.
- NativeVideoPlayerController
- Controller for managing native video player via platform channels
- NativeVideoPlayerIosBufferConfig
- AVPlayer buffering parameters (iOS only).
- NativeVideoPlayerMediaInfo
- NativeVideoPlayerPlaybackRange
- An A-B playback range: playback is confined to start..end.
- NativeVideoPlayerPlaylist
- Sequential playback of multiple sources on ONE controller, with auto-advance when an item completes.
- NativeVideoPlayerPlaylistItem
- One entry in a NativeVideoPlayerPlaylist.
- NativeVideoPlayerQuality
- NativeVideoPlayerSidecarSubtitle
- An external (sidecar) subtitle source: a VTT or SRT file referenced by URL, local file path, or provided as raw content.
- NativeVideoPlayerState
- Represents the state of the native video player
- NativeVideoPlayerSubtitleStyle
- Visual style AND position for sidecar subtitles rendered by the plugin's Flutter overlay (covers the caption customization requested in issue #29: size, colors, and where on the video the captions sit).
- NativeVideoPlayerSubtitleTrack
- Represents a subtitle/closed caption track in the video player
- NativeVideoPlayerVideoSize
-
The native video's display dimensions, reported by texture-rendered
views (see
NativeVideoPlayerConfig.androidTextureMode) so the widget can letterbox theTextureto the correct aspect ratio. - PlatformUtils
- Stub implementation for web/WASM platforms
- PlaybackAnalytics
- Derives playback quality-of-experience events (startup time, stalls, watched duration, quality switches, completion) from a controller's existing event streams — no extra platform traffic.
- PlaybackAnalyticsEvent
- One QoE event with an optional numeric value (milliseconds for durations) and free-form data.
- PlayerActivityEvent
- Activity state event for playback changes
- PlayerControlEvent
- Control state event for user interactions and settings
- PositionCheckpoints
- Throttled position reporting for resume-position persistence.
- StoryboardThumbnail
- One scrub-preview entry: the image (or sprite-sheet region) shown while the scrubber is between start and end.
- StoryboardThumbnails
- WebVTT storyboard parsing for scrub-bar thumbnail previews.
- SubtitleCue
- One timed subtitle cue parsed from a VTT/SRT source.
- VideoDownload
- A completed download as stored in the controller's index.
- VideoDownloadController
- Web/WASM stub: downloads need dart:io. Mirrors the io API so shared code compiles; every member throws.
- VideoDownloadProgress
- One progress update from VideoDownloadController.download.
Enums
- PlaybackAnalyticsEventType
- Types of playback quality-of-experience events.
- PlayerActivityState
- Player activity state representing playback status
- PlayerControlState
- Player control state for user interactions and settings
- SubtitleFormat
- Subtitle text formats supported by the sidecar parser.
- SubtitleTrackSource
- Where a subtitle track comes from.
- VideoDownloadStatus
- Lifecycle states of one download.
Extensions
- PlayerActivityStateExtension on PlayerActivityState
- Extension methods for activity state