The open-source IPTV player that never buffers. Combine all your sources — free TV, paid services, debrids — into one unified interface with Smart Channels, intelligent EPG matching, and automatic stream failover.
Built with Flutter for Android, macOS, Linux, and Windows.
Most IPTV players let you watch one provider at a time. When a stream buffers, you're stuck. And your free channels, paid services, and debrids are all in separate apps. clubTivi changes that — it brings everything into one interface and automatically switches streams when problems are detected. No more buffering. No more app-hopping. No more manually hunting for a working channel.
The headline feature that sets clubTivi apart. Group the same channel from multiple sources — free TV, paid services, debrids — into a single Smart Channel:
- One-click creation — multi-select matching channels, hit "New Smart Channel"
- Automatic failover — when buffering is detected, instantly switches to the next healthy stream
- Mix any source — combine free, paid, and debrid streams for the same channel in one group
- Priority ordering — arrange streams in your preferred order; the best source plays first
- Full EPG integration — Smart Channels show the same guide data as regular channels
- Visual indicators — amber ⚡ bolt icon, playing-stream highlight, expand to see all members
- Right-click management — rename, delete, remove members, add channels to existing groups
- 4-tier intelligent auto-matching — explicit mapping → tvgId lookup → normalized name match → call-sign extraction (WABC, WCBS, etc.)
- Full timeline guide view — horizontally scrollable multi-day programme grid with now-playing highlight
- EPG for Smart Channels — guide data pulls from the best-matched member automatically
- XMLTV support — load EPG from any URL or local file
- Compatible with EPG providers like epg.best and others
- Now-playing text on every channel row — see what's on without opening the guide
- Unlimited providers — add free TV (Pluto TV, etc.), paid IPTV services, debrids, and more
- One unified interface — all sources merge into one searchable, filterable channel list
- Provider badges — see which provider each stream comes from at a glance
- 324K+ channels tested — handles massive playlists with instant startup via phased loading
- Multiple favorite lists — create custom lists (Sports, News, Movies, etc.)
- Sidebar navigation — browse by provider group, favorite list, or "All Channels"
- Smart search — real-time filtering with debounced search across all channels
- Vanity names — rename any channel without affecting the underlying data
- Channel history — backspace to toggle between current and previous channel
- Full keyboard navigation — arrow keys, Enter for fullscreen, number keys for direct channel entry
- Volume control — left/right arrow keys adjust volume with visual overlay
- D-pad optimized — Android TV remote and gamepad support with focus-based navigation
- Multi-select — Shift+click or Cmd+click to select multiple channels for batch operations
- Debug dialog — press
Dto see stream details, EPG mapping, provider info, and failover alternatives
- media_kit powered — libmpv/FFmpeg backend for broad codec support
- Fullscreen mode — double-click or press Enter to toggle
- Preview row — see a live preview of the selected channel before committing
- Info overlay — channel name, EPG now-playing, and provider shown on channel switch
- Multi-audio track support — handles streams with multiple audio tracks (EAC-3, AAC, etc.)
- Instant startup — favorites and providers load first (Phase 0), everything else loads in background
- Phased loading — splash screen → favorites → sidebar groups → EPG → full channel list
- Lazy EPG loading — guide data fetched only for visible/favorite channels first
- Efficient logo caching — channel logos load once and persist across sessions
- Session persistence — remembers your last channel, scroll position, and sidebar state
| Platform | Status |
|---|---|
| macOS | ✅ Full support |
| Android (Phone/Tablet/TV) | ✅ Full support |
| Linux | ✅ Full support |
| Windows | ✅ Full support |
- Flutter SDK (3.29+)
- For Android: Android Studio + Android SDK
- For macOS: Xcode 15+
- For Linux:
clang,cmake,ninja-build,pkg-config,libgtk-3-dev,libmpv-dev - For Windows: Visual Studio 2022 with C++ desktop development workload
git clone https://github.com/clubanderson/clubTivi.git
cd clubTivi
flutter pub get
flutter run -d macos # or linux, windows, <android-id>- Go to Settings (gear icon) and add your IPTV provider (M3U URL or Xtream Codes credentials)
- Add an EPG source URL for programme guide data
- Channels load automatically — star your favorites ⭐
- Multi-select channels → create Smart Channels ⚡ for automatic failover
| Layer | Technology |
|---|---|
| UI Framework | Flutter 3.29+ / Dart 3.11+ |
| State Management | Riverpod |
| Video Playback | media_kit (libmpv/FFmpeg) |
| Local Database | Drift (SQLite) |
| EPG Parsing | Custom XMLTV parser |
| Playlist Parsing | Custom M3U/M3U+ & Xtream Codes parser |
lib/
├── main.dart # App entry point
├── data/
│ ├── datasources/local/ # Drift database, queries, migrations
│ ├── models/ # Channel, EPG, Provider models
│ └── services/ # Stream alternatives, failover engine
├── features/
│ ├── channels/ # Channel list, guide view, Smart Channels, sidebar
│ ├── player/ # Video player, failover, playback controls
│ ├── providers/ # Provider management (add/edit/delete)
│ ├── settings/ # App settings, EPG config
│ └── shows/ # VOD / series browser
└── platform/ # Platform-specific adaptations
Key design decisions:
- Single-screen architecture — channels, guide, search, and Smart Channels all live in
channels_screen.dartfor instant navigation - Phased startup — favorites render in <1s, full channel list loads incrementally in background
- Smart Channel groups stored in SQLite (
failover_groups+failover_group_channelstables) with in-memory index for O(1) lookups - EPG matching runs 4 tiers of heuristics so channels match guide data without manual configuration
- Multi-platform Flutter app (macOS, Android, Linux, Windows)
- M3U / M3U Plus / Xtream Codes parser
- Video player with media_kit
- Channel list with favorites, search, groups
- XMLTV EPG parser with 4-tier auto-matching
- Full timeline guide view
- Multi-provider management
- Smart Channels with automatic failover
- Keyboard, gamepad, and remote control navigation
- Instant startup with phased loading
- Session persistence
- Warm failover (background stream health monitoring)
- Catch-up / timeshift (provider-dependent)
- Recording (local DVR)
- Theming and customization
- Backup/restore settings and Smart Channel configs
- Multi-language support
- Web companion remote control
Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
- Fork the repo
- Create a feature branch (
git checkout -b feat/amazing-feature) - Commit with DCO sign-off (
git commit -s -m 'feat: add amazing feature') - Push and open a PR
This project is licensed under the Apache License 2.0 — see the LICENSE file for details.
clubTivi is a media player application. It does not provide any content, streams, or IPTV subscriptions. Users are responsible for ensuring they have the legal right to access any content they configure in the application.