Metadata-Version: 2.4
Name: madhavmusiccli
Version: 0.1.0
Summary: A Termux-first terminal music player — streams YouTube via yt-dlp, touch-friendly TUI
Project-URL: Bug Tracker, https://pypi.org/project/madhavmusiccli/
Project-URL: Changelog, https://pypi.org/project/madhavmusiccli/#history
License: MIT
License-File: LICENSE
Keywords: android,cli,madhav,music,player,terminal,termux,textual,tui,youtube
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Sound/Audio :: Players
Classifier: Topic :: Terminals
Requires-Python: >=3.9
Requires-Dist: aiofiles>=23.0.0
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: mutagen>=1.47.0
Requires-Dist: platformdirs>=4.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: rich>=13.0.0
Requires-Dist: syncedlyrics>=0.7.0
Requires-Dist: textual>=0.47.0
Requires-Dist: typer>=0.9.0
Requires-Dist: yt-dlp>=2024.1.0
Provides-Extra: dev
Requires-Dist: black>=23.0; extra == 'dev'
Requires-Dist: flake8>=6.0; extra == 'dev'
Requires-Dist: isort>=5.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Provides-Extra: pygame
Requires-Dist: pygame>=2.5.0; extra == 'pygame'
Description-Content-Type: text/markdown

# MadhavMusicCLI 🎵

> A Termux-first terminal music player — stream YouTube, manage playlists, view lyrics, all inside your terminal.

[![PyPI](https://img.shields.io/pypi/v/madhavmusiccli)](https://pypi.org/project/madhavmusiccli/)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

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

```bash
# 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

```bash
pip install madhavmusiccli
music
```

> **Note**: On desktop, install `pygame` for audio:
> ```bash
> pip install madhavmusiccli pygame
> ```

## 🎮 Usage

```bash
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:

```toml
[project.entry-points."madhavmusiccli.providers"]
myprovider = "mypkg.provider:MyProvider"
```

Subclass `MusicProvider` from `madhavmusiccli.plugins.base`.

## 🛠️ Development

```bash
git clone <your-repo>
cd CLI_music
pip install -e ".[dev]"
pytest -q
music
```

## 📦 Upload to PyPI

See [PYPI_UPLOAD.md](PYPI_UPLOAD.md) for full instructions.

```bat
upload_pypi.bat --test   # TestPyPI first
upload_pypi.bat          # real PyPI
```

## 📄 License

MIT — see [LICENSE](LICENSE)
