tuliprox - A Powerful IPTV Proxy & Playlist Processor

tuliprox is a high-performance IPTV proxy and playlist processor written in Rust 🦀. It unifies M3U/M3U8 playlists, Xtream providers, Stalker/Ministra portals, Plex, Emby, Jellyfin and local media, reshapes them into clean outputs, and serves them to IPTV players and media clients from one place.

Want to join the community

Join us on Discord

License

See LICENSE.

🏆 Key Features

1. Written in Rust — Maximum Performance, Minimal Footprint

• Single binary — no Python, no Node.js, no Java, no runtime overhead
• Extremely low CPU usage — even with hundreds of concurrent streams
• Very low RAM consumption — runs comfortably on 256 MB, disk-based processing mode for even less
• Native async I/O with Tokio — thousands of concurrent streams without breaking a sweat
• Rock-solid stability — designed to run 24/7 for months without memory leaks, restarts, or degradation
• Runs on Raspberry Pi, tiny VPS, NAS, or any x86/ARM system
• No external database required — everything embedded

2. Custom B+Tree Storage Engine — No External Database Needed

• Versioned 4 KiB Slotted Page format with checksummed headers, pages, cells, and overflow chains
• Adaptive LZ4 compression and overflow pages for compact variable-size values
• Mmap-backed streaming scans without loading the complete database into memory
• Shared query snapshots reuse mmap mappings, validated pages, and decoded internal routes
• WAL-protected in-place updates with Immediate and Batch flush policies
• Fully built replacements and compaction results are verified before atomic publication
• Typed startup migration upgrades recognized legacy v1/v2 databases to v3
• Identity- and generation-bound sorted indexes accelerate playlist-order streaming
• String interning (Arc<str>) for playlist entries reduces memory footprint
• Page-local updates, tombstone reuse, free-page reuse, and explicit compaction reclaim disk space

3. Input Sources — Bring Everything Together

• Xtream Codes: Import Live, VOD, Series, Catchup and EPG metadata through the native provider API. Alias pools and CSV batch inputs make large account sets manageable.
• M3U/M3U8: Load remote or local playlists with custom headers, credentials and EPG sources. CSV batch inputs cover providers that expose multiple playlist URLs.
• Stalker & Ministra: Process complete portal catalogs with MAC, credentials or combined authentication, configurable MAG profiles, reliable create_link playback resolution, resumable refreshes and per-alias CSV configuration.
• Local Media Library: Scan movies and series directly from disk, enrich them with NFO or TMDB metadata and publish them through the same M3U, Xtream and STRM outputs as provider content.
• Plex, Emby & Jellyfin: Import selected movie and TV libraries directly from an existing media server, refresh them manually or on a schedule and resolve protected playback and artwork through Tuliprox.
• Staged Sources: Overlay a prepared Live, VOD or Series catalog onto another provider while keeping the original provider responsible for stream delivery.

4. Four Output Formats — One Tool to Rule Them All

Format	Description
M3U/M3U8	For all IPTV players (VLC, Tivimate, iMPlayer, etc.)
Xtream Codes API	Full Xtream API with Live, VOD, Series, Catchup, EPG
HDHomeRun	Emulation for Plex, Jellyfin, Emby — auto-discovery via SSDP
STRM	Kodi/Jellyfin/Emby compatible with multi-version support and quality tags

Generate all four formats simultaneously from the same source — one setup, every platform covered.

5. Multi-Tenant IPTV Edge Gateway

• Advertised Server Profiles: Define multiple LAN or public reverse-proxy profiles with independent protocol, host, port, path, timezone and Xtream welcome message, then assign one profile to each user.
• Target-Based User Access: Bind every account to a curated target and expose it through M3U or the Xtream Codes API
• Per-User Delivery Policies: Choose reverse proxy or redirect behavior, Live/VOD/Series access, category selection, connection limits and priorities independently for every account
• Multiple Deployment Profiles: Advertise LAN and public HTTPS endpoints without duplicating playlists or provider configuration
• Flexible User Storage: Keep accounts in versionable YAML or migrate them to the integrated user database and manage them from the Web UI
• Hot-Reloaded Gateway Configuration: Apply server, user and access-policy changes without restarting the service

