github.com/euzu/tuliprox @v3.3.56

tuliprox - A Powerful IPTV Proxy & Playlist Processor

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.

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

• 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

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

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

4. Reverse Proxy & 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 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

5. Provider Failover & DNS Rotation — Maximum Availability

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

6. Multi-Source Merging & Advanced Processing Pipeline

• 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

7. 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

8. 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

9. 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

10. Web UI — Full Control in the Browser

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

11. EPG (Electronic Program Guide)

• 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

12. 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

13. 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)

14. Complete Xtream Codes API Implementa