Skip to main content

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.

Crate is a self-hosted music manager built around a simple idea: you tell it which artists you care about, and it takes care of the rest. It queries pluggable metadata providers — MusicBrainz, Deezer, or your own custom gRPC provider — to build a full picture of an artist’s discography, then works with slskd (a Soulseek client) to search for, score, download, organize, and tag every track automatically. The result is a locally-owned, well-tagged music library that grows on its own as you discover new artists.

​
How It Works

Crate’s pipeline moves music from discovery to your library in four stages. Metadata providers supply artist and album data over gRPC. Crate uses that data to decide what to look for, then hands search requests to slskd. When slskd returns results, Crate scores each candidate using quality tiers, artist-name matching, upload-slot availability, and queue-length decay — and downloads the best match. After download, Crate moves the file into your library folder using a configurable naming template and writes ID3v2, Vorbis, or RIFF tags depending on format. 
Metadata Providers          slskd (Soulseek)         Your Library
─────────────────           ────────────────         ────────────
MusicBrainz (gRPC)  ──┐                              
Deezer (gRPC)       ──┼──▶  Crate  ──▶  Score  ──▶  Organize + Tag
Custom provider     ──┘      ▲
                             │
                        SQLite state
                      (artists, albums,
                        tracks, queue)

​
Key Concepts

Crate models your music library as a hierarchy of artists, albums, and tracks. Each level carries a status that drives what Crate does next.

Artists

An artist pulled from a provider. Set to watched (full discography tracked), partial (some albums watched), or owned (all tracks in library). Enable new-release detection per artist to auto-add future albums.

Albums

A release belonging to a watched artist. Status is watched (tracks set to wanted), owned (all tracks in library), or ignored (tracks cascade to ignored, preserving any already owned or downloading).

Tracks

Individual tracks within an album. Statuses: wanted (queued for download), downloading (actively being fetched via slskd), owned (file present in library), or ignored (skipped by automation).

Downloads

Each download attempt has its own lifecycle: pending → searching → downloading → organizing → complete, or failed (retried with exponential backoff up to ~2 hours before giving up).

​
Features at a Glance

Crate ships with everything needed for a hands-off music library, and a few extras for power users:
Configure a priority-ordered list of quality tiers (for example: FLAC → MP3 320 → MP3 256). Crate always respects tier order when picking a download, and an optional fallback toggle rejects files outside your configured tiers entirely. A scheduled upgrade scanner re-queues tracks that could be improved.
Failed downloads retry with backoff (5 min → 15 min → 30 min → 1 h). Sources that go offline mid-transfer or whose queued downloads stall are temporarily shadow-banned (default 60 min, configurable). Specific file–user combinations that fail permanently are blacklisted so they’re never retried.
Browse every slskd result for any track — scored, annotated with format and queue info, with blacklisted and shadow-banned sources shown but dimmed. Pick any result to force-download it regardless of scoring.
Tag-based scan of your on-disk collection with dry-run preview. MusicBrainz-tagged files (Picard/beets) link to their real provider IDs automatically. Everything else imports under a reserved local provider and can be linked to a provider later to reveal missing tracks.
Crate ships a Lidarr v1 API shim at /api/v1/ so iOS apps like Helmarr can manage your library as if Crate were Lidarr. No extra configuration needed — point the app at your Crate URL with any API key.

​
Technology Stack

Crate is designed to run as a single Docker container with no external runtime dependencies beyond slskd.
LayerTechnology
BackendGo + Chi router + SQLite (pure Go, no CGO)
FrontendReact + TypeScript + Vite + Tailwind CSS
Metadata providersMusicBrainz + Deezer via gRPC (extensible)
Audio taggingID3v2 (MP3), Vorbis comments (FLAC), RIFF INFO (WAV)
Downloadsslskd (Soulseek client)
DeploymentDocker — single multi-stage container
The backend and both bundled provider binaries (provider-musicbrainz, provider-deezer) are compiled with CGO_ENABLED=0, so the final image is a small Alpine container with no native library requirements.

​
Mobile-First UI

Crate’s interface is built mobile-first: a bottom navigation bar on small screens, a sidebar on desktop. Every page — library, artist detail, album detail, downloads queue, activity log, settings — is designed to be fully usable from a phone.
Crate has no built-in authentication. Anyone who can reach port 6969 can use the app. If you expose Crate outside your local network, place a reverse proxy with authentication in front of it — for example Cloudflare Zero Trust, Authelia, or nginx basic auth. See the Configuration page for more details.

​
Next Steps

Ready to get Crate running? The Quickstart guide walks you through a working Docker Compose stack in under 5 minutes.

Build docs developers (and LLMs) love

Get started for freeTalk to us