6. Reverse Proxy, Shared HLS & Stream Management — Enterprise-Grade

• Reverse Proxy Mode: Streams are proxied through Tuliprox — provider URLs stay invisible to end users
• Redirect Mode: Lightweight redirection for resource-efficient operation
• Shared MPEG-TS Streams: One provider stream shared across multiple users — saves valuable provider slots
• Shared HLS Sessions: Multiple viewers reuse one server-side HLS session while retaining individual access leases, user limits and accounting
• HLS Segment Cache & Prefetch: Fetch manifests, segments and initialization maps once, serve them locally and prefetch upcoming segments within configurable disk and concurrency budgets
• HLS Recovery Tools: Optional manifest recovery, bounded segment repair and corrupt-segment diagnostics for difficult upstream streams
• HLS Session Management: Short-lived provider reservations for HLS/Catchup without blocking real slots
• User Connection Priority: Higher-priority users evict lower-priority connections when all provider slots are full
• Soft Connections & Soft Priority: Users can temporarily exceed their normal slot limit with preemptible soft slots;
  a dedicated soft_priority applies only while a connection is on a soft slot and automatically switches back to the normal
  priority when a regular slot becomes free again
• Grace Period: Configurable transition window during connection handovers — no abrupt drops
• Bandwidth Throttling: With flexible units (KB/s, MB/s, kbps, mbps)
• Per-Stream Metrics: Bandwidth and transferred bytes per stream in the Web UI (opt-in)
• Stream History: Optional persisted stream lifecycle telemetry for connects, disconnects, preemptions, and startup failures
• QoS Aggregation: Optional background reliability snapshots built from stream history for long-term stream quality analysis
• Custom Fallback Videos: User-defined video files for channel unavailable, connections exhausted, account expired, etc.
• Channel-Switch Friendly Reservations: Instant takeover on channel switch — no TTL wait
• Custom Stream Response Timeout: Auto-stop fallback streams after configurable duration
• Buffer Reuse: Reusable serialization buffers minimize heap allocations during streaming
• Universal Catchup: Serve provider catchup/archive as plain M3U with .ts segments proxied through Tuliprox — any player, any timeline, no vendor lock-in
• Smart Background Work: Skip metadata resolution and probing for entries you don't need — save CPU and provider slots on huge providers that only need partial coverage

7. Provider Connectivity, Failover & VPN Routing

• Provider URL Failover: Automatic rotation on errors (5xx, timeout) — seamless switching, no viewer disruption
• Configurable Provider URL Start Policy: Per provider, choose whether new requests resume from the last working URL or
  always restart from the first URL
• provider:// URL Scheme: Reference providers by name — Tuliprox resolves to the active URL automatically
• DNS-Aware Connection Routing: Provider DNS resolved asynchronously and cached
• Resolved DNS Persistence: Resolved IPs persisted separately — no source config overwrite during hot reloads
• Outgoing HTTP/HTTPS/SOCKS5 Proxy: Route playlist downloads, metadata requests, probing and proxied streams through a corporate proxy, VPN gateway or Gluetun container
• Public IP Verification: Display the effective public IPv4/IPv6 in the Web UI to confirm that VPN and proxy routing are working as intended
• Provider Aliases: Manage multiple accounts from the same provider with different credentials
• Batch Input: Xtream, M3U and Stalker batch inputs via CSV files for mass provider management
• Staged Cluster Source Routing: Per-cluster decision whether Live/VOD/Series comes from staged input, main input, or is skipped entirely

8. Multi-Source Merging & Advanced Processing Pipeline

