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.

Quality tiers are the primary way you tell Crate what kind of audio files to accept. Rather than a single global format preference, you define an ordered list of acceptable quality levels. When Crate scores search results, the tier position of a file determines most of its score — higher in the list means more preferred, and no other scoring factor can override a tier difference.

​
What Is a Quality Tier?

A quality tier is a simple rule: a format name, an optional minimum bitrate, and a human-readable label. Crate evaluates each candidate file against your tier list from top to bottom and uses the first tier the file satisfies. The QualityTier model has three fields:
​
format
string
required
The audio container/codec to match. Case-insensitive. Supported values: flac, mp3, wav, ogg, opus, aac, m4a.
​
min_bitrate
integer
Optional minimum bitrate in kbps. Only meaningful for lossy formats like MP3. A file must have a bitrate at or above this value to match the tier. Omit or set to 0 to accept any bitrate for the format.
​
label
string
required
A display name shown in the Settings UI and the manual search results list (e.g. "FLAC", "MP3 320", "MP3 256").

​
Priority Order

The position of a tier in the list determines its priority. Higher in the list = higher priority = more preferred. The scoring system assigns:
  • Rank 0 (first tier): 100 points
  • Rank 1 (second tier): 75 points
  • Rank 2 (third tier): 50 points
  • Each additional rank: −25 points, floored at 25 points
Because tier scores are spaced 25 points apart and the artist-name bonus is capped at 20 points, quality always dominates: a file matching a higher tier will always beat a file matching a lower tier, even if the lower-tier file comes from an artist-named source with a free upload slot.

​
Example Configuration

[
  { "format": "flac", "label": "FLAC" },
  { "format": "mp3", "min_bitrate": 320, "label": "MP3 320" },
  { "format": "mp3", "min_bitrate": 256, "label": "MP3 256" }
]
With this list, Crate prefers FLAC above all else. If no FLAC is available, it accepts an MP3 at 320 kbps or higher. If that’s also unavailable, it accepts MP3 at 256 kbps or higher. A 192 kbps MP3 matches none of the tiers.

​
Quality Fallback Toggle

The fallback toggle controls what happens when a file doesn’t match any configured tier:
Crate downloads the best available file even if it doesn’t match any tier. Non-tier files score below the lowest tier but are still accepted. This is the safer default: you’ll always get something, even if it’s not your preferred quality.
To run a strict lossless-only library, set FLAC as your single tier and disable quality fallback. Crate will refuse any non-FLAC file automatically, and you can use manual search to hand-pick a specific file for tracks that have no FLAC sources.

​
Upgrade Scheduler

Crate includes an upgrade scanner that runs alongside the normal scan interval (CRATE_SCAN_INTERVAL, default 6h). On each cycle, it processes one artist per day and re-queues any owned tracks whose current format would rank lower than the top tier. A track is considered upgradeable when any of the following is true:
  • Its recorded download_format is null (format unknown) and at least one tier is configured.
  • Its download_format is known but does not match any configured tier (e.g. a format not in your list), and at least one tier is configured.
  • Its download_format is matched in your tier list but at a rank higher than 0 (i.e. it is not already in the top-priority tier).
When a better copy is downloaded, it replaces the old file (even if the old file was organized under an older naming template) and the track record is updated with the new format and bitrate.
Files outside the library folder — such as those imported from a user-managed location — are never deleted, even when replaced by an upgrade.

​
Configuring Tiers in the Settings UI

Quality tiers are configured under Settings → Quality Tiers. Changes take effect immediately for new downloads; the upgrade scheduler will apply them to owned tracks over subsequent scan cycles.

​
Supported Formats

All formats below are downloaded and tracked in the database. Formats without metadata tagging support are still fully functional — they are organized into the library folder and their format/bitrate is recorded for upgrade-scoring purposes.
FormatDownloadMetadata taggingCover art
FLACYesYes (Vorbis comments)Yes
MP3YesYes (ID3v2)Yes
WAVYesYes (RIFF INFO)No
OGGYesNoNo
OpusYesNoNo
AACYesNoNo
M4AYesNoNo

Build docs developers (and LLMs) love

Get started for freeTalk to us