Documentation

Everything you need to deploy, configure, and extend Crate.

Overview

Crate is a self-hosted music manager for collectors. It connects to music metadata providers (MusicBrainz, Deezer, or your own) to search and browse artists, then downloads tracks from Soulseek via slskd. Downloaded files are automatically organized, tagged with full metadata and cover art, and placed in your library.

The stack is a Go backend with SQLite, a React frontend, and standalone gRPC provider binaries — all shipped in a single Docker image.

Deployment

The recommended deployment is via Docker Compose with slskd as a sidecar. Crate needs a Soulseek account (provided through slskd) to download music.

# docker-compose.yml
services:
  crate:
    image: ghcr.io/theoutdoorprogrammer/crate:latest
    ports:
      - "6969:6969"
    volumes:
      - ./crate:/app/data             # SQLite databases
      - ./slskd/downloads:/app/downloads  # Must match slskd's download dir
      - ./library:/app/library       # Organized music library
    environment:
      - CRATE_SLSKD_URL=http://slskd:5030
      - CRATE_SLSKD_API_KEY=your_api_key
    depends_on:
      - slskd
    restart: unless-stopped

  slskd:
    image: slskd/slskd:latest
    ports:
      - "5030:5030"
    volumes:
      - ./slskd:/app                  # slskd data (config, downloads)
      - ./library:/music             # Share your library on Soulseek
    environment:
      - SLSKD_REMOTE_CONFIGURATION=true
      - SLSKD_API_KEY=your_api_key
      - SLSKD_SOULSEEK_USERNAME=your_username
      - SLSKD_SOULSEEK_PASSWORD=your_password
    restart: unless-stopped

Volumes

Three volume mounts are important:

• Data directory — where Crate stores its SQLite databases. Map to a persistent path.
• Downloads directory — shared with slskd. Crate reads completed downloads from here. Must be the same path slskd writes to.
• Library directory — where organized, tagged music files end up. Point your media server (Navidrome, Plex, etc.) here.

Authentication

Crate does not include built-in authentication. It's designed to run behind your existing auth layer — a reverse proxy with basic auth, Authelia, Authentik, Cloudflare Access, a VPN, or whatever you prefer. If it's only accessible on your local network, no auth may be necessary.

Environment Variables

These are set at startup and control core paths, ports, and provider configuration. All have sensible defaults — only CRATE_SLSKD_API_KEY is required.

UI Settings

These settings are stored in the database and configurable from the Settings page in the web UI. Changes take effect immediately without restarting.

Naming Template

The folder and file layout for downloads is a template you can change from Settings → Library, with a live preview as you type. Use it to match an existing library convention (e.g. one served by Navidrome) so Crate's downloads slot in cleanly. The default matches Crate's original layout:

{artist}/{album} ({year})/{track:2} - {title}

Example: to match the common Artist/Artist - Year - Album convention:

{artist}/{artist} - {year} - {album}/{track:2} {title}

Behavior

