flex_video_player 0.1.1

A flexible, production-ready Flutter video player package supporting MP4, HLS, reels, quality switching, subtitles, and more. Works on Android, iOS, macOS, and Web.

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