A Docker-based Xtream Codes proxy that filters IPTV content (Live TV, Movies, Series) from multiple sources with per-source dedicated routes, merged playlists, stream proxying, advanced filtering, monitoring and downloading.

• 📺 Full Xtream Codes API Proxy - Works with any Xtream-compatible player (TiviMate, XCIPTV, etc.)
• 🔗 Multi-Source Support - Configure multiple Xtream providers with dedicated routes per source
• 🎬 Merged Playlist - Combine all sources into a single unified endpoint with virtual IDs
• 🛡️ Stream Proxy - Optionally proxy all streams through the server (hides upstream URLs, better for 4K)
• 🛣️ Per-Source Routing - Each source has its own URL path to avoid ID conflicts
• 🎬 Live TV, Movies & Series - Filter all content types independently
• 🔧 Web-based Configuration - Easy UI to manage sources, settings and filters
• 🎯 Advanced Filtering - Include/exclude filters with multiple match types per source
• 🚫 Exclude All - Start with empty and whitelist only what you want
• 🏷️ Source Prefixing - Optionally prefix group names to identify content origin
• 🔄 Smart Caching - Background refresh with configurable TTL and real-time progress bar
• 💾 Persistent Cache - Survives container restarts
• � Content Browser - Browse and search all your content with cover art and details
• 📂 Custom Categories - Create manual or automatic categories with pattern matching
• 📱 Telegram Notifications - Get notified when new content matches your categories
• ⬇️ VOD & Series Downloads - Download movies and series episodes locally with a cart-based queue
• 🎞️ Jellyfin/Kodi Metadata - Auto-generate .nfo files and download poster art alongside videos for seamless library integration
• ▶️ Built-in Stream Preview - Preview streams directly in the browser with mpegts.js/hls.js support, audio track selection, and keyboard shortcuts
• 📡 Series Monitoring - Automatically track series for new episodes with auto-download and Telegram alerts
• �🐳 Docker Ready - Easy deployment with docker-compose

docker run -d \ --name xtreamfilter \ -p 8080:5000 \ -v ./data:/data \ --restart unless-stopped \ spanishst/xtreamfilter:latest

Or with docker-compose, create a docker-compose.yml:

services: xtreamfilter: image: spanishst/xtreamfilter:latest container_name: xtreamfilter ports: - "8080:5000" volumes: - ./data:/data - ./downloads:/data/downloads restart: unless-stopped environment: - TZ=Europe/Paris

Then run:

docker-compose up -d

1. Clone the repository:

git clone https://github.com/spanishst/xtreamfilter.git cd xtreamfilter

2. Build and run:

docker-compose up --build -d

1. Open the web UI:

http://localhost:8080 

2. Add your Xtream source(s) in the Sources section:

   • Name, Host, Username, Password
   • Dedicated Route (required): URL path for this source (e.g., myprovider)

3. Configure your filters for each source - Live TV, VOD, and Series

4. Connect your IPTV player using one of the connection URLs shown in the UI

XtreamFilter provides multiple ways to connect your IPTV player:

Combines all sources into a single playlist with virtual IDs that prevent conflicts:

Server: http://YOUR_SERVER_IP:8080/merged Username: proxy Password: proxy 

• All sources appear in one unified playlist
• Virtual IDs ensure no conflicts between sources (each source gets a 10M ID range)
• Filters from each source are applied

Each source has its own dedicated endpoint:

Filtered endpoint (with your filter rules applied):

Server: http://YOUR_SERVER_IP:8080/<route> Username: (from your provider) Password: (from your provider) 

Unfiltered endpoint (full catalog from this source):

Server: http://YOUR_SERVER_IP:8080/<route>/full Username: (from your provider) Password: (from your provider) 

Generate M3U playlists for players that don't support Xtream API:

When enabled, all streams are proxied through the XtreamFilter server instead of redirecting clients directly to upstream servers.

