adaptive_video_player 2.0.4
adaptive_video_player: ^2.0.4 copied to clipboard
A Flutter video player for YouTube and direct video URLs with adaptive controls. Supports Android, iOS, Windows, macOS, Linux, and Web.
๐ฅ 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 #
- โ Smart auto-detection of YouTube vs. direct streams
- โ
Double-tap-to-seek gesture (ยฑ10s) and
-10s/+10scapsule buttons - โ
Hold-to-2x speed gesture (
2x โฉ) on long-press - โ
Granular Playback Speed Stepper (
AdaptiveSpeedStepperPopup) (0.25x - 2.0x) - โ Timeline hover & scrub timestamp preview pill
- โ
Video Chapters (
VideoChapter) with segmented progress bar markers - โ Netflix-style Episodes Drawer with thumbnail progress bars
- โ Dual-column Audio Tracks & Subtitles modal
- โ
Anti-Screen Capture Shield (
preventScreenCapture: true) - โ
Persistent Disk Caching for offline replay (
CachedVideoPlayerPlus) - โ
In-Memory Bytes Playback (
videoBytes) - โ
True OS-Level Picture-in-Picture & Fullscreen (Android
RemoteActions, WindowsHWND_TOPMOST, Web HTML5) - โ YouTube Error 150/153 bypass via localhost origin
- โ
Unified YouTube floating control pill
[ โง PiP | โถ Fullscreen ] - โ
Built-in Arabic (RTL) & English (LTR) localization (
PlayerTextConfig.arabic()) - โ Custom HTTP headers for authenticated/tokenized video streams
- โ Automatic multi-bitrate track switcher directly from HLS manifests
- โ Custom 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






