flex_video_player 0.1.2

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.

Stand with Palestine 🇵🇸

I believe in freedom, justice, and the right of people to live in peace and dignity.

Support ❤️

flex_video_player is an open-source package built and maintained to help Flutter developers build reliable video experiences.

If this package helps you in your projects, you can support its development here:

👉 Support me on Patreon

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