Skip to main content

adaptive_video_player 2.0.4 copy "adaptive_video_player: ^2.0.4" to clipboard
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.

pub package Flutter Platforms WASM Ready License: MIT


๐ŸŽ‰ 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.compilerOptions with 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 autopictureinpicture with MutationObserver sync
  • 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.

See full CHANGELOG โ†’


โšก 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.

Adaptive Video Player v2.0.3 cross-platform branch preview concept

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
Android player concept with touch controls, chapters and PiP iOS phone and tablet concept with audio, subtitles and PiP
Touch controls ยท Chapters ยท Picture-in-Picture Audio and subtitles ยท Inline playback ยท Picture-in-Picture
Windows macOS
Windows player concept with desktop fullscreen and floating PiP macOS player concept with chapters, speed and host window integration
Desktop fullscreen ยท Floating PiP ยท Keyboard controls Desktop playback ยท Chapters and speed ยท Host setup required
Linux Web
Linux player concept with an in-app mini-player and episode navigation Web browser player concept with fullscreen, chapter scrubbing and subtitles
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://localhost origin 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 LIVE indicator, 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, +10s pills, 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 to 2.0x and 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 via CachedVideoPlayerPlus for 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 AdaptiveVideoPlayerPlugin via WindowManager.LayoutParams.FLAG_SECURE. Screen recordings, screenshots, and task switcher preview thumbnails are blocked out.
  • ๐ŸŽ iOS: 100% Automatic โ€” Zero Swift/Obj-C setup. Handled by AdaptiveVideoPlayerPlugin via 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 on PrintScreen/Ctrl+Shift+S, and @media print blackouts.
  • ๐Ÿ 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 / +10s capsule 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, Windows HWND_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 #

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

๐Ÿ“ License #

Licensed under the MIT License โ€” see the LICENSE file for details.


๐Ÿ‘จโ€๐Ÿ’ป Author #

Ahmed Mohamed Osman ยท GitHub: @ahmedalam782

๐Ÿ™ Dependencies #