Metadata-Version: 2.4
Name: watermelon-music
Version: 0.2.0
Summary: A Python terminal music player and SDK for the Watermelon music platform
Author-email: SatyamPote <satyampote@example.com>
License: MIT
Project-URL: Homepage, https://watermelon-web.onrender.com
Project-URL: Documentation, https://watermelon-web.onrender.com/docs/
Project-URL: Repository, https://github.com/watermelon-music/Watermelon-lib
Project-URL: Issues, https://github.com/watermelon-music/Watermelon-lib/issues
Keywords: music,player,terminal,youtube,streaming,cli
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
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 :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Dynamic: license-file

# 🍉 Watermelon Python Library

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

A Python terminal music player + SDK for the [Watermelon](https://watermelon-web.onrender.com) music platform. Free, open-source, no ads.

---

## Features

- 🔍 **Real-time search** — results update letter by letter as you type
- ⬇️ **Smart cache loop** — downloads one song, plays it, auto-deletes when next starts
- 🎵 **Background playback** — minimise the terminal, music keeps playing
- 🤖 **AI recommendations** — Gemini 2.5 Flash picks your next song automatically
- 📻 **Radio** — stream internet radio stations
- 📚 **History** — full SQLite listening history, persisted across sessions
- 🛠️ **SDK** — use as a pure Python library in your own code

---

## Install

```bash
pip install watermelon-music
```

**Requirements:**
- Python 3.9+
- `ffplay` (part of [ffmpeg](https://ffmpeg.org)) for audio playback:
  ```
  Windows : winget install ffmpeg
  macOS   : brew install ffmpeg
  Linux   : sudo apt install ffmpeg
  ```

---

## Quick Start

### Terminal Player

```bash
watermelon
```

### SDK Usage

```python
from watermelon import WatermelonClient, LocalDB

client = WatermelonClient()

# Search
songs = client.search.songs("Arijit Singh")
print(songs[0])  # Kesariya — Arijit Singh

# Get metadata
song = client.songs.get("dQw4w9WgXcQ")
print(song.title, song.duration_str)

# Stream URL (for your own player)
url = client.songs.stream_url("dQw4w9WgXcQ")

# Download to file
path = client.songs.download("dQw4w9WgXcQ", output_path="./song.mp3")

# Search artists / albums / playlists
artists = client.search.artists("AR Rahman")
albums  = client.search.albums("Dilwale Dulhania")

# Radio
stations = client.radio.browse()
hindi    = client.radio.search("hindi")

# AI Recommendations (Gemini 2.5 Flash)
recs = client.ai.recommendations(title="Kesariya", artist="Arijit Singh")
for song in recs:
    print(song)

# Global stats
stats = client.stats.get()
print(stats.total_streams)

# Local database
db = LocalDB()
db.history.add(songs[0], source="search")
history = db.history.recent(limit=20)
top_artists = db.activity.top_artists(limit=10)
```

---

## Custom Server (Self-Hosted)

```python
client = WatermelonClient(base_url="http://your-server.com:3000")
```

Or set it permanently in `~/.watermelon/config.json`:

```json
{ "base_url": "http://your-server.com:3000" }
```

---

## Terminal UI Controls

| Screen | Key | Action |
|---|---|---|
| Menu | ^S | Search |
| Menu | ^L | Library |
| Menu | ^R | Radio |
| Menu | / | Settings (lyrics language) |
| Menu | ^Q / Ctrl+C | Quit |
| Menu | ↑ / ↓ + Enter | Navigate & select |
| Any screen | ^S / ^L / ^R / / | Jump straight to Search / Library / Radio / Settings (music keeps playing) |
| Search | Type | Update results live |
| Search | ↑ / ↓ | Navigate results |
| Search | Enter | Play selected song |
| Search | ^R | Get AI recommendations |
| Search | ^B / ESC | Back to menu |
| Player | ^N | Next song |
| Player | ^P | Pause / Resume |
| Player | ^U / ^D | Volume up / down |
| Player | ^Y | Lyrics |
| Player | / | Settings |
| Player | ^B / ESC | Back to menu |
| Radio | Type | Search stations |
| Radio | Enter | Stream station |
| Radio | ^B / ESC | Back |
| Library | ↑ / ↓ + Enter | Navigate & replay |
| Library | ^R | Refresh history |
| Lyrics | ↑ / ↓ | Scroll lyrics |
| Lyrics | ^Y / ^B | Close |

---

## Architecture

```
~/.watermelon/
├── watermelon.db    ← SQLite (history, activity, cache, session)
├── cache/           ← One .mp3 at a time
└── config.json      ← base_url, volume, theme
```

```
WatermelonClient
├── .search   → SearchAPI   (/search/songs, /artists, /albums, /playlists)
├── .songs    → SongAPI     (/song/:id, /stream/:id, /download/:id)
├── .radio    → RadioAPI    (/radio/stations, /radio/search)
├── .ai       → AIAPI       (/api/recommendations)
├── .stats    → StatsAPI    (/stats)
└── .auth     → AuthAPI     (/auth/delete-user)

LocalDB
├── .history  → HistoryRepo   (songs_history table)
├── .activity → ActivityRepo  (user_activity table)
├── .cache    → CacheRepo     (cached_songs table)
└── .session  → SessionRepo   (session_state table)
```

---

## Development

```bash
git clone https://github.com/watermelon-music/Watermelon-lib
cd Watermelon-lib
pip install -e ".[dev]"

# Run the player
watermelon

# Run tests
pytest
```

---

## License

MIT © [SatyamPote](https://github.com/SatyamPote) / [watermelon-music](https://github.com/watermelon-music)
