cli-music-player-cthulhu 1.0.10

A lightweight terminal music player with mpv engine and auto-setup

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

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:

# 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:

   git clone https://github.com/thiagofmendonca/cli-music-player.git
   cd cli-music-player
   pip install .
   pip install pyinstaller
   

2. Build:

   # 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)