Legend017/mediaflow-proxy
0
1---2title: MediaFlow Proxy3emoji: 🎥4colorFrom: blue5colorTo: green6sdk: docker7app_port: 88888pinned: false9license: mit10thumbnail: >-11 https://cdn.githubraw.com/mhdzumair/mediaflow-proxy/main/mediaflow_proxy/static/logo.png12---13 14 15# MediaFlow Proxy16 17<div style="text-align: center;">18 <img src="https://cdn.githubraw.com/mhdzumair/mediaflow-proxy/main/mediaflow_proxy/static/logo.png" alt="MediaFlow Proxy Logo" width="200" style="border-radius: 15px;">19</div>20 21MediaFlow Proxy is a powerful and flexible solution for proxifying various types of media streams. It supports HTTP(S) links, HLS (M3U8) streams, and MPEG-DASH streams, including DRM-protected content. This proxy can convert MPEG-DASH DRM-protected streams to decrypted HLS live streams in real-time, making it one of the fastest live decrypter servers available.22 23## Features24 25- Convert MPEG-DASH streams (DRM-protected and non-protected) to HLS26- Support for Clear Key DRM-protected MPD DASH streams27- Support for non-DRM protected DASH live and VOD streams28- Proxy HTTP/HTTPS links with custom headers29- Proxy and modify HLS (M3U8) streams in real-time with custom headers and key URL modifications for bypassing some sneaky restrictions.30- Retrieve public IP address of the MediaFlow Proxy server for use with Debrid services31- Support for HTTP/HTTPS/SOCKS5 proxy forwarding32- Protect against unauthorized access and network bandwidth abuses33- Support for play expired or self-signed SSL certificates server streams `(verify_ssl=false)` default is `false`34- Flexible request proxy usage control per request `(use_request_proxy=true/false)` default is `true`35- Obfuscating endpoint parameters by encrypting them to hide sensitive information from third-party.36- Optional IP-based access control restriction & expiration for encrypted URLs to prevent unauthorized access37 38## Configuration39 40Set the following environment variables:41 42- `API_PASSWORD`: Required. Protects against unauthorized access and API network abuses.43- `PROXY_URL`: Optional. HTTP/HTTPS/SOCKS5 proxy URL for forwarding network requests.44- `ENABLE_STREAMING_PROGRESS`: Optional. Enable streaming progress logging. Default is `false`.45 46## Installation47 48### Option 1: Self-Hosted Deployment49 50#### Using Docker from Docker Hub51 521. Pull & Run the Docker image:53 ```54 docker run -p 8888:8888 -e API_PASSWORD=your_password mhdzumair/mediaflow-proxy55 ```56 57#### Using pip58 59> [!IMPORTANT] 60> Ensure that you have Python 3.10 or higher installed.61 621. Install the package:63 ```64 pip install mediaflow-proxy65 ```66 672. Set the `API_PASSWORD` and other environment variables in `.env`:68 ```69 echo "API_PASSWORD=your_password" > .env70 ```71 723. Run the MediaFlow Proxy server:73 ```74 mediaflow-proxy75 ```76 You can access the server at `http://localhost:8888`.77 784. To run the server with uvicorn options: (Optional)79 ```80 uvicorn mediaflow_proxy.main:app --host 0.0.0.0 --port 8888 --workers 481 ```82 83 84#### Using git & poetry85 86> [!IMPORTANT] 87> Ensure that you have Python 3.10 or higher installed.88 89 901. Clone the repository:91 ```92 git clone https://github.com/mhdzumair/mediaflow-proxy.git93 cd mediaflow-proxy94 ```95 962. Install dependencies using Poetry:97 ```98 poetry install99 ```100 1013. Set the `API_PASSWORD` environment variable in `.env`:102 ```103 echo "API_PASSWORD=your_password" > .env104 ```105 1064. Run the FastAPI server:107 ```108 poetry run uvicorn mediaflow_proxy.main:app --host 0.0.0.0 --port 8888 --workers 4109 ```110 111 112#### Build and Run Docker Image Locally113 1141. Build the Docker image:115 ```116 docker build -t mediaflow-proxy .117 ```118 1192. Run the Docker container:120 ```121 docker run -d -p 8888:8888 -e API_PASSWORD=your_password --restart unless-stopped --name mediaflow-proxy mediaflow-proxy122 ```123 124### Option 2: Premium Hosted Service (ElfHosted)125<div style="text-align: center;">126 <img src="https://store.elfhosted.com/wp-content/uploads/2024/08/mediaflow-proxy.jpg" alt="ElfHosted Logo" width="200" style="border-radius: 15px;">127</div>128For a hassle-free, high-performance deployment of MediaFlow Proxy, consider the premium hosted service through ElfHosted.129 130To purchase:1311. Visit [https://store.elfhosted.com/product/mediaflow-proxy](https://store.elfhosted.com/product/mediaflow-proxy)1322. Follow ElfHosted's setup instructions133 134Benefits:135- Instant setup and automatic updates136- High performance and 24/7 availability137- No server maintenance required138 139Ideal for users who want a reliable, plug-and-play solution without the technical overhead of self-hosting.140 141### Option 3: Hugging Face Space Deployment142 1431. Visit the HF Space: [mhdzumair/mediaflow-proxy](https://huggingface.co/spaces/mhdzumair/mediaflow-proxy)1442. Click on three dots on the right side of the page and select "Duplicate Space"1453. Set the `API_PASSWORD` secret value & Set Visibility to "Public"1464. Click on "Duplicate Space" to deploy the API147 148## Usage149 150### Endpoints151 1521. `/proxy/hls/manifest.m3u8`: Proxify HLS streams1532. `/proxy/stream`: Proxy generic http video streams1543. `/proxy/mpd/manifest.m3u8`: Process MPD manifests1554. `/proxy/mpd/playlist.m3u8`: Generate HLS playlists from MPD1565. `/proxy/mpd/segment.mp4`: Process and decrypt media segments1576. `/proxy/ip`: Get the public IP address of the MediaFlow Proxy server158 159Once the server is running, for more details on the available endpoints and their parameters, visit the Swagger UI at `http://localhost:8888/docs`.160 161### Examples162 163#### Proxy HTTPS Stream (without using configured proxy)164 165```bash166mpv "http://localhost:8888/proxy/stream?d=https://jsoncompare.org/LearningContainer/SampleFiles/Video/MP4/sample-mp4-file.mp4&api_password=your_password&use_request_proxy=false"167```168 169#### Proxy HTTPS self-signed certificate Stream170 171```bash172mpv "http://localhost:8888/proxy/stream?d=https://self-signed.badssl.com/&api_password=your_password&verify_ssl=false"173```174 175 176#### Proxy HLS Stream with Headers177 178```bash179mpv "http://localhost:8888/proxy/hls/manifest.m3u8?d=https://devstreaming-cdn.apple.com/videos/streaming/examples/img_bipbop_adv_example_fmp4/master.m3u8&h_referer=https://apple.com/&h_origin=https://apple.com&h_user-agent=Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/118.0.0.0 Safari/537.36&api_password=your_password"180```181 182#### Live DASH Stream (Non-DRM Protected)183 184```bash185mpv -v "http://localhost:8888/proxy/mpd/manifest.m3u8?d=https://livesim.dashif.org/livesim/chunkdur_1/ato_7/testpic4_8s/Manifest.mpd&api_password=your_password"186```187 188#### VOD DASH Stream (DRM Protected)189 190```bash191mpv -v "http://localhost:8888/proxy/mpd/manifest.m3u8?d=https://media.axprod.net/TestVectors/v7-MultiDRM-SingleKey/Manifest_1080p_ClearKey.mpd&key_id=nrQFDeRLSAKTLifXUIPiZg&key=FmY0xnWCPCNaSpRG-tUuTQ&api_password=your_password"192```193 194Note: The `key` and `key_id` parameters are automatically processed if they're not in the correct format.195 196### URL Encoding197 198For players like VLC that require properly encoded URLs, use the `encode_mediaflow_proxy_url` function:199 200```python201from mediaflow_proxy.utils.http_utils import encode_mediaflow_proxy_url202 203encoded_url = encode_mediaflow_proxy_url(204 mediaflow_proxy_url="http://127.0.0.1:8888",205 endpoint="/proxy/mpd/manifest.m3u8",206 destination_url="https://media.axprod.net/TestVectors/v7-MultiDRM-SingleKey/Manifest_1080p_ClearKey.mpd",207 query_params={208 "key_id": "nrQFDeRLSAKTLifXUIPiZg",209 "key": "FmY0xnWCPCNaSpRG-tUuTQ",210 "api_password": "your_password"211 },212 request_headers={213 "referer": "https://media.axprod.net/",214 "origin": "https://media.axprod.net",215 }216)217 218print(encoded_url)219 220# http://127.0.0.1:8888/proxy/mpd/manifest.m3u8?key_id=nrQFDeRLSAKTLifXUIPiZg&key=FmY0xnWCPCNaSpRG-tUuTQ&api_password=your_password&d=https%3A%2F%2Fmedia.axprod.net%2FTestVectors%2Fv7-MultiDRM-SingleKey%2FManifest_1080p_ClearKey.mpd&h_referer=https%3A%2F%2Fmedia.axprod.net%2F&h_origin=https%3A%2F%2Fmedia.axprod.net221```222 223This will output a properly encoded URL that can be used with players like VLC.224 225```bash226vlc "http://127.0.0.1:8888/proxy/mpd/manifest.m3u8?key_id=nrQFDeRLSAKTLifXUIPiZg&key=FmY0xnWCPCNaSpRG-tUuTQ&api_password=dedsec&d=https%3A%2F%2Fmedia.axprod.net%2FTestVectors%2Fv7-MultiDRM-SingleKey%2FManifest_1080p_ClearKey.mpd"227```228 229### Generating Encrypted URLs230 231To generate an encrypted URL with optional IP restriction and expiration, Use the `/generate_encrypted_or_encoded_url` endpoint via swagger UI or programmatically as shown below:232```python233import requests234 235url = "http://localhost:8888/generate_encrypted_or_encoded_url"236data = {237 "mediaflow_proxy_url": "http://localhost:8888",238 "endpoint": "/proxy/mpd/manifest.m3u8",239 "destination_url": "https://media.axprod.net/TestVectors/v7-MultiDRM-SingleKey/Manifest_1080p_ClearKey.mpd",240 "query_params": {241 "key_id": "nrQFDeRLSAKTLifXUIPiZg",242 "key": "FmY0xnWCPCNaSpRG-tUuTQ"243 },244 "request_headers": {245 "referer": "https://media.axprod.net/",246 "origin": "https://media.axprod.net",247 },248 "expiration": 3600, # URL will expire in 1 hour249 "ip": "123.123.123.123", # Optional: Restrict access to this IP250 "api_password": "your_password"251}252 253response = requests.post(url, json=data)254encrypted_url = response.json()["encoded_url"]255print(encrypted_url)256```257 258You can then use the `encoded_url` in your player or application to access the media stream.259 260 261### Using MediaFlow Proxy with Debrid Services and Stremio Addons262 263MediaFlow Proxy can be particularly useful when working with Debrid services (like Real-Debrid, AllDebrid) and Stremio addons. The `/proxy/ip` endpoint allows you to retrieve the public IP address of the MediaFlow Proxy server, which is crucial for routing Debrid streams correctly.264 265When a Stremio addon needs to create a video URL for a Debrid service, it typically needs to provide the user's public IP address. However, when routing the Debrid stream through MediaFlow Proxy, you should use the IP address of the MediaFlow Proxy server instead.266 267Here's how to utilize MediaFlow Proxy in this scenario:268 2691. If MediaFlow Proxy is accessible over the internet:270 - Use the `/proxy/ip` endpoint to get the MediaFlow Proxy server's public IP.271 - Use this IP when creating Debrid service URLs in your Stremio addon.272 2732. If MediaFlow Proxy is set up locally:274 - Stremio addons can directly use the client's IP address.275 276 277## Future Development278 279- Add support for Widevine and PlayReady decryption280 281## Acknowledgements and Inspirations282 283MediaFlow Proxy was developed with inspiration from various projects and resources:284 285- [Stremio Server](https://github.com/Stremio/stremio-server) for HLS Proxify implementation, which inspired our HLS M3u8 Manifest parsing and redirection proxify support.286- [Comet Debrid proxy](https://github.com/g0ldyy/comet) for the idea of proxifying HTTPS video streams.287- [mp4decrypt](https://www.bento4.com/developers/dash/encryption_and_drm/), [mp4box](https://wiki.gpac.io/xmlformats/Common-Encryption/), and [devine](https://github.com/devine-dl/devine) for insights on parsing MPD and decrypting Clear Key DRM protected content.288- Test URLs were sourced from:289 - [OTTVerse MPEG-DASH MPD Examples](https://ottverse.com/free-mpeg-dash-mpd-manifest-example-test-urls/)290 - [OTTVerse HLS M3U8 Examples](https://ottverse.com/free-hls-m3u8-test-urls/)291 - [Bitmovin Stream Test](https://bitmovin.com/demos/stream-test)292 - [Bitmovin DRM Demo](https://bitmovin.com/demos/drm)293 - [DASH-IF Reference Player](http://reference.dashif.org/dash.js/nightly/samples/)294- [HLS Protocol RFC](https://www.rfc-editor.org/rfc/rfc8216) for understanding the HLS protocol specifications.295- Claude 3.5 Sonnet for code assistance and brainstorming.296 297## Contributing298 299Contributions are welcome! Please feel free to submit a Pull Request.300 301## License302 303[MIT License](LICENSE)304 305 306## Disclaimer307 308This project is for educational purposes only. The developers of MediaFlow Proxy are not responsible for any misuse of this software. Please ensure that you have the necessary permissions to access and use the media streams you are proxying.