Native Android client for Music Assistant, the open-source music server that integrates all your music sources and players.

MassDroid is a full-featured Music Assistant companion app built around music exploration and discovery. It gives you complete remote control over all your MA players while also learning from your listening habits to surface personalized recommendations, generating Smart Mix playlists and genre radio stations entirely on-device, enriching your library with metadata from Last.fm, and helping you discover similar artists across all your music providers. Lightweight at under 4 MB, with no ads, no trackers, and no cloud dependencies.

• Follow Me: Walk between rooms and your music follows. Detects which room you are in using nearby Bluetooth devices and automatically transfers playback to the right speaker.
• Smarter detection: Improved room matching with signal smoothing, better scoring, and faster response to movement.
• Per-room settings: Assign a player, playlist, volume level, and detection sensitivity to each room.
• Calibration wizard: Guided room calibration with quality feedback so you know when a room is ready.
• WiFi location awareness: Prevents false room detection when you are at a different location (e.g. office vs home).
• Time schedule: Set active days and hours so Follow Me only runs when you need it.
• Start Song Radio: Start a radio station based on the currently playing track, directly from the player menu.
• Save queue to playlist: Save your current queue as a new or existing playlist, with duplicate detection.
• Redesigned Players screen: Richer player cards with room badges and streamlined controls.
• Theme toggle: Switch between Dark, Light, and Auto themes.
• Fix DSTM staying disabled after failed Smart Mix playback
• Fix audio focus steal on app startup
• UI polish: splash screen, permission dialogs, redesigned Library controls, Player Settings available from Now Playing

• Similar Artists : Open any artist and see related artists from Last.fm, resolved across all your music providers. Genre validation ensures name collisions are filtered out. Results are cached locally for fast repeat visits.
• Last.fm Enrichment : Artist bios, album descriptions, genres, and release years are pulled from Last.fm when your music provider lacks the data. Everything is cached and reused across the app.
• Smart Mix : One tap, instant playlist. The on-device recommendation engine scores artists by recent listening, weighs genre affinity and time-of-day patterns, then builds a queue that fits your current mood. Tracks are interleaved so the same artist never plays back-to-back.
• Genre Radio : Pick a genre chip on the Discover screen and get a curated playlist. Artist selection is weighted by your play history to keep the mix personal and fresh.
• Smart Listening : Runs silently in the background. Every play, skip, like, and unlike trains a per-artist preference model that decays over 60 days, so the engine adapts as your taste evolves.
• Recommendation Insights : View your top artists, albums, and genres, plus manage blocked artists from Settings.

Walk between rooms and your music follows you. MassDroid uses BLE fingerprinting to detect which room you are in and automatically transfer playback or notify you to switch speakers.

• BLE Room Detection : Scans nearby Bluetooth devices (TVs, speakers, routers, IoT) and matches their signal pattern against calibrated room fingerprints using k-NN classification.
• Per-Room Configuration : Assign a Music Assistant player to each room, set a preferred playlist for auto-play, configure volume level, and toggle shuffle.
• Calibration Wizard : Walk through each room while the app collects 10 BLE scans, builds weighted fingerprints, and computes beacon profiles with quality assessment (Good/Weak).
• Time Schedule : Set active days and hours so proximity detection only runs when you want it.
• Auto-Transfer : Optionally transfer the queue automatically without notification when you change rooms.
• Screen-Off Detection : Works with screen off using PendingIntent BLE scans (OS-managed, no wake locks).
• Motion Gating : Sensor hub (significant motion + step detector) triggers scans only when you are actually moving, saving battery.

Requires Android 12+ with Bluetooth support.

To get reliable room detection, treat each room like a BLE fingerprinting problem, not just a “find the strongest beacon” problem.

• Calibrate inside the room, not near the doorway : Doorways blend adjacent-room fingerprints and make transitions less stable.
• Low signal can still be useful : A room can have weak BLE beacons and still be detectable if the overall RSSI pattern is consistent and different from nearby rooms.
• Common beacons are fine : The same TV, speaker, or router can appear in multiple rooms. What matters is that the RSSI pattern changes between rooms.
• Prefer stationary devices : TVs, speakers, consoles, routers, and smart home hubs are good anchors. Phones, watches, earbuds, and other personal devices are intentionally ignored.
• Private-address devices are not automatically bad : Some useful devices advertise with private BLE addresses. Use the inspection tools below to see what the app is actually using or ignoring.
• Use STRICT as the default : Use NORMAL only for genuinely weaker rooms that need a more forgiving BLE policy.
• Use Wi-Fi AP override only for separate locations : Stick to connected Wi-Fi AP is best for distinct places like Home, Office, or a detached space. It is not meant for nearby rooms on the same Wi-Fi.

MassDroid includes a few built-in tools to help you tune room detection without guessing:

• Calibration Data : Shows the saved room fingerprint, number of beacons, number of samples, and whether the room currently looks Good or Weak.
• Recalibrate : Rebuilds the room fingerprint from fresh BLE scans. Use this after moving devices or if a room keeps misdetecting.
• Inspect BLE : Runs a high-accuracy BLE scan and shows:
  • which devices Follow Me would use as room anchors right now
  • which stable devices are visible but not yet in the room profile
  • which devices are ignored because they are mobile or excluded by the current policy
