Metadata-Version: 2.4
Name: tsuki-music
Version: 1.0.0
Summary: 100% Free Terminal Music Player CLI for Windows — Powered by YouTube Music, Pygame & Rich
Author-email: Tsukiziro <tsukiziro@users.noreply.github.com>
License: MIT
Project-URL: Homepage, https://github.com/tsukiziro/tsuki-music
Project-URL: Documentation, https://github.com/tsukiziro/tsuki-music
Project-URL: Instagram, https://instagram.com/tsukiziro
Project-URL: Telegram, https://t.me/Tsukiziro
Keywords: music,terminal,cli,player,youtube-music,audio,windows,rich,tsuki-music,tsukiziro
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Sound/Audio :: Players
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: yt-dlp>=2024.3.10
Requires-Dist: pygame>=2.5.0
Requires-Dist: pywin32>=306; sys_platform == "win32"
Requires-Dist: ytmusicapi>=1.7.0
Requires-Dist: rich>=13.7.0
Requires-Dist: typer>=0.9.0
Requires-Dist: requests>=2.31.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"

# 🎵 Tsuki Free Music CLI

**Tsuki Free Music CLI** is a 100% free, interactive terminal music player built for Windows (CMD, PowerShell, Windows Terminal) using **Python**, **YouTube Music (`yt-dlp`)**, **Pygame/WMPlayer Audio Engine**, and **Rich**.

> [!NOTE]
> **No Spotify Premium, No Developer API Keys, and No Accounts Required!**
> Stream and play full high-quality audio directly inside your terminal window for free.

---

## 🌟 Key Features

1. **📻 Infinite YouTube Radio Autoplay**: When your search list or queue ends, the player automatically fetches related recommendation songs from YouTube and keeps playing infinitely like YouTube Music Radio!
2. **✨ Auto Clean & Clear Terminal UI**: Automatically clears the terminal screen (`cls`) when searching, playing, or viewing playlists to keep your CLI UI crisp, uncluttered, and elegant!
3. **📁 Local JSON Playlists (Max 2 Limit)**: Create up to 2 custom local playlists stored in `%APPDATA%\tsuki-music\library.json`.
4. **⌨ Keyboard Arrow Controls**: In the live `nowplaying` screen, use arrow keys to control music instantly:
   - `[→]` **Right Arrow**: Skip to Next Song
   - `[←]` **Left Arrow**: Skip to Previous Song
   - `[↑]` **Up Arrow**: Increase Volume
   - `[↓]` **Down Arrow**: Decrease Volume
   - `[Space / P]`: Pause / Resume Audio
   - `[Q]`: Exit Live Screen

---

## ⚡ Superfast Command Shortcuts

Inside `tsuki`:

| Shortcut | Full Command | Description | Example |
| :--- | :--- | :--- | :--- |
| `s <query>` | `search <query>` | Search YouTube Music | `s After Dark` |
| `↑` / `↓` + **ENTER** | Interactive Track Selection | Highlight & play song directly with arrow keys | Press `↑` / `↓` then **ENTER** |
| `<number>` | `play <number>` | Play song number directly | `10` or `1` |
| `np` | `nowplaying` | Open live Now Playing screen (with `[→]` `[←]` `[↑]` `[↓]` arrow controls) | `np` |
| `pcr <name>` | `playlist create <name>` | Create new custom playlist (Max 2 allowed) | `pcr "Chill Mix"` |
| `pl` | `playlists` | List custom playlists | `pl` |
| `pl 1` / `pl 2` | `playlist view <1|2>` | View songs in playlist #1 or #2 by serial number | `pl 1` |
| `pp 1` / `pp 2` | `playlist play <1|2>` | Play playlist #1 or #2 by serial number with Infinite Autoplay | `pp 1` |
| `padd 1 3` | `playlist add <1|2> <num>` | Add song #3 from search to playlist #1 | `padd 1 3` |
| `v<0-100>` | `volume <0-100>` | Change volume percentage | `v50` or `v100` |

---

## 🚀 Quickstart Guide

### Install CLI & Dependencies
```powershell
pip install -e .
```

### Launch Interactive Mode
```powershell
tsuki
```

---

## 🧪 Run Unit Tests

```powershell
pytest tests/test_music.py
```
