๐ฅ Adaptive Video Player
A comprehensive Flutter video player package that seamlessly handles both YouTube videos and direct video URLs with adaptive player selection. Works on Android, iOS, macOS, Windows, Linux, and Web โ with platform-specific engines tuned for each target.
๐ What's New in the v2.0.4 release candidate
This branch prepares a follow-up release that migrates to package:material_ui (fixing the flutter/material.dart deprecation lints) and requires Flutter 3.47+. It also carries the 2.0.3 WebAssembly import fixes and Android Kotlin Gradle configuration. The package score is calculated by pub.dev after publication; the current published v2.0.2 score is 150/160. See the release verification notes for checks and remaining limits.
๐ค Android Built-in Kotlin
- Uses
kotlin.compilerOptionswith JVM 17 and removes legacy Kotlin plugin configuration flagged by pub.dev.
๐ผ๏ธ Universal Auto Picture-in-Picture (v2.0.1)
- Seamless PiP across ALL platforms when minimizing or backgrounding during active playback
- Android 12+: Native auto-enter with
setAutoEnterEnabled(true) - iOS 14.2+: Inline auto-PiP with
AVPictureInPictureController - Windows & macOS: Always-on-top floating window (380ร214) at bottom-right
- Web (Chrome 120+/Edge): HTML5
autopictureinpicturewithMutationObserversync - Linux: In-app floating mini-player overlay
๐ HTML5 Browser Fullscreen (v2.0.1)
- True native browser fullscreen API on web with seamless enter/exit transitions
๐ Verification
- 260 unit tests โ all pass
- 0 static analysis warnings
- Platform behavior varies; see the six platform designs and platform-specific setup notes below.
โก 10-Second Quick Start
AdaptiveVideoPlayer(
config: VideoConfig(
videoUrl: "https://youtu.be/VIDEO_ID",
),
);
(Just drop it in โ it automatically adapts to YouTube or direct MP4/HLS streams!)
Explore the preview
Use the example application to inspect the implemented controls. The images below are concept designs; use real device recordings to confirm behavior before release. See the release verification notes for checks and limitations.
Designs for all six platforms
These AI-generated concept designs illustrate the branch experience. Click any image to view the full-size design. They are not screenshots or evidence of platform testing.
| Android | iOS |
|---|---|
![]() |
![]() |
| Touch controls ยท Chapters ยท Picture-in-Picture | Audio and subtitles ยท Inline playback ยท Picture-in-Picture |
| Windows | macOS |
|---|---|
![]() |
![]() |
| Desktop fullscreen ยท Floating PiP ยท Keyboard controls | Desktop playback ยท Chapters and speed ยท Host setup required |
| Linux | Web |
|---|---|
![]() |
![]() |
| Desktop playback ยท In-app mini-player ยท Episodes | Browser fullscreen ยท Chapter scrubbing ยท Quality and subtitles |
Linux's mini-player stays inside the app. macOS desktop window services require host integration. Web fullscreen and PiP depend on browser support and activation rules. Generation prompts and asset details.
โจ Features
๐ฌ Adaptive Video Player Engine
- Smart Source Detection โ Automatically differentiates YouTube (video IDs, short URLs, embeds) from direct streams (MP4, HLS, DASH).
- Single Widget API โ Just drop
AdaptiveVideoPlayer(config: VideoConfig(...))anywhere. - Cross-Platform Parity โ Unified design and controls across Android, iOS, Windows, macOS, Linux, and Web.
๐ก๏ธ Anti-Screen Capture Shield (preventScreenCapture: true)
- OS-Level Privacy โ Asks the OS to render the window black during screenshots or screen recordings where the platform supports it (Android, iOS, Windows). Web uses best-effort DOM deterrents; macOS and Linux fall back safely without protection. No client-side shield can stop a camera pointed at the screen.
- Android (
FLAG_SECURE) โ Blocks screenshots, screen recorders, and app switcher preview leaks. - Windows (
SetWindowDisplayAffinity) โ Win32 display affinity (WDA_MONITOR) blacks out Snipping Tool, OBS, and print screens. - Web DOM Shield โ Focus blur detection, clipboard flushing, and print media obscuration.
๐บ YouTube Player with Unified Native Architecture
- Error 150/153 Bypass โ Serves embedded player via localized
http://localhostorigin for unrestricted embedding. - Unified Controls Pill โ Single clean control pill
[ โง PiP | โถ Fullscreen ]with auto-fading timer and no duplicate fullscreen icons. - Picture-in-Picture (PiP) โ Android native PiP with notification actions, Windows always-on-top window (
HWND_TOPMOST), and in-app draggable miniplayer. - Live Stream Ready โ Automatic
LIVEindicator, viewer count, and live sync. - Custom Gestures โ Double-tap seek (ยฑ10s, ยฑ20s, ยฑ30s) and touch-to-reveal overlay.
๐๏ธ Normal Video Player (HLS, DASH, MP4, Offline Bytes)
- YouTube Capsule/Pill Controls โ Modern circular
-10s,Play/Pause,+10spills, hover-expanding Volume slider, and Time + Chapter pill. - Timeline Hover & Scrub Timestamp Pill โ Shows active chapter title and preview timestamp above the cursor/thumb with track expansion.
- Video Chapters (
VideoChapter) โ Segmented progress bar with chapter gap markers and active chapter indicators. - Hold-to-2x Speed Gesture (
2x โฉ) โ Long-press anywhere on the video to boost playback to2.0xand release to restore. - Speed Stepper Popup (
AdaptiveSpeedStepperPopup) โ Granular speed steps (0.25x,0.5x,0.75x,1.0x,1.25x,1.5x,1.75x,2.0x). - Netflix-Style Episodes Drawer โ Next episode queue, thumbnail watched progress bar, and active episode indicator.
- Dual-Column Audio & Subtitles Modal โ High-fidelity sheet for selecting multi-language audio dubs and SRT/VTT subtitles.
- Persistent Disk Caching (
enableCache: true) โ Local storage caching viaCachedVideoPlayerPlusfor instant zero-buffering replays. - In-Memory Bytes Playback (
videoBytes) โ Direct encrypted/in-memory playback without writing video files to disk. - Built-in Arabic (
ar) & English (en) Localization โ Full RTL layout support with standard LTR timeline preservation. - Desktop Keyboard Shortcuts โ
Space(Play/Pause),โ/โ(Seek ยฑ10s),โ/โ(Volume),M(Mute),F/Esc(Fullscreen).
๐ฅ๏ธ Platform Support
| Platform | YouTube Engine | Direct Video Engine | Notes |
|---|---|---|---|
| Android / iOS | flutter_inappwebview via localhost |
video_player |
Native InAppWebView with local origin server, bypasses Error 150/153, full controls & PiP |
| Windows | flutter_inappwebview via localhost |
video_player_win |
Native Win32 borderless fullscreen & always-on-top PiP window |
| macOS | flutter_inappwebview via localhost |
video_player |
Native AVFoundation playback |
| Linux | flutter_inappwebview via localhost |
video_player_media_kit |
Initialized via AdaptiveVideoPlayerPlatform.ensureInitialized() |
| Web | HTML iframe | video_player |
HTML5 Fullscreen, native browser PiP, WASM-ready |
Why localhost origin for YouTube? YouTube restricts iframe embedding from
data:/file://origins (Error 150/153). Serving via a local HTTP origin (http://localhost) provides a secure, trusted origin YouTube permits across Mobile and Desktop.
๐ Feature Comparison
| Feature | adaptive_video_player |
youtube_player_flutter |
chewie |
video_player |
|---|---|---|---|---|
| ๐ฏ Universal Player (YouTube + Direct Streams) | โ | โ | โ | โ |
| ๐ก๏ธ Anti-Screen Capture Shield (OS-level where supported) | โ | โ | โ | โ |
| ๐ช Full Desktop Support (Windows, macOS, Linux) | โ | โ | โ ๏ธ | โ ๏ธ |
| ๐๏ธ YouTube-Style Capsule Pill Controls | โ | โ | โ | โ |
| โฑ๏ธ Timeline Chapter Scrubbing & Tooltip | โ | โ | โ | โ |
โฉ Hold-to-2x Speed Boost (2x โฉ) |
โ | โ | โ | โ |
| ๐บ Native & In-App Picture-in-Picture (PiP) | โ | โ | โ | โ |
| ๐ด YouTube Live Stream Badge & Viewers | โ | โ | โ | โ |
| โ๏ธ Multi-Quality Switcher & Subtitle Dubs | โ | โ | โ | โ |
| ๐ Netflix-Style Episodes Queue Drawer | โ | โ | โ | โ |
| ๐พ Persistent Disk Caching (Zero Buffering) | โ | โ | โ | โ |
| ๐ Arabic & English RTL/LTR Localization | โ | โ | โ | โ |
| ๐ No custom native code for screen protection | โ | โ | โ | โ |
๐ฆ Installation
Add to your pubspec.yaml:
dependencies:
adaptive_video_player: ^1.3.3 # Published baseline; use the Git dependency above for this preview.
๐ Platform Permissions & Setup
๐ค Android
Add the required permissions in android/app/src/main/AndroidManifest.xml:
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.WAKE_LOCK"/>
<uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>
To support Picture-in-Picture (PiP), background playback, and smooth fullscreen transitions without activity restarts, update <activity> and <application> in AndroidManifest.xml:
<application
...
android:usesCleartextTraffic="true">
<activity
android:name=".MainActivity"
android:supportsPictureInPicture="true"
android:configChanges="orientation|keyboardHidden|keyboard|screenSize|smallestScreenSize|locale|layoutDirection|fontScale|screenLayout|density|uiMode"
...>
๐ iOS
Add to ios/Runner/Info.plist for WebView rendering and background audio / Picture-in-Picture (PiP):
<key>io.flutter.embedded_views_preview</key>
<true/>
<key>UIBackgroundModes</key>
<array>
<string>audio</string>
</array>
(Optional, for http:// video URLs)
<key>NSAppTransportSecurity</key>
<dict>
<key>NSAllowsArbitraryLoads</key>
<true/>
<key>NSAllowsArbitraryLoadsInWebContent</key>
<true/>
</dict>
The native plugin requires iOS 13.0 or later. It supports both CocoaPods and Swift Package Manager. Flutter picks one when you build. Do not add adaptive_video_player yourself in the Podfile or in Xcodeโs package list.
Swift Package Manager is the default on Flutter 3.44 and later. Flutter builds this plugin from ios/adaptive_video_player/Package.swift.
flutter config --enable-swift-package-manager
CocoaPods is used when Swift Package Manager is turned off. Flutter builds this plugin from ios/adaptive_video_player.podspec.
flutter config --no-enable-swift-package-manager
After switching, rebuild so Xcode picks up the other integration:
flutter clean
flutter pub get
flutter run
Info.plist setup above is the same for both. Some dependencies of this package, including flutter_inappwebview_ios and media_kit_video, still ship CocoaPods only. Flutter keeps CocoaPods for those plugins and may print a Swift Package Manager warning that names them. That warning is not about adaptive_video_player.
๐ macOS
In both macos/Runner/DebugProfile.entitlements and macos/Runner/Release.entitlements:
<key>com.apple.security.network.client</key>
<true/>
๐ช Windows
YouTube playback on Windows requires NuGet for building flutter_inappwebview:
winget install Microsoft.NuGet
(Note: Borderless Fullscreen and Always-on-Top Picture-in-Picture on Windows use native Win32 user32.dll APIs automaticallyโno extra permissions needed).
๐ง Linux
Requires WebKit/GTK (e.g. libwebkit2gtk-4.1-dev on Ubuntu/Debian).
Initialize the platform engine in your main() before runApp():
import 'package:adaptive_video_player/adaptive_video_player.dart';
void main() {
AdaptiveVideoPlayerPlatform.ensureInitialized();
runApp(const MyApp());
}
๐ Web
No extra permission files needed. Native HTML5 Fullscreen and requestPictureInPicture() work out of the box. Ensure direct video hosts have CORS enabled. Fully WASM-compatible.
๐ก๏ธ Screenshot & Screen Recording Prevention (Anti-Capture Shield)
Protect premium DRM content and sensitive media from being recorded or screenshotted. When enabled, screenshots, screen recordings, and app switcher snapshots render as a solid black window:
AdaptiveVideoPlayer(
config: VideoConfig(
videoUrl: 'https://example.com/movie.mp4',
preventScreenCapture: true, // black screen on captures where the OS supports it
),
);
๐ No custom native code needed (platform permissions below still apply):
- ๐ค Android: 100% Automatic โ Zero Kotlin/Java setup. Handled by
AdaptiveVideoPlayerPluginviaWindowManager.LayoutParams.FLAG_SECURE. Screen recordings, screenshots, and task switcher preview thumbnails are blocked out. - ๐ iOS: 100% Automatic โ Zero Swift/Obj-C setup. Handled by
AdaptiveVideoPlayerPluginvia secure window sublayer containment. - ๐ช Windows Desktop: 100% Automatic โ Zero permissions needed. Invokes Win32 native
SetWindowDisplayAffinity(hwnd, WDA_MONITOR)via FFI. Snipping Tool, OBS, and Print Screen capture a black rectangle. - ๐ Web: 100% Automatic โ Full-viewport DOM obscuration shield (
z-index: 2147483647), automatic focus loss/blur detection, clipboard flushing onPrintScreen/Ctrl+Shift+S, and@media printblackouts. - ๐ macOS & ๐ง Linux: Safe, graceful fallback protections with zero crashes.
๐ Quick Start
import 'package:adaptive_video_player/adaptive_video_player.dart';
// YouTube โ detected automatically
AdaptiveVideoPlayer(
config: VideoConfig(
videoUrl: 'https://www.youtube.com/watch?v=2Or3_FX1KrA',
),
);
// Direct video โ detected automatically
AdaptiveVideoPlayer(
config: VideoConfig(
videoUrl: 'https://upload.mp3quran.net/group1_pbuh/maher.mp4',
),
);
๐ Usage Examples
1. Quality Picker, Video Chapters & Multi-Language Subtitles
AdaptiveVideoPlayer(
config: VideoConfig(
videoUrl: 'https://www.mp3quran.net/uploads/videos/group1_pbuh/maher.mp4',
chapters: const [
VideoChapter(title: 'Introduction', startTime: Duration.zero),
VideoChapter(title: 'Main Recitation', startTime: Duration(seconds: 20)),
VideoChapter(title: 'Conclusion', startTime: Duration(seconds: 45)),
],
qualities: const [
VideoQuality(
title: 'Auto (HLS)',
url: 'https://upload.mp3quran.net/group1_pbuh/maher.mp4',
),
VideoQuality(
title: 'HD',
url: 'https://upload.mp3quran.net/group1_pbuh/maher.mp4',
),
VideoQuality(
title: 'SD',
url: 'https://upload.mp3quran.net/group1_pbuh/maher.mp4',
),
],
initialQuality: const VideoQuality(
title: 'Auto (HLS)',
url: 'https://upload.mp3quran.net/group1_pbuh/maher.mp4',
),
subtitles: const [
SubtitleTrack(
id: 'en',
title: 'English',
content: '''
1
00:00:01,000 --> 00:00:04,000
This is a sample English subtitle.
''',
),
SubtitleTrack(
id: 'ar',
title: 'ุนุฑุจู',
content: '''
1
00:00:01,000 --> 00:00:04,000
ูุฐู ุชุฑุฌู
ุฉ ุชุฌุฑูุจูุฉ ุจุงููุบุฉ ุงูุนุฑุจูุฉ.
''',
),
],
initialSubtitle: const SubtitleTrack(
id: 'en',
title: 'English',
),
playerConfig: const YouTubePlayerConfig(
text: PlayerTextConfig.arabic(), // Or PlayerTextConfig.english()
visibility: PlayerVisibilityConfig(
showSkipButtons: true,
skipDuration: Duration(seconds: 10),
),
),
onAnalyticsEvent: (event, data) {
debugPrint('Analytics: $event - Data: $data');
},
),
);
2. Recorded vs. Live Stream Switcher
AdaptiveVideoPlayer(
config: const VideoConfig(
videoUrl: 'https://upload.mp3quran.net/group1_pbuh/maher.mp4',
viewerCount: '93k VIEWERS',
qualities: [
VideoQuality(
title: 'Recorded (MP4)',
url: 'https://upload.mp3quran.net/group1_pbuh/maher.mp4',
isLive: false,
),
VideoQuality(
title: 'HLS Stream (.m3u8)',
url: 'https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8',
isLive: true,
),
],
),
);
3. YouTube with Custom Configuration & Forced Desktop Mode
AdaptiveVideoPlayer(
config: VideoConfig(
videoUrl: 'https://www.youtube.com/watch?v=2Or3_FX1KrA',
playerConfig: YouTubePlayerConfig(
playback: const PlayerPlaybackConfig(
autoPlay: true,
loop: false,
forceHD: true,
enableCaption: true,
forceDesktopMode: true, // Uses WebViews on Android/iOS
),
style: const PlayerStyleConfig(
iconColor: Colors.white,
progressBarPlayedColor: Colors.red,
progressBarHandleColor: Colors.redAccent,
backgroundColor: Colors.black,
),
visibility: const PlayerVisibilityConfig(
showSettingsButton: true,
showFullscreenButton: true,
),
text: const PlayerTextConfig(
playerSettingsText: 'Settings',
autoPlayText: 'Auto Play',
loopVideoText: 'Loop',
forceHdQualityText: 'Force HD',
enableCaptionsText: 'Captions',
muteAudioText: 'Mute',
),
),
),
);
4. YouTube Live Stream
AdaptiveVideoPlayer(
config: const VideoConfig(
videoUrl: 'https://www.youtube.com/watch?v=bNyUyrR0PHo',
isLive: true,
viewerCount: '15.4K',
),
);
5. Local Video File & Memory Bytes
// From local file
AdaptiveVideoPlayer(
config: VideoConfig(
videoUrl: '/path/to/local/video.mp4',
isFile: true,
),
);
// From in-memory Uint8List bytes
AdaptiveVideoPlayer(
config: VideoConfig(
videoUrl: '',
videoBytes: myUint8ListBytes,
),
);
6. Anti-Screen Capture Shield & Offline Disk Cache
AdaptiveVideoPlayer(
config: VideoConfig(
videoUrl: 'https://example.com/premium_course.mp4',
// Prevents screen recording & screenshots (renders black surface on Android & Windows)
preventScreenCapture: true,
// Caches video stream locally on disk for zero-latency replay and offline viewing
enableCache: true,
),
);
๐๏ธ Configuration Reference
VideoConfig
| Property | Type | Default | Description |
|---|---|---|---|
videoUrl |
String |
required | Video target URL |
isFile |
bool |
false |
True if the URL is a local file path |
isLive |
bool |
false |
Enables LIVE indicator and disables seek bar |
viewerCount |
String? |
null |
Displayed when isLive is true |
videoBytes |
Uint8List? |
null |
In-memory video bytes buffer |
qualities |
List<VideoQuality>? |
null |
Available qualities or sources |
initialQuality |
VideoQuality? |
null |
Initial active quality |
subtitles |
List<SubtitleTrack>? |
null |
Available subtitle tracks |
initialSubtitle |
SubtitleTrack? |
null |
Initial active subtitle track |
chapters |
List<VideoChapter>? |
null |
Timeline chapters with gap markers and hover titles |
controlsBuilder |
AdaptiveControlsBuilder? |
null |
Custom controls overlay builder |
subtitleBuilder |
SubtitleBuilder? |
null |
Custom subtitles UI builder |
enableCache |
bool |
false |
Enables disk caching for network videos via CachedVideoPlayerPlus |
preventScreenCapture |
bool |
false |
When true, renders video/window black in screenshots & screen recordings (DRM/privacy shield) |
onAnalyticsEvent |
void Function(String, Map<String, dynamic>)? |
null |
External analytics hook |
playerConfig |
YouTubePlayerConfig |
const YouTubePlayerConfig() |
Player style, text, visibility, and playback config |
YouTubePlayerConfig
PlayerPlaybackConfig
| Property | Type | Default | Description |
|---|---|---|---|
autoPlay |
bool |
false |
Auto-start playback |
loop |
bool |
false |
Loop video |
mute |
bool |
false |
Start muted |
forceHD |
bool |
false |
Force HD quality |
enableCaption |
bool |
false |
Enable captions |
forceDesktopMode |
bool |
false |
Use WebView player on Android/iOS |
allowExternalLinks |
bool |
true |
Open external links in system browser |
PlayerStyleConfig
| Property | Type | Default | Description |
|---|---|---|---|
progressBarPlayedColor |
Color |
#FF0033 |
Progress bar active color |
progressBarHandleColor |
Color |
#FF0033 |
Progress bar thumb color |
iconColor |
Color |
Colors.white |
Control icons color |
textColor |
Color |
Colors.white |
Text color |
backgroundColor |
Color |
#1D1D1D |
Player background |
loadingIndicatorColor |
Color |
#FF0033 |
Loading spinner color |
errorIconColor |
Color |
Colors.red |
Error icon color |
settingsBackgroundColor |
Color |
#1D1D1D |
Settings sheet background |
PlayerTextConfig
Defaults strictly to English (PlayerTextConfig()), allowing host applications to supply any language and text direction via PlayerTextConfig.fromMap() or custom translations (see example/lib/languages/ for modular language file examples):
| Property | Type | Default | Description |
|---|---|---|---|
invalidYoutubeUrlText |
String |
"Invalid YouTube URL" |
Error when YouTube URL is invalid |
videoLoadFailedText |
String |
"Failed to load video" |
Error when video fails to load |
playerSettingsText |
String |
"Player Settings" |
Settings sheet header title |
autoPlayText |
String |
"Auto Play" |
Auto-play toggle label |
loopVideoText |
String |
"Loop Video" |
Loop toggle label |
forceHdQualityText |
String |
"Force HD Quality" |
Force HD toggle label |
enableCaptionsText |
String |
"Enable Captions" |
Captions toggle label |
muteAudioText |
String |
"Mute Audio" |
Mute toggle label |
qualityText |
String |
"Quality (Resolution)" |
Quality selector menu title |
autoText |
String |
"Auto" |
Automatic resolution option |
subtitlesText |
String |
"Subtitles" |
Subtitles menu title |
offText |
String |
"Off" |
Disabled subtitle option |
noQualitiesAvailableText |
String |
"No qualities available" |
Notice when no resolutions exist |
noSubtitlesAvailableText |
String |
"No subtitles available" |
Notice when no subtitles exist |
skipBackwardText |
String |
"Rewind 10s" |
Tooltip for -10s button |
skipForwardText |
String |
"Forward 10s" |
Tooltip for +10s button |
PlayerVisibilityConfig
| Property | Type | Default | Description |
|---|---|---|---|
showControls |
bool |
true |
Show player controls overlay |
showFullscreenButton |
bool |
true |
Show fullscreen toggle button |
showSettingsButton |
bool |
true |
Show settings gear button |
showSkipButtons |
bool |
true |
Show -10s and +10s seek buttons |
skipDuration |
Duration |
Duration(seconds: 10) |
Relative seek duration for skip buttons |
showAutoPlaySetting |
bool |
true |
Show auto-play toggle in settings |
showLoopSetting |
bool |
true |
Show loop toggle in settings |
showForceHDSetting |
bool |
true |
Show Force HD toggle in settings |
showCaptionsSetting |
bool |
true |
Show captions toggle in settings |
showMuteSetting |
bool |
true |
Show mute toggle in settings |
๐๏ธ Architecture
lib/
โโโ adaptive_video_player.dart # Public library exports & Smart YouTube/VOD detection
โโโ src/
โโโ core/ # Domain contracts, DI, constants & platform services
โ โโโ contracts/ # Core interfaces (SRP / ISP)
โ โ โโโ i_video_player_controller.dart
โ โ โโโ i_fullscreen_service.dart
โ โ โโโ i_playback_controls.dart
โ โ โโโ i_quality_manageable.dart
โ โ โโโ i_subtitle_manageable.dart
โ โ โโโ i_volume_controls.dart
โ โโโ constants/ # YouTube & HLS JS constants & strings
โ โโโ models/ # Shared enums, player state & display modes
โ โโโ services/ # Screen protection, Native PiP & Fullscreen services
โโโ normal_video_player/ # Normal video player implementation
โ โโโ coordinator/ # Modular full-screen & PiP coordinators
โ โโโ mixins/ # State mixins (Controller, Subtitles, Resilience, PiP)
โ โโโ models/ # VideoConfig, VideoQuality, VideoChapter, VideoEpisode
โ โโโ utils/ # Win32 FFI & Web fullscreen helpers
โ โโโ widgets/ # Adaptive bottom bar, timeline, popups, episodes drawer
โโโ youtube_player/ # YouTube cross-platform player implementation
โโโ models/ # YouTubePlayerConfig, PlayerStyleConfig, PlayerVisibility
โโโ utils/ # Web iframe exports & platform stubs
โโโ views/ # Desktop & Web player views with unified overlay
โโโ widgets/ # InAppWebView localhost server, buttons, live badge
๐ง Supported Formats
YouTube URLs: youtube.com/watch?v=... ยท youtu.be/... ยท youtube.com/embed/... ยท m.youtube.com/watch?v=... ยท direct video IDs
Video Files & Streams: MP4 ยท MOV ยท AVI ยท MKV ยท WebM ยท M4V ยท 3GP ยท HLS (.m3u8) ยท DASH (.mpd) ยท In-Memory Bytes
โ FAQ
Q: I get "Error 153" or "Error 150" with YouTube embeds.
A: Handled automatically โ the package serves YouTube via an internal http://localhost origin that Google trusts, bypassing origin rejections across Android, iOS, Windows, macOS, and Linux.
Q: Why was there a duplicate fullscreen button in YouTube?
A: Resolved in v2.0+ โ the internal HTML5 button is hidden and replaced by a unified, luxury floating control pill [ โง PiP | โถ Fullscreen ] where PiP is cleanly positioned right before Fullscreen.
Q: How does Anti-Screen Capture work?
A: Simply set preventScreenCapture: true. Android activates FLAG_SECURE, Windows invokes native Win32 SetWindowDisplayAffinity(WDA_MONITOR) via FFI, and Web engages an active focus/blur obfuscation shield. Any screenshot or screen recording will capture a solid black frame.
Q: How does Android Picture-in-Picture handle background controls?
A: When entering native PiP on Android, the package registers native OS RemoteActions (Play, Pause, Seek -10s, Seek +10s) in the system PiP window, and automatically suppresses unclickable Flutter UI overlays.
Q: Does iOS use CocoaPods or Swift Package Manager?
A: Both. Flutter 3.44 and later uses Swift Package Manager by default and builds this plugin from its Package.swift. Turn Swift Package Manager off with flutter config --no-enable-swift-package-manager to build it from the podspec instead. You do not add the plugin manually in either case. Warnings that name flutter_inappwebview_ios or media_kit_video come from those dependencies, which are still CocoaPods-only.
๐ฎ Roadmap
xSmart auto-detection of YouTube vs. direct streamsxDouble-tap-to-seek gesture (ยฑ10s) and-10s/+10scapsule buttonsxHold-to-2x speed gesture (2x โฉ) on long-pressxGranular Playback Speed Stepper (AdaptiveSpeedStepperPopup) (0.25x - 2.0x)xTimeline hover & scrub timestamp preview pillxVideo Chapters (VideoChapter) with segmented progress bar markersxNetflix-style Episodes Drawer with thumbnail progress barsxDual-column Audio Tracks & Subtitles modalxAnti-Screen Capture Shield (preventScreenCapture: true)xPersistent Disk Caching for offline replay (CachedVideoPlayerPlus)xIn-Memory Bytes Playback (videoBytes)xTrue OS-Level Picture-in-Picture & Fullscreen (AndroidRemoteActions, WindowsHWND_TOPMOST, Web HTML5)xYouTube Error 150/153 bypass via localhost originxUnified YouTube floating control pill[ โง PiP | โถ Fullscreen ]xBuilt-in Arabic (RTL) & English (LTR) localization (PlayerTextConfig.arabic())Custom HTTP headers for authenticated/tokenized video streamsAutomatic multi-bitrate track switcher directly from HLS manifestsCustom poster/thumbnail image before playback starts
Got a feature request? Open an issue.
๐ค Contributing
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
๐ License
Licensed under the MIT License โ see the LICENSE file for details.
๐จโ๐ป Author
Ahmed Mohamed Osman ยท GitHub: @ahmedalam782
๐ Dependencies
- youtube_player_flutter โ YouTube player for mobile
- flutter_inappwebview โ WebView for desktop YouTube
- video_player โ Flutter's official video player
- video_player_platform_interface โ Platform interface
- video_player_media_kit โ Linux playback via media_kit
- video_player_win โ Windows playback via Media Foundation
- url_launcher โ Launching external URLs safely
- web โ Modern Web APIs for WASM compatibility