• Privacy: Upstream server URLs are hidden from clients
• 4K Performance: Adaptive buffering optimized for 4K streams (up to 25 Mbps)
• Freeze Prevention: Smart pre-buffering and dynamic buffer sizing
• Single Point of Control: All traffic flows through your server

The proxy includes an intelligent buffering system designed to prevent freezes when upstream servers have issues:

How it works:

1. Pre-buffering: Before sending any data to the client, the proxy fills a 4 MB buffer to ensure smooth playback start
2. Throughput monitoring: Measures upstream speed every 2 seconds, keeping 10 samples for stability
3. Slowdown detection: If current throughput drops below 60% of average:
   • Buffer doubles (e.g., 1 MB → 2 MB)
   • On consecutive slowdowns, buffer increases 4x for faster response
4. Stable recovery: After 4 stable periods (~20s), buffer reduces by 25% to optimize memory
5. Logging: All buffer adjustments are logged at INFO level for monitoring

Example log output:

Pre-buffer filled: 4096.0KB in 0.34s (11993.5 KB/s) Upstream slowdown detected (2285 KB/s < 11950 KB/s avg), increasing buffer: 1024KB -> 2048KB Upstream slowdown detected (1781 KB/s < 7832 KB/s avg), increasing buffer: 2048KB -> 8192KB Upstream stable (2033 KB/s), reducing buffer: 16384KB -> 12288KB 

Enable/disable via the web UI in the Connection URLs card, or via API:

# Enable proxy curl -X POST http://localhost:8080/api/proxy/enable # Disable proxy  curl -X POST http://localhost:8080/api/proxy/disable # Check status curl http://localhost:8080/api/proxy/status

When disabled, clients receive a 302 redirect to the upstream URL.

