Metadata-Version: 2.4
Name: fluxmedia
Version: 1.6.19
Summary: A powerful, cross-platform media portal and processing toolkit.
License-Expression: MIT
Project-URL: Homepage, https://github.com/pdev-labs/FluxMedia-py
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Topic :: Multimedia :: Video
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich>=13.7.0
Requires-Dist: requests>=2.31.0
Requires-Dist: yt-dlp>=2025.2.18
Requires-Dist: textual>=0.50.0
Requires-Dist: mutagen>=1.47.0
Requires-Dist: instaloader>=4.11.0
Dynamic: license-file

<div align="center">

# 🌊 FluxMedia

**The official Python module and PyPI package for FluxMedia, featuring a customizable LAN QR share portal and rich media player.**

[![PyPI version](https://img.shields.io/pypi/v/fluxmedia.svg?style=for-the-badge&color=cyan)](https://pypi.org/project/fluxmedia/)
[![Python versions](https://img.shields.io/pypi/pyversions/fluxmedia.svg?style=for-the-badge&color=blue)](https://pypi.org/project/fluxmedia/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)

*A powerful, open-source, and cross-platform command-line media downloader designed for simplicity, robustness, and speed.*

</div>

---

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

## 🚀 Quick Start

> [!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](https://github.com/pdev-labs/FluxMedia-py/blob/main/INSTALLATION_GUIDE.md).

### 1. Installation
Install FluxMedia globally on any system running Python 3.10+ directly via `pip`:
```bash
pip install fluxmedia
```
*If you run into an `externally-managed-environment` error on modern Linux systems, install using `pipx` instead:*
```bash
pipx install fluxmedia
```

### 2. Execution
Run the interface from any terminal or command prompt:
```bash
fluxmedia
```

---

## ✨ Key Features

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

---

## 🛠️ Requirements & Setup

* **Python**: Version 3.10 or higher.
* **FFmpeg (Highly Recommended)**: Required for merging high-definition video formats and converting audio to MP3.

```bash
# Windows
winget install Gyan.FFmpeg

# macOS
brew install ffmpeg

# Linux (Debian/Ubuntu)
sudo apt install ffmpeg
```

---

## 🔍 Troubleshooting

<details>
<summary><b>1. LAN QR Sharing Fails on Phone/Tablet</b></summary>

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:
  ```powershell
  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.
</details>

<details>
<summary><b>2. Audio Extraction or Trimming Fails</b></summary>

* **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. 
</details>

<details>
<summary><b>3. Permission Denied on Android (Termux)</b></summary>

If downloads fail with `PermissionError` when writing to `/sdcard/Download/FluxMediaDownloads/`:
* Run the following command in Termux to grant file system storage access permissions:
  ```bash
  termux-setup-storage
  ```
</details>

<details>
<summary><b>4. Locked Files on Windows Update</b></summary>

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:
  ```bash
  pip install -U fluxmedia
  ```
</details>

<details>
<summary><b>5. SSL Certificate Verification Failures</b></summary>

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`
</details>

---

## 👑 Credits & Support

This project was created and is fully maintained by **[pdev-labs](https://github.com/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](https://img.shields.io/badge/GitHub-pdev--labs-181717?style=for-the-badge&logo=github)](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](https://github.com/pdev-labs/FluxMedia-py/issues)**

---

## 📜 Changelog

Check out the full [CHANGELOG.md](https://github.com/pdev-labs/FluxMedia-py/blob/main/CHANGELOG.md) for detailed release history.

### Latest Release: [v1.6.18]
- **Changelog Maintenance**: Added automated rules for maintaining `CHANGELOG.md` and `README.md`.
- **Global Video Download Countdown**: Added a 5-second interactive terminal countdown prompt when standard video files already exist on disk (yt-dlp).
- **Instagram Profile Countdown**: Added smart 5-second interactive Terminal prompts to the Instagram downloader.
- **Instagram Profile Scraper**: Implemented a new scraper option via `instaloader` to bulk download all public media.
- **TUI Instagram Support**: Added a dedicated `📸 Instagram` tab to the advanced Textual UI interface.

<div align="center">
  <i>Made with ❤️ by pdev-labs</i>
</div>
