After a download completes and before metadata tags are written, the organizer moves the file from the slskd downloads directory into your library folder. The destination path is derived from a naming template you control, so Crate can match whatever folder structure your media player or NAS convention expects.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.
How the Organizer Works
Once a transfer succeeds, the organizer:- Finds the downloaded file by basename inside the downloads directory (searching recursively).
- Resolves the destination path by rendering the naming template against the track’s metadata.
- Creates any missing parent directories.
- Moves the file to the destination (
renameif same device, copy-then-delete if cross-device). - Removes the file it replaced, if the track was already owned at a different path (e.g. a quality upgrade after a template change).
- Calls the tagger to write metadata into the newly moved file.
- Records the library-relative path on the track record.
Default Template
Token Reference
| Token | Meaning |
|---|---|
{artist} / {albumartist} | Artist name. These are identical — Crate tracks album artists only. |
{album} | Album title. |
{year} | Album release year. Renders empty when the year is unknown. |
{track} | Track number. Supports zero-padding: {track:2} → 06. |
{disc} | Disc number. Supports padding. Renders empty when unknown or 0. |
{title} | Track title. |
{track} and {disc}) accept an optional pad width after a colon. {track:2} left-pads the track number with zeros to at least 2 digits; {track:3} pads to 3. Any other token does not support a pad width — the template validator will reject it.
Dangling Decoration Cleanup
When an empty token like{year} appears inside decoration (parentheses, brackets, separators), Crate automatically removes the orphaned punctuation rather than leaving ugly artifacts:
| Template segment | Year known | Year unknown |
|---|---|---|
{album} ({year}) | OK Computer (1997) | OK Computer |
{disc}-{track:2} | 1-06 (disc 1) | 06 (disc 0) |
({year} - {disc}) also collapse correctly.
Template Rules
Template must be a relative path
Template must be a relative path
Do not start the template with
/ or \. The library root is added automatically.The last segment must contain {title} or {track}
The last segment must contain {title} or {track}
The filename segment (everything after the last
/) must include at least one of {title} or {track} so individual tracks get unique names within an album folder.No empty segments
No empty segments
Doubled or trailing slashes, and segments that consist entirely of blank-able tokens (like a standalone
{year} segment), are rejected at validation time.Unsafe characters are replaced
Unsafe characters are replaced
Characters that are unsafe on common filesystems —
< > : " / \ | ? * — are replaced with _ in every metadata value before it is written into the path.Applying Template Changes
The naming template applies only to new downloads. Changing it does not rename or move files that are already in the library. However, when a quality upgrade downloads a better copy, it uses the current template for the new path and removes the old file — even if the old file was organized under a different template.Files imported from an existing library are never moved, renamed, or modified, regardless of how the naming template changes. This includes both the initial import and any subsequent template edits.
Example Templates
- Default (Artist/Album/Track)
- With disc number
- Flat (no album folder)