• Merge multiple input sources (M3U, Xtream, Stalker, Plex, Emby, Jellyfin, Local Library) into a single target
• Filter Engine: Complex boolean expressions — (Group ~ "^DE.*") AND NOT (Name ~ ".*XXX.*")
• Mapper DSL: A custom Domain-Specific Language for powerful transformations
  • Regex-based renaming with capture groups and backreferences
  • Variables, if/else blocks, loops (for_each)
  • Built-in functions: replace, pad, format, first, capitalize, lowercase, uppercase, template
  • Counters with padding (e.g. 001, 002)
  • Transform operations directly in mappings
• Template System: Centralized, reusable pattern collection
  • Global templates shared across sources and mappings
  • Inline templates for backward compatibility
  • List templates for sequences
  • Hot-reload on template changes
• Sort Engine:
  • Regex sequences for groups and channels
  • order: none to preserve source order
  • Filter-based sorting — sort only specific entries
  • Named capture groups for multi-level sorting (c1, c2, c3)
• Accent-Independent Matching: match_as_ascii — "Cinema" matches "Cinéma"
• Deunicoding: On-the-fly Unicode normalization in filters and value comparisons
• Output Filters: Apply filters to the final playlist state after all transformations
• Favorites System: Explicit add_favourite(group_name) script function for bouquet management
• Auto-Curated Trakt Bouquets: Drop in Trakt Charts and serve "Trending Now" and "Most Popular" as live Xtream categories — your playlist refreshes itself with what people are actually watching, no manual curation

9. Local Media Library — Integrate Your Own Movies & Series

• Recursive directory scanning for local video files
• Automatic classification (Movie vs. Series)
• Multi-source metadata: NFO files, TMDB API, filename parsing
• Incremental scanning — only new or changed files are processed
• Integration into Xtream API and M3U playlists — local content served like IPTV channels
• Metadata formats including NFO support
• Scheduled library scans — automatic updates via cron
• Episode backgrounds with direct TMDB image URLs
• Virtual ID management for stable assignment

10. Metadata Resolution & Stream Probing

• Background Metadata Queue: Metadata resolution and stream analysis run in the background when provider connections
  are idle — prevents "No Connections" errors for active users
• Metadata Fairness: Configurable ratio between resolve and probe tasks — no probe starvation
• FFprobe Integration: Automatic detection of codec, resolution, HDR (HDR10/HLG/Dolby Vision), audio channels
• FFprobe respects provider limits: If no slot is available, the item is skipped — zero risk of provider bans
• TMDB Integration: Automatic lookup of missing TMDB IDs and release dates
• TMDB No-Match Cooldown: Prevents infinite loops on items with no TMDB match
• Quality Tagging: Automatic STRM tags like [2160p 4K HEVC HDR TrueHD 7.1]
• Flat Grouping: Multi-version merge (e.g. 4K + 1080p) in a single folder — compatible with Jellyfin/Emby multi-version feature
• Probe Priority: Configurable priority for probe tasks — provider slots stay free for real users
• Metadata Retry State: Persistent retry/cooldown state per item in a dedicated database
• No-Change Cache: Deduplication cache prevents unnecessary re-resolution of unchanged items
• Live Stream Probing: Periodic re-probing of live streams with configurable interval

11. Role-Based Access Control (RBAC) — Enterprise-Grade Security

• 14 permissions across 7 domains (config, source, user, playlist, library, system, epg)
• Each permission with independent .read and .write grants
• Custom groups via groups.txt — define your own roles (e.g. viewer, source_manager)
• User-to-group assignment — one user can belong to multiple groups
• Union-based permission resolution — group permissions stack additively
• Compact bitmask (u16) in JWT — zero file I/O per request, single-instruction bitwise checks
• Password-version tracking in JWT — automatic token invalidation on password change
• RBAC admin panel in the Web UI with tabbed user/group management and permission checkbox grid
• Built-in admin group — always full permissions, cannot be deleted
• Backward compatible — existing user.txt files work without changes

12. Web UI — Full Control in the Browser

