mediaflow-proxy: a streaming proxy that reshapes HLS and DASH on the fly

What the proxy actually sits between

MediaFlow Proxy is described as a streaming proxy for HTTP(S), HLS with M3U8 playlists, and MPEG-DASH, including ClearKey DRM and real-time DASH to HLS conversion. The highlights list adds Xtream Codes API proxying, Acestream, Telegram streaming over MTProto, transcoding, and advanced routing.

The interesting part is the reshaping. A manifest proxy can rewrite a playlist on the fly, so segment URLs get rewritten to point back through the proxy, filters are applied to the manifest, and the client sees a playlist the proxy controls. DASH to HLS conversion is the harder version of the same idea, taking a DASH stream with ClearKey protection and republishing it as HLS, which is the format most players and most set-top boxes will accept.

Beyond that there is a long list of source types, because the proxy is aimed at people who have a stream URL of some kind and want a stable endpoint for it. Xtream Codes API proxying covers IPTV panels, Acestream is an older IPTV protocol, and Telegram media is pulled over MTProto. The `telethon>=1.42.0` dependency is the Telegram client library, and `cryptg` is the accelerated Telegram crypto extension.

There is also a plain generic HTTP(S) proxy with custom headers, which covers the case where the upstream needs a specific header set and the client cannot send it. And there is the deferred media source family, with `alldebrid` and `real-debrid` among the repository topics, which is the token based link resolving side of the project.

FastAPI and aiohttp underneath, Gunicorn and Uvicorn in front

The dependency list in pyproject.toml describes the architecture accurately.

`fastapi` provides the application and its API surface, `aiohttp` is the async HTTP client used to fetch upstream manifests and segments, and `aiohttp-socks` adds SOCKS proxy support for reaching upstreams that require it. `uvicorn` and `gunicorn` are both there because the Dockerfile runs Gunicorn with the Uvicorn worker class, which is the standard way to serve an async ASGI app with multiple worker processes.

The rest of the list maps to features. `telethon` and `cryptg` for Telegram. `av>=14.0.0` is the PyAV binding to ffmpeg libraries, and the Dockerfile installs the matching `libavcodec-dev`, `libavformat-dev` and related packages, so transcoding is a first class part of the image rather than an optional add-on. `pycryptodome` and `cryptography>=48.0.0` handle the encrypted URL generation and the DRM work. `xmltodict` and `lxml` handle manifest parsing, `beautifulsoup4` handles HTML when Telegram scraping is involved, `pydantic-settings` handles configuration, and `psutil` is there for process and system inspection.

`redis[hiredis]>=5.0.0` backs the rate limiting, and `curl_cffi` is a curl-compatible HTTP client with browser impersonation, which is a common trick for reaching upstreams that reject requests based on TLS fingerprinting.

The package targets Python 3.10 and newer, is classified as Beta, and exposes one console script, `mediaflow-proxy = "mediaflow_proxy.main:run"`. The project version in pyproject.toml is 2.4.1.

Running it as a container, with Redis alongside

The quick start is a single Docker run:

docker run -p 8888:8888 -e API_PASSWORD=your_password mhdzumair/mediaflow-proxy

The port is 8888 and the one environment variable in that command is the API password, which is how requests to the proxy are authenticated.

The compose file shows the fuller deployment, with two services. Redis uses the `redis:7-alpine` image in a container named `mfp-redis`, with a named volume `redis_data` and a healthcheck that runs `redis-cli ping` every ten seconds. The proxy service is built from the git repository at the main branch, publishes `8888:8888`, and depends on Redis being healthy before it starts. Its environment sets the API password, `FORWARDED_ALLOW_IPS` to a wildcard, and `REDIS_URL` pointing at the Redis service. The compose file also includes a commented out port mapping for Redis, described as optional for debugging and to be removed in production.

The Dockerfile is a two stage build. The builder stage uses `python:3.14-slim`, installs build-essential and the ffmpeg development libraries, installs the Rust toolchain with rustup, installs uv, copies only pyproject.toml and uv.lock, and runs `uv sync --frozen --no-install-project --no-dev` so the dependency layer is cached separately from the source.

The runtime stage is also `python:3.14-slim` and installs only ffmpeg and a handful of shared libraries. Its environment sets the Gunicorn tuning directly: `PORT` 8888, `GUNICORN_WORKERS` 4, `GUNICORN_WORKER_CLASS` uvicorn.workers.UvicornWorker, a 120 second timeout, `GUNICORN_MAX_REQUESTS` of 500 with a jitter of 200, and access and error logs to stdout. A non-root user is created and the process runs as it.

The `FORWARDED_ALLOW_IPS` setting is the reverse proxy hint: it tells the app which upstream addresses it may trust forwarded headers from, and the compose file sets it to a wildcard, which is convenient behind a proxy and wrong to keep in production.

Transcoding, pre-buffering and the optional OCR extras

The highlights mention optional GPU transcoding to fMP4 with H.264 and AAC, pre-buffering, segment skipping and stream transformers.

