Metadata-Version: 2.4
Name: fluxmedia
Version: 1.6.14
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
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.7]
- **Media Player Updates**: Added double-click to skip 10 seconds, `hours:minutes:seconds` format support for longer videos, and comprehensive YouTube-style keyboard shortcuts (`k`, `j`, `l`, `f`, `m`, and `0-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.

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