MadhavMusicCLI 🎵
A Termux-first terminal music player — stream YouTube, manage playlists, view lyrics, all inside your terminal.
✨ Features
| Feature | Details |
|---|---|
| 🎵 YouTube Streaming | Search & stream via yt-dlp — no API key needed |
| 📱 Termux/Android | Touch-friendly, compact layout, auto-detects termux-media-player |
| 💾 Local Music | Scans MP3, FLAC, OGG, WAV, M4A, OPUS from your device |
| 📋 Queue & Playlists | Build queues, manage listening order |
| 🎤 Lyrics | Synced lyrics via syncedlyrics |
| 📜 History | Persistent listening history |
| 🎨 4 Themes | Default · Dracula · Nord · Gruvbox |
| ⌨️ Keyboard-first | Full keyboard & touch navigation |
| 🔌 Plugin System | Add providers via Python entry-points |
🚀 Installation
Termux (Android) — Recommended
# 1. Install Python + audio tools
pkg install python mpv
# 2. (Optional) Install Termux:API app from F-Droid for termux-media-player support
# 3. Install MadhavMusicCLI
pip install madhavmusiccli
# 4. Launch!
music
Linux / macOS / Windows
pip install madhavmusiccli
music
Note: On desktop, install
pygamefor audio:pip install madhavmusiccli pygame
🎮 Usage
music # launch with auto-detected music folder
music --library ~/Music # specify music directory
music --theme dracula # start with Dracula theme
music --version # show version
⌨️ Key Bindings
| Key | Action |
|---|---|
Ctrl+Q |
Quit |
Ctrl+P |
Play / Pause |
Ctrl+N |
Next track |
Ctrl+B |
Previous track |
Ctrl+S |
Search YouTube |
Ctrl+L |
Lyrics panel |
Ctrl+H |
History panel |
Ctrl+T |
Cycle theme |
Space |
Play / Pause |
← → |
Seek ±5 seconds |
↑ ↓ |
Navigate list |
Enter |
Play selected |
F1 |
Help |
🔌 Audio Backends (Auto-detected)
MadhavMusicCLI automatically picks the best backend:
| Priority | Backend | Platform |
|---|---|---|
| 1 | termux-media-player |
Termux/Android (Termux:API) |
| 2 | mpv |
All platforms (pkg install mpv) |
| 3 | pygame |
Desktop (Linux/macOS/Windows) |
| 4 | ffplay |
All platforms (ffmpeg) |
🔌 Plugin System
Add custom music providers via pyproject.toml entry-points:
[project.entry-points."madhavmusiccli.providers"]
myprovider = "mypkg.provider:MyProvider"
Subclass MusicProvider from madhavmusiccli.plugins.base.
🛠️ Development
git clone <your-repo>
cd CLI_music
pip install -e ".[dev]"
pytest -q
music
📦 Upload to PyPI
See PYPI_UPLOAD.md for full instructions.
upload_pypi.bat --test # TestPyPI first
upload_pypi.bat # real PyPI
📄 License
MIT — see LICENSE
1 maintainer
Metadata
1 maintainer
Release files for madhavmusiccli 1.0.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| madhavmusiccli-1.0.1.tar.gz | 19.5 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| madhavmusiccli-1.0.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 48.0 kB
Release files / madhavmusiccli-1.0.1.tar.gz
| Download URL | madhavmusiccli-1.0.1.tar.gz |
|---|---|
| Size | 19.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b8506a61f7f936fb31e6eb17b01fb9a46bc251474176fdaf290680e50abbff3d
|
|
BLAKE2b-256 checksum How to use checksums |
e652afb5353e8a616e5670151dcf45171185983f495be0454f8520bacf4b783b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.9
|
Release files / madhavmusiccli-1.0.1-py3-none-any.whl
| Download URL | madhavmusiccli-1.0.1-py3-none-any.whl |
|---|---|
| Size | 28.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
903fffa8ad911330a94b3f2321a9030aa541560f623891ba0dc6825a0b9e8907
|
|
BLAKE2b-256 checksum How to use checksums |
e82b2d8bfd33bef631fb7ed6e57c9bc24e77dfd4d440a8cc389bf3dd963a5ec0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.9
|
