https://github.com/sfortis/massdroid

MassDroid is a native Android companion app for Music Assistant, offering seamless integration with Android's native media controls. Manage your music from the lock screen, notification shade, Bluetooth headphones, car stereo, or Wear OS watch.
https://github.com/sfortis/massdroid

android client musicassistant pwa

Last synced: 4 months ago
JSON representation

MassDroid is a native Android companion app for Music Assistant, offering seamless integration with Android's native media controls. Manage your music from the lock screen, notification shade, Bluetooth headphones, car stereo, or Wear OS watch.

• Host: GitHub
• URL: https://github.com/sfortis/massdroid
• Owner: sfortis
• License: gpl-3.0
• Created: 2026-01-17T06:57:22.000Z (5 months ago)
• Default Branch: master
• Last Pushed: 2026-01-20T14:52:27.000Z (5 months ago)
• Last Synced: 2026-01-22T22:50:25.602Z (5 months ago)
• Topics: android, client, musicassistant, pwa
• Language: Kotlin
• Homepage:
• Size: 3.41 MB
• Stars: 15
• Watchers: 0
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          


  





  

    

  



# MassDroid - Android Companion App for Music Assistant

MassDroid is a native Android application that wraps the [Music Assistant](https://music-assistant.io/) 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.

## Why MassDroid?

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.

## 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.

## Screenshots

| Main UI | Sidebar | Settings |

|:---:|:---:|:---:|

|  |  |  |

## Architecture

MassDroid hosts the Music Assistant PWA inside a WebView and injects a JavaScript bridge layer to connect it with Android's native APIs.



  



### Components

| 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](https://github.com/music-assistant/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. |

## Installation

### Option 1: Download APK (Recommended)

1. Download the latest APK from the [Releases](https://github.com/sfortis/massdroid/releases) page.

2. Install on your Android device (enable "Install from unknown sources" if needed).

3. On first launch, enter your Music Assistant server URL.

### Option 2: Build from Source

```bash

git clone https://github.com/sfortis/massdroid.git

cd massdroid

./gradlew assembleRelease

```

The APK will be at `app/build/outputs/apk/release/app-release.apk`

## Requirements

- Android 8.0 (Oreo) or higher

- A running [Music Assistant](https://music-assistant.io/) server

## Configuration

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 |

## Permissions

| 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 |

## Troubleshooting

**Certificate issues after renewal?**

- Go to Settings > Advanced > Clear Certificate & Cache

- Restart the app and select the new certificate when prompted

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

This project is licensed under the GNU General Public License v3.0 - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- [Music Assistant](https://music-assistant.io/) – The amazing self-hosted music server

- [SendSpin](https://github.com/music-assistant/sendspin) – Audio streaming protocol used by Music Assistant

## Support

If you encounter any issues, please [open an issue](https://github.com/sfortis/massdroid/issues) on GitHub.