Pre-buffering is the feature that matters most for user experience. When a player requests a live stream, the proxy can hold the first segments and serve a burst, so the player starts playing immediately instead of stuttering through the join. Segment skipping lets the proxy drop segments the client has already seen, which reduces bandwidth on a live or long VOD stream. Stream transformers are the hook for rewriting manifests and payloads as they pass through.

There is an optional dependency group that needs calling out, because it defines the shape of the project more than the feature list does:

maxstream = [
    "Pillow",
    "pytesseract",
    "ddddocr",
]

The comment above it describes them as local OCR engines for the Maxstream and uprot.net captcha bypass, and the note explains that the system tesseract-ocr binary must also be available, with an apt install of tesseract-ocr on Debian or Ubuntu. The install command is `pip install "mediaflow-proxy[maxstream]"`.

So the tool ships, as an opt-in extra, a way to solve the challenge on a captcha-protected source in order to fetch from it automatically. That is the feature to think about before you deploy it. It is opt-in and scoped to a specific source, but it is also the kind of capability that changes your obligations around the content you are pulling, and the project's own disclaimer asks users to ensure they have the necessary permissions to access the media streams they proxy.

Encrypted URLs, rate limiting and the Rust alternative

Two operational details in the highlights are worth understanding before you expose this to anyone.

Encrypted URL generation means the proxy hands out URLs that encode their own parameters, so a client does not need to carry credentials or upstream tokens in the request. This is what makes the proxy usable behind a reverse proxy and in front of a client that only knows a URL. The `pycryptodome` dependency is the encryption side. The reverse proxy friendliness also comes from the forwarded headers handling, which is what `FORWARDED_ALLOW_IPS` controls.

Redis-backed rate limiting protects the upstream and the proxy itself from a client that asks for too much. It is also the reason the compose file treats Redis as a hard dependency with a healthcheck rather than an optional extra.

The project also points at an alternative implementation in the same ecosystem. MediaFlow Proxy Light is described as a Rust reimplementation that is fully API compatible with this proxy, for lower memory usage and higher throughput on constrained hardware such as a small VPS, a NAS or a Raspberry Pi. The README states benchmarks showing 7 to 8 times less memory, 1.7 to 3.4 times less CPU per request and up to 4 times higher throughput, and says existing tokens, encrypted URLs and client integrations work without changes. Those are the project's own published figures, not an independent measurement.

That compatibility claim is the interesting part. Because the two implementations speak the same API, the choice between them is a deployment decision rather than a migration, and the Python one remains the reference for feature coverage since the Light version is the newer and narrower implementation.

Development, documentation and release notes generated by a model

The repository is organized like a maintained service rather than a script. There is a `Dockerfile`, a `docker-compose.yml`, a `docker-compose.portainer` variant for Portainer deployments, a `heroku.yml` for Heroku, a `Makefile`, `mkdocs.yml` with the documentation built by MkDocs from the `docs/` folder, and a `tests/` directory.

The documentation site is the primary user manual, and the README points at it as such. Building the docs locally takes two commands, `uv sync --group docs` and then `uv run mkdocs serve`. The presence of a `uv.lock` means the project uses uv for dependency resolution, with the same tool the Dockerfile uses to install dependencies frozen from the lock file.

The Makefile is where the project reveals something unusual. It has a `prompt` target that generates a release note for a version by analysing the commit log between two tags, with an instruction to organise the note by importance rather than commit order, to create sections for new features, bug fixes and documentation only when relevant, to use emojis at the start of each item, and to preserve contributor username mentions in a Contributors section. It reads the commit range with git log, formats it with awk, and takes the version range, the contributors list and the release body file path as variables. The Makefile also carries Gemini API settings, with a default model of `gemini-3-flash-preview` and a max tokens setting of 8000.

So the changelog for a release is produced by asking a language model to summarise the commits, with a prompt that encodes the house style. That is a defensible way to keep release notes current, and it is also a place where a reviewer should look closely, because a model summarising commits is a summariser rather than a reporter.

The project is MIT licensed with the LICENSE file at the root, the repository is not archived, and the last push was on 2026-09-06, with releases 2.4.9 from 2026-05-19, 2.4.8 from 2026-04-22 and 2.4.7 from 2026-04-19.

Editorial conclusion

Adopt mediaflow-proxy if you need to serve a stream you already have rights to through your own endpoint, with HLS rewriting, ClearKey DASH to HLS conversion, IPTV source pulling or ffmpeg transcoding in one process. Do not adopt it to redistribute streams you do not have permission for, since the project itself asks users to ensure they have the necessary permissions. Verify first which deployment shape fits, whether the Docker image on port 8888 or the Python package, that ffmpeg and the optional OCR extras are present if you need transcoding, and that the memory footprint of the Python implementation is acceptable on your host.

Frequently asked questions

Official sources

1. License: MIT
2. mhdzumair/mediaflow-proxy on GitHub
3. Project website
4. README
5. Releases