• Dashboard: System status, active streams, CPU usage, provider connections in real-time via WebSocket
• Source Editor: Dedicated forms for M3U, Xtream, Stalker, Plex, Emby, Jellyfin and local-library inputs, with drag & drop, block selection and batch mode
• Playlist Explorer: Tree and gallery view for channels with EPG timeline and search
• Download & Recording Manager: Provider-aware VOD downloads and live recordings with retries, fairness, and RBAC-controlled actions
• Config Editor: Direct editing of config.yml, source.yml, mapping.yml in the browser
• User Management: API users with category selection, priority, soft-priority, normal/soft connection limits, auto-generated credentials
• Network Access Policy UI: API-user network restrictions can be configured with CIDR and GeoIP country rules, including the global GeoIP-unavailable deny/allow policy.
• RBAC Admin Panel: Tabbed user/group management, permission checkbox grid, write-without-read warnings
• Stream Table: Real-time stream monitoring with copy-to-clipboard, bandwidth metrics, episode titles
• EPG View: Timeline with channels, now-line, program details
• Messaging Config View: Discord, Telegram, Pushover, REST webhook configuration with template editor
• Multiple Themes: Dark/bright and additional themes available
• GeoIP Country Flags: Country flags displayed when GeoIP is active
• Playlist User Login: Playlist users can select their own groups/bouquets
• Resource Proxy: Channel logos and images loaded via authenticated same-origin endpoints — HTTP upstream assets render behind HTTPS frontends
• Mobile-friendly: Responsive design for all screen sizes

UI/UX Highlights:

