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.

After the organizer moves a downloaded file into the library, the tagger writes metadata into it. Crate uses the correct native tag format for each container: ID3v2 for MP3, Vorbis comments for FLAC, and RIFF INFO for WAV. Formats without a supported tag format (OGG, Opus, AAC, M4A) are still downloaded and organized — they just don’t receive embedded tags.
Tagging is non-destructive. Crate opens the existing tag block, strips only the fields it manages, and rewrites those fields. Any tags written by other tools — ReplayGain analysis, MusicBrainz Picard IDs, AcoustID fingerprints, ISRC codes — are preserved unchanged.

​
Tag Formats by File Type

Crate opens the file with Parse: true so all existing ID3v2 frames survive. It then replaces only the frames it owns by calling SetTitle, SetArtist, SetAlbum, and SetYear, then clearing and rewriting the track number (TRCK), disc number (TPOS), and attached picture (APIC) frames before saving.Frames written by other tools — UFID (MusicBrainz recording ID), TXXX (custom tags), RVA2 / RGAD (ReplayGain), TSRC (ISRC) — are never touched.Fields written: title, artist, album, year, track number, disc number, cover art (front cover APIC frame).

​
Tags Written

The following fields are written to every supported format (where the format supports them):
FieldMP3 (ID3v2)FLAC (Vorbis)WAV (RIFF INFO)
Track titleTIT2TITLEINAM
Artist nameTPE1ARTISTIART
Album titleTALBALBUMIPRD
YearTDRCDATEICRD
Track numberTRCKTRACKNUMBERITRK
Disc numberTPOSDISCNUMBERIKEY
Cover artAPICPICTURE✗

​
Cover Art

Cover art is fetched from the album’s cover_url (provided by the metadata provider — MusicBrainz, Deezer, or a custom gRPC provider) and embedded during tagging. Fetching is done with a 10-second timeout; if the fetch fails or returns a non-200 status, the tag is still written without cover art rather than failing the entire tagging step. For MP3 files, the APIC (Attached Picture) frame is deleted and re-added as a front-cover picture each time to prevent accumulating duplicate frames on tracks that are re-tagged during a quality upgrade. For FLAC files, all existing PICTURE metadata blocks are removed and a single new front-cover block is appended.

​
MusicBrainz Recording ID

When a track is imported from a MusicBrainz-tagged file, or sourced via the MusicBrainz provider, the MusicBrainz recording ID is stored as mb_recording_id on the track record in the Crate database. This is kept as a separate signal rather than being resolved to a release-track ID, which avoids ambiguity when a recording appears on multiple releases.
If you import a library that was previously tagged by MusicBrainz Picard or beets, those files carry MusicBrainz IDs that Crate reads during import. Artists, albums, and tracks are created under the musicbrainz provider with their real provider IDs, and they behave exactly like entities you browsed and watched through the Crate UI — including new-release detection, upgrade scheduling, and relinking.

​
Unsupported Formats

OGG, Opus, AAC, and M4A files are downloaded and organized into the library folder normally. The tagger receives the file but logs a warning and returns without writing anything, so these files remain exactly as they arrived from Soulseek. They are still tracked in the database with their format and bitrate recorded, so the upgrade scheduler can re-queue them if a preferred-format source becomes available.

Build docs developers (and LLMs) love

Get started for freeTalk to us