AI-assisted live IPTV / broadcast stream analysis — channel discovery, speech-to-text summaries, vision scene understanding, EPG, and ad detection — in one stack.
Languages: 🇬🇧 English · 🇹🇷 Türkçe
Features · Screenshots · Web dashboard · REST API · Telegram bot · Quick start · Configuration
Satellite Eye helps you understand TV streams faster. Instead of manually checking channels one by one, you can see what is on air, get quick summaries, capture live screenshots, and follow likely ad breaks from one place.
Open the web app, ask in plain language, and get clear answers without digging through complex stream data. You can also use the same flow from the Telegram bot to get quick summaries and now-playing info on mobile.
| Area | Description |
|---|---|
| Channel management | Aggregate channel lists from multiple M3U sources, browse them in one place, and find what you need with search, country, and category filters. |
| Now-playing info (EPG) | See what is currently on air, what started before, and what is next — without jumping between external guide sites. |
| Speech summaries | Capture live audio, transcribe it with Whisper, and generate a short LLM summary so you can catch up on any channel in seconds. |
| Natural-language chat | Ask questions naturally in the web app or Telegram — "What is on now?", "Summarize this channel" — and get direct answers. |
| Scene snapshots | Capture a live frame from any stream and get a plain-language description of what is happening on screen. |
| Ad break tracking | Monitor selected channels and receive alerts when a commercial break likely starts or ends, with visual and audio evidence. |
| Reliable stream access | Connect to protected or difficult streams with custom HTTP headers and signed URL resolution. |
| Runtime settings | Manage everyday app settings from the UI while keeping sensitive secrets in environment variables. |
| Language-aware responses | Set a response language so all summaries and assistant replies stay consistent for your audience. |
Demo 1 — "What's on BBC America right now? Can you give me a summary?" — live audio capture, speech-to-text, and LLM summary in one answer.
Demo 2 — "Are there any people on BBC Lifestyle? If so, how many and what are their genders?" — vision-based people detection with structured result.
Demo 3 — "What cartoon is currently on the Disney Channel?" — multi-country channel disambiguation followed by EPG answer.
- Channel browser — Search and filter channels instead of scrolling through long playlists.
- Live AI chat — Ask natural-language questions and get direct answers about what is on air.
- Summary card — Get a short "what is happening now" recap for the selected channel.
- Screenshot preview — Capture and review a live frame without leaving the chat flow.
- Ad watchlist — Track selected channels and get notified when ad breaks likely begin or end.
- Settings panel — Adjust runtime behavior from the browser; sensitive values stay in
.env. - API status bar — Check service readiness at a glance before using advanced features.
- Telegram guide — Quick command reference so mobile usage stays simple.
When frontend/dist is built, the same FastAPI process serves the SPA at /. If the build is missing, / shows a minimal API landing page with links to /docs and sample endpoints.
| Endpoint group | Examples |
|---|---|
| Health | GET /health |
| Channels | GET /api/channels, GET /api/channels/categories, GET /api/channels/refresh-status, GET /api/channels/{channel}/epg |
| EPG | GET /api/epg/{channel}, POST /api/epg/sync |
| AI | POST /api/ai/query (chat), POST /api/ai/analyze (STT + summary), GET /api/ai/settings, GET /api/ai/media/audio/{token} |
| Vision | GET /api/vision/status, POST /api/vision/screenshot, POST /api/vision/watchlist/scan, GET /api/vision/evidence/{path} |
| Settings | GET /api/settings/public, PUT /api/settings/public |
Full schemas and interactive docs: http://localhost:8000/docs (Swagger UI).
Requires TELEGRAM_BOT_TOKEN in .env.
| Command | Description |
|---|---|
/start |
Welcome message and command help. |
/summary <channel> |
Capture live audio → Whisper transcription → LLM summary. |
/epg <channel> |
Current program name and description from EPG. |
/screenshot <channel> |
Capture a frame and send it as a photo with caption. |
/adtrack <channel> |
Start periodic ad monitoring; alerts when programming likely resumes. |
Free-text messages are routed through the same /api/ai/query pipeline as the web UI, with an optional language hint from the Telegram client. Channel ambiguity is resolved with numbered replies, same as the web flow.
- Python 3.11+ (CI runs on newer versions as well).
- ffmpeg — stream capture, audio extraction, Telegram voice transcoding.
- Node.js 18+ — frontend build toolchain.
- Ollama — local LLM runtime for text and vision models.
- Optional: GPU for faster Whisper inference and vision model performance.
- Input sources — M3U playlists for stream URLs and XMLTV feeds for EPG program data.
- Backend — FastAPI with REST endpoints, background refresh tasks, and SQLite-backed caching.
- AI stack — Local Ollama models for text and vision, faster-whisper for speech-to-text.
- Media pipeline — ffmpeg-based capture for audio segments and screenshots from live streams.
- Clients — React + Vite web dashboard and an optional Telegram bot sharing the same query pipeline.
- Configuration —
.env-driven settings with public runtime options editable from the UI.
- CPU: 4+ cores (x86_64 or ARM64)
- RAM: 8 GB minimum, 16 GB recommended
- Storage: 10 GB free (models and caches may increase usage)
- Software: Python 3.11+, Node.js 18+, ffmpeg, Ollama
- Network: Stable connection for M3U/XMLTV sources and initial model downloads
pip install -r requirements.txt
cp .env.example .env
# Edit .env: set Ollama model tags and optionally TELEGRAM_BOT_TOKENDevelopment (recommended) — backend + Vite dev server with API proxy:
cd frontend && npm install && cd ..
./dev.sh- API:
http://127.0.0.1:8000(or customPORT) - Frontend:
http://127.0.0.1:5173
Production — build the SPA and serve everything from one process:
cd frontend && npm install && npm run build && cd ..
python app.pyOpen http://localhost:8000 for the UI and /docs for Swagger.
With AUTO_PULL_OLLAMA_MODELS enabled, missing model tags are pulled automatically on startup (requires ollama on PATH).
.env.example is the authoritative template. Notable groups:
- Telegram — Bot token.
- LLM — Model tags (
LLM_MODEL,VISION_MODEL) andOLLAMA_HOST. - Vision — Vision model, scene audio duration, optional fusion pass.
- Whisper — Model size, device, language detection, fallback language.
- Data sources —
M3U_URL,M3U_EXTRA_URLS,EPG_URL,EPG_EXTRA_URLS, refresh intervals, default country filter. - CORS —
CORS_ORIGINSfor deployed UI origins. - Ad detection — Thresholds, scan concurrency, cache TTL, watchlist size cap.
- Runtime —
PORT,DEBUG,LOG_LEVEL,TMP_DIR,SYSTEM_RESPONSE_LANGUAGE, ffmpeg headers, signed-stream resolver rules.
SatelliteEye/
├── CONTRIBUTING.md # Contributor standards and workflow
├── app.py # Entry point: uvicorn + Telegram bot + Ollama model check
├── backend/
│ ├── ai/ # Query router, LLM engine, STT, prompts, shared pipeline
│ ├── channels/ # M3U parsing, EPG fetching, stream management, disambiguation
│ ├── database/ # SQLite cache layer
│ ├── settings/ # Public runtime settings API
│ ├── telegram/ # Bot command handlers, i18n
│ └── vision/ # Screenshot capture, ad detector, vision LLM adapter
├── docs/
│ └── screenshots/ # Demo images and GIFs for README
├── frontend/ # React + Vite SPA (Tailwind CSS)
├── tests/ # pytest suite (backend + integration)
└── scripts/ # Quality gate scripts, dev helpers
Issues and pull requests are welcome. See CONTRIBUTING.md for coding standards, testing expectations, and commit conventions. If this project saves you time, a star on GitHub helps others discover it.
This project is released under the MIT License.
If Satellite Eye is useful for your workflow, consider starring the repository and sharing it with others who work with IPTV or broadcast monitoring.