• Detection Mode : STRICT requires a cleaner BLE match. NORMAL is a fallback for weaker rooms.
• Wi-Fi AP Override : Lets a room use the currently connected Wi-Fi access point instead of BLE anchors.

• If a room looks good in real life but still shows Weak, inspect whether it has a low-signal but structured fingerprint rather than simply “not enough strong beacons”.
• If two nearby rooms confuse each other, recalibrate both away from the doorway and compare their Inspect BLE results.
• If a remote location keeps false-triggering from home, store its Wi-Fi AP and enable Stick to connected Wi-Fi AP.
• If detection feels slow during movement, test with the screen off as well as screen on. The motion-driven scanning path is more aggressive during real room-to-room movement.

MassDroid includes a local recommendation engine that learns your listening habits and generates personalized content.

• BLL Temporal Decay : Recent plays weigh dramatically more than older ones, even if the old track was played many times.
• MMR Re-ranking : Prevents genre clustering by penalizing items too similar to already-selected ones.
• Genre Adjacency : Built from co-occurrence in your play history to discover genres you might enjoy.
• Exploration Budget : 70% top matches, 20% adjacent genres, 10% wildcard for serendipitous discovery.
• Last.fm Genre Fallback : When your music provider has no genre data, the app queries Last.fm artist tags (optional, cached locally for 30 days). Enriched genres are used across the entire app: recommendations, Smart Mix, genre radio, and library search.

All recommendation data stays on-device in a local Room database. Nothing is sent to external services.

• Discover Home : Dynamic recommendation sections with recently played, top picks, genre radio, and Smart Mix
• Library Browsing : Artists, Albums, Tracks, Playlists, Radio, and Browse with search, sort, grid/list views, and provider filtering. Genre-based search finds artists, albums, and tracks by genre when your library has been enriched with Last.fm tags.
• Artist & Album Detail : Rich detail views with descriptions, genres, similar artists, and now-playing indicators
• Player Controls : Play, pause, skip, seek, volume, shuffle, repeat across all MA players
• Now Playing : Full-screen player with album art, seek bar, favorite toggle, lyrics, and artist blocking
• Queue Management : View, drag-to-reorder, transfer between players, and manage the playback queue with action sheets
• Favorites : Mark artists, albums, tracks, and playlists as favorites, filter library by favorites
• Phone as Speaker : Sendspin protocol turns your phone into a Music Assistant player. Audio streams as Opus frames over WebSocket, decoded and played through your phone speaker or headphones.
• Follow Me : BLE fingerprint-based room detection with auto-transfer, per-room playlists, volume, and scheduling
• Artist Blocking : Block any artist from all recommendations, radio stations, and Smart Mix results
• Media Session : Android media notification with playback controls
• Player Settings : Rename players, set icons, configure crossfade and volume normalization
• Connection Diagnostics : Live latency graph with roundtrip stats and server version info
• mTLS Support : Client certificate authentication for secure remote access
• MiniPlayer : Persistent mini player bar across all screens

• Kotlin, Jetpack Compose, Material 3
• MVVM, Hilt, Coroutines/Flow
• OkHttp WebSocket, kotlinx.serialization
• Media3 / MediaSession
• Room (local recommendation database)

MassDroid communicates with your Music Assistant server over a persistent WebSocket connection. All player state, library data, queue changes, and favorites are synced in real time through server-pushed events. The app never polls; updates appear instantly as they happen on the server or from other clients.

When Sendspin is enabled, the phone registers as a Music Assistant player. Audio is streamed as Opus frames over a second WebSocket, decoded on-device, and played through the phone speaker or headphones.

• Android 8.0+ (API 26)
• A running Music Assistant server (v2.x)
• Bluetooth support for Follow Me (room detection)

All permissions are requested at runtime when needed. Proximity-related permissions (Bluetooth, Location, Activity Recognition) are only requested when you enable Follow Me.

Download the latest signed APK from GitHub Releases.

The most recent debug build is always available at the dev-latest release.

Debug and release builds can be installed side by side (different package IDs). Debug builds are not signed with the release key, so you cannot upgrade from debug to release or vice versa.

1. Open MassDroid and go to Settings
2. Enter your Music Assistant server URL (e.g. http://192.168.1.100:8095)
3. Log in with your Music Assistant credentials
4. Your players will appear on the Home screen

For remote access with mTLS, install a client certificate on your device and select it in Settings. The app will use it for both WebSocket and image connections.

Most of the discovery and enrichment features rely on the Last.fm API: similar artists, artist bios, album descriptions, genre tags, and release years. Data is only fetched when your music provider lacks the information, and all results are cached locally.

To set it up:

1. Create a free Last.fm API account and get your API key
2. Go to Settings in MassDroid and enter the key in the Last.fm API Key field

Without it the core player and library features work fine, but you will miss out on similar artists, bios, and genre enrichment for Smart Mix and Genre Radio.

This project is licensed under the MIT License. See LICENSE for details.