mediaflow-proxy 2.4.2__tar.gz → 2.4.4__tar.gz

{mediaflow_proxy-2.4.2 → mediaflow_proxy-2.4.4}/.gitignore

@@ -138,4 +138,8 @@ mediaflow_proxy/drm/*
 !mediaflow_proxy/drm/__init__.py
 !mediaflow_proxy/drm/decrypter.py
 
-.vscode/
+.vscode/
+stremio-test-addon/
+wireproxy/
+test_samples/
+logs.txt

{mediaflow_proxy-2.4.2 → mediaflow_proxy-2.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mediaflow-proxy
-Version: 2.4.2
+Version: 2.4.4
 Summary: A high-performance proxy server for streaming media, supporting HTTP(S), HLS, and MPEG-DASH with real-time DRM decryption.
 Project-URL: Homepage, https://github.com/mhdzumair/mediaflow-proxy
 Project-URL: Repository, https://github.com/mhdzumair/mediaflow-proxy
@@ -13,15 +13,15 @@ Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Requires-Dist: aiofiles
 Requires-Dist: aiohttp
 Requires-Dist: aiohttp-socks
+Requires-Dist: av>=14.0.0
 Requires-Dist: beautifulsoup4
 Requires-Dist: cryptg>=0.4.0
 Requires-Dist: curl-cffi
@@ -31,6 +31,7 @@ Requires-Dist: lxml
 Requires-Dist: psutil
 Requires-Dist: pycryptodome
 Requires-Dist: pydantic-settings
+Requires-Dist: redis[hiredis]>=5.0.0
 Requires-Dist: telethon>=1.42.0
 Requires-Dist: tenacity
 Requires-Dist: tqdm
@@ -96,6 +97,15 @@ MediaFlow Proxy is a powerful and flexible solution for proxifying various types
 - Optional IP-based access control for encrypted URLs
 - URL expiration support for encrypted URLs
 
+### On-the-fly Transcoding
+- **Universal video/audio transcoding** to browser-compatible fMP4 (H.264 + AAC)
+- **GPU hardware acceleration** (NVIDIA NVENC, Apple VideoToolbox, Intel VAAPI/QSV) with automatic CPU fallback
+- Supports **any input container** (MKV, MP4, TS, WebM, FLV, etc.) and codec (HEVC, VP8/VP9, MPEG-2, MPEG-4, AC3, EAC3, Vorbis, Opus, etc.)
+- **On-the-fly streaming** -- no full-file buffering; pipe-based demuxing for MKV/TS/WebM and moov-atom probing for MP4
+- **Smart format detection** -- filename extension hints + magic byte sniffing to avoid wasteful probe attempts
+- Available on **all proxy endpoints**: `/proxy/stream`, Telegram, Acestream, and Xtream Codes
+- Triggered by `&transcode=true` query parameter with optional `&start=<seconds>` for seeking
+
 ### Additional Features
 - Built-in speed test for RealDebrid and AllDebrid services
 - Custom header injection and modification
@@ -217,6 +227,50 @@ Set the following environment variables:
 - `DASH_SEGMENT_CACHE_TTL`: Optional. TTL in seconds for cached DASH segments. Default: `60`. Longer values help with slow network playback.
 - `FORWARDED_ALLOW_IPS`: Optional. Controls which IP addresses are trusted to provide forwarded headers (X-Forwarded-For, X-Forwarded-Proto, etc.) when MediaFlow Proxy is deployed behind reverse proxies or load balancers. Default: `127.0.0.1`. See [Forwarded Headers Configuration](#forwarded-headers-configuration) for detailed usage.
 
+### Redis Configuration (Optional)
+
+Redis enables cross-worker coordination for rate limiting and caching. This is **recommended** when running with multiple workers (`--workers N`) to prevent CDN rate-limiting issues (e.g., Vidoza 509 errors).
+
+- `REDIS_URL`: Optional. Redis connection URL. Default: `None` (disabled). Example: `redis://localhost:6379` or `redis://user:pass@host:6379/0`.
+
+**When to use Redis:**
+- Running multiple uvicorn workers (`--workers 4` or more)
+- Streaming from rate-limited CDNs like Vidoza
+- Need shared caching across workers (extractor results, HEAD responses, segments)
+
+**Features enabled by Redis:**
+- **Rate limiting**: Prevents rapid-fire requests that trigger CDN 509 errors
+- **HEAD cache**: Serves repeated HEAD probes (e.g., ExoPlayer) without upstream connections
+- **Stream gate**: Serializes initial connections to rate-limited URLs
+- **Extractor cache**: Shares extraction results across all workers
+- **Segment cache**: Shares downloaded segments across workers
+
+**Docker Compose example with Redis:**
+```yaml
+services:
+  redis:
+    image: redis:7-alpine
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  mediaflow-proxy:
+    image: mhdzumair/mediaflow-proxy:latest
+    ports:
+      - "8888:8888"
+    environment:
+      - API_PASSWORD=your_password
+      - REDIS_URL=redis://redis:6379
+    depends_on:
+      redis:
+        condition: service_healthy
+```
+
+**Note**: If Redis is not configured, MediaFlow Proxy works normally but rate limiting features are disabled. This is fine for single-worker deployments or CDNs that don't rate-limit aggressively.
+
 ### Acestream Configuration
 
 MediaFlow Proxy can act as a proxy for Acestream P2P streams, converting them to HLS or MPEG-TS format that any media player can consume.
@@ -243,6 +297,8 @@ MediaFlow Proxy can act as a proxy for Acestream P2P streams, converting them to
 |-----------|-------------|
 | `id` | Acestream content ID (alternative to infohash) |
 | `infohash` | Acestream infohash (40-char hex from magnet link) |
+| `transcode` | Set to `true` to transcode to browser-compatible fMP4 (H.264 + AAC) |
+| `start` | Seek start time in seconds (used with `transcode=true`) |
 
 **Example URLs:**
 ```
@@ -252,6 +308,9 @@ https://your-mediaflow/proxy/acestream/stream?id=YOUR_CONTENT_ID&api_password=yo
 # MPEG-TS stream (infohash from magnet)
 https://your-mediaflow/proxy/acestream/stream?infohash=b04372b9543d763bd2dbd2a1842d9723fd080076&api_password=your_password
 
+# Transcode to browser-compatible fMP4
+https://your-mediaflow/proxy/acestream/stream?id=YOUR_CONTENT_ID&transcode=true&api_password=your_password
+
 # HLS manifest (alternative)
 https://your-mediaflow/proxy/acestream/manifest.m3u8?id=YOUR_CONTENT_ID&api_password=your_password
 ```
@@ -324,6 +383,9 @@ TELEGRAM_SESSION_STRING=your_session_string_here
 |----------|-------------|
 | `/proxy/telegram/stream` | Stream media from t.me link or file_id |
 | `/proxy/telegram/stream/{filename}` | Stream with custom filename |
+| `/proxy/telegram/transcode/playlist.m3u8` | HLS transcode playlist (recommended for browser playback and smooth seeking) |
+| `/proxy/telegram/transcode/init.mp4` | fMP4 init segment for Telegram transcode playlist |
+| `/proxy/telegram/transcode/segment.m4s` | fMP4 media segment for Telegram transcode playlist |
 | `/proxy/telegram/info` | Get media metadata |
 | `/proxy/telegram/status` | Session status and health check |
 
@@ -336,6 +398,8 @@ TELEGRAM_SESSION_STRING=your_session_string_here
 | `message_id` | Message ID within the chat (use with `chat_id`) |
 | `file_id` | Bot API file_id (use with `file_size`) |
 | `file_size` | File size in bytes (required when using `file_id`) |
+| `transcode` | Set to `true` for direct transcode mode on `/proxy/telegram/stream` (URL Generator defaults to `/proxy/telegram/transcode/playlist.m3u8` when no start time is set) |
+| `start` | Seek start time in seconds (direct transcode mode only, used with `transcode=true`) |
 
 #### Supported Input Formats
 
@@ -1069,11 +1133,65 @@ Ideal for users who want a reliable, plug-and-play solution without the technica
 4. `/proxy/mpd/playlist.m3u8`: Generate HLS playlists from MPD
 5. `/proxy/mpd/segment.mp4`: Process and decrypt media segments
 6. `/proxy/ip`: Get the public IP address of the MediaFlow Proxy server
-7. `/extractor/video?host=`: Extract direct video stream URLs from supported hosts (see supported hosts in API docs)
+7. `/extractor/video`: Extract direct video stream URLs from supported hosts (see below)
 8. `/playlist/builder`: Build and customize playlists from multiple sources
+9. `/proxy/transcode/playlist.m3u8`: Generate HLS VOD playlist for generic stream transcode
+10. `/proxy/transcode/init.mp4`: fMP4 init segment for generic transcode playlist
+11. `/proxy/transcode/segment.m4s`: fMP4 media segment for generic transcode playlist
+12. `/proxy/telegram/transcode/playlist.m3u8`: Generate HLS VOD playlist for Telegram transcode
+13. `/proxy/telegram/transcode/init.mp4`: fMP4 init segment for Telegram transcode playlist
+14. `/proxy/telegram/transcode/segment.m4s`: fMP4 media segment for Telegram transcode playlist
 
 Once the server is running, for more details on the available endpoints and their parameters, visit the Swagger UI at `http://localhost:8888/docs`.
 
+### Video Extractor Endpoint
+
+The extractor endpoint extracts direct video stream URLs from various video hosting services. It supports an optional file extension in the URL for better player compatibility.
+
+#### Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `/extractor/video` | Base endpoint (generic, backward compatible) |
+| `/extractor/video.m3u8` | HLS streams - helps ExoPlayer detect HLS |
+| `/extractor/video.mp4` | MP4 streams |
+| `/extractor/video.mkv` | MKV streams |
+| `/extractor/video.ts` | MPEG-TS streams |
+| `/extractor/video.webm` | WebM streams |
+| `/extractor/video.avi` | AVI streams |
+
+#### Why Use Extensions?
+
+Some video players (notably Android's ExoPlayer used in Stremio) determine the media source type from the URL before making any HTTP requests. Without the correct extension:
+
+- ExoPlayer sees `/extractor/video?...` → Uses `ProgressiveMediaSource`
+- ExoPlayer sees `/extractor/video.m3u8?...` → Uses `HlsMediaSource` ✓
+
+For HLS streams, using the `.m3u8` extension ensures the player uses the correct HLS playback pipeline.
+
+#### Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `host` | Yes | Extractor host name (e.g., `TurboVidPlay`, `Vidoza`) |
+| `d` | Yes | Destination URL (the video page URL to extract) |
+| `api_password` | Yes* | API password (*if configured) |
+| `redirect_stream` | No | If `true`, returns 302 redirect to the proxied stream URL |
+
+#### Example Usage
+
+**Get extraction result as JSON:**
+```
+GET /extractor/video?host=Vidoza&d=https://videzz.net/example.html&api_password=your_password
+```
+
+**Redirect directly to stream (for players):**
+```
+GET /extractor/video.m3u8?host=TurboVidPlay&d=https://turbovidhls.com/t/abc123&api_password=your_password&redirect_stream=true
+```
+
+This redirects to the proxied HLS manifest URL, and because the request URL contains `.m3u8`, players like ExoPlayer will correctly use HLS playback.
+
 ### Xtream Codes (XC) API Proxy
 
 MediaFlow Proxy can act as a stateless pass-through proxy for Xtream Codes API, allowing you to proxy streams from XC-compatible IPTV providers through MediaFlow. This is particularly useful for:
@@ -1254,6 +1372,44 @@ Apply stream content transformations for specific hosting providers.
 - **Example:** `&transformer=ts_stream&x_headers=content-length,content-range` for streams with PNG wrappers.
 - **Note:** This parameter is automatically set when using extractors for supported hosts.
 
+**`/proxy/transcode/playlist.m3u8` and `/proxy/telegram/transcode/playlist.m3u8` (recommended)**  
+Use HLS transcode playlists for smooth browser playback and robust seeking with fMP4 segments.  
+- **Usage:** Open the playlist endpoint directly with `d` (or Telegram params), optional `api_password`, and optional `h_*` headers.  
+- **Effect:** Generates an HLS VOD playlist that references `init.mp4` + `segment.m4s` endpoints with browser-compatible H.264/AAC output.  
+- **URL Generator behavior:** When transcode is enabled and no start time is provided, URL Generator outputs these playlist URLs by default.
+
+**`&transcode=true` (direct mode)**  
+Transcode the stream directly to browser-compatible fragmented MP4 (fMP4) with H.264 video and AAC audio.  
+- **Usage:** Add `&transcode=true` to `/proxy/stream`, `/proxy/telegram/stream`, `/proxy/acestream/stream`, or Xtream Codes live/movie/series stream URLs.  
+- **Effect:** Re-encodes unsupported video codecs (HEVC, VP8/VP9, MPEG-2, MPEG-4, etc.) to H.264 and unsupported audio codecs (AC3, EAC3, Vorbis, Opus, FLAC, DTS, etc.) to AAC. Browser-compatible codecs (H.264 video, AAC audio) are passed through without re-encoding.  
+- **GPU Acceleration:** Automatically uses GPU encoding when available (NVIDIA NVENC, Apple VideoToolbox, Intel VAAPI/QSV). Falls back to CPU (libx264) otherwise.  
+- **On-the-fly:** Streaming is real-time with pipe-based demuxing. For MP4 inputs, the moov atom is probed and rewritten for immediate playback without downloading the full file.
+
+**`&start=120`**  
+Seek to a specific time position before starting transcoded playback.  
+- **Usage:** Add `&start=120` (value in seconds) alongside `&transcode=true` in direct transcode mode  
+- **Effect:** Starts transcoding from the specified time offset. For indexed containers (MKV cues, MP4 moov), this seeks to the nearest keyframe. For non-indexed formats (TS), this is a byte-estimate seek.  
+- **Supported Endpoints:** `/proxy/stream`, `/proxy/telegram/stream`, `/proxy/acestream/stream`, Xtream Codes live/movie/series endpoints  
+- **Note:** `start` is not used by `/proxy/transcode/playlist.m3u8` or `/proxy/telegram/transcode/playlist.m3u8` endpoints.
+- **Example:** `&transcode=true&start=300` starts playback from 5 minutes into the stream
+
+**`&ratelimit=vidoza`**  
+Apply host-specific rate limiting to prevent CDN 509 (Bandwidth Limit Exceeded) errors. Requires Redis to be configured.  
+- **Usage:** Add `&ratelimit=handler_id` to the `/proxy/stream` URL  
+- **Effect:** Limits the frequency of upstream connections to avoid triggering rate limits on aggressive CDNs.  
+- **Auto-detection:** If not specified, rate limiting is automatically applied for known hosts (e.g., Vidoza).  
+- **Available Handlers:**
+  - `vidoza` - 5-second cooldown between connections, HEAD caching, stream gating (auto-detected for vidoza.net)
+  - `aggressive` - 3-second cooldown, suitable for other rate-limited hosts
+  - `none` - Explicitly disable rate limiting (use when auto-detection is unwanted)
+- **How it works:** When a rate-limited stream is requested:
+  1. HEAD responses are cached to serve repeated probes without upstream connections
+  2. A cooldown period prevents rapid-fire GET requests
+  3. If another request arrives during cooldown, returns `503 Service Unavailable` with `Retry-After` header
+  4. Players automatically retry after the cooldown, resulting in smooth playback
+- **Requires:** `REDIS_URL` must be configured for rate limiting to function. Without Redis, rate limiting is disabled.
+- **Example:** `&ratelimit=vidoza` for Vidoza streams, or `&ratelimit=none` to disable auto-detection.
+
 **`&rp_content-type=video/mp2t`**  
 Set response headers that propagate to HLS/DASH segments.  
 - **Usage:** Add `&rp_header-name=value` to the proxy URL (rp_ prefix)  
@@ -1347,6 +1503,51 @@ mpv "http://localhost:8888/proxy/acestream/manifest.m3u8?id=your_content_id&star
 
 **Note:** The `start_offset` parameter is particularly useful for live streams where the prebuffer system cannot prefetch segments when sitting at the live edge. By starting slightly behind (e.g., `-18` seconds), there are future segments available for prebuffering, resulting in smoother playback. This works for both native HLS and DASH/MPD streams converted to HLS.
 
+#### Transcode Stream for Browser Playback
+
+```bash
+# Recommended: HLS transcode playlist for generic streams
+mpv "http://localhost:8888/proxy/transcode/playlist.m3u8?d=https://example.com/video.mkv&api_password=your_password"
+
+# Recommended: HLS transcode playlist for Telegram streams
+mpv "http://localhost:8888/proxy/telegram/transcode/playlist.m3u8?d=https://t.me/channelname/123&api_password=your_password"
+
+# Direct transcode mode with explicit seek start (start at 5 minutes)
+mpv "http://localhost:8888/proxy/stream?d=https://example.com/video.mp4&transcode=true&start=300&api_password=your_password"
+
+# Acestream transcode (direct mode)
+mpv "http://localhost:8888/proxy/acestream/stream?id=YOUR_CONTENT_ID&transcode=true&api_password=your_password"
+```
+
+**Note:** Transcoding uses GPU hardware acceleration when available (NVIDIA, Apple VideoToolbox, Intel). Browser-compatible codecs (H.264 video, AAC audio) are passed through without re-encoding to minimize resource usage.
+
+#### Transcode Performance Benchmarks
+
+Benchmark results for on-the-fly HEVC (H.265) to H.264 transcoding. Source: 4K (3840x2160) 30-second clip at 24fps with EAC3 5.1 audio, from a real movie file.
+
+**MediaFlow Proxy (on-the-fly streaming via PyAV pipeline):**
+
+| Source | Encoder | Wall Clock | Video Frames | Effective FPS | Output |
+|--------|---------|-----------|--------------|---------------|--------|
+| 4K HEVC MKV (EAC3) | VideoToolbox (GPU) | **11.7s** | 722 | **61.7 fps** | 15.1 MB |
+| 4K HEVC MKV (EAC3) | libx264 (CPU) | 26.2s | 722 | 27.6 fps | 15.1 MB |
+
+**Direct FFmpeg CLI baseline (local file, no HTTP proxy):**
+
+| Source | Encoder | Wall Clock | CPU Time | CPU Usage |
+|--------|---------|-----------|----------|-----------|
+| 4K HEVC MKV | VideoToolbox (GPU) | **11.9s** | 10.7s | 92% |
+| 4K HEVC MKV | libx264 (CPU) | 11.4s | 81.7s | 725% |
+
+**Key observations:**
+- **GPU MediaFlow matches direct FFmpeg** -- the optimized pipeline adds near-zero overhead (11.7s vs 11.9s)
+- GPU **exceeds real-time by 2.5x** for 4K 24fps content (62 fps), meaning no buffering delays
+- **GPU uses ~7x less CPU** than software encoding (92% vs 725%), leaving resources free for concurrent streams
+- The pipeline optimizations (thread-safe queues, eliminated async round-trips, skip redundant decoder flush) reduced GPU wall-clock from ~17s to ~11.7s (**31% improvement**)
+- On servers with NVIDIA GPUs, hardware HEVC decoding (`hevc_cuvid`) would further reduce both wall-clock time and CPU usage
+
+*Tested on Apple Silicon (M4) with PyAV 16.1.0 and FFmpeg 8.0. Results vary by hardware, content complexity, and network conditions.*
+
 #### Stream with Header Removal (Fix Content-Length Issues)
 
 ```bash

{mediaflow_proxy-2.4.2 → mediaflow_proxy-2.4.4}/README.md

@@ -56,6 +56,15 @@ MediaFlow Proxy is a powerful and flexible solution for proxifying various types
 - Optional IP-based access control for encrypted URLs
 - URL expiration support for encrypted URLs
 
+### On-the-fly Transcoding
+- **Universal video/audio transcoding** to browser-compatible fMP4 (H.264 + AAC)
+- **GPU hardware acceleration** (NVIDIA NVENC, Apple VideoToolbox, Intel VAAPI/QSV) with automatic CPU fallback
+- Supports **any input container** (MKV, MP4, TS, WebM, FLV, etc.) and codec (HEVC, VP8/VP9, MPEG-2, MPEG-4, AC3, EAC3, Vorbis, Opus, etc.)
+- **On-the-fly streaming** -- no full-file buffering; pipe-based demuxing for MKV/TS/WebM and moov-atom probing for MP4
+- **Smart format detection** -- filename extension hints + magic byte sniffing to avoid wasteful probe attempts
+- Available on **all proxy endpoints**: `/proxy/stream`, Telegram, Acestream, and Xtream Codes
+- Triggered by `&transcode=true` query parameter with optional `&start=<seconds>` for seeking
+
 ### Additional Features
 - Built-in speed test for RealDebrid and AllDebrid services
 - Custom header injection and modification
@@ -177,6 +186,50 @@ Set the following environment variables:
 - `DASH_SEGMENT_CACHE_TTL`: Optional. TTL in seconds for cached DASH segments. Default: `60`. Longer values help with slow network playback.
 - `FORWARDED_ALLOW_IPS`: Optional. Controls which IP addresses are trusted to provide forwarded headers (X-Forwarded-For, X-Forwarded-Proto, etc.) when MediaFlow Proxy is deployed behind reverse proxies or load balancers. Default: `127.0.0.1`. See [Forwarded Headers Configuration](#forwarded-headers-configuration) for detailed usage.
 
+### Redis Configuration (Optional)
+
+Redis enables cross-worker coordination for rate limiting and caching. This is **recommended** when running with multiple workers (`--workers N`) to prevent CDN rate-limiting issues (e.g., Vidoza 509 errors).
+
+- `REDIS_URL`: Optional. Redis connection URL. Default: `None` (disabled). Example: `redis://localhost:6379` or `redis://user:pass@host:6379/0`.
+
+**When to use Redis:**
+- Running multiple uvicorn workers (`--workers 4` or more)
+- Streaming from rate-limited CDNs like Vidoza
+- Need shared caching across workers (extractor results, HEAD responses, segments)
+
+**Features enabled by Redis:**
+- **Rate limiting**: Prevents rapid-fire requests that trigger CDN 509 errors
+- **HEAD cache**: Serves repeated HEAD probes (e.g., ExoPlayer) without upstream connections
+- **Stream gate**: Serializes initial connections to rate-limited URLs
+- **Extractor cache**: Shares extraction results across all workers
+- **Segment cache**: Shares downloaded segments across workers
+
+**Docker Compose example with Redis:**
+```yaml
+services:
+  redis:
+    image: redis:7-alpine
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  mediaflow-proxy:
+    image: mhdzumair/mediaflow-proxy:latest
+    ports:
+      - "8888:8888"
+    environment:
+      - API_PASSWORD=your_password
+      - REDIS_URL=redis://redis:6379
+    depends_on:
+      redis:
+        condition: service_healthy
+```
+
+**Note**: If Redis is not configured, MediaFlow Proxy works normally but rate limiting features are disabled. This is fine for single-worker deployments or CDNs that don't rate-limit aggressively.
+
 ### Acestream Configuration
 
 MediaFlow Proxy can act as a proxy for Acestream P2P streams, converting them to HLS or MPEG-TS format that any media player can consume.
@@ -203,6 +256,8 @@ MediaFlow Proxy can act as a proxy for Acestream P2P streams, converting them to
 |-----------|-------------|
 | `id` | Acestream content ID (alternative to infohash) |
 | `infohash` | Acestream infohash (40-char hex from magnet link) |
+| `transcode` | Set to `true` to transcode to browser-compatible fMP4 (H.264 + AAC) |
+| `start` | Seek start time in seconds (used with `transcode=true`) |
 
 **Example URLs:**
 ```
@@ -212,6 +267,9 @@ https://your-mediaflow/proxy/acestream/stream?id=YOUR_CONTENT_ID&api_password=yo
 # MPEG-TS stream (infohash from magnet)
 https://your-mediaflow/proxy/acestream/stream?infohash=b04372b9543d763bd2dbd2a1842d9723fd080076&api_password=your_password
 
+# Transcode to browser-compatible fMP4
+https://your-mediaflow/proxy/acestream/stream?id=YOUR_CONTENT_ID&transcode=true&api_password=your_password
+
 # HLS manifest (alternative)
 https://your-mediaflow/proxy/acestream/manifest.m3u8?id=YOUR_CONTENT_ID&api_password=your_password
 ```
@@ -284,6 +342,9 @@ TELEGRAM_SESSION_STRING=your_session_string_here
 |----------|-------------|
 | `/proxy/telegram/stream` | Stream media from t.me link or file_id |
 | `/proxy/telegram/stream/{filename}` | Stream with custom filename |
+| `/proxy/telegram/transcode/playlist.m3u8` | HLS transcode playlist (recommended for browser playback and smooth seeking) |
+| `/proxy/telegram/transcode/init.mp4` | fMP4 init segment for Telegram transcode playlist |
+| `/proxy/telegram/transcode/segment.m4s` | fMP4 media segment for Telegram transcode playlist |
 | `/proxy/telegram/info` | Get media metadata |
 | `/proxy/telegram/status` | Session status and health check |
 
@@ -296,6 +357,8 @@ TELEGRAM_SESSION_STRING=your_session_string_here
 | `message_id` | Message ID within the chat (use with `chat_id`) |
 | `file_id` | Bot API file_id (use with `file_size`) |
 | `file_size` | File size in bytes (required when using `file_id`) |
+| `transcode` | Set to `true` for direct transcode mode on `/proxy/telegram/stream` (URL Generator defaults to `/proxy/telegram/transcode/playlist.m3u8` when no start time is set) |
+| `start` | Seek start time in seconds (direct transcode mode only, used with `transcode=true`) |
 
 #### Supported Input Formats
 
@@ -1029,11 +1092,65 @@ Ideal for users who want a reliable, plug-and-play solution without the technica
 4. `/proxy/mpd/playlist.m3u8`: Generate HLS playlists from MPD
 5. `/proxy/mpd/segment.mp4`: Process and decrypt media segments
 6. `/proxy/ip`: Get the public IP address of the MediaFlow Proxy server
-7. `/extractor/video?host=`: Extract direct video stream URLs from supported hosts (see supported hosts in API docs)
+7. `/extractor/video`: Extract direct video stream URLs from supported hosts (see below)
 8. `/playlist/builder`: Build and customize playlists from multiple sources
+9. `/proxy/transcode/playlist.m3u8`: Generate HLS VOD playlist for generic stream transcode
+10. `/proxy/transcode/init.mp4`: fMP4 init segment for generic transcode playlist
+11. `/proxy/transcode/segment.m4s`: fMP4 media segment for generic transcode playlist
+12. `/proxy/telegram/transcode/playlist.m3u8`: Generate HLS VOD playlist for Telegram transcode
+13. `/proxy/telegram/transcode/init.mp4`: fMP4 init segment for Telegram transcode playlist
+14. `/proxy/telegram/transcode/segment.m4s`: fMP4 media segment for Telegram transcode playlist
 
 Once the server is running, for more details on the available endpoints and their parameters, visit the Swagger UI at `http://localhost:8888/docs`.
 
+### Video Extractor Endpoint
+
+The extractor endpoint extracts direct video stream URLs from various video hosting services. It supports an optional file extension in the URL for better player compatibility.
+
+#### Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `/extractor/video` | Base endpoint (generic, backward compatible) |
+| `/extractor/video.m3u8` | HLS streams - helps ExoPlayer detect HLS |
+| `/extractor/video.mp4` | MP4 streams |
+| `/extractor/video.mkv` | MKV streams |
+| `/extractor/video.ts` | MPEG-TS streams |
+| `/extractor/video.webm` | WebM streams |
+| `/extractor/video.avi` | AVI streams |
+
+#### Why Use Extensions?
+
+Some video players (notably Android's ExoPlayer used in Stremio) determine the media source type from the URL before making any HTTP requests. Without the correct extension:
+
+- ExoPlayer sees `/extractor/video?...` → Uses `ProgressiveMediaSource`
+- ExoPlayer sees `/extractor/video.m3u8?...` → Uses `HlsMediaSource` ✓
+
+For HLS streams, using the `.m3u8` extension ensures the player uses the correct HLS playback pipeline.
+
+#### Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `host` | Yes | Extractor host name (e.g., `TurboVidPlay`, `Vidoza`) |
+| `d` | Yes | Destination URL (the video page URL to extract) |
+| `api_password` | Yes* | API password (*if configured) |
+| `redirect_stream` | No | If `true`, returns 302 redirect to the proxied stream URL |
+
+#### Example Usage
+
+**Get extraction result as JSON:**
+```
+GET /extractor/video?host=Vidoza&d=https://videzz.net/example.html&api_password=your_password
+```
+
+**Redirect directly to stream (for players):**
+```
+GET /extractor/video.m3u8?host=TurboVidPlay&d=https://turbovidhls.com/t/abc123&api_password=your_password&redirect_stream=true
+```
+
+This redirects to the proxied HLS manifest URL, and because the request URL contains `.m3u8`, players like ExoPlayer will correctly use HLS playback.
+
 ### Xtream Codes (XC) API Proxy
 
 MediaFlow Proxy can act as a stateless pass-through proxy for Xtream Codes API, allowing you to proxy streams from XC-compatible IPTV providers through MediaFlow. This is particularly useful for:
@@ -1214,6 +1331,44 @@ Apply stream content transformations for specific hosting providers.
 - **Example:** `&transformer=ts_stream&x_headers=content-length,content-range` for streams with PNG wrappers.
 - **Note:** This parameter is automatically set when using extractors for supported hosts.
 
+**`/proxy/transcode/playlist.m3u8` and `/proxy/telegram/transcode/playlist.m3u8` (recommended)**  
+Use HLS transcode playlists for smooth browser playback and robust seeking with fMP4 segments.  
+- **Usage:** Open the playlist endpoint directly with `d` (or Telegram params), optional `api_password`, and optional `h_*` headers.  
+- **Effect:** Generates an HLS VOD playlist that references `init.mp4` + `segment.m4s` endpoints with browser-compatible H.264/AAC output.  
+- **URL Generator behavior:** When transcode is enabled and no start time is provided, URL Generator outputs these playlist URLs by default.
+
+**`&transcode=true` (direct mode)**  
+Transcode the stream directly to browser-compatible fragmented MP4 (fMP4) with H.264 video and AAC audio.  
+- **Usage:** Add `&transcode=true` to `/proxy/stream`, `/proxy/telegram/stream`, `/proxy/acestream/stream`, or Xtream Codes live/movie/series stream URLs.  
+- **Effect:** Re-encodes unsupported video codecs (HEVC, VP8/VP9, MPEG-2, MPEG-4, etc.) to H.264 and unsupported audio codecs (AC3, EAC3, Vorbis, Opus, FLAC, DTS, etc.) to AAC. Browser-compatible codecs (H.264 video, AAC audio) are passed through without re-encoding.  
+- **GPU Acceleration:** Automatically uses GPU encoding when available (NVIDIA NVENC, Apple VideoToolbox, Intel VAAPI/QSV). Falls back to CPU (libx264) otherwise.  
+- **On-the-fly:** Streaming is real-time with pipe-based demuxing. For MP4 inputs, the moov atom is probed and rewritten for immediate playback without downloading the full file.
+
+**`&start=120`**  
+Seek to a specific time position before starting transcoded playback.  
+- **Usage:** Add `&start=120` (value in seconds) alongside `&transcode=true` in direct transcode mode  
+- **Effect:** Starts transcoding from the specified time offset. For indexed containers (MKV cues, MP4 moov), this seeks to the nearest keyframe. For non-indexed formats (TS), this is a byte-estimate seek.  
+- **Supported Endpoints:** `/proxy/stream`, `/proxy/telegram/stream`, `/proxy/acestream/stream`, Xtream Codes live/movie/series endpoints  
+- **Note:** `start` is not used by `/proxy/transcode/playlist.m3u8` or `/proxy/telegram/transcode/playlist.m3u8` endpoints.
+- **Example:** `&transcode=true&start=300` starts playback from 5 minutes into the stream
+
+**`&ratelimit=vidoza`**  
+Apply host-specific rate limiting to prevent CDN 509 (Bandwidth Limit Exceeded) errors. Requires Redis to be configured.  
+- **Usage:** Add `&ratelimit=handler_id` to the `/proxy/stream` URL  
+- **Effect:** Limits the frequency of upstream connections to avoid triggering rate limits on aggressive CDNs.  
+- **Auto-detection:** If not specified, rate limiting is automatically applied for known hosts (e.g., Vidoza).  
+- **Available Handlers:**
+  - `vidoza` - 5-second cooldown between connections, HEAD caching, stream gating (auto-detected for vidoza.net)
+  - `aggressive` - 3-second cooldown, suitable for other rate-limited hosts
+  - `none` - Explicitly disable rate limiting (use when auto-detection is unwanted)
+- **How it works:** When a rate-limited stream is requested:
+  1. HEAD responses are cached to serve repeated probes without upstream connections
+  2. A cooldown period prevents rapid-fire GET requests
+  3. If another request arrives during cooldown, returns `503 Service Unavailable` with `Retry-After` header
+  4. Players automatically retry after the cooldown, resulting in smooth playback
+- **Requires:** `REDIS_URL` must be configured for rate limiting to function. Without Redis, rate limiting is disabled.
+- **Example:** `&ratelimit=vidoza` for Vidoza streams, or `&ratelimit=none` to disable auto-detection.
+
 **`&rp_content-type=video/mp2t`**  
 Set response headers that propagate to HLS/DASH segments.  
 - **Usage:** Add `&rp_header-name=value` to the proxy URL (rp_ prefix)  
@@ -1307,6 +1462,51 @@ mpv "http://localhost:8888/proxy/acestream/manifest.m3u8?id=your_content_id&star
 
 **Note:** The `start_offset` parameter is particularly useful for live streams where the prebuffer system cannot prefetch segments when sitting at the live edge. By starting slightly behind (e.g., `-18` seconds), there are future segments available for prebuffering, resulting in smoother playback. This works for both native HLS and DASH/MPD streams converted to HLS.
 
+#### Transcode Stream for Browser Playback
+
+```bash
+# Recommended: HLS transcode playlist for generic streams
+mpv "http://localhost:8888/proxy/transcode/playlist.m3u8?d=https://example.com/video.mkv&api_password=your_password"
+
+# Recommended: HLS transcode playlist for Telegram streams
+mpv "http://localhost:8888/proxy/telegram/transcode/playlist.m3u8?d=https://t.me/channelname/123&api_password=your_password"
+
+# Direct transcode mode with explicit seek start (start at 5 minutes)
+mpv "http://localhost:8888/proxy/stream?d=https://example.com/video.mp4&transcode=true&start=300&api_password=your_password"
+
+# Acestream transcode (direct mode)
+mpv "http://localhost:8888/proxy/acestream/stream?id=YOUR_CONTENT_ID&transcode=true&api_password=your_password"
+```
+
+**Note:** Transcoding uses GPU hardware acceleration when available (NVIDIA, Apple VideoToolbox, Intel). Browser-compatible codecs (H.264 video, AAC audio) are passed through without re-encoding to minimize resource usage.
+
+#### Transcode Performance Benchmarks
+
+Benchmark results for on-the-fly HEVC (H.265) to H.264 transcoding. Source: 4K (3840x2160) 30-second clip at 24fps with EAC3 5.1 audio, from a real movie file.
+
+**MediaFlow Proxy (on-the-fly streaming via PyAV pipeline):**
+
+| Source | Encoder | Wall Clock | Video Frames | Effective FPS | Output |
+|--------|---------|-----------|--------------|---------------|--------|
+| 4K HEVC MKV (EAC3) | VideoToolbox (GPU) | **11.7s** | 722 | **61.7 fps** | 15.1 MB |
+| 4K HEVC MKV (EAC3) | libx264 (CPU) | 26.2s | 722 | 27.6 fps | 15.1 MB |
+
+**Direct FFmpeg CLI baseline (local file, no HTTP proxy):**
+
+| Source | Encoder | Wall Clock | CPU Time | CPU Usage |
+|--------|---------|-----------|----------|-----------|
+| 4K HEVC MKV | VideoToolbox (GPU) | **11.9s** | 10.7s | 92% |
+| 4K HEVC MKV | libx264 (CPU) | 11.4s | 81.7s | 725% |
+
+**Key observations:**
+- **GPU MediaFlow matches direct FFmpeg** -- the optimized pipeline adds near-zero overhead (11.7s vs 11.9s)
+- GPU **exceeds real-time by 2.5x** for 4K 24fps content (62 fps), meaning no buffering delays
+- **GPU uses ~7x less CPU** than software encoding (92% vs 725%), leaving resources free for concurrent streams
+- The pipeline optimizations (thread-safe queues, eliminated async round-trips, skip redundant decoder flush) reduced GPU wall-clock from ~17s to ~11.7s (**31% improvement**)
+- On servers with NVIDIA GPUs, hardware HEVC decoding (`hevc_cuvid`) would further reduce both wall-clock time and CPU usage
+
+*Tested on Apple Silicon (M4) with PyAV 16.1.0 and FFmpeg 8.0. Results vary by hardware, content complexity, and network conditions.*
+
 #### Stream with Header Removal (Fix Content-Length Issues)
 
 ```bash

{mediaflow_proxy-2.4.2 → mediaflow_proxy-2.4.4}/mediaflow_proxy/configs.py

@@ -64,8 +64,16 @@ class Settings(BaseSettings):
     dash_prebuffer_emergency_threshold: int = 90  # Emergency threshold percentage to trigger aggressive cache cleanup.
     dash_prebuffer_inactivity_timeout: int = 60  # Seconds of inactivity before cleaning up stream state.
     dash_segment_cache_ttl: int = 60  # TTL (seconds) for cached media segments; longer = better for slow playback.
+    dash_player_lock_timeout: float = 2.5  # Max wait (seconds) for player requests when a segment lock is busy.
+    dash_prebuffer_lock_timeout: float = 0.25  # Max wait (seconds) for background prebuffer lock acquisition.
+    dash_prefetch_max_concurrent: int = 1  # Max concurrent live DASH prefetch downloads to reduce lock contention.
+    dash_live_initial_media_prebuffer: bool = (
+        False  # Whether manifest-time prebuffer should fetch live media segments (init segments are still prewarmed).
+    )
     mpd_live_init_cache_ttl: int = 60  # TTL (seconds) for live init segment cache; 0 disables caching.
     mpd_live_playlist_depth: int = 8  # Number of recent segments to expose per live playlist variant.
+    remux_to_ts: bool = False  # Remux fMP4 segments to MPEG-TS for ExoPlayer/VLC compatibility.
+    processed_segment_cache_ttl: int = 60  # TTL (seconds) for caching processed (decrypted/remuxed) segments.
 
     # FlareSolverr settings (for Cloudflare bypass)
     flaresolverr_url: str | None = None  # FlareSolverr service URL. Example: http://localhost:8191
@@ -88,6 +96,13 @@ class Settings(BaseSettings):
     telegram_max_connections: int = 8  # Max parallel DC connections for downloads (max 20, careful of floods).
     telegram_request_timeout: int = 30  # Request timeout in seconds.
 
+    # Transcode settings
+    enable_transcode: bool = True  # Whether to enable on-the-fly transcoding endpoints (MKV→fMP4, HLS VOD).
+    transcode_prefer_gpu: bool = True  # Prefer GPU acceleration (NVENC/VideoToolbox/VAAPI) when available.
+    transcode_video_bitrate: str = "4M"  # Target video bitrate for re-encoding (e.g. "4M", "2000k").
+    transcode_audio_bitrate: int = 192000  # AAC audio bitrate in bits/s for the Python transcode pipeline.
+    transcode_video_preset: str = "medium"  # Encoding speed/quality tradeoff (libx264: ultrafast..veryslow).
+
     user_agent: str = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Safari/537.36"  # The user agent to use for HTTP requests.
 
     # Upstream error resilience settings
@@ -96,6 +111,12 @@ class Settings(BaseSettings):
     upstream_retry_delay: float = 1.0  # Delay (seconds) between retry attempts.
     graceful_stream_end: bool = True  # Return valid empty playlist instead of error when upstream fails.
 
+    # Redis settings
+    redis_url: str | None = None  # Redis URL for distributed locking and caching. None = disabled.
+    cache_namespace: str | None = (
+        None  # Optional namespace for instance-specific caches (e.g. pod name or hostname). When set, extractor results and other IP-bound data are stored under this namespace so multiple pods sharing one Redis don't serve each other's IP-specific URLs.
+    )
+
     class Config:
         env_file = ".env"
         extra = "ignore"