• Extension is automatic — the downloaded file's extension is appended; don't put it in the template.
• Empty tokens clean up after themselves — when {year} is unknown, {album} ({year}) renders as Album Title, not Album Title (). Dangling separators next to empty tokens are removed the same way.
• New downloads only — changing the template never renames existing files. Quality upgrades organize with the current template and remove the file they replace, even if it lived at a path from an older template.
• Safety — templates must be relative paths, the filename must contain {title} or {track}, and filesystem-unsafe characters (<>:"/\|?*) in metadata are replaced with _. Invalid templates are rejected when you save.

Providers

Providers supply music metadata (artist search, discography browsing, album/track details, cover art). Crate ships with two built-in providers and supports adding custom ones via gRPC.

Built-in Providers

How Providers Work

• Default provider — set in settings as provider_primary. Used for search and browse unless the user switches providers in the search UI.
• Entity tracking — every artist, album, and track stores which provider and provider ID it came from. This is how Crate knows where to check for new releases.
• Provider switching — you can change the default provider at any time. Existing entities keep their original provider association.
• Relinking — any entity can be relinked to a different provider via the API. Useful if you switch primary providers and want to unify your library.
• Orphan detection — if a provider goes offline, entities from that provider show as “orphaned” in the UI.
• Caching — provider responses are cached in a separate SQLite database (cache.db) with configurable TTL. The cache can be cleared from the Settings page.

Provider Configuration

The CRATE_PROVIDERS environment variable defines which providers to load. Format:

# Built-in providers (binary path relative to crate binary)
CRATE_PROVIDERS=musicbrainz:./provider-musicbrainz:50051,deezer:./provider-deezer:50052

# External provider (network address instead of binary path)
CRATE_PROVIDERS=musicbrainz:./provider-musicbrainz:50051,spotify:external:192.168.1.10:50053

Built-in providers are started as child processes by Crate. External providers connect to a remote gRPC server you run separately.

Download Flow

When you watch an artist, album, or track, here's what happens:

1. Queuing — watched items are saved with status wanted. The scheduler checks for new wanted tracks every scan interval.
2. Search — Crate searches slskd (Soulseek) for each wanted track, scoring all results through a unified scoring system.
3. Selection — the highest-scoring result is selected. Blacklisted files, shadow-banned users, and files outside configured tiers (when fallback is disabled) are excluded.
4. Download — the file is downloaded via slskd. Track status changes to downloading. The downloader checks progress every 10 seconds.
5. Organize — completed downloads are moved into the library using the configurable naming template.
6. Tag — metadata (artist, album, track name, track number, year) and cover art are embedded into the file.
7. Notify — if Navidrome is configured, a library scan is triggered. Track status becomes owned.

Retry, Blacklist & Shadow Bans

Not every download succeeds on the first try. Crate handles failures automatically:

• No results — track stays wanted. The scheduler will try again on the next cycle.
• Transfer failure (rejected, errored, cancelled) — the specific username + filename pair is permanently blacklisted. Future searches skip that source but can still find the track from other users.
• Stale detection — downloads are monitored for progress with state-aware timeouts: 5 minutes for active transfers, 30 minutes for queued transfers (waiting for a slot), and 10 minutes for requested transfers. If no progress is made within the timeout, the download is cancelled.
• Shadow banning — when a queued download stalls or a download fails to start (e.g. user offline), the user is temporarily blocked for a configurable duration (default 60 minutes). Unlike permanent file blacklists, shadow bans expire automatically. This prevents wasting time retrying users who are consistently unavailable.
• Retry backoff — failed downloads retry with increasing delays: 5m → 15m → 30m → 1h. After 4 attempts (~2 hours), the track reverts to wanted for the next scheduler cycle.
• Management — view and remove both blacklisted files and shadow-banned users from the Blocked Sources section in Settings.

Concurrency

The max_concurrent_slskd setting (default 10) limits how many downloads run simultaneously. The max_auto_queue setting (default 50) caps how many tracks the scheduler adds per cycle, preventing the queue from growing unbounded.

Scoring System

Every search result is scored through a unified pipeline that balances quality, correctness, and availability. The highest-scoring file wins.

The title must appear in the filename (hard filter). All bonuses combined (max 45) can overcome one quality tier gap but never two, ensuring your quality preferences are respected while still favoring available, correctly-labeled sources.

Quality Upgrades

Crate continuously improves your library quality. The quality system works as follows:

1. Quality tiers are priority-ordered in settings (default: FLAC > MP3 320 > MP3 256). Higher in the list = better.
2. When a track is downloaded, its format and bitrate are recorded.
3. The scheduler scans one artist per day (round-robin), checking if any owned tracks can be upgraded to a higher quality tier.
4. Upgradeable tracks are re-queued automatically. The new download replaces the old file.

The requeue_cooldown_days setting (default 7) prevents the scheduler from re-queuing the same track too frequently if better quality isn't available yet.

Lidarr API Compatibility

Crate includes a Lidarr v1 API compatibility shim at /api/v1/, allowing iOS and Android apps built for Lidarr to manage your Crate library. No extra configuration needed — point the app at your Crate URL with any API key and it works.

Concept Mapping

Lidarr and Crate model things differently. The shim translates between them transparently:

Supported Endpoints

The shim implements the Lidarr v1 endpoints that mobile apps typically use:

• System — status, health check, disk space
• Profiles — quality profiles, metadata profiles
• Library — root folders, custom filters, calendar, history, wanted/missing
• Artists — search, lookup, add (with monitoring strategy), list, get, delete
• Albums — list, delete, monitor/unmonitor toggle (with track status cascade)
• Tracks — list tracks for an album
• Downloads — queue status
• Commands — ArtistSearch, AlbumSearch

Authentication

The shim accepts any API key in the X-Api-Key header or apikey query parameter. Crate has no built-in auth — use a reverse proxy if you need access control.

Contributing

The Lidarr shim covers the most common endpoints. If your app needs an endpoint that isn't implemented yet, contributions are welcome — the shim is a single file at internal/api/lidarr.go.

Library Import

Crate can adopt a music collection it didn't download. Settings → Library → Import Existing Library scans your library folder, reads embedded tags, and records everything as owned — making Crate a drop-in manager for an established Navidrome/media-server setup rather than a fresh-start tool.

How it works

• Tag-based, not path-based — folder structure and file names are ignored entirely; only embedded metadata (MP3 ID3, FLAC Vorbis comments) matters. If your library plays correctly in a tag-based server like Navidrome, it will import correctly.
• Dry run first — the scan preview reports exactly what an import would add, claim, and skip, without writing anything.
• Non-destructive, always — files are never moved, renamed, or modified. Import doesn't apply the naming template to existing files.
• MusicBrainz tags link automatically — libraries tagged by Picard or beets carry MusicBrainz IDs, and those entities import under the MusicBrainz provider with their real IDs. Everything else imports under the reserved local provider and can be relinked to a real provider anytime (for search, cover art, or new-release watching).
• Wanted tracks get claimed — files matching tracks you already watch flip them to owned instead of leaving them queued for download.
• Quality upgrades apply — imported tracks record their real format and bitrate (parsed from the files). Import MP3s with a FLAC-first tier list and the upgrade scanner will gradually replace them, one artist per day. Files outside the library folder are never deleted, even when an upgrade replaces them.
• Idempotent — re-running an import skips what it already knows. Files missing artist/album/title tags are skipped and reported with reasons.

Navidrome Integration

Crate can trigger a Navidrome library scan after each successful download, so new music appears in your streaming library immediately.

Setup

Configure these three settings in the Crate UI (Settings page):

All three fields are required. If any are empty, the Navidrome integration is silently disabled. Crate authenticates via the Subsonic API token+salt scheme.

Supported Formats

The downloader recognizes all these formats when scoring search results. The tagger embeds metadata into FLAC (Vorbis comments) and MP3 (ID3v2) files. Cover art is embedded in both formats.

API Reference

Crate exposes a REST API on the same port as the web UI. All endpoints return JSON.

Status

Search & Browse

Library

Watching

Downloads

Providers

Blocked Sources

Settings & Activity

Custom Providers

You can build your own metadata provider by implementing the gRPC service defined in proto/provider/provider.proto. The service interface includes:

• SearchArtists — search by name, return ranked results
• GetArtist — full artist details with discography
• GetAlbum — album details with track listing
• GetTrack — individual track details

Run your provider as a standalone gRPC server and add it to the CRATE_PROVIDERS env var:

CRATE_PROVIDERS=musicbrainz:./provider-musicbrainz:50051,my-provider:external:my-host:50053

Use the external keyword as the binary path to tell Crate it should connect to a remote server instead of launching a child process. Community-built providers and the database schema are documented in DATABASE.md.

Database

Crate uses three SQLite databases:

• crate.db — main database. Artists, albums, tracks, settings, download queue, blacklist. WAL mode, single writer connection. Schema migrations via goose (embedded SQL files, run automatically on startup).
• cache.db — provider response cache with TTL. Can be safely deleted to force re-fetching, or cleared from the Settings page.
• activity.db — event log. Download completions, errors, scheduler actions. Auto-pruned based on activity_retention_days.

The full database schema is documented in DATABASE.md in the repository.