• Status Health Banner: Single green/amber/red health indicator in the header aggregates realtime connection, backend, and provider capacity with hover breakdown and click-through to the Stats view
• Live Metric Sparklines: Stats cards show interactive time-series sparklines for CPU, memory, network, active users, and active user connections — hover shows cursor + tooltip, system metrics sampled every 2 s for responsive charts
• Bookmarkable Views (Deep Linking): The active view is reflected in the URL hash (#stats, #source_editor) so views can be bookmarked, shared, and navigated directly; browser back/forward works as expected
• At a glance: Single green/amber/red health banner in the header aggregates every signal that matters (realtime connection, backend, provider capacity), with hover breakdown and click-through to detailed Stats. Live metric sparklines for CPU, memory, network, active users and connections — hover for cursor + tooltip, sampled every 2 s so the charts never feel stale.
• A UI that feels right: Micro-interactions (cards lift, buttons ripple, chevrons rotate), animated theme transitions, debounced filter input that stays responsive on huge expressions, shift+click range selection in the category editor, guided empty states that tell you what to do next, paged tables with localized empty messages. Every effect honors prefers-reduced-motion: reduce.
• Works the way you work: Bookmarkable views via URL hash (#stats, #source_editor) so you can share links and the browser back/forward buttons just work. Persisted sidebar state and table page size survive reloads. Sessions auto-logout cleanly when the JWT expires — no mysterious 401s.
• For everyone: UI languages with full RTL support (drop a file in assets/i18n and a new language is live — no rebuild), a recoverable error boundary that keeps one misbehaving view from taking the app down, and confirmation dialogs before any destructive download/recording action.

13. EPG (Electronic Program Guide)

• Multi-Source EPG: Multiple EPG sources with priorities — best coverage through combination
• ICS Calendar Sources: Convert iCalendar events into XMLTV programmes, assign them through Smart Match and optionally fill schedule gaps with configurable dummy blocks
• Auto-EPG: Automatic EPG URL generation from providers
• Smart Match: Fuzzy matching with configurable threshold for automatic channel-to-EPG assignment
• XMLTV Timeshift: Full timezone support (Europe/Paris, America/New_York, -2:30, +0:15, etc.) with automatic DST handling
• EPG Memory Cache: In-memory cache for fast Web UI and short-EPG lookups — reduces disk access
• Logo Override: EPG logos can override channel logos
• Async Processing: EPG streamed and processed asynchronously — minimal memory overhead even with large guides
• EPG Icon Proxy: HTTP upstream assets rendered through HTTPS frontend
• Strip & Normalize: Configurable terms and regex for better channel matching
• EPG Title Synchronization: Automatic sync after playlist updates

14. Notifications & Monitoring

• Telegram: Bot notifications with markdown support and thread support (chat-id:thread-id)
• Discord: Webhook notifications with Handlebars templates
• Pushover: Push notifications
• REST Webhooks: Custom HTTP methods, headers, Handlebars templating
• Watch Notifications: Real-time alerts on group changes in playlists
• Processing Stats: Automatic notification after playlist updates with statistics and processing duration
• Per-Message Templates: Individual Handlebars templates per message type (Info, Stats, Error, Watch) and channel
• Template Loading: Templates from files or HTTP/HTTPS URIs with automatic discovery
• Typed Messaging Pipeline: Strictly typed pipeline instead of raw JSON strings — robust and maintainable
• Never Fill Up Unnoticed: Disk-usage alerts through your existing Telegram/Discord/Pushover channels — opt-in, configurable thresholds, hourly re-arm so a stuck-at-95% disk keeps nagging until you actually fix it

15. Scheduling & Automation

• Cron-based scheduler: Multiple schedules with optional target selection
• Scheduled library scans: Automatic local library scans alongside playlist updates
• Hot config reload: Configuration changes detected and applied automatically — no restart needed
• Config file watcher: Monitors config.yml, source.yml, mapping.yml, api-proxy.yml, template files
• Auto-update on boot: Optional playlist update on startup
• Staged inputs: Side-loading — load metadata from staged input, serve streams from provider
• Panel API integration: Auto-renew expired provider accounts or provision new ones to maintain minimum valid accounts
• Playlist caching: Configurable cache duration for provider playlists (60s, 5m, 12h, 1d)

16. Management REST API — Automate Everything

• Configuration Management: Read and update application, source and API-gateway configuration remotely
• Processing Control: Trigger playlist refreshes, target-scoped updates, library scans and GeoIP database updates
• Playlist Inspection: Preview Live, VOD and Series content before publishing it to users
• Transfer Automation: Queue, pause, resume, retry and cancel downloads or live recordings from external tools
• Operational Visibility: Query status, active streams, stream history, QoS snapshots and system information
• Script-Friendly Formats: Use JSON for broad compatibility or CBOR on supported endpoints for compact responses

17. Complete Xtream Codes API Implementation

• Player API (Live, VOD, Series streams)
• Category listings with icons
• VOD Info & Series Info with episodes and metadata
• Catchup / Timeshift API with session tracking
• XMLTV / EPG API
• Panel API for account management
• POST and GET request support
• Series/Catchup lookup with virtual ID support
• Bandwidth and connection info in user info response
• Custom server message support
• Multi-server configuration with different protocols and ports

18. Security

• Argon2 password hashing: Industry standard for password storage
• JWT authentication: Compact bitmask encoding with password-version tracking for automatic token invalidation
• Rate limiting: Per-IP rate limiting with configurable burst and period
• Content Security Policy: Configurable CSP headers
• API User Network Access Restrictions: Per-user network_access rules can restrict API proxy accounts by IPv4/IPv6 CIDR ranges and/or GeoIP country codes. Matching any configured CIDR or country allows the request; otherwise the request is denied before it is forwarded upstream.
• GeoIP-Unavailable Policy: Country-based network restrictions default to deny when GeoIP is disabled, missing, or not loaded. Operators can explicitly accept that risk with reverse_proxy.geoip.unavailable_policy: allow; CIDR-only misses, unknown countries, and country mismatches still deny.
• SSL/TLS support: Configurable including accept_insecure_ssl_certificates option
• Header stripping: Configurable removal of referer, Cloudflare, and X-headers
• Rewrite secret: Mandatory secret for stable resource URLs in reverse proxy mode

19. Operations & Deployment

• Docker: Alpine and Scratch images — minimal image size
• Docker Compose templates: traefik, crowdsec, gluetun/socks5, iptv-org/epg templates ready to use
• One-Click Dev Setup: Open in GitHub Codespaces or VS Code Dev Containers and start hacking — Rust toolchain, WASM targets, and every build tool pre-configured
• Zero-downtime config reload: ArcSwap<Config> for atomic configuration swaps without interruption
• Disk-based processing: Playlist processing from disk instead of RAM — massively reduced memory consumption
• CLI mode: One-shot processing without a server — ideal for scripting and CI/CD
• Server mode: Long-running HTTP server with background tasks
• Healthcheck endpoint: /api/v1/status for Docker/uptime monitoring
• SSDP discovery: HDHomeRun auto-discovery via SSDP and proprietary UDP protocol (port 65001)
• Database viewer: CLI flags to inspect internal databases
• Environment variables: ${env:VAR} interpolation in all config files
• Default User-Agent: Configurable default user-agent for all outgoing requests

🎯 Target Audiences

For IPTV Enthusiasts

• Merge multiple providers into one unified playlist
• Filter, rename, sort channels — exactly the way you want
• Automatic EPG assignment with fuzzy matching
• Kodi/Jellyfin/Emby integration via STRM
• Plex integration via HDHomeRun

For Self-Hosted & Homelab Users

• Single Docker container — no database stack needed
• Runs on Raspberry Pi and tiny VPS instances
• Minimal resource usage thanks to Rust and disk-based processing
• Route all upstream traffic through a VPN or SOCKS5 gateway and verify the public IP from the Web UI
• Runs 24/7 for months with rock-solid stability and near-zero maintenance
• Traefik/Crowdsec/Gluetun/IPTV-org-epg templates ready to deploy

For Multi-User Operations

• Publish multiple virtual IPTV endpoints and plans from one Tuliprox instance
• User management with connection limits and priority levels
• RBAC with 14 granular permissions across 7 domains
• Provider slot sharing for live streams
• Custom fallback videos for professional support
• Panel API integration for automated account management

For Developers & Power Users

• Mapper DSL for arbitrary transformations
• Template system for reusability
• Management REST API for configuration, processing, transfers and operational automation
• CLI mode for scripting and CI/CD
• Database viewer for debugging and analysis

🐋 Docker Container Templates

• traefik template
• crowdsec template
• gluetun/socks5 template
• iptv-org-epg template
• tuliprox (incl. traefik) template

> ./docker/container-templates

Quick start

Install with docker the latest image.

services:
  tuliprox:
    container_name: tuliprox
    image: ghcr.io/euzu/tuliprox-alpine:latest
    working_dir: /app
    volumes:
      - /home/tuliprox/config:/app/config
      - /home/tuliprox/data:/app/data
      - /home/tuliprox/cache:/app/cache
    environment:
      - TZ=Europe/Paris
    ports:
      - "8901:8901"
    restart: unless-stopped

Open the Browser and continue setup.

Project layout

• backend/: main server and processing pipeline
• frontend/: Yew Web UI
• shared/: DTOs and shared logic
• config/: example configuration
• docs/: Markdown source for the project documentation

Documentation

The detailed documentation lives in Markdown under docs/ and is meant to be rendered as a static site.

• Docs source: docs/src/index.md
• Build static docs: make docs
• Serve generated docs with the Web UI build at /static/docs/

Main entry points:

• Getting Started
• Core Features
• Build & Deploy
• Installation
• Configuration Overview
  • Main Config
  • Sources & Targets
  • API Proxy
  • Streaming & Proxy Behavior
  • Mapping & Templates
• Examples & Recipes
• Operations & Debugging
• Troubleshooting & Resilience

Documentation strategy

The recommended format is:

• source in Markdown
• generated as static HTML
• shipped together with the frontend/web root

For this repository, mdBook is the best fit:

• Markdown stays easy to edit in Git
• static HTML output is simple to host
• it fits a Rust project better than a Node-heavy doc stack
• navigation and search come out of the box