ProxyStream

IPTV aggregator proxy that unifies Xtream Codes, M3U, and Stalker Portal providers behind a single endpoint with intelligent stream failover.

What it does

• Aggregates any number of upstream IPTV providers (Xtream, M3U URLs, Stalker portals — configured via YAML).
• Exposes three inbound protocols clients can connect to:
  • Xtream Codes API (/player_api.php, /live/..., /movie/...)
  • M3U playlist (/get.php, /playlist.m3u)
  • Stalker Portal (/stalker_portal/server/load.php)
• Merges channels and VOD across providers with fuzzy name matching + tvg-id mapping.
• Live failover: if one provider's stream stalls / 4xx / 5xx / gets rate-limited, switches to the next.
• Per-stream health scoring (0–100) drives provider selection.
• EPG aggregation from multiple XMLTV sources, served at /epg.xml.
• Admin dashboard at /admin (HTMX + Jinja2).

Quick start

Local dev (uv)

# Install uv: https://docs.astral.sh/uv/getting-started/installation/
git clone <repo-url> proxystream
cd proxystream

uv sync                          # create venv + install deps
cp .env.example .env             # then edit with your settings
cp config/providers.yaml.example config/providers.yaml  # configure providers
uv run python main.py            # starts on :8080

Docker

docker compose up -d --build
# Health:   http://localhost:8080/health
# Docs:     http://localhost:8080/docs
# Admin:    http://localhost:8080/admin/

Configuration

Layer	File	Purpose
Runtime settings	.env (or env vars with PROXYSTREAM_ prefix)	Listen port, failover thresholds, health scoring, fuzzy match, EPG refresh
Providers	config/providers.yaml	Upstream providers — Xtream, M3U, Stalker — any count
Database	SQLite at data/proxystream.db (or /data/proxystream.db in container)	Health scores, failover logs, admin users

See .env.example for every available env var.

Project layout

proxystream/
├── main.py              # FastAPI app entrypoint
├── config.py            # pydantic-settings: all thresholds, env vars
├── db.py                # SQLAlchemy async engine + sessionmaker
├── providers/
│   ├── base.py          # Abstract provider interface
│   ├── xtream.py        # Xtream Codes backend
│   ├── m3u.py           # M3U URL backend
│   ├── stalker.py       # Stalker Portal backend
│   ├── config.py        # Provider config models
│   ├── models.py        # Provider models
│   └── registry.py      # Provider registry
├── aggregator/
│   ├── merger.py        # Channel/VOD unification + dedup
│   ├── catalog.py       # Catalog management
│   ├── epg.py           # EPG fetch, merge, serve
│   ├── health.py        # Health scoring + monitoring
│   └── failover.py      # Stream failover logic
├── api/
│   ├── xtream_api.py    # Xtream Codes emulation routes
│   ├── xtream_auth.py   # Xtream auth helpers
│   ├── m3u_api.py       # M3U playlist routes
│   ├── stalker_api.py   # Stalker Portal emulation routes
│   └── epg_api.py       # EPG serving routes
├── admin/
│   ├── routes.py        # Admin dashboard routes
│   ├── auth.py          # Admin authentication
│   ├── static/          # CSS assets
│   └── templates/       # Jinja2 templates
├── proxy/
├── config/
│   └── providers.yaml   # Provider definitions (template)
├── data/                # Runtime data (gitignored)
├── scripts/             # Utility scripts
├── tests/
├── Dockerfile
├── docker-compose.yml
└── pyproject.toml

API Endpoints

Endpoint	Description
GET /health	Health check
GET /ready	Readiness probe (DB + Redis + providers)
GET /docs	Swagger UI
GET /redoc	ReDoc
GET /player_api.php	Xtream Codes API
GET /get.php	M3U playlist output
GET /playlist.m3u	M3U playlist output
GET /stalker_portal/	Stalker Portal emulation
GET /epg.xml	EPG data
GET /admin/	Admin dashboard

Roadmap

Phase	Status	Deliverable
1	✅ Done	Project scaffold + FastAPI app skeleton + Docker setup
2	✅ Done	Provider abstraction layer (base class + Xtream implementation)
3	✅ Done	Xtream Codes API emulation (inbound)
4	✅ Done	Channel merger + fuzzy matching
5	✅ Done	Live stream proxy with basic failover
6	✅ Done	Health scoring system
7	✅ Done	M3U output + Stalker portal emulation
8	✅ Done	EPG aggregation
9	✅ Done	VOD support
10	✅ Done	Admin dashboard

License

MIT.