🍉 Watermelon Python Library

A Python terminal music player + SDK for the Watermelon 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

pip install watermelon-music

Requirements:

• Python 3.9+
• ffplay (part of ffmpeg) for audio playback:

  Windows : winget install ffmpeg
  macOS   : brew install ffmpeg
  Linux   : sudo apt install ffmpeg
  

Quick Start

Terminal Player

watermelon

SDK Usage

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)

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

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

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

Terminal UI Controls

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

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 / watermelon-music