Skip to content

Output Structure

TrackSplit writes one album folder per video into your output directory. This page explains what every file is, what it is for, and what changes when your source files carry CrateDigger metadata.

Want to see it first? The interactive library browser lets you click through real artists, albums, cover art, and tracklists.

What you get

After a successful run you will find a folder structure like this inside your output directory:

Artist/
  folder.jpg
  artist.jpg
  Festival Year (Stage)/
    01 - Track Title.flac
    02 - Track Title.flac
    ...
    cover.jpg
    .tracksplit_manifest.json

Every file in that structure has a specific purpose. Some are for your music server. One is for TrackSplit only.

The two levels of output

The quality of your output depends on what metadata is in the source video.

With CrateDigger tags (enriched sources): TrackSplit has everything it needs. The album folder is named Festival Year (Stage) when the source carries a festival name (most common case), or Venue Year for non-festival venue recordings (e.g. a club or arena set with no named festival). Tracks get canonical artist names, MusicBrainz IDs, festival and venue details, and per-track genre. Your music server can link every artist, album, and collaborator correctly.

Without CrateDigger tags (any chaptered video): TrackSplit still works. It infers the artist and album from whatever it finds in the filename and embedded tags, numbers the tracks, and writes what it can. The album folder is named after the source filename. You get a properly split, tagged album, just without the rich festival metadata.

In both cases you get the same files. The difference is in how accurate and complete the metadata inside those files is.

Directory layout explained

Artist folder

Artist/
  folder.jpg
  artist.jpg

The top-level folder is named after the artist. Inside it, two image files are placed at the artist level so your music server can display artist artwork:

  • folder.jpg: the artist cover image, picked up by Jellyfin and similar servers as the artist folder image.
  • artist.jpg: the same image under a different name, used by Kodi and other players that look for artist.jpg specifically.

Both files contain the same image. TrackSplit writes both so the artist looks correct in whichever server you use.

The DJ photo is placed as a rounded square thumbnail, center-cropped from the source image so faces keep natural proportions. A landscape source (such as fanart.jpg) is cropped to its center square rather than squashed to fit.

Multi-artist (B2B) sets go under the primary artist's folder. When a set has more than one headliner (as listed in the CrateDigger CRATEDIGGER_1001TL_ARTISTS tag), TrackSplit places the album inside the first-listed artist's folder rather than creating a combined folder like Martin Garrix & Alesso/. The artist artwork (folder.jpg, artist.jpg) reflects the primary artist.

Album folder

Festival Year (Stage)/
  01 - Track Title.flac
  02 - Track Title.flac
  cover.jpg
  .tracksplit_manifest.json

Each video gets its own album folder inside the artist folder. The folder name comes from the metadata:

  • CrateDigger source with a festival tag: Festival Year (Stage), or Festival Year when no stage is set.
  • CrateDigger source without a festival tag (venue recording): Venue Year using the venue name, or the location name (from the 1001Tracklists page heading) if no venue is set, or the stage name if neither is available. If that location string already contains the year (e.g. "Bay Oval Park 2026-01-31"), the year is not appended a second time.
  • Plain chaptered video: the source filename (without extension).

Multi-artist (B2B) sets get a "(with ...)" annotation on the folder name. When a set has more than one headliner, all guest artists (everyone after the first) are appended to the folder name: Red Rocks Amphitheatre 2025 (with Alesso). For three or more headliners the guests are joined with &: Festival 2025 (with Alesso & John Summit). When the base album name already ends with a parenthetical (such as a stage name), the "with" annotation is merged into it rather than added as a second pair of parentheses: UMF Miami 2026 (Mainstage, with Alesso). The ALBUM tag inside every track file always contains the clean album name without this annotation; the annotation appears only in the folder name.

Track files

One audio file per chapter. Filenames follow the pattern NN - Title.flac (or .opus), where NN is a zero-padded number starting at 01.

