cli-music-player-cthulhu 1.0.10
A lightweight terminal music player with mpv engine and auto-setup
Requires Python: >=3.8

# FreeThullu Music Player 🐙🎵

**Version 1.0.10**

A powerful, hybrid music player that summons your beats from the deep.
Featuring a modern **GUI** (PyQt6) for desktop comfort and a robust **CLI** mode for terminal dwellers.

## ✨ Features

- **Hybrid Interface:**
  - **Unified Binary:** A single executable for all modes.
  - **GUI (Default):** Modern Dark Theme, Tabbed Interface (Now Playing, Library, Search, Queue), and Animated Visuals.
  - **CLI (`--cli`):** Lightweight, keyboard-driven terminal interface.
- **Robust Debugging:** Use `--debug` to troubleshoot playback or scraping issues.
- **Universal Playback:**
  - **Local Library:** Deep recursive scanning, instant filtering, and file management.
  - **Online Streaming:** Seamless **YouTube** and **SoundCloud** (prefix `sc:`) integration.
- **Immersive Experience:**
  - **Animated FreeThullu:** Watch the Great Old One pulse to the rhythm.
  - **Synced Lyrics:** Automatic fetching from LRCLib and Letras.mus.br.
- **Smart Queue:**
  - Manage your playlist with ease.
  - **Context Menus:** Right-click to add multiple items to the queue.
  - **Jump:** Double-click any item in the queue to play immediately.
- **Cross-Platform:** Native support for **Linux** and **Windows** (with auto-mpv setup).

## 🚀 Installation

### Via PIP

```bash
pip install cli-music-player-cthulhu
```

### System Requirements

- **Python 3.9+**
- **Linux:** Requires `mpv` (`sudo apt install mpv` / `sudo pacman -S mpv`).
- **Windows:** Auto-downloads `mpv` on first run.

## 🎮 Usage

Launch the player using the unified command:

```bash
# Start in GUI mode (Default)
musicplayer

# Start in CLI mode (Terminal)
musicplayer --cli

# Enable Debug Mode (Works for both GUI and CLI)
musicplayer --debug
musicplayer --cli --debug

# You can also use the alias:
freethullu-player
```

### 🖥️ Graphical Interface (GUI)
Launch the full experience with animated visuals and tabbed navigation.

**Controls:**
- **Navigation:** Use tabs to switch views.
- **Library:** Type in the filter box. **Press Enter** to trigger a deep recursive search in subfolders.
- **Search:** Type queries for YouTube. Prefix with `sc:` for SoundCloud.
- **Queueing:** Select multiple items (Ctrl/Shift+Click) -> Right Click -> *Add to Queue*.

### 📟 Terminal Interface (CLI)
A lightweight, keyboard-driven interface for terminal fans.

**Controls:** 
- `Space`: Pause/Play
- `/`: Online Search
- `a`: Add current selection to Queue
- `n`: Next track
- `p`: Previous track
- `q`: Quit

---

## 📦 Building from Source

To build standalone executables (Linux/Windows):

1. **Clone and Install Dependencies:**
   ```bash
   git clone https://github.com/thiagofmendonca/cli-music-player.git
   cd cli-music-player
   pip install .
   pip install pyinstaller
   ```

2. **Build:**
   ```bash
   # Linux
   python build_exe.py
   
   # Windows (via GitHub Actions recommended)
   # Or manual: Ensure libmpv-2.dll is in the folder
   pyinstaller --noconfirm --onefile --name "FreeThulluPlayer" --add-data "musicplayer/assets;musicplayer/assets" --add-data "VERSION;." --icon "musicplayer/assets/frame1.png" --hidden-import "musicplayer" run_musicplayer.py
   ```

## 📜 License

GNU Affero General Public License v3.0 (AGPLv3)