tuliprox

Tuliprox is a high-performance IPTV proxy and playlist processor written in Rust. It is designed for several use cases:

IPTV Enthusiasts

• Merge multiple providers into one unified playlist.
• Filter, rename, and sort channels.
• Automatic EPG assignment with fuzzy matching.
• Integration with Kodi, Jellyfin, Emby (via STRM), and Plex (via HDHomeRun).

Self-Hosted & Homelab Users

• Single Docker container deployment with no external database required (uses a custom B+Tree engine).
• Low resource footprint suitable for Raspberry Pi or small VPS.
• VPN/SOCKS5 routing for upstream traffic with public IP verification via Web UI.

Multi-User Operations

• Multi-tenant edge gateway to publish multiple virtual endpoints.
• User management with connection limits and priority levels.
• RBAC (Role-Based Access Control) with 14 granular permissions.
• Panel API for automated account management.

Developers & Power Users

• Mapper DSL: For arbitrary playlist transformations.
• Management REST API: For configuration, processing, and operational automation.
• CLI Mode: For scripting and CI/CD integration.

The MetadataUpdateManager is an asynchronous background engine (activated via resolve_background: true on an input) that processes metadata without blocking the main playlist update.

Key Behaviors:

• Isolation: A dedicated Tokio Task (Worker) is started per Provider-Input to prevent slow providers from affecting others.
• Task-Merging: If a stream needs both TMDB info and an FFprobe, they are merged into a single Task.
• Preemption: FFprobe tasks run at the lowest priority (user_priority: 127). If a user starts streaming, the FFprobe process is immediately aborted/preempted to free the connection slot for the user.
• Persistence: Retry, exhaustion, and cooldown states are saved in metadata_retry_state.db. This ensures Tuliprox remembers the status of broken streams across server restarts.
• Cascading Updates: Metadata updates are saved to the Input DB and immediately cascaded into all Target DBs without requiring a full playlist rebuild.

Tuliprox uses several distinct identifiers to manage HLS playback, ranging from shared content identity to individual user playback sessions. Understanding these is critical for debugging URL structures and session behavior.

Key Identifiers

• HlsSessionKey (Shared Content): A stable tuple of input_id, the literal HLS kind, and stream_ref (the original input_stream_id). This identifies the content itself, regardless of which target or mirror is used.
• proxy_session_id (Shared Public URL Identity): An opaque token derived from the HlsSessionKey and a configured secret. It is used to construct canonical URLs for shared content.
• HlsPlaybackFamilyKey (User/Client Family): A tuple of the Tuliprox username and a client fingerprint key, used to group playback attempts by user and device.
• hls_access_lease_id (Per Playback URL Identity): A random lookup key for a specific server-side HlsAccessLease. This is not a shared-content identity; it is unique to a single playback attempt.
• HLS cache user session token: An internal token associated with an access lease for admission control.

Canonical URL Structure

Public canonical paths follow this pattern:

/hls/shared/live/<proxy_session_id>/<hls_access_lease_id>/manifest.m3u8
/hls/shared/live/<proxy_session_id>/<hls_access_lease_id>/<segment_file>
/hls/shared/live/<proxy_session_id>/<hls_access_lease_id>/map/<map_file>
/hls/shared/live/<proxy_session_id>/<hls_access_lease_id>/r/<resource_file>

Tuliprox follows a Separation of Concerns design pattern. Instead of a single monolithic file, configuration is split into five distinct files that must be placed in your config/ directory to fully utilize the system.

Tuliprox uses a central Home Directory to resolve all relative paths defined in your configuration files (e.g., storage_dir: ./data). To ensure predictable behavior, you should explicitly define or understand how this directory is determined.

Path Resolution Order

Tuliprox determines the Home Directory using the following priority:

1. CLI Argument: --home or -H (Highest Priority)
2. Environment Variable: TULIPROX_HOME
3. Fallback: The physical directory where the tuliprox binary is located.

Default Directory Structure

When initialized, Tuliprox creates a standard directory tree under the Home Directory:

tuliprox_home/
 ├─ config/         # Contains config.yml, source.yml, mapping.yml, user.txt
 ├─ data/           # Primary storage_dir for B+Tree databases (*.db)
 ├─ data/backup/    # Backups initiated by the Web UI
 ├─ data/user/      # User-specific configurations (like favorites)
 ├─ downloads/     # Downloaded VODs
 └─ web/            # Frontend assets for the Web UI
 └─ cache/          # Cached resources

# Example: Setting the home directory via CLI
tuliprox --home /opt/tuliprox

# Example: Setting the home directory via Environment Variable
export TULIPROX_HOME=/opt/tuliprox
tuliprox

Tuliprox processes input playlists through a specific lifecycle. Understanding this helps you decide which stage to use for your mapping rules.

1. Input playlist
2. Identity Freeze: Removes duplicates.
3. Processing Pipe (Order configurable via processing_order):
   • F: Filter
   • R: Rename
   • M: Mapper (Blocks with stage: processing)
4. Metadata Resolution: Resolves series, VOD, and stream probes.
5. EPG Enrichment: Adds EPG data.
6. Late Mapping: Mapper blocks with stage: after_epg (can access epg_channel_id and logo).
7. Consolidation: Collects inputs, applies Favourites/Trakt categories.
8. Finalization: Merges groups $\rightarrow$ Sorts $\rightarrow$ Assigns channel numbers $\rightarrow$ Mapping Counters $\rightarrow$ Watches $\rightarrow$ Persistence.

Note: counter blocks always run at the very end, after merging and sorting, regardless of the stage defined in the mapper blocks.