If the video has audio before the first chapter marker (an unlabelled intro section) and that pre-chapter gap is at least 5 seconds, TrackSplit creates an extra track numbered 00 - Intro for that segment. Gaps shorter than 5 seconds are folded into track 1 instead, so track 1 begins at the start of the file and absorbs the lead-in audio. This avoids tiny sliver files for negligible gaps. The threshold is fixed and not user-configurable.

cover.jpg

The album cover image, placed at the album level. It is also embedded inside every track file, so your music server sees it whether it reads the folder image or the file tags.

This file is always created.

What's on the cover: the artist name above an accent rail, with the festival (or closest available location) below the rail, then the date, then the stage. The accent color is sampled from the background image.

Background image source: the cover uses the embedded video cover image as a blurred full-bleed background. The source must be landscape (aspect ratio at least 1.2). If the embedded image is portrait or near-square, TrackSplit falls back to a generated gradient background and logs a warning. When an MKV carries multiple image attachments, an attachment named cover_land is preferred over one named cover as the background source.

How the cover identifies the artist(s): the cover follows the same source data used for folder names and tags.

With CrateDigger tags: the cover draws one line per identified act, taken from the CRATEDIGGER_1001TL_ARTISTS tag. A single act whose name contains &, vs, or similar (for example Above & Beyond) stays on one line automatically, no configuration required. A back-to-back or collaboration set shows the primary act on the first line and each additional act on its own line prefixed with & (for example MARTIN GARRIX on the first line, & ALESSO on the second). The shared font is sized to fit the longest line so the stack stays visually aligned.

If an act you consider a single group is being split across lines, that means CrateDigger identified it as multiple acts. The place to fix this is upstream in CrateDigger (its artists.json groups list or DJ cache), not in TrackSplit.

Without CrateDigger tags: the album artist comes from the filename and there is no structured act list. The cover falls back to splitting the displayed name on &, B2B, VS, and X (with surrounding spaces), as well as the "Act (members)" parenthetical form. A standalone act whose name contains one of those connectors will be split across lines, and there is no TrackSplit setting to prevent it. This is cosmetic only: the artist folder name and the tags always use the whole artist name.

Festival accent fallback. The line directly below the accent rail shows the festival name when one is present. If there is no festival, TrackSplit falls back to the venue, then to the location (from the 1001Tracklists page heading), then to the first comma-separated segment of the stage, then leaves the slot empty. When stage is what fills the accent line, the separate stage subline below is suppressed so the same text does not appear twice. Whitespace-only festival, venue, location, or stage values are treated as empty and fall through the chain.

If the text that fills the accent slot contains a comma, it is split at the first comma: the part before the comma stays in the accent slot, and the remainder renders as an additional white detail line below the date, above any stage line. This matters most for sets with no registered 1001Tracklists source, where the location is a single free-text string combining venue and city (for example "Portal do Amanhã, Parque Villa-Lobos São Paulo"). Official festival and venue names contain no comma, so they are unaffected.

Gapless playback

FLAC output is inherently gapless: any player that handles FLAC correctly will move from one track to the next without a gap or click.

Opus output is gapless in players that support gapless playback, such as Symfonium and mpv. TrackSplit achieves this by prepending two 20ms warmup frames (40ms total) to each track after the first and setting the pre_skip field in the Opus stream header to 1920, so the decoder discards the warmup cleanly and audio starts exactly at the chapter boundary.

Two conditions are required for this path:

  • The source Opus stream uses 20ms frames (the default in Matroska files produced by CrateDigger).
  • The audio is mono or stereo (standard channel mapping family 0).

When either condition is not met, TrackSplit falls back to re-encoding with libopus, which also produces gapless output but takes longer.

Players that do not support gapless playback, such as the Jellyfin mobile app, will introduce a 1-2s gap between tracks regardless of file content. This is a player-side limitation that cannot be fixed at the file level.

.tracksplit_manifest.json

A small record file TrackSplit uses internally (one per album folder). It stores the identity of the source recording, the audio fingerprint, and the complete set of tags and filenames from the last run, so TrackSplit can detect on the next run what changed and apply only what is necessary.

