Watermelon Documentation
Welcome to the official Watermelon documentation! Watermelon is an open-source Android music streaming platform built with modern tools — no ads, no subscriptions, just music.
What is Watermelon?
Watermelon is a fully open-source music streaming app for Android that lets you search, stream, and download music from YouTube Music seamlessly. It features a clean Material Design 3 interface, offline downloads, smart playlists, and self-hosted server capabilities.
Key highlights:
- Free & Open Source — MIT licensed, community-driven
- Ad-free — No interruptions, ever
- Smart Search — Find songs, artists, albums, and playlists instantly
- Offline Downloads — Save tracks for offline listening
- Self-hostable — Run your own server on Render or any Node.js host
- Premium Features — Cashfree-powered subscriptions for advanced features
Quick Links
- API Reference — Explore the REST API endpoints
- Self-Hosting Guide — Deploy your own Watermelon server
- FAQ — Common questions answered
- Changelog — See what’s new in each release
GitHub Repository
Find the source code, report issues, and contribute on GitHub: watermelon-music/Watermelon-apk
Tech Stack
Watermelon is built with modern tooling across three layers:
Android App
- Kotlin — 100% Kotlin codebase
- Jetpack Compose — Declarative UI with Material Design 3 and Premium Aesthetic Overhaul
- Coroutines & Flow — Async data streams
- Room Database — Local caching for offline mode
- ExoPlayer — Smooth audio playback with seeking
Web Backend (API)
- Node.js + Express — REST API server
- yt-dlp — Extracts audio from YouTube Music
- Supabase — PostgreSQL database & authentication
- Cashfree SDK — Secure Backend-driven Web Checkout for subscriptions
- Telegram Bot API — Remote bot commands
Website & Docs
- Next.js 15 — React framework with App Router
- Nextra — Documentation site with full-text search
- Tailwind CSS — Utility-first styling
- Framer Motion — Smooth animations
- shadcn/ui — Accessible component primitives
Features in Detail
Smart Search
Search across songs, artists, albums, and playlists with instant results powered by yt-dlp.
Offline Downloads
Download tracks directly to your device for offline listening. Files are saved locally and played via ExoPlayer.
Smart Playlists
Create and manage playlists with drag-and-drop reordering. Playlists sync to your self-hosted Supabase database.
Radio Mode
Discover new music with auto-generated radio stations based on your listening history.
Telegram Bot
Control playback, search songs, and manage your queue via Telegram — perfect for sharing music with friends.
Premium Subscriptions
Unlock advanced features like a fully ad-free experience, exclusive UI themes, and unlimited skipping with Cashfree-powered subscriptions.
Community
Join the growing Watermelon community:
- GitHub Discussions — github.com/watermelon-music/Watermelon-apk/discussions
- GitHub Issues — Report bugs and request features
- Pull Requests — Contributions are always welcome
License
Watermelon is released under the MIT License. You are free to use, modify, and distribute the software as long as the original license and copyright notice are included.
Contributors
Watermelon is primarily built and maintained by a small passionate team:
| Contributor | Role | What they built |
|---|---|---|
| Satyam (@SatyamPote) | Creator & Lead Developer | Entire Android app, Express API server, Supabase backend, Cashfree payments integration, Telegram bot, and this website |
| GitHub Actions | CI/CD Automation | Automated version bumps, release builds, and deployment pipelines |
| Watermelon Dev | Android Contributor | Premium UI Overhaul, auth fixes, adaptive layouts, and release management |
Want your name here? Contribute on GitHub — we welcome PRs, bug reports, and feature requests!
Roadmap
Check the Changelog for the latest features. Up next:
- iOS support (Swift + SwiftUI)
- Desktop app (Electron/Tauri)
- Web player (PWA)
- Collaborative playlists
- Lyrics integration
- Equalizer presets
Credits
Watermelon is built on the shoulders of incredible open-source projects:
| Project | What it powers | Link |
|---|---|---|
| Next.js | React framework & static generation | nextjs.org |
| React | UI components & state management | react.dev |
| TypeScript | Type-safe codebase | typescriptlang.org |
| Tailwind CSS | Utility-first styling | tailwindcss.com |
| Framer Motion | Animations & transitions | framer.com/motion |
| Nextra | Documentation site generator | nextra.site |
| shadcn/ui | Accessible component primitives | ui.shadcn.com |
| Lucide React | Beautiful open-source icons | lucide.dev |
⭐ If you find these projects useful, please give them a star on GitHub. The open-source community thrives on your support.