fluxmedia 1.5.7

FluxMedia - Cross-platform Command-Line Media Downloader

🌊 FluxMedia

[!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.

FluxMedia is a powerful, open-source, and cross-platform command-line media downloader designed for simplicity, robustness, and speed. Built on top of yt-dlp and rich, it provides a beautiful terminal user interface (TUI) to download videos, audio streams, playlists, channel uploads, and subtitles from thousands of supported websites.

---

🚀 Quick Start

1. Installation

Install FluxMedia globally on any system running Python 3.10+ directly via pip:

pip install fluxmedia

If you run into an externally-managed-environment error on modern Linux systems, install using pipx instead:

pipx install fluxmedia

2. Execution

Run the interface from any terminal or command prompt:

fluxmedia

---

✨ Key Features

• 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 (requires FFmpeg).
• Metadata & Cover Art 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.

---

🛠️ Requirements & Setup

• 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: sudo apt install ffmpeg

---

🔍 Troubleshooting

1. 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. If FFmpeg is missing, install it as follows:
  • Windows: winget install Gyan.FFmpeg
  • Termux (Android): pkg install ffmpeg
  • macOS: brew install ffmpeg

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 (WinError 32 / Access is Denied)

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 (SSLError)

If downloads fail with [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate:

• macOS Users: Go to your Applications/Python folder and double-click Install Certificates.command to download and install the required root certificates.
• All Platforms: Run the following command in your terminal to upgrade your root certificates library:

  pip install --upgrade certifi
  

6. Slow Download Speeds & Throttling

If download speeds are extremely slow:

• Update the Downloader Engine: Media platforms frequently change their streaming protocols. Go to main menu option 11. Updates Manager and select 1. Update yt-dlp to fetch the latest download engine patches.
• ISP Throttling: Some ISPs throttle automated HTTP video requests. Running a VPN can bypass these local network throttling blocks.

7. HTTP 403 Forbidden / Sign-In Required / Age-Restricted Errors

If downloads fail with HTTP Error 403: Forbidden, age-restriction walls, or geo-blocks:

• Pass Cookies: You can pass authentication credentials from your browser. Go to main menu option 10. Configuration ➔ 7. Preferred Cookies Browser and choose the browser you use (e.g., chrome, edge, firefox, brave, or safari). This allows FluxMedia to download files using your active browser session cookies without typing your password.

8. ExtractorError / Unsupported URL

If you get parsing errors on newer video layouts:

• Simply run the Updates Manager inside the app (Option 11) or upgrade the core downloader from your command prompt:

  pip install -U yt-dlp
  

9. Externally Managed Environment Error (externally-managed-environment)

If installing FluxMedia system-wide fails with error: externally-managed-environment on modern Linux distributions (such as Ubuntu 23.04+, Debian 12+, etc.):

• Use pipx (Recommended): pipx automatically manages isolated environments for Python CLI tools:

  pipx install fluxmedia
  

• Use a Virtual Environment: Create and activate a virtual environment before running pip:

  python3 -m venv .venv
  source .venv/bin/activate
  pip install fluxmedia
  

• Override System Safeguards (Not Recommended): Override the safeguard at the risk of breaking system packages:

  pip install fluxmedia --break-system-packages
  

---

👑 Credits & Support

This project was created and is fully maintained by Priyanshu Chauhan (@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! ⭐

• GitHub Repository: https://github.com/pdev-labs/FluxMedia-py
• GitHub Profile: https://github.com/pdev-labs
• Support via UPI: priyanshuc@fam

---

🐛 Bugs, Errors & Feedback

Got an issue, bug, or feature request? I would love to hear from you! Please file reports directly at: 👉 FluxMedia Issue Tracker

To help me resolve errors quickly, please:

1. Search active issues first to avoid duplicate bug tickets.
2. Provide details about your Operating System and whether FFmpeg is installed.
3. Paste logs or stderr dumps. (Local execution logs are saved inside your home directory under ~/.fluxmedia/fluxmedia.log).