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

Clone and Install Dependencies:

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

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)

Metadata

Release files for cli-music-player-cthulhu 1.0.10

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cli-music-player-cthulhu 1.0.10
File	Size	Uploaded
cli_music_player_cthulhu-1.0.10.tar.gz	523.2 kB	Jan 20, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for cli-music-player-cthulhu 1.0.10
File	Interpreter	ABI	Platform	Reset
cli_music_player_cthulhu-1.0.10-py3-none-any.whl 525.3 kB Jan 20, 2026	Python 3	none	any	Details

Total release size: 1.0 MB

Release files / cli_music_player_cthulhu-1.0.10.tar.gz

Download URL	cli_music_player_cthulhu-1.0.10.tar.gz
Size	523.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`44f3715c06a931016656f72c3d060617ce13e54fad662ccaf543e9ff8e952a77`
BLAKE2b-256 checksum How to use checksums	`942cae5f06dd5bf0d3c6a5bf221fca8cd6bc42c67fb14dd45c544127a1c8b413`
Upload date	Jan 20, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.7`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/thiagofmendonca/cli-music-player
Publishing commit: github.com/thiagofmendonca/cli-music-player/tree/dc74c5995cd677df6dfcef6ae99f5399441ee6f2

Workflow

Publishing configuration: github.com/thiagofmendonca/cli-music-player/blob/dc74c5995cd677df6dfcef6ae99f5399441ee6f2/.github/workflows/python-publish.yml
Publishing logs: github.com/thiagofmendonca/cli-music-player/actions/runs/21175921932/attempts/1

Artifact

Subject: cli_music_player_cthulhu-1.0.10.tar.gz
SHA-256 checksum: 44f3715c06a931016656f72c3d060617ce13e54fad662ccaf543e9ff8e952a77 Verifying attestations

Release files / cli_music_player_cthulhu-1.0.10-py3-none-any.whl

Download URL	cli_music_player_cthulhu-1.0.10-py3-none-any.whl
Size	525.3 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`161bdf0db4978b5520d1c1c5b06d1330f0c8c4a01d40d70e3f00fb5322adef89`
BLAKE2b-256 checksum How to use checksums	`b4e4a3e512b3e871a30637679133d4f979557b801e3b75e01b64da1e3d0d5d7f`
Upload date	Jan 20, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.7`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/thiagofmendonca/cli-music-player
Publishing commit: github.com/thiagofmendonca/cli-music-player/tree/dc74c5995cd677df6dfcef6ae99f5399441ee6f2

Workflow

Publishing configuration: github.com/thiagofmendonca/cli-music-player/blob/dc74c5995cd677df6dfcef6ae99f5399441ee6f2/.github/workflows/python-publish.yml
Publishing logs: github.com/thiagofmendonca/cli-music-player/actions/runs/21175921932/attempts/1

Artifact

Subject: cli_music_player_cthulhu-1.0.10-py3-none-any.whl
SHA-256 checksum: 161bdf0db4978b5520d1c1c5b06d1330f0c8c4a01d40d70e3f00fb5322adef89 Verifying attestations