tuliprox is a high-performance IPTV proxy and playlist processor written in Rust 🦀. It ingests M3U/M3U8 playlists, Xtream sources and local media, reshapes them into clean outputs, and serves them to Plex,
Jellyfin, Emby, Kodi and similar clients.

• 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

• Purpose-built B+Tree with Slotted Page architecture
• Adaptive LZ4 compression for minimal disk footprint
• Zero-copy scans at up to 96,000 ops/sec
• Batch upsert for massive throughput during playlist updates
• Atomic I/O with file locking — no corrupt data, ever
• Configurable flush policy (Immediate, Batch, None)
• String interning (Arc<str>) for playlist entries reduces memory footprint
• B+Tree compaction to reclaim disk space
• Persistent value caching with thread-safe access
• Packed block update optimization — direct disk writes for same-size updates, bypassing expensive read-scan-modify-write cycles

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

• Reverse Proxy Mode: Streams are proxied through Tuliprox — provider URLs stay invisible to end users
• Redirect Mode: Lightweight redirection for resource-efficient operation
• Shared Live Streams: One provider stream shared across multiple users — saves valuable provider 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.
• HLS Session Management: Short-lived provider reservations for HLS/Catchup without blocking real slots
• 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

• Provider URL Failover: Automatic rotation on errors (5xx, timeout) — seamless switching, no viewer disruption
• 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
• Provider Aliases: Manage multiple accounts from the same provider with different credentials
• Batch Input: Xtream and M3U 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

• Merge multiple input sources (M3U, Xtream, 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

• 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

• 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

• 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

• Dashboard: System status, active streams, CPU usage, provider connections in real-time via WebSocket
• Source Editor: Global input management with drag & drop, block selection, batch mode, scroll wheel support
• 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
• 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

• Multi-Source EPG: Multiple EPG sources with priorities — best coverage through combination
• 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

• 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

• 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)

• 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

• 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
• SSL/TLS support: Configurable including accept_insecure_ssl_certificates option
• Proxy support: HTTP, HTTPS, SOCKS5 proxies for all outgoing requests
• Header stripping: Configurable removal of referer, Cloudflare, and X-headers
• Rewrite secret: Mandatory secret for stable resource URLs in reverse proxy mode

• Docker: Alpine and Scratch images — minimal image size
• Docker Compose templates: traefik, crowdsec, gluetun/socks5 templates ready to use
• 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

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

• 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
• Runs 24/7 for months with rock-solid stability and near-zero maintenance
• Traefik/Crowdsec/Gluetun templates ready to deploy

• 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

• Mapper DSL for arbitrary transformations
• Template system for reusability
• REST API for automation
• CLI mode for scripting and CI/CD
• Database viewer for debugging and analysis

• traefik template
• crowdsec template
• gluetun/socks5 template
• tuliprox (incl. traefik) template

> ./docker/container-templates

Join us on Discord

See LICENSE.

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.

• 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

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

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