Omni Video Player는 YouTube, Vimeo, 로컬 자산 및 네트워크 URL 등 다양한 소스에서 비디오를 재생할 수 있도록 설계된 유연한 Flutter 위젯입니다. 재생 컨트롤, 스타일링 및 동작에 대한 완전한 사용자 정의 옵션을 제공하여 어떤 Flutter 애플리케이션에도 쉽게 통합할 수 있습니다. 이 패키지는 Android, iOS, Web 플랫폼을 지원하며 크로스 플랫폼 일관성을 보장합니다. 깔끔한 API와 내장된 오류 처리 기능으로 유연성 손실 없이 비디오 통합을 단순화합니다.
사용 사례
앱에 YouTube 동영상 삽입하기
Flutter 내에서 Vimeo 콘텐츠 재생
원격 URL에서 비디오 스트리밍
로컬 비디오 자산 사용
사용자 지정 비디오 플레이어 만들기
주요 기능
YouTube, Vimeo, 자산 및 네트워크 비디오 지원
높은 사용자 정의 가능한 UI 및 컨트롤
크로스 플랫폼 호환성 (Android, iOS, Web)
내장된 오류 처리 및 로딩 상태
최소 설정으로 간단한 통합
적합한 대상
미디어 집약형 애플리케이션
비디오 콘텐츠를 갖춘 교육 앱
콘텐츠 전달 플랫폼
사용자 정의 비디오 플레이어 구현
다중 소스 비디오 지원을 필요로 하는 앱
고려 사항
온라인 비디오 소스 사용을 위해 인터넷 접속이 필요합니다
고급 사용자 정의를 위해 추가 구성이 필요할 수 있습니다
각 플랫폼에서 지원하는 비디오 형식에 제한됨
YouTube/Vimeo 재생을 위한 외부 API에 의존
원본 README
연결된 소스 저장소의 README 원문 스냅샷입니다. 최신 내용은 저장소에서 확인하세요.
The ultimate All-in-One Flutter video solution. Stream YouTube, Vimeo, HLS, and local files with a single, unified controller.
🚀 Why Omni Video Player?
Stop juggling multiple packages for different video sources. omni_video_player wraps the complexity of specialized extractors and webviews into a single, powerful widget.
Smart YouTube Handling: Direct extraction via youtube_explode_dart with an automatic WebView fallback. The player seamlessly switches to WebView if the primary method fails, ensuring uninterrupted playback and no black screens for your users.
Vimeo Ready: Stable playback using optimized WebViews.
Adaptive Streaming: Native support for HLS (.m3u8) with built-in quality selection UI.
Unified Controller: One controller to rule them all. Manage state, volume, and seeking regardless of the source.
📊 Compatibility Matrix
Source / Format
Android
iOS
WebView (Android & iOS - alt/fallback)
Web
Notes
YouTube
✅
✅
✅
✅
Auto-fallback to WebView on primary method fails.
Vimeo
-
-
✅
✅
High stability via WebView.
HLS (.m3u8)
✅
✅
-
✅
Multi-quality switching supported.
Network (.mp4/etc)
✅
✅
-
✅
Standard streaming.
Assets/Files
✅
✅
-
✅
Local storage & bundle support.
AVI
✅
❌
-
✅
Not supported on iOS (OS limitation).
WebM
✅
❌
✅
✅
Requires WebView on iOS (no native support); seeking is disabled on iOS (WebKit can't seek WebM without freezing).
✨ Key Features
📦 Universal Sources: YouTube (Live/VOD), Vimeo, Network, Assets, and Local Files.
⚙️ Quality Selector: Built-in UI to switch resolutions for YouTube and HLS streams.
🎨 Fully Skinnable: Customize the UI, overlays, and controls to match your brand.
⏩ Advanced UX: Double-tap to seek, playback speed control (0.5x to 2.0x), and swipe gestures.
🔊 Global Sync: Synchronize volume and mute states across multiple player instances.
⛶ Native Fullscreen: Smooth transition to fullscreen mode on mobile.
🧪 Preview
YouTube
YouTube Live
M3U8 Network Link
Vimeo
🛠️ Quick Start
1. Installation
Add this to your pubspec.yaml:
dependencies:omni_video_player:^latest_version
2. Platform Setup (Optional)
Configure these only if your use case requires it:
Android (AndroidManifest.xml)
INTERNET: Required for any online stream (YouTube, Vimeo, Web).
Want to see the player in action with all its features? We have provided a comprehensive example project.
Download/Clone this repository.
Navigate to the example/ folder.
Run lib/main.dart on your device or emulator.
This demo showcases everything the library supports: quality switching, source transitions, custom controls, and more. It is the best way to understand the full potential of omni_video_player.
Reactive UI with Controller
Control the player from anywhere in your widget tree:
Play an ordered queue of videos with on-video previous/next buttons. Set autoAdvance to move to the next video automatically when one finishes, and loop to wrap around the ends:
Only one audible player plays at a time: starting an audible player pauses the audible one before it. Muted players sit outside that rule — any number of them play together, and unmuting one makes it join the rule, pausing whoever was audible at that moment. Muting a playing video releases it from the rule without stopping it.
A player holds the wakelock while it is audible or fullscreen, so a list of decorative muted loops does not keep the device awake, while a video you muted and kept watching full screen still does.
For a row or list of muted looping videos, set autoPlay: true and autoMuteOnStart: true, and leave pauseWhenOutOfView at its default: playback starts when the player is fully visible and stops when it scrolls away. onFinished fires once at the real end of every playback and re-arms afterwards, so it can drive a "play N times" counter.
A player given an explicit initialVolume keeps it. The shared volume no longer overwrites it when the player is created, and later changes to the shared volume still reach it unless synchronizeMuteAcrossPlayers is false. When both are set, autoMuteOnStart wins and initialVolume becomes the level the player returns to once unmuted.
🔮 Roadmap
Feature
Description
Status
Picture-in-Picture
Play in floating overlay (OS level).
🏗️ Researching
Playlist Support
Queue system for multiple videos.
✅ (4.0.0)
Download Mode
Cache management for offline viewing.
🔜 Planned
Cast Support
Google Cast & AirPlay integration.
🔜 Planned
❓ FAQ
Known Issue: "Made for Kids" YouTube Videos
Youtube videos marked as "Made for Kids" in YouTube Studio cannot be played using the default extraction method on mobile platforms (iOS/Android) due to API restrictions.
Solution 1: If you own the video, uncheck the "Made for Kids" option in YouTube Studio.
Solution 2: Initialize the player with forceYoutubeWebViewOnly: true. This bypasses the default extraction and plays the video via WebView.
Why is there no quality selection for YouTube on iOS?
On Android, we can handle separate Audio and Video streams provided by the API, allowing for multiple quality options.
The iOS Limitation: The native iOS player struggles to synchronize separate Audio/Video tracks without pre-loading the entire file (causing huge delays).
The Result: On iOS, we must use a "muxed" stream (combined audio/video). The YouTube API currently provides only one muxed stream at 360p. Therefore, quality selection is disabled on iOS as there are no other combined streams available to switch to.
Why can't I seek WebM videos on iOS?
WebM has no native iOS support, so it plays through a WebView. WebKit, however, cannot seek a WebM stream without freezing the decoder (the frame stalls and can't recover). To avoid a broken state, seeking is disabled for WebM on iOS: the seek bar and skip gestures are turned off, while play/pause and duration work normally. WebM seeking works on Android (native playback).
📄 License
Released under the BSD 3-Clause License. See LICENSE for details.