MediaFlow Proxy

MediaFlow Proxy is a streaming proxy designed for high-performance media handling. Key features include:

• Streaming Protocols: Supports HTTP(S), HLS (M3U8), and MPEG-DASH.
• DRM & Conversion: Supports ClearKey DRM and real-time DASH-to-HLS conversion.
• Specialized Sources: Supports IPTV (Xtream Codes), Acestream, and Telegram (MTProto) streaming.
• Media Processing: Optional GPU transcoding (fMP4 H.264/AAC), pre-buffering, segment skip, and stream transformers.
• Infrastructure Features: Redis-backed rate limiting, encrypted URL generation, and reverse-proxy–friendly forwarded headers.

MediaFlow Proxy is a flexible server designed for proxifying media streams. It supports:

• HTTP(S)
• HLS (M3U8)
• MPEG-DASH (including ClearKey DRM)

A key capability is the real-time conversion of DRM-protected DASH streams into decrypted HLS streams.

To achieve a 100% success rate and <100ms response times for Maxstream links, you can use the optional Cache pre-warmer.

How it works:

1. A background task takes a curated list of uprot URLs and resolves them preventively using the OCR pipeline.
2. It maps (uprot_url, season, episode) → maxstream_url and saves it to a JSON file with a 22-hour TTL.
3. When a user requests a link, extract() checks the cache first. If a HIT occurs, it returns the link immediately without performing runtime captcha solving.

Implementation Note: This is an async background service that must be hooked into your application lifecycle. It is pre-wired in the extract() method. To use it, import the service:

from mediaflow_proxy.services.uprot_url_cache import ... # (Implementation details in EasyProxy fork)

Encoding Support

• Standard Base64: Uses + and /.
• URL-Safe Base64: Uses - and _ instead of + and /.
• Padding: The system automatically handles missing = padding.

Detection Heuristics

The proxy uses the following to identify base64 strings:

1. Character Set: Validates against A-Z, a-z, 0-9, +, /, =.
2. Protocol Check: Ensures the string does not start with common protocols like http:// or https://.
3. Length Check: Validates minimum length.
4. Decoding Validation: Verifies the decoded result is a valid URL.

Security and Compatibility

• Not Encryption: Base64 is encoding only; it provides no security. All existing API keys and IP restrictions still apply.
• Backward Compatibility: Regular (non-base64) URLs continue to work normally without any configuration changes.

MediaFlow Proxy has specific constraints regarding Digital Rights Management (DRM) and stream encryption that affect which content can be proxied:

• Commercial DRM is not supported: You cannot use MediaFlow Proxy to decrypt streams protected by Widevine, PlayReady, or FairPlay. These systems require license server communication and hardware security modules that the proxy cannot emulate.
• Key rotation is not supported: Streams that change encryption keys during playback will fail.
• ClearKey/AES-128 only: The proxy can only decrypt content if you already possess the decryption keys (specifically ClearKey or AES-128 formats).

If your setup requires it, the legacy colon-separated format is still supported:

{base64_upstream}:{actual_username}:{api_password}

Note: The new base64-encoded format is preferred because some IPTV applications may not correctly handle colons within the username field.

Pre-buffering is enabled by default to improve playback smoothness. It uses intelligent logic to balance performance and resource usage.

Core Behaviors:

• Smart Variant Selection (HLS): It does not buffer all quality variants in a master playlist. It only starts buffering the specific variant the player requests.
• Live Stream Optimization: For live streams, it buffers from the END of the playlist (the most recent segments) to ensure the player has the freshest content.
• VOD Support: For VOD, it buffers from the start of the stream.
• Inactivity Cleanup: To prevent memory leaks, the pre-buffer automatically stops refreshing and cleans up resources after 60 seconds of inactivity (no segment requests).
• Memory Protection: The system respects configurable memory limits and will stop buffering if system memory usage exceeds defined thresholds.

MediaFlow Proxy is the primary Python-based implementation. If your deployment environment has constraints, you may want to use MediaFlow Proxy Light (a Rust reimplementation).

Use MediaFlow Proxy Light if you need:

• Lower memory usage (benchmarks show 7–8× less memory).
• Higher throughput (up to 4× higher).
• Lower CPU usage (1.7–3.4× less CPU per request).
• Deployment on constrained hardware like small VPS, NAS, or Raspberry Pi.

Compatibility: MediaFlow Proxy Light is API-compatible with the original proxy. Existing tokens, encrypted URLs, and client integrations will work without any changes.

When using the /proxy/stream endpoint, you can provide a filename parameter in your URL generation request. This ensures the proxy preserves the filename in the resulting URL, which helps media players (such as Infuse) correctly identify the media and fetch appropriate metadata instead of displaying generic names like "Stream".

Note: This parameter is only valid for the /proxy/stream endpoint and should not be used with MPD or HLS proxy endpoints.

Choose the correct endpoint based on your use case:

If you are running on constrained hardware (such as a small VPS, NAS, or Raspberry Pi) and require lower memory usage and higher throughput, use MediaFlow Proxy Light (a Rust reimplementation).

Compatibility Notes:

• It is fully API-compatible with the original MediaFlow Proxy.
• Existing tokens, encrypted URLs, and client integrations work without changes.
• Performance benefits include 7–8× less memory usage and up to 4× higher throughput.