MusicAssistantMate · Support
How can we help?
Connect your server, choose a room and control your music. Help for iPhone, Mac, Apple TV and Apple Watch.
Direct contact
Tell us your device model, operating system, app version and Music Assistant version. Include the sign-in method, exact error message and steps that lead to the problem. Remove private details from screenshots. Never send passwords, access tokens or sign-in links containing a token.
support@mate.buildGet started
You need a reachable Music Assistant server, a user account and music services and players set up on that server. MusicAssistantMate provides the remote control; it does not supply music, subscriptions or a server.
Supported platforms: iPhone with iOS 17 or later, Mac with macOS 14 or later, Apple TV with tvOS 17 or later, and Apple Watch with watchOS 10 or later. Apple Watch also needs the iPhone app.
iPhone and Mac
- Enter the full address of your Music Assistant server, including protocol, port and any path your setup requires.
- Choose Sign in with Home Assistant if Home Assistant is configured as a sign-in provider on your server.
- Alternatively, open More sign-in options and use a direct Music Assistant account or a personal Music Assistant access token. These fields are not for your Spotify or other music-service password.
- Allow local network access when requested. After signing in, select an available room and a track, album or playlist.
Apple TV
Enter the server address and choose Sign in on iPhone. Keep an iPhone or iPad nearby and complete the system sign-in. Apple TV receives its own Music Assistant session. Direct account and token sign-in are available under More sign-in options.
Try the preview
Take a look around opens sample content without a server. The rooms and library in this preview are simulated.
Frequently asked questions
My server is not reachable
Check that the server is running and that you can open its web interface from the same network. Check local network permission, the full server address and any VPN or reverse proxy. Use the final server address: native API requests do not follow redirects. Publicly accessible server addresses require HTTPS with a valid certificate. Local HTTP connections are unencrypted.
Select Reconnect to retry. A temporary network outage does not remove your saved sign-in. An expired or revoked session requires you to sign in again.
Home Assistant sign-in does not work
Check that Home Assistant sign-in is enabled on the Music Assistant server and that the server’s normal sign-in page works. On Apple TV, complete the system prompt on the nearby iPhone or iPad. You can also use a direct Music Assistant account or personal token. Correct server certificate problems at the server.
Music services, albums or rooms are missing
Check the same user account in the Music Assistant web interface. The server decides which services and players the account can access. A service must be connected, available and shared with the account. The app does not import sign-ins from other installed music apps. Use Load more for additional library items.
How do I connect Spotify or another music service?
Set up the service in Music Assistant. On iPhone and Mac, Profile → Connect & manage music services opens the server’s service management. Administrator permission may be required. For Apple TV, use the server interface on an iPhone or computer. Music-service credentials stay with the server and the relevant provider.
Why is there no sound on my iPhone, Mac or Apple TV?
MusicAssistantMate currently controls existing Music Assistant players. It does not play audio directly on iPhone, Mac, Apple TV or Apple Watch. Select an available player under Rooms, check its volume and test playback in Music Assistant.
Can I play music in multiple rooms?
Under Rooms, choose Connect speakers and select compatible devices. Grouping depends on the players and capabilities reported by Music Assistant. Set up permanent groups and resolve compatibility issues on the server.
Can I connect away from home?
Your device needs a network route to your Music Assistant server, for example through a VPN or a securely configured HTTPS endpoint. The app does not provide a remote-access relay. Music Assistant’s WebRTC remote access is not currently implemented.
My Apple Watch cannot control playback
Open the iPhone app, sign in and check that it can reach the server. Then tap Refresh in the Watch app. Keep the companion connection available and both apps up to date. The Watch controls playback through the iPhone; it does not connect directly to the server. A last-known track may remain visible while control is unavailable. Commands are not queued for later execution.
Why do search results differ between service accounts?
Search depends on each service, account permissions and your Music Assistant version. Multiple accounts of the same service may have different catalogue-search coverage. Check the service section and any notices in the app; library matches and catalogue matches are not always identical.
Disconnect or remove an account
iPhone and Mac: open Profile → Saved accounts, use the trash button beside the account and confirm to remove its local credentials. This does not delete the account on your server or revoke the server session.
Disconnect and Sign out only disconnect the current session in the app; saved credentials remain. Apple TV currently has no button for removing a saved account locally. Revoke the session or token in Music Assistant to prevent further access; that does not erase the local Keychain entry.
Uninstalling the app alone does not guarantee that Keychain entries are removed. For details, see the privacy policy.