MassDroid is a native Android application that wraps the Music Assistant web interface, providing seamless integration with Android's native media controls. Control your music from the lock screen, notification shade, Bluetooth headphones, car stereo, or Wear OS watch.
You can access Music Assistant from any browser, but a native Android app offers real advantages:
| Feature | Browser | MassDroid |
|---|---|---|
| Basic playback & UI | Yes | Yes |
| Lock screen with album art | Yes | Yes |
| Pause from lock screen | Yes | Yes |
| Next/Previous/Seek from lock screen | No | Yes |
| Bluetooth hardware buttons | Unreliable | Yes |
| Car stereo controls | Unreliable | Yes |
| Background playback | Unreliable (Android may kill browser) | Reliable (foreground service) |
| Auto-play on Bluetooth connect | No | Yes |
| Auto-resume after network change | No | Yes |
| Wear OS support | No | Yes |
| Dedicated app icon | Bookmark only | Native app |
| Full-screen UI | Browser chrome visible | Clean, no distractions |
In short: Browser works for basic use. MassDroid adds reliable background playback, full media controls, and smart automation features.
- Full Music Assistant UI – Access the complete Music Assistant web interface in a native Android shell.
- Native Media Controls – Control playback from lock screen, notification shade, Bluetooth devices, and Wear OS.
- Album Artwork – Beautiful album art displayed in notifications and on lock screen.
- Seekable Progress Bar – Track progress with native seek support.
- Auto-play on Bluetooth – Automatically resume playback when connecting to Bluetooth audio devices (with smart reload for stale connections).
- Auto-resume on Network Change – Seamless playback continuation when switching between WiFi and mobile data.
- Page Zoom – Adjustable zoom level (50%-150%) for better content fit on any screen.
- Battery Optimization – WebView timers pause when not playing to save battery in background.
- Dark Mode Support – Follows system theme automatically.
- Color Accent Customization – Choose your preferred accent color for the UI.
- mTLS Support – Client certificate authentication for secure server connections.
- Configurable Server URL – Connect to any Music Assistant server.
- Check for Updates – Automatic update checking with in-app download and install.
| Main UI | Sidebar | Settings |
|---|---|---|
 |
 |
 |
MassDroid hosts the Music Assistant PWA inside a WebView and injects a JavaScript bridge layer to connect it with Android's native APIs.
| Component | Role |
|---|---|
| MA Server | Music Assistant backend, communicates via two WebSocket connections: API (commands, player events) and SendSpin (audio streaming). |
| WebView | Runs the full PWA UI. The built-in SendSpin client handles audio playback to the phone speaker. |
| JS Bridge | Five injected scripts that intercept navigator.mediaSession, hook WebSocket connections, manage API commands, and track player selection — forwarding state to Android via @JavascriptInterface. |
| MediaSession | Exposes playback controls to the lock screen, notification shade, Bluetooth/car stereo, and Wear OS. Includes a seekable progress bar. |
| AudioService | Foreground service that keeps playback alive in the background and displays a MediaStyle notification with album artwork. |
| Automation | BluetoothAutoPlayReceiver auto-starts/stops on BT connect/disconnect. NetworkChangeMonitor auto-resumes after WiFi/LTE switches. Both scoped to phone speaker only — external players (Sonos, Chromecast, etc.) are never affected. |
- Download the latest APK from the Releases page.
- Install on your Android device (enable "Install from unknown sources" if needed).
- On first launch, enter your Music Assistant server URL.
git clone https://github.com/sfortis/massdroid.git
cd massdroid
./gradlew assembleReleaseThe APK will be at app/build/outputs/apk/release/app-release.apk
- Android 8.0 (Oreo) or higher
- A running Music Assistant server
Access settings from the navigation drawer (hamburger menu):
| Setting | Description |
|---|---|
| Music Assistant URL | Your server URL (e.g., https://mass.example.com) |
| Keep Screen On | Prevent screen timeout while app is open |
| Auto-play on Bluetooth | Resume playback when Bluetooth audio connects |
| Auto-resume on Network | Resume after WiFi/mobile data switch |
| Page Zoom | Adjust page zoom level (50%-150%) |
| Accent Color | Customize the app's accent color |
| Clear Certificate & Cache | Reset saved client certificate and WebView cache |
| Check for Updates | Manually check for new versions on GitHub |
| Permission | Purpose |
|---|---|
INTERNET |
Connect to your Music Assistant server |
ACCESS_NETWORK_STATE |
Detect network changes for auto-resume |
WAKE_LOCK |
Keep audio streaming while screen is off |
BLUETOOTH_CONNECT |
Detect Bluetooth audio connections |
FOREGROUND_SERVICE |
Keep playing music in background |
FOREGROUND_SERVICE_MEDIA_PLAYBACK |
Media playback foreground service type (Android 14+) |
POST_NOTIFICATIONS |
Show media notification with controls |
REQUEST_IGNORE_BATTERY_OPTIMIZATIONS |
Prevent OS from killing background playback |
REQUEST_INSTALL_PACKAGES |
Install app updates from GitHub |
Certificate issues after renewal?
- Go to Settings > Advanced > Clear Certificate & Cache
- Restart the app and select the new certificate when prompted
Contributions are welcome! Please feel free to submit a Pull Request.
This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.
- Music Assistant – The amazing self-hosted music server
- SendSpin – Audio streaming protocol used by Music Assistant
If you encounter any issues, please open an issue on GitHub.