1. Open the web UI and go to the Sources section
2. Click Add Source to add a new provider
3. Enter the source details:
   • Name: Friendly name for the source (e.g., "Provider A")
   • Host: The Xtream server URL (e.g., http://provider.example.com)
   • Username/Password: Your credentials for this provider
   • Prefix (optional): Text to prepend to group names (e.g., [ProvA] )
   • Dedicated Route (required): URL path for this source (e.g., providera)
   • Enabled: Toggle to enable/disable this source

Each source must have a dedicated route. This ensures:

• No ID conflicts between providers (two sources may have series with the same ID)
• Clean separation of content per source
• Correct playback for all content types

Example with two sources:

• Source "Smarters" with route smarters:
  • Filtered: http://YOUR_SERVER_IP:8080/smarters
  • Unfiltered: http://YOUR_SERVER_IP:8080/smarters/full
• Source "Strong" with route strong:
  • Filtered: http://YOUR_SERVER_IP:8080/strong
  • Unfiltered: http://YOUR_SERVER_IP:8080/strong/full

The Prefix option prepends text to all group names from a source, helping identify content origin when viewing in your player.

Example:

• Source with prefix [US] → Groups become [US] Sports, [US] Movies, etc.

Each source has its own independent filter configuration:

• Filters are applied per-source
• You can have different include/exclude rules per provider
• Select a source in the filter dropdown to edit its specific filters

• Live TV - Television channels
• VOD - Movies/Films
• Series - TV series

• Include - Only keep matching items (whitelist mode)
• Exclude - Remove matching items (blacklist mode)

The Exclude All option lets you start with a clean slate by excluding everything, then adding include rules to whitelist specific content:

1. Click "Exclude All Groups" or "Exclude All Channels"
2. Add "Include" filters for the specific content you want to keep

This is useful when you only want a small subset of content from a large catalog.

Include only French content (Live TV):

• Type: include, Match: starts_with, Value: FR|

Exclude adult content (all categories):

• Type: exclude, Match: contains, Value: XXX

Include specific streaming services:

• Type: include, Match: exact, Value: NETFLIX SERIES
• Type: include, Match: exact, Value: DISNEY+ MOVIES

Start fresh and whitelist:

1. Add: Type: exclude, Match: all, Value: *
2. Add: Type: include, Match: starts_with, Value: FR|

The proxy caches all data from upstream servers for fast responses:

• Default TTL: 1 hour (3600 seconds)
• Background Refresh: Automatic refresh before cache expires
• Real-time Progress: Visual progress bar with step-by-step updates
• Cross-Worker Sync: Progress is visible even when page is reloaded
• Disk Persistence: Cache survives container restarts
• Per-Source Caching: Each source is cached independently
• Cancel Button: Abort stuck refreshes if needed

The web UI shows:

• Total Live Streams, Movies, and Series counts
• Cache validity status (✅ valid, ⚠️ expired, 🔄 refreshing)
• Last refresh time
• Progress bar during refresh with current step and source

The Browse feature provides a rich interface to explore all your IPTV content:

• Visual Grid View - Browse movies and series with cover art thumbnails
• Search & Filter - Search by name, filter by group/category
• Content Details - View descriptions, ratings, cast, and episode lists
• Quick Actions - Add items to custom categories directly from the browser
• Pagination - Efficiently browse large catalogs
• ▶️ Stream Preview - Preview video streams directly without leaving the page

Access the browser at /browse or click the 🔍 Browse Content button on the main page.

The Browse page includes an integrated player for quickly previewing streams before downloading or adding to your library:

Create your own categories to organize content across all sources:

Manually curate collections by adding items one by one:

1. Create a category with mode Manual
2. Browse content and click the ➕ button to add items
3. Items remain in the category until you remove them

Automatically collect content based on search patterns:

1. Create a category with mode Automatic
2. Define search patterns (contains, starts with, regex, etc.)
3. Choose pattern logic: Match ANY (OR) or Match ALL (AND)
4. Optionally filter by Recently Added (last 7, 14, 30 days, etc.)
5. Enable Apply source filter rules to respect your source filters

Pattern Match Types:

Example: Create a "New 4K Movies" category:

• Mode: Automatic
• Content Types: VOD only
• Pattern: contains → 4K
• Recently Added: Last 7 days
• Notify Telegram: ✅

Automatic categories refresh when the cache refreshes, detecting new content automatically.

Get notified on Telegram when automatic categories find new content:

1. Create a Telegram Bot:

   • Message @BotFather on Telegram
   • Send /newbot and follow the prompts
   • Copy the Bot Token (e.g., 123456789:ABCdefGHI...)

2. Get your Chat ID:

   • Message @userinfobot on Telegram
   • It will reply with your Chat ID (e.g., 1234567890)
   • For groups/channels, add the bot and get the group ID

3. Configure in XtreamFilter:

   • Go to the main page and click ⚙️ Configure next to "Telegram Notifications"
   • Enter your Bot Token and Chat ID
   • Enable notifications and click 💾 Save
   • Click 🔔 Test to verify it works

4. Enable per category:

   • Edit an automatic category
   • Check 📱 Send Telegram notification when new items are found

Download VOD movies and series episodes locally with a built-in cart-based queue system, accessible from the Browse and Cart pages.

• Movies (VOD) — Add films directly from the Browse page. If a movie exists in multiple sources, a modal lets you choose which provider to download from.
• Series Episodes — Three granularity levels via an episode selector:
  • Individual episodes (checkbox selection)
  • Full season ("Add Season" button)
  • Entire series ("Add All Episodes" button)

Items are queued through a persistent cart (data/cart.json) that survives container restarts. The background download worker processes items sequentially (one at a time) to respect provider connection limits.

Item lifecycle: queued → downloading → completed / failed / cancelled

• Duplicate prevention — Adding an already-queued item returns HTTP 409
• Crash recovery — Items stuck in downloading after a restart are automatically re-queued
• Live progress — The Cart page polls every 2 seconds for real-time speed, progress, and pause status

All settings are configurable from the Cart page UI and persisted in config.json:

Available Player Profiles:

Downloads are organized automatically with Jellyfin/Kodi-compatible folder structures and metadata:

<download_path>/ ├── Films/ │ └── Movie Name/ │ ├── Movie Name.mp4 │ ├── Movie Name.nfo # Jellyfin/Kodi movie metadata │ └── poster.jpg # Movie poster artwork └── Series/ └── Show Name/ ├── tvshow.nfo # Series-level metadata ├── poster.jpg # Series poster artwork ├── S01/ │ ├── Show Name S01E01 - Episode Title.mkv │ ├── Show Name S01E01 - Episode Title.nfo │ └── Show Name S01E02.mkv └── S02/ └── Show Name S02E01 - Pilot.mp4 

When downloading VOD or series content, XtreamFilter automatically fetches metadata from the Xtream API and writes Jellyfin/Kodi-compatible .nfo files alongside each video:

NFO features:

• <uniqueid type="imdb"> / <uniqueid type="tmdb"> tags for automatic provider matching
• <ratings> container with proper Kodi/Jellyfin structure
• <thumb aspect="poster"> and <fanart> image URL references
• <premiered> tag for release date display and sorting
• Poster artwork downloaded as poster.jpg in each movie/series folder
• XML declaration with encoding="UTF-8" standalone="yes" for full compatibility

Automatically track your favorite series for new episodes. When new episodes are detected, they can be auto-queued for download, sent as Telegram notifications, or both.

1. Add a series to monitor from the Browse page by clicking the 📡 Monitor button on any series
2. Choose monitoring scope:
   • New episodes only — Snapshots current episodes as "known"; only future additions trigger
   • Specific season — Watch only a single season for new episodes
   • All episodes — Treat every episode as new on first check (useful to download an entire series)
3. Choose an action:
   • Download — Auto-queue new episodes to the download cart
   • Notify — Send a Telegram notification only
   • Both — Download and notify
4. Automatic checks — The monitor runs after each cache refresh, scanning all enabled series
5. Preview — Click 👁 Preview on any monitored series to see all episodes with their status (new, known, downloaded)

Each source with a dedicated route exposes these endpoints:

Configuration is stored in data/config.json:

{ "sources": [ { "id": "abc123", "name": "My Provider", "host": "http://provider.example.com", "username": "myuser", "password": "mypass", "enabled": true, "prefix": "", "route": "myprovider", "filters": { "live": { "groups": [], "channels": [] }, "vod": { "groups": [], "channels": [] }, "series": { "groups": [], "channels": [] } } } ], "content_types": { "live": true, "vod": true, "series": true }, "options": { "proxy_streams": false } }

Cache is stored in data/api_cache.json and automatically rebuilt on startup.

XtreamFilter is built on a modern async Python stack for maximum performance:

For 4K streams and large catalogs, the application is optimized with:

• Fully async: All I/O operations are non-blocking for high concurrency
• Connection pooling: Reuses connections to upstream servers (100 max, 20 per host)
• Adaptive buffering: Dynamic buffer sizing from 1 MB to 16 MB based on upstream speed
• Pre-buffering: 4 MB initial buffer before streaming starts
• Smart timeouts: 30s connect, 600s read for large streams
• Retry mechanism: Automatic retry with exponential backoff on upstream failures
• Keep-alive: 65 seconds for connection reuse
• Streaming response: Memory-efficient async generators for large streams

services: xtreamfilter: build: . container_name: xtreamfilter ports: - "8080:5000" volumes: - ./data:/data - ./downloads:/data/downloads restart: unless-stopped environment: - TZ=Europe/Paris

Run locally without Docker:

pip install fastapi uvicorn[standard] httpx jinja2 python-multipart lxml rapidfuzz packaging uvicorn app.main:app --host 0.0.0.0 --port 5000 --reload

The app will be available at http://localhost:5000

uv run pytest tests/ -v