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 can adopt a music collection it didn’t download. The built-in importer reads embedded tags from every MP3 and FLAC file it finds, records each track as owned in the database, and — for files tagged with MusicBrainz IDs — links them directly to their real provider entities. Folder structure is completely ignored; only the metadata embedded in the files matters. The process is non-destructive: files are never moved, renamed, or modified at any point.

​
How the Importer Works

Before triggering a run, it helps to understand the two paths your files can take:
  • MusicBrainz-tagged files (tagged by MusicBrainz Picard or beets) carry artist MBIDs, release-group IDs, and release-track IDs. The importer detects these and imports the entire artist/album/track hierarchy under the musicbrainz provider with their real IDs — they behave exactly like artists you discovered through the search UI.
  • Everything else imports under the reserved local provider. IDs are stable SHA-256 hashes derived from tag content (artist, album, title, disc/track number) and are prefixed loc-. These IDs survive file moves and renames because they are never path-based.
Run MusicBrainz Picard over your collection before importing. Files that carry consistent MBIDs import under the musicbrainz provider and immediately participate in discography tracking, upgrade scanning, and new-release detection — no further linking required.

​
Running an Import

Always run with Dry Run enabled the first time. A dry run reads every file and produces a full report — artists added, albums added, tracks claimed, files skipped with reasons — without writing a single row to the database. Review the report before committing.
1

Open the import dialog

Go to Settings → Library → Import Existing Library. The dialog lets you confirm the library path and toggle the dry-run option.
2

Run a dry-run scan first

Leave Dry Run checked and click Start Import. The UI polls GET /api/library/import while the scan runs, displaying a live progress counter. When complete, the report shows:
  • artists_added — new artist rows that would be created
  • albums_added — new album rows that would be created
  • tracks_added — new track rows that would be created
  • tracks_claimed — existing wanted tracks that would gain a file
  • tracks_known — already-owned tracks that would be left untouched
  • musicbrainz_linked — tracks linked via real MusicBrainz IDs
  • files_skipped — files that could not be imported, with reasons (up to 100 sample paths shown)
3

Review skipped files

Files are skipped when any of the three required tags — artist, album, or title — are missing. The report lists each skipped path and the reason. Fix tags in Picard or a tag editor, then re-run the dry run.
4

Commit the import

Uncheck Dry Run and click Start Import again. The importer is idempotent: any track it already knows (matched by provider ID or by title within the album) is skipped — re-running after adding new files is always safe. The API equivalents are:
POST /api/library/import
Content-Type: application/json

{ "dry_run": false }

GET /api/library/import

​
What Happens After Import

​
Wanted tracks get claimed

If you already watch an album and your imported files match its tracks by title, those tracks flip from wanted to owned instead of being queued for download. The importer records the real file format and bitrate at the same time.

​
Quality upgrades apply immediately

Imported tracks record their actual format and bitrate (parsed directly from the files). The upgrade scanner treats them identically to downloaded tracks — import MP3s with a FLAC-first quality tier and Crate will queue upgrades automatically. Files outside the library directory are never deleted when replaced by an upgrade.

​
Local artists are flagged “not linked”

Artists imported under the local provider appear with a not linked badge in the Library view. They are fully usable as-is — you can browse their albums, see which tracks are owned, and queue missing tracks for download — but Crate cannot check for new releases or fill gaps until the artist is linked to a real provider.

​
Linking a Local Artist to a Provider

Linking replaces the local IDs with real provider IDs and pulls the full discography so gaps become visible.
1

Open the artist page

Navigate to the artist in the Library. The not linked badge appears next to the artist name.
2

Search and select the correct provider entry

Click Link to Provider, search by name, and pick the correct artist from the results. You choose — Crate never auto-matches to avoid linking to the wrong artist.
3

Crate fetches the full discography

Crate pulls every album from the provider and folds your existing files in:
  • Albums are matched by title + year (case-insensitive; year is optional on either side to handle missing tags).
  • Tracks within matched albums are matched by title (case-insensitive), with disc/track number used as a tiebreak when multiple tracks share a title.
  • Matched albums and tracks are re-pointed to their real provider IDs in place — owned files are never lost, only re-linked.
  • Provider albums with no local match are created with all tracks set to wanted, revealing the gaps in your collection.
4

Handle unmatched items

Tracks that the fuzzy matcher could not place stay owned + local and are flagged on the album page. From there you can:
  • Merge a leftover local album into the correct provider release, if the importer created a duplicate.
  • Link a stray local track to the provider track it belongs to.
Owned files are only ever re-pointed, never deleted.
Prefer to import by writing directly to the database? The full schema reference — including the local provider convention and custom importer tips — is covered in the Database Schema page.

Build docs developers (and LLMs) love

Get started for freeTalk to us