The official Python module and PyPI package for FluxMedia, featuring a customizable LAN QR share portal and rich media player.
A powerful, open-source, and cross-platform command-line media downloader designed for simplicity, robustness, and speed.
Important
Disclaimer & Educational Notice: This program is developed strictly for educational and research purposes. You must obtain explicit permission from the original content creators before downloading any videos or media. The author does not assume any liability for unauthorized downloads or usage of this tool.
Tip
Looking for detailed step-by-step installation instructions for your specific OS (Windows, macOS, Linux, or Termux)? Check out the Detailed OS-Specific Setup Guide.
Install FluxMedia globally on any system running Python 3.10+ directly via pip:
pip install fluxmediaIf you run into an externally-managed-environment error on modern Linux systems, install using pipx instead:
pipx install fluxmediaRun the interface from any terminal or command prompt:
fluxmedia| Feature | Description |
|---|---|
| 🎨 Dynamic Console TUI | Renders rich tables, panels, and live progress bars for download speeds, ETA, and file sizes. |
| 🎵 Smart Audio Extraction | Automatically extract and convert media into high-quality MP3 (192kbps) with embedded cover art and metadata. |
| 🏷️ Metadata Embedding | Automatically write video thumbnails and details (description, uploader, dates) directly into your downloads. |
| 📚 Batch Downloads | Save entire playlists or recent uploads from content creator channels. |
| 📝 Subtitles Capturing | Download caption files directly for specified language codes. |
| ⚙️ Global Settings | Customize download folders, default formats, filename structures, and UI themes inside the app. |
| 🌐 LAN QR Share Portal | Easily share downloaded media over your local network using an interactive web portal. |
- Python: Version 3.10 or higher.
- FFmpeg (Highly Recommended): Required for merging high-definition video formats and converting audio to MP3.
# Windows
winget install Gyan.FFmpeg
# macOS
brew install ffmpeg
# Linux (Debian/Ubuntu)
sudo apt install ffmpeg1. LAN QR Sharing Fails on Phone/Tablet
If your phone cannot load the link generated by the QR Share Server (http://<IP>:8000):
- Windows Network Profile: Windows Firewall blocks incoming traffic on Public networks. Open Windows Settings ➔ Network & internet ➔ Wi-Fi, click your connection properties, and change the network profile type to Private.
- Windows Firewall Inbound Rule: Add an inbound firewall rule in PowerShell to whitelist port 8000:
New-NetFirewallRule -DisplayName "FluxMedia LAN Share" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 8000-8020
- Same Network: Ensure your phone is connected to the exact same Wi-Fi connection (or phone hotspot) as your laptop.
2. Audio Extraction or Trimming Fails
- FFmpeg Dependency: Merging streams, converting to MP3/M4A, and trimming downloads require FFmpeg. Make sure you have FFmpeg installed on your machine and added to your system's PATH.
3. Permission Denied on Android (Termux)
If downloads fail with PermissionError when writing to /sdcard/Download/FluxMediaDownloads/:
- Run the following command in Termux to grant file system storage access permissions:
termux-setup-storage
4. Locked Files on Windows Update
If upgrading FluxMedia or yt-dlp inside the app fails because the files are locked in memory:
- Close the application and run the update command directly from a standard terminal window:
pip install -U fluxmedia
5. SSL Certificate Verification Failures
If downloads fail with [SSL: CERTIFICATE_VERIFY_FAILED]:
- macOS Users: Go to your Applications/Python folder and double-click
Install Certificates.command. - All Platforms: Run:
pip install --upgrade certifi
This project was created and is fully maintained by pdev-labs. I am a student in India (Standard 11, PCM with CS) and I spent a couple of weeks designing, coding, and perfecting FluxMedia alone.
If you find this tool helpful, please support my work by giving it a star on GitHub! ⭐
- Support via UPI:
priyanshuc@fam
Got an issue, bug, or feature request? I would love to hear from you! Please file reports directly at: 👉 FluxMedia Issue Tracker
Check out the full CHANGELOG.md for detailed release history.
- Media Player Updates: Added double-click to skip 10 seconds,
hours:minutes:secondsformat support for longer videos, and comprehensive YouTube-style keyboard shortcuts (k,j,l,f,m, and0-9). - Automated PyPI Publishing: Implemented GitHub Actions CI/CD workflows for secure Trusted Publishing to PyPI.
- PyPI README Fixes: Resolved 404 broken link errors on PyPI by utilizing absolute GitHub blob URLs.
- Share Portal Customization Submenu: Added a settings panel to configure profile display name, profile image (local/URL), custom website file/folder, and password configurations directly.
- Premium Material 3 Tones: Introduced 4 new theme tones (Royal Purple, Crimson Rose, Sunset Orange, Indigo Breeze) across all templates.
- Responsive Layout Optimizations: Optimized page header to stack controls cleanly on mobile viewports while preserving standard inline spacing on desktops.
- Port Overriding: Enabled running the sharing server on a custom port if the default port 8000 is occupied.