flex_video_player

A flexible, production-ready Flutter video player package for Android, iOS, macOS, and Web.

Built with a clean public API over video_player, so the underlying engine can be replaced without changing consumer code.

Platform Support

Android iOS macOS Web
✅ ✅ ✅ ✅

Features

  • Sources: Network MP4, HLS .m3u8, asset, local file, offline file
  • Resolvers: Vimeo and Bunny resolver structure with custom callback support
  • Playback: Play, pause, seek, position, duration, progress percentage
  • Audio: Mute/unmute, volume control
  • Speed: Configurable playback speed
  • Display: Fullscreen, portrait/landscape, system UI handling
  • Quality: Quality selector with backend MP4 URLs + Auto HLS option
  • Subtitles: WebVTT subtitles with custom styling
  • Reels: Vertical video reels mode (PageView-based)
  • UX: Loading overlay, buffering overlay, error overlay with retry
  • Lifecycle: App background/foreground handling
  • Wakelock: Keep screen on while playing (wakelock_plus)
  • Retry: Auto and manual retry with exponential backoff
  • Tracking: Analytics events and progress callbacks
  • Protection: Optional screen protection (Android FLAG_SECURE, iOS capture detection)
  • Config: Every feature is independently configurable

Installation

dependencies:
  flex_video_player: ^0.1.0

Quick Start

final controller = FlexVideoController(
  source: FlexVideoSource.hls(url: 'https://example.com/video.m3u8'),
  config: const FlexVideoConfig(
    autoPlay: true,
    wakelock: FlexWakelockConfig(enabled: true),
  ),
);

FlexVideoPlayer(
  controller: controller,
  onCompleted: () => debugPrint('Done'),
  onError: (error) => debugPrint('Error: ${error.message}'),
);

Note: Full API documentation and more examples will be added as features are implemented phase by phase.

Web Support

flex_video_player compiles and runs on Flutter Web. The table below documents each feature's Web behaviour.

Supported on Web

Feature Notes
MP4 playback Works via the browser's native <video> element
Network HLS (.m3u8) Works on Safari; other browsers need hls.js (V2 roadmap)
Asset sources Works
Play / pause / seek / volume / speed Works
Subtitles (WebVTT) Works — http package is Web-compatible
Quality selector Works — each quality is a separate MP4 URL
Reels Works
Retry / error overlay Works
Lifecycle (background/foreground) Works via WidgetsBindingObserver
Fullscreen route Works via Navigator push — SystemChrome calls are no-ops on Web
Orientation lock No-op on Web (guarded by kIsWeb); no crash
Wakelock wakelock_plus silently no-ops on Web; no crash

Not Supported on Web

Feature Behaviour Error type
File / offline sources Returns a typed error immediately; playback does not start FlexVideoErrorType.webUnsupported
Screen protection All calls are no-ops (kIsWeb guard in service); no crash, no events —
HLS on Chrome / Firefox The <video> element rejects M3U8 — propagates as a platform error FlexVideoErrorType.platform
FLAG_SECURE Android-only OS feature; not applicable on Web —

Handling Web-Unsupported Errors

FlexVideoErrorType.webUnsupported is non-retryable — the retry button is hidden and auto-retry is suppressed automatically.

FlexVideoPlayer(
  controller: controller,
  onError: (error) {
    if (error.type == FlexVideoErrorType.webUnsupported) {
      // show a "feature not available on Web" message
    }
  },
);

HLS Browser Matrix

Browser HLS native support V1 recommendation
Safari (macOS / iOS) ✅ Native Use HLS .m3u8 directly
Chrome ✗ Provide MP4 via FlexVideoQuality
Firefox ✗ Provide MP4 via FlexVideoQuality
Edge ✗ Provide MP4 via FlexVideoQuality

For cross-browser support, supply multiple FlexVideoQuality entries (MP4 at different resolutions) and let the user or your app select the appropriate one.

Roadmap

See CHANGELOG.md for released changes.

Planned for future versions: native Media3 adapter, AVPlayer advanced adapter, DRM, offline downloads, Chromecast, AirPlay, Picture-in-Picture, hls.js for Web.

License

MIT

Libraries

flex_video_player