This file is only for TrackSplit, not for your music server. Your server will ignore it. You can delete it at any time to force TrackSplit to rebuild that album from scratch. You do not need to back it up.

What your music server uses

File Used by music server Used by TrackSplit
*.flac / *.opus Yes, these are the tracks No
cover.jpg Yes, album artwork No
folder.jpg Yes, artist artwork No
artist.jpg Yes, artist artwork (Kodi) No
.tracksplit_manifest.json No Yes, rerun reconciliation only

Tags written to every track

TrackSplit embeds metadata tags inside each audio file. Your music server reads these to display artist names, album titles, track numbers, and dates.

The core tags written on every track:

Tag What it contains
TITLE The track title (from the chapter name)
ARTIST The performing artist for this track
ALBUMARTIST The headlining artist for the whole set
ALBUM The clean album name. For multi-artist sets this is the base name without the "(with ...)" folder annotation.
TRACKNUMBER The track number
DISCNUMBER Always 1
DISCTOTAL Always 1

Additional tags are written when the information is available:

Tag When it appears
DATE When the source has a date (recording/event date)
ORIGINALDATE Same value as DATE; Navidrome and other servers use this for the "original date" field
RELEASEDATE Same value as DATE; Navidrome and other servers use this for the "release date" field
TRACKTOTAL When the total track count is known
GENRE Per-track genre from CrateDigger (multi-value when the source carries several genres), or the album genre as a fallback
PUBLISHER When present in the source; written as separate repeated values when the source carries multiple labels
ARTISTS Multi-value list of individual artists (enables per-artist linking in Jellyfin and Lyrion)
ALBUMARTISTS Multi-value list of individual album artists (for B2B sets)
MUSICBRAINZ_ARTISTID Per-artist MusicBrainz IDs, aligned with ARTISTS
MUSICBRAINZ_ALBUMARTISTID Per-album-artist MusicBrainz IDs, aligned with ALBUMARTISTS
FESTIVAL Festival name (CrateDigger sources only)
STAGE Stage name (CrateDigger sources only)
VENUE Venue name (CrateDigger sources only)
RELEASECOUNTRY The festival's country, written as-is (for example "United States" or "Belgium"). Uses the MusicBrainz/Picard field name so servers such as Navidrome recognize it automatically. CrateDigger sources only; omitted when no country is present.

Tags are omitted entirely when the information is not available. Empty tags are never written.

What does NOT change

TrackSplit only reads your source video files. It never modifies, moves, or deletes them. All output goes to the directory you specify (or the current working directory if you omit --output).

Advanced details

Artist tagging policy

  • ARTIST is the display string for this specific track: for example "AFROJACK ft. Eva Simons". When CrateDigger supplies a per-chapter PERFORMER tag, TrackSplit uses it verbatim so "Artist ft. Remixer" forms are preserved. When a chapter title has no artist separator, ARTIST falls back to ALBUMARTIST.
  • ARTISTS is a multi-value list of the individual artists on this track: "AFROJACK", "Eva Simons". Jellyfin and Lyrion use this to link each contributor to their own artist page.
  • MUSICBRAINZ_ARTISTID is positionally aligned with ARTISTS. Empty slots are preserved when an individual artist's MusicBrainz ID is unknown, so the position still matches. The whole tag is omitted if every slot is empty.
  • ALBUMARTIST is the headliner display string for the whole set. For B2B sets with CrateDigger metadata this is something like "Armin van Buuren & KI/KI".
  • ALBUMARTISTS is a multi-value list of individual headliners: "Armin van Buuren", "KI/KI". Written for both solo and B2B sets.
  • MUSICBRAINZ_ALBUMARTISTID is positionally aligned with ALBUMARTISTS. Omitted entirely if every slot is empty.
  • Per-track artists whose name matches the album artist (case-insensitively) are normalized to the album artist's exact casing. This prevents Lyrion from listing two rows for the same artist and stops Jellyfin from showing stray uppercase variants.
  • GENRE is per-track when CrateDigger supplies a chapter-level genre tag. It falls back to the album's genre list otherwise. When the source carries multiple genres joined by | (for example House|Techno), each is written as a separate repeated Vorbis comment, the same way ARTISTS is handled. PUBLISHER follows the same rule: multiple pipe-separated labels become separate repeated values.

Metadata tiers

  • Tier 1 (any chaptered video): TrackSplit infers artist and album from filename and embedded tags. The album folder uses the filename stem. You get numbered, tagged tracks with whatever metadata the source carries.
  • Tier 2 (CrateDigger-tagged source): TrackSplit uses the canonical artist, festival, venue, date, and MusicBrainz IDs embedded by CrateDigger. The album folder uses Festival Year (Stage) naming for festival sets, or Venue Year (or Location Year) for venue recordings without a festival name. Every tag is populated precisely with no guessing.

CrateDigger cache reuse

TrackSplit reads CrateDigger's caches directly, not just the tags baked into the MKV. This is how consistent artist spellings, festival aliases, MusicBrainz IDs, and DJ artwork stay in sync between your video library (CrateDigger) and your music library (TrackSplit) without TrackSplit needing any of its own config.

Lookup chain. For each curated data file, TrackSplit checks candidate directories in priority order and uses the first file found, matching CrateDigger's own resolution:

  1. Environment variable: if CRATEDIGGER_DATA_DIR is set and the directory exists, it is the sole source. CrateDigger honours the same variable, so exporting it points both tools at the same folder.
  2. Walk-up: starting from the folder containing the input video, TrackSplit walks up to 10 parent directories looking for a .cratedigger/ subfolder.
  3. CrateDigger's own data directory: the folder where CrateDigger stores its curated data by default:
Platform Path
Linux ~/CrateDigger/
macOS ~/CrateDigger/
Windows Documents\CrateDigger\

Each file is resolved independently. A library-local .cratedigger/places.json replaces the user-level one entirely, but if the walk-up directory has no places.json (or the legacy festivals.json), the user-level file is used. The same applies to artists.json. This means you can have a .cratedigger directory for folder layout config without needing to duplicate your place and artist definitions there.

If none of the locations has the file, TrackSplit continues without it (raw tag values pass through unchanged). No configuration is needed when CrateDigger is installed in its default location.

Cache files TrackSplit reads:

File What TrackSplit uses it for
places.json (legacy: festivals.json) Canonical place name and alias resolution, covering both festivals and venues. Rewrites raw festival names (e.g. "TML", "A State Of Trance Festival") to their canonical form ("Tomorrowland", "ASOT"), and decomposes edition suffixes ("Tomorrowland Winter" to "Tomorrowland" + edition "Winter"). Also resolves venue aliases (e.g. "Red Rocks Amphitheatre" to "Red Rocks"). Drives the FESTIVAL and VENUE tags, the album folder name, and the cover art text.
artists.json Canonical artist name resolution (e.g. "tiesto" to "Tiësto"). Applied before the artist folder name and the ALBUMARTIST tag are written. Case- and diacritic-insensitive, so both "Tiesto" and "TIËSTO" resolve correctly.
dj_cache.json Supplements artists.json with per-DJ aliases scraped by CrateDigger. Loaded before artists.json so manual entries in artists.json win when the same alias appears in both.
mbid_cache.json Fills missing MusicBrainz artist IDs. For Tier-1 sources (no CrateDigger tags) the ALBUMARTIST is looked up here to populate MUSICBRAINZ_ALBUMARTISTID. For Tier-2 sources, any empty slot in the positional MBID list (per-track MUSICBRAINZ_ARTISTID and album-level MUSICBRAINZ_ALBUMARTISTID) is backfilled from this cache. Unknown names stay empty.
artists/{slug}/dj-artwork.jpg DJ portrait used to compose the artist cover (folder.jpg / artist.jpg). Slugs are hyphenated (for example martin-garrix). Looked up by the CrateDigger canonical slug (from the CRATEDIGGER_ALBUMARTIST_SLUGS tag, index 0), used verbatim, hyphens and any & included. For files without that tag, the slug is derived from the artist name with slugify, which strips everything outside a-z0-9 and produces a concatenated key (for example martingarrix); that key only matches cache folders created under the older concatenated naming, so files without the tag should be re-enriched with CrateDigger to get artwork matched under the current hyphenated folders.
artists/{slug}/fanart.jpg Fallback portrait used when dj-artwork.jpg is not present. Resolved by the same slug.

Re-run manifest details (schema 4)

.tracksplit_manifest.json is the album's internal cache (schema version 4). It contains:

  • Source identity: the CrateDigger 1001Tracklists ID (CRATEDIGGER_1001TL_ID) embedded in the MKV, which is the primary stable identifier for CrateDigger-tagged sources. For sources without that tag, a best-effort fingerprint of the audio stream (codec, sample rate, channels, and Matroska time base (the audio stream tick rate, which changes if the file is re-muxed)) plus chapter boundaries is used as a fallback.
  • Source path: the file path where the source MKV was last found. Stored for reference only; a path change does not by itself mean the album has to be rebuilt.
  • Album tags: the album-level metadata used for the last run (artist, festival, venue, date, stage, format, and similar).
  • Track list: one entry per output track (including the intro at position 0 when present), each recording its filename, start and end times, and the tags embedded into that file.

The manifest JSON is written with literal Unicode: accented characters appear as-is, not as escape sequences.

What a rerun does (cheapest applicable operation):

What changed What TrackSplit does Audio re-encoded?
Source file moved or renamed (path changed, same recording) Refreshes the stored path in the manifest No
Album or artist folder name changed (e.g. artist spelling fix) Renames/moves the album folder and rewrites tags in place No
A track title or performer changed Renames the affected track file and rewrites its tags No
Per-track or album-level tags changed (label, genre, MBIDs, etc.) Rewrites tags in place across affected tracks No
Audio stream changed (re-encode, codec, sample rate, channels), output format changed, number of tracks changed, or a chapter boundary moved Full re-split: audio is re-extracted from the source (and re-encoded, unless the Opus copy path applies) Yes

"Tags rewritten" means TrackSplit opens the existing audio file and updates its Vorbis comment block. The audio data is untouched. "Folder renamed/moved" means the album folder is moved to its new location on disk; track files inside stay intact.

A re-split is only triggered when the audio itself must change. Reorganizing your CrateDigger library (moving source files to a different folder, renaming the library root) or editing artist/festival metadata that affects folder names will not cause a re-split.

Migration from older manifests: the first run after upgrading from a version that wrote schema 3 manifests reads the old file and, if nothing meaningful changed, rewrites it to schema 4 without re-splitting or re-tagging. If the old album predates the current tag schema or cover renderer version, that first run also rewrites tags or recomposes covers to bring the album current; audio is still not re-extracted.

Compatibility: an older TrackSplit version reading a schema 4 manifest will not recognize the schema and will fall back to a full re-split, leaving your audio safe. Schema 4 manifests are not forward-compatible, but they are safe for older readers.

Deleting the manifest forces a full rebuild of that album. Passing --force on the command line rebuilds every album regardless of manifests.

Folder cleanup on re-run

When a re-split or move is triggered, TrackSplit tidies up leftover files from the previous run automatically. It identifies old output by album identity (the stable source ID or fingerprint recorded in the manifest), not by matching folder names or source paths.

  • Album folder moved: if the album folder path changed (because the artist name, festival name, venue name, or stage changed), the old folder is deleted and a new one is created at the correct location.
  • Track files renamed or removed: if track names changed within an album but the folder stayed the same, orphan audio files from the previous run are removed from the album directory.
  • Empty artist folders are not removed: if all albums move out of an artist folder (for example, after a name correction in places.json or artists.json), the now-empty artist folder stays behind. Delete it manually if it appears.
  • --force follows the same rules: it rebuilds every album but applies the same folder and file cleanup logic described above.