Crate’s Music Assistant integration does two things that work together: it syncs your MA library immediately after every download completes, and it gives you a way to mark a track as bad directly from the Music Assistant app without ever touching the Crate UI. When you drop a track into a dedicated reject playlist inside MA, Crate detects the change, deletes the bad file, blacklists the source, and automatically re-queues the track so a better copy gets downloaded. Like the Navidrome integration, this is entirely optional — Crate functions fully without it.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/TheOutdoorProgrammer/crate/llms.txt
Use this file to discover all available pages before exploring further.
Enabling or changing the Music Assistant connection requires a Crate
restart to take effect. The persistent WebSocket connection cannot be
hot-started without running an idle background process when MA is
unconfigured — so connection settings are applied at startup. You can still
edit the values in the Settings UI at any time; they will be picked up on the
next restart.
What the integration adds
Library sync
After each download is organized, Crate sends a
music/sync command to MA
over the live WebSocket connection. MA’s filesystem sync is checksum-based
and incremental, so only the new file is processed.Mark bad from the app
Drop any locally-owned track into the reject playlist in the MA app. Crate’s
reject watcher detects the playlist change via a pushed
media_item_updated
event and handles everything automatically.The reject workflow
The reject workflow is event-driven: MA pushes amedia_item_updated event to
all authenticated WebSocket clients whenever a library item changes, including
when a track is added to a playlist. Crate listens for that event and
reconciles the reject playlist without polling.
Drop the track into the reject playlist
In the Music Assistant app, add the track you want to replace to your
configured reject playlist (default name: Crate Reject). This can be
done from any MA client — phone, tablet, or desktop.
Crate detects the change
MA pushes a
media_item_updated event for the playlist. Crate’s reject
watcher is subscribed to all events on the shared WebSocket connection and
recognises the event by the playlist’s URI (library://playlist/<id>).Crate maps the track to a library file
The watcher fetches the playlist’s current tracks and checks each one’s
filesystem provider mapping. That mapping contains the library-relative
path — the same path Crate stores in its database — so Crate can identify
exactly which track record to act on. Tracks from streaming providers (not
local files) are left untouched in the playlist.Reject, blacklist, and re-queue
For each matched track, Crate runs the shared reject logic:
- Deletes the file from the library
- Blacklists the source user (permanent, per-file) so they are never retried
- Sets the track status back to
wanted, re-queuing it for auto-download
Setup
Open the Integrations settings
In the Crate UI, navigate to Settings → Integrations → Music Assistant.
Enter your Music Assistant URL
Paste the base URL of your MA server — for example,
http://music-assistant:8095 or https://ma.example.com. Crate
automatically converts http:// → ws:// and https:// → wss:// and
appends /ws to build the WebSocket endpoint. You do not need to enter a
WebSocket URL.Enter your Music Assistant token
Provide a long-lived access token from your MA instance. This is used to
authenticate the WebSocket connection on every connect and reconnect.
Set the reject playlist name (optional)
Enter the name of the playlist Crate should watch for tracks to reject. The
default is Crate Reject. If the playlist does not exist in MA, Crate
creates it automatically when it first connects.
Configuration reference
Settings keys
Settings keys
| Setting key | Default | Description |
|---|---|---|
music_assistant_url | (none) | Base URL of your MA server (http:// or https://) |
music_assistant_token | (none) | Long-lived access token for WebSocket authentication |
music_assistant_reject_playlist | Crate Reject | Name of the playlist Crate watches for rejections |
music_assistant_url and music_assistant_token must be set for the
integration to activate. With either field blank, no WebSocket connection is
opened and no background goroutine runs.Connection and reconnect behaviour
Connection and reconnect behaviour
Crate maintains a single persistent WebSocket connection to MA, shared by
the sync notifier and the reject watcher. If the connection drops, Crate
reconnects with exponential backoff starting at 1 second, capping at 30
seconds. A session that lasts more than 60 seconds resets the backoff to 1
second on the next disconnect.On each reconnect, Crate re-authenticates and then re-resolves the reject
playlist, reconciling any tracks that were added to the playlist while
disconnected.
What happens to streaming tracks in the reject playlist
What happens to streaming tracks in the reject playlist
Only tracks with a
filesystem provider mapping — local library files — are
processed by the reject watcher. Tracks from streaming providers (Spotify,
Tidal, etc.) that end up in the reject playlist are left in place and logged
as unactionable. They will not be deleted or re-queued.Design note
Polling the reject playlist on a timer was considered and rejected in favour of the event-driven approach. MA pushes amedia_item_updated event to every
authenticated WebSocket client whenever a playlist changes, so there is no need
to poll — doing so would waste cycles for no gain. The watcher registers an
event handler that filters for its specific playlist URI and signals a
reconcile only when that playlist changes. See
ADR-0006
for the full design rationale.