When Crate finds a track in theDocumentation 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.
wanted state, it automatically searches Soulseek through your connected slskd instance, evaluates every result using a multi-factor scoring system, and starts downloading the best match — all without manual intervention. The same pipeline handles retries, stale detection, and post-download organization so tracks reliably land in your library.
Download Pipeline
Each download queue entry moves through the following states:pending
The track has been enqueued and is waiting for an available concurrent-download slot. The scheduler picks up pending entries on every tick.
searching
Crate submitted a search to slskd and is polling for results. Searches that do not complete within 5 minutes are evaluated with whatever results have arrived so far.
downloading
A suitable file was selected and the slskd transfer is in progress. Crate polls the transfer and tracks byte-level progress.
organizing
The transfer succeeded. Crate is moving the file from the downloads directory into the library folder and writing metadata tags.
Scoring System
Every file returned by slskd is scored on a scale dominated by quality, with availability breaking ties. A higher score wins.Quality tier score (dominates)
Quality tier score (dominates)
Crate evaluates each file against your configured quality tiers in priority order. The first matching tier determines the base score:
- Tier rank 0 (highest priority, e.g. FLAC): 100 points
- Tier rank 1 (e.g. MP3 320): 75 points
- Tier rank 2 (e.g. MP3 256): 50 points
- Each additional rank: −25 points, floored at 25
Artist name match bonus (+20)
Artist name match bonus (+20)
If the filename contains the artist name (case-insensitive), the file earns up to 20 bonus points. This bonus is capped below the tier gap (25 points) so quality always dominates — a correct-format file from the right artist beats a higher-format file from an unrelated one only when the tier scores are tied.
Free upload slot bonus (+10)
Free upload slot bonus (+10)
Users with a free upload slot available earn 10 bonus points. This reflects actual availability: a slot-free peer will usually start sending immediately rather than queuing behind other transfers.
Queue-length-aware score (up to +15)
Queue-length-aware score (up to +15)
Crate applies an inverse-decay bonus based on the peer’s upload queue length:
15 / (1 + queueLength). A peer with no queue earns the full 15 points; one with 14 queued transfers earns 1 point. This softly penalises busy peers without hard-excluding them.requireArtist: true). Manual search surfaces every result regardless of these filters.
Retry with Backoff
If a download fails (no suitable file, transfer error, stale detection), it is rescheduled with exponential backoff:| Attempt | Delay | Cumulative |
|---|---|---|
| 1 | 5 min | 5 min |
| 2 | 15 min | 20 min |
| 3 | 30 min | 50 min |
| 4 | 1 h | ~2 h |
failed. Scheduler-sourced downloads (queued automatically by the scan interval) are removed from the queue rather than left as failed entries, to keep the queue clean.
Shadow Banning (User Cooldowns)
A shadow ban is a temporary block on a specific Soulseek user. Crate records a cooldown entry with an expiry timestamp; while the cooldown is active, that user is excluded from scoring for auto-downloads. Cooldowns expire automatically — they do not require manual intervention. Shadow bans are triggered when:- A transfer fails to start (the download request is rejected by slskd)
- A queued transfer stalls past the stale timeout — the peer entered the queue but never advanced
Stale Detection
Crate monitors active and queued transfers and cancels them when no progress is made within a state-specific timeout:| Transfer state | Stale timeout | Action on timeout |
|---|---|---|
InProgress / Initializing | 5 minutes | Blacklist file, retry download |
Queued (waiting for slot) | 30 minutes | Shadow ban user, retry download |
Requested | 10 minutes | Shadow ban user, retry download |
Blacklist vs. Cooldowns
Blacklist (permanent)
A permanent per-user per-file block. Created when a transfer errors, is rejected, or is cancelled by slskd, or when an active transfer stalls with no progress. Crate will never attempt to download that specific filename from that user again.
Cooldowns (temporary)
A temporary per-user block that expires automatically. Created when a user’s queued or requested transfer stalls. The user is not permanently excluded — they can serve other files after the cooldown expires.
Negative Keywords
Negative keywords let you skip files whose names match unwanted patterns during automatic downloads. Common examples:acapella, instrumental, karaoke, live.
negative_match: true), so you can override the filter when needed.
Manual Search
The manual search flow lets you browse every result slskd found for a track — scored, annotated, and with blacklist/lock status clearly shown. The flow is async:POST /api/tracks/{id}/search returns a search_id; the frontend polls GET /api/tracks/{id}/search/{searchId} until is_complete is true, then shows the full result list. Selecting a result calls POST /api/tracks/{id}/download with the chosen username, filename, size, and bit_rate.
File Integrity
Once a day, Crate checks that everyowned track’s recorded file path still exists on disk. If the file is missing, the track reverts to wanted and will be re-downloaded on the next scheduled scan. This guards against accidental deletions or library moves made outside of Crate.