All-in-one Flutter video player – stream from YouTube, Vimeo, network, assets files

Introduction

omni_video_player is a Flutter video player built on top of Flutter’s official video_player plugin.

It supports YouTube (via youtube_explode_dart with an automatic WebView-based fallback implemented using webview_flutter to handle cases where YouTube rate-limits requests, temporarily blocking direct extraction — see issue #323),

Vimeo videos (now using webview_flutter for improved stability and maintainability), as well as network and asset videos.

A single unified controller is provided to manage playback across all supported video types seamlessly.

🎨 Highly customizable — tweak UI, show/hide controls, and easily integrate your own widgets. 🎮 The controller gives full control over video state and callbacks for smooth video management on mobile and web.

🎯 Long-term goal: to create a universal, flexible, and feature-rich video player that works flawlessly across all platforms and video sources, using the most robust and actively maintained technologies to ensure consistent behavior over time.

Supported Platforms & Status

Video Source Type	Android	iOS	Web	Status
YouTube	✅	✅	✅	✅ Supported — uses youtube_explode_dart by default on mobile, and WebView (webview_flutter) on web or as fallback on mobile to bypass temporary rate-limit blocks
Vimeo	✅	✅	❌	✅ Supported — uses webview_flutter
Network	✅	✅	✅	✅ Supported
Asset	✅	✅	✅	✅ Supported
File	✅	✅	❌	✅ Supported
Twitch	-	-	-	🔜 Planned
TikTok	-	-	-	🔜 Planned
Dailymotion	-	-	-	🔜 Planned

✨ Features

• ✅ Play videos from:

  • YouTube (live and regular videos, with automatic WebView fallback powered by webview_flutter to keep playback working even under temporary YouTube rate-limit restrictions)
  • Vimeo (public — now using official webview_flutter for stable playback)
  • Network video URLs
  • Flutter app assets
  • File from device

• 🎛 Customizable player UI (controls, theme, overlays, labels)

• 🔁 Autoplay, replay, mute/unmute, volume control

• ⏪ Seek bar & scrubbing

• 🖼 Thumbnail support (custom or auto-generated for YouTube and Vimeo)

• 🔊 Global playback & mute sync across players

• ⛶ Fullscreen player

• ⚙️ Custom error and loading widgets

• ⏱ Playback Speed

• 🎚️ Quality selection UI:

  • Supports YouTube quality switching
  • Supports HLS/network stream quality switching

🧪 Demo

🚀 Getting Started

Installation

Check the latest version on:

dependencies:
  omni_video_player: <latest_version>

---

🛠️ Android Setup

In your Flutter project, open:

android/app/src/main/AndroidManifest.xml

<!-- Add inside <manifest> -->
<uses-permission android:name="android.permission.INTERNET"/>

<!-- Add inside <application> -->
<application
    android:usesCleartextTraffic="true"
    ... >
</application>

✅ The INTERNET permission is required for streaming videos.

⚠️ The usesCleartextTraffic="true" is only needed if you're using HTTP (not HTTPS) URLs.

---

🍎 iOS Setup

To allow video streaming over HTTP (especially for development or non-HTTPS sources), add the following to your Info.plist file:

<!-- ios/Runner/Info.plist -->
<key>NSAppTransportSecurity</key>
<dict>
  <key>NSAllowsArbitraryLoads</key>
  <true/>
</dict>

📦 Usage Examples

Network

VideoSourceConfiguration.network(
  videoUrl: Uri.parse('https://example.com/video.mp4'),
);

YouTube

VideoSourceConfiguration.youtube(
  videoUrl: Uri.parse('https://youtu.be/xyz'),
  preferredQualities: [OmniVideoQuality.high720, OmniVideoQuality.low144],
);

Vimeo

VideoSourceConfiguration.vimeo(
  videoId: '123456789',
  preferredQualities: [OmniVideoQuality.high720],
);

Asset

VideoSourceConfiguration.asset(
  videoDataSource: 'assets/video.mp4'),
);

📱 Example App

Explore the example/ folder for working demos:

• Full demo using different video sources: main.dart
• Minimal setup with controller and play/pause logic: example.dart

💡 Great starting points to understand how to integrate and customize the player.

🎯 Sync UI with AnimatedBuilder

When using OmniPlaybackController, the controller itself is a Listenable, meaning it notifies listeners when playback state changes (e.g. play, pause, fullscreen).

To build dynamic UI that reacts to those changes (like updating a play/pause button), wrap your widgets with AnimatedBuilder:

OmniVideoPlayer(
  options: VideoPlayerConfiguration.youtube(
    videoUrl: Uri.parse('https://www.youtube.com/watch?v=cuqZPx0H7a0'),
  ),
  callbacks: VideoPlayerCallbacks(
    onControllerCreated: (controller) {
      _controller = controller;
      setState(() {}); // Enables the button below
    },
  ),
),

AnimatedBuilder(
  animation: Listenable.merge([controller]),
  builder: (context, _) {
    if (controller == null) return const CircularProgressIndicator();

    final isPlaying = controller.isPlaying;

    return ElevatedButton.icon(
      onPressed: () =>
          isPlaying ? controller.pause() : controller.play(),
      icon: Icon(isPlaying ? Icons.pause : Icons.play_arrow),
      label: Text(isPlaying ? 'Pause' : 'Play'),
    );
  },
);

✅ Why it's needed

Flutter widgets don’t rebuild on Listenable changes by default. AnimatedBuilder lets your UI stay in sync without manually calling setState() on every controller update — making your code more efficient and reactive.

ℹ️ Recommended for any UI that depends on the controller (playback state, fullscreen, etc.). It ensures consistent behavior and avoids state mismatch.

🔮 Future Developments

Feature	Description	Implemented
📃 Playlist Support	YouTube playlist playback and custom video URL lists	❌
⏩ Double Tap Seek	Skip forward/backward by configurable duration	✅
📚 Side Command Bars	Left and right customizable sidebars for placing user-defined widgets or controls	❌
🧭 Header Bar	Custom header with title, channel info, and actions	❌
🖼 Picture-in-Picture (PiP)	Play video in floating overlay while multitasking	❌
📶 Quality Selection	Switch between 360p, 720p, 1080p, etc. during playback	✅ (YouTube, Network HLS)
⏱ Playback Speed Control	Adjust speed: 0.5x, 1.5x, 2x, etc.	✅
🔁 Looping / Repeat	Loop a single video or an entire playlist	❌
♿ Accessibility	Screen reader support, keyboard nav, captions, ARIA, high contrast, etc.	❌
⬇️ Download / Offline Mode	Save videos temporarily for offline playback	❌
📺 Chromecast & AirPlay	Stream to external devices like TVs or smart displays	❌
🔒 Parental Controls	Restrict age-inappropriate or sensitive content	❌
⚙️ Settings Button	Easily access and configure playback preferences	❌
👉 Swipe to Exit Fullscreen	Swipe down (or specific gesture) to exit fullscreen mode	✅

📄 License

BSD 3-Clause License – see LICENSE