Community-powered IPTV player with 16,000+ crowdsourced channels, privacy-first analytics, and community statistics.
TV Viewer is a free, open-source IPTV player where the community maintains the channel list. Users report broken streams, submit new channels, and anonymously share aggregate usage signals that improve stream health and discovery for everyone. No account needed. No ads. No tracking by default.
If TV Viewer saves you a cable bill or just makes your day better, consider supporting development:
- Community Statistics page now shows richer totals for channels, categories, countries, and recent additions
- Timezone-based country detection improves local recommendations and privacy-preserving analytics on Android and Web
- Supabase backend migrated to project
cdtxpefohpwtusmqengu - APKPure notify workflow added to the release pipeline
- Docker Hub stays current with
asummoner/tvviewerapp:latest
See the CHANGELOG for full release history.
- 🌍 16,000+ channels worldwide — Aggregated from community-maintained playlists and configurable sources
- 👥 Crowdsourced quality — Users report broken streams and submit fixes from the app or GitHub
- 📊 Community Statistics — Anonymous aggregated usage data for active users, plays, countries, and platform trends
- 🌐 Timezone-based country detection — Privacy-friendly local country inference without GPS or IP lookup
- 📂 Rich browsing — Filter by category, country, language, and media type (TV/Radio)
- 📻 Dedicated radio experience — Background audio playback, genre browsing, and now-playing controls on Android
- 🔀 Multi-source failover — Switch between alternative stream sources without leaving playback
- 💾 Offline-friendly caching — Local cache and favorites still work when Supabase is unavailable
- 📺 EPG support — XMLTV-based now/next program data with live progress bars
- 🔒 Privacy-first telemetry — Opt-in analytics only, with no login and no PII collection
- 🛡️ Hardened web backend — SSRF protections, safe Supabase writes, and server-side statistics aggregation
- 🐳 Self-hosted web/Docker edition — FastAPI + HLS.js UI for NAS and browser deployments
| Channel | Status | Notes |
|---|---|---|
| GitHub Releases | ✅ Live | Windows zip, Linux source, Android APK + AAB assets |
| Google Play | ✅ Live | Primary Android store distribution |
| F-Droid | 🟡 MR open | fdroid-build.yml produces unsigned APK artifacts |
| APKPure | 🟡 Pending | apkpure-notify.yml helps release discovery |
| Samsung Galaxy Store | 🟡 Pending | Planned additional Android storefront |
| Docker Hub | ✅ Live | asummoner/tvviewerapp:latest |
| Platform | Download | Notes |
|---|---|---|
| Android | Google Play / Latest Release | Android 8.0+ (API 26) |
| Windows | Latest Release | Self-contained, VLC bundled |
| Web / Docker | docker run -p 8765:8765 asummoner/tvviewerapp:latest |
Browser-based, NAS-friendly |
| Linux | From source | Python 3.12+ + VLC |
- Download the latest Windows asset from Releases
- Extract anywhere and run
TVViewer.exe
- Install from Google Play or download the latest APK from Releases
- Open TV Viewer and start browsing channels immediately
git clone https://github.com/tv-viewer-app/tv_viewer.git
cd tv_viewer
pip install -r requirements.txt
python main.pydocker run -d --name tv-viewer -p 8765:8765 --restart unless-stopped asummoner/tvviewerapp:latest
# Open http://localhost:8765pip install -r web/requirements.txt
python -m web.server
# Open http://localhost:8765| Layer | Stack | Notes |
|---|---|---|
| Desktop | Python 3.12 + CustomTkinter + VLC | Native Windows/Linux client |
| Mobile | Flutter 3.32.0 + Material 3 | Gradle 8.9, AGP 8.7.0, Kotlin 1.9.22 |
| Web | FastAPI + vanilla JS + HLS.js | Browser UI + self-hosted Docker image |
| Shared backend | Supabase (cdtxpefohpwtusmqengu) |
Channels, status, analytics, aggregated stats |
| Android audio | just_audio + audio_service |
Background playback for radio streams |
| CI/CD | 28 GitHub Actions workflows | Release, store, Docker, analytics, backend ops |
| Document | Description |
|---|---|
| CHANGELOG.md | Version history and release notes |
| docs/ARCHITECTURE.md | System architecture and current platform stack |
| CONTRIBUTING.md | How to contribute channels, code, and docs |
| docs/SUPPORT_GUIDE.md | Troubleshooting guide |
| docs/API.md | API notes for the web backend |
| docs/TEST_PLAN.md | Test plan and coverage |
| docs/RELEASE_PROCESS.md | Release checklist |
| PRIVACY_POLICY.md | Privacy policy |
tv_viewer_project/
├── main.py # Desktop entry point
├── config.py # Configuration and current version (2.20.2)
├── Dockerfile # Docker image definition
├── core/ # Channel manager, repository, stream checker
├── ui/ # Desktop UI
├── utils/ # Shared utilities, analytics, normalization, Supabase client
├── web/ # FastAPI backend + static web client
├── flutter_app/ # Flutter Android app source + fastlane metadata
├── tests/ # Python tests (299+)
├── docs/ # Project documentation
└── .github/workflows/ # CI/CD automation (28 workflows)
TV Viewer uses 28 GitHub Actions workflows across validation, release orchestration, store publishing, Docker publishing, analytics, and Supabase maintenance. Key workflows include:
ci.yml— core CI for Python/Web changesbuild.yml/release.yml/release-gate.yml— release pipeline and gatingbuild-apk.yml/play-store-deploy.yml— Android APK/AAB build and Google Play deploymentfdroid-build.yml/apkpure-notify.yml— alternate Android distribution channelsdocker-publish.yml— multi-arch Docker Hub publish (latest+ version tags)supabase-*.ymland analytics workflows — backend health, keepalive, monitoring, reporting
See docs/SUPPORT_GUIDE.md for detailed troubleshooting.
| Problem | Solution |
|---|---|
| VLC not found | The Windows release bundles VLC. From source, install VLC locally |
| No channels | Check connectivity and refresh sources |
| Stream not playing | Try another source from the source selector |
| Statistics unavailable | Verify the web server can reach Supabase and /api/statistics is enabled |
| Supabase unavailable | The app continues to work from cache; analytics and shared health resume later |
We welcome contributions! See CONTRIBUTING.md for how to:
- 📺 Submit new channels or report broken ones
- 🐛 Report bugs
- 💻 Contribute code
- 📖 Improve documentation
MIT License — see LICENSE for details.
- IPTV-org and other community playlist maintainers
- python-vlc for desktop playback
- Flutter for the Android client
- Supabase for the shared backend and aggregated analytics