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.

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.

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.

Multi-artist names break across lines. If the artist field contains &, B2B, VS, or X (with spaces around the connector, case-insensitive), the cover stacks one artist per line with the connector carried to each subsequent line, so a three-way B2B like "Axwell & Sebastian Ingrosso & Steve Angello" renders as three stacked lines. The shared font is sized to fit the longest line so the stack stays visually aligned. A parenthetical credit like "Everything Always (Dom Dolla & John Summit)" splits into the act on the first line and the inner artists on the second.

Keeping a group name on one line. Some duos and trios ("Dimitri Vegas & Like Mike", "Swedish House Mafia") read best as a single unit. TrackSplit does not detect these automatically; it splits on any &. To keep a group on one line, add an alias in the CrateDigger artists.json file that maps the long form to a short canonical form. This file lives in the CrateDigger data directory:

Platform Path
Linux ~/CrateDigger/artists.json
macOS ~/CrateDigger/artists.json
Windows Documents\CrateDigger\artists.json

Alternatively, place it in a library-local .cratedigger/artists.json next to your video files if you want the alias to apply only to that library. The file uses {canonical: [aliases]} shape:

{
  "aliases": {
    "DVLM": ["Dimitri Vegas & Like Mike"]
  }
}

With this entry, any track tagged Dimitri Vegas & Like Mike resolves to DVLM before the cover is drawn, so the name renders on one line at a larger font and stays readable on small thumbnails in Kodi or Jellyfin. The alias also affects the artist folder name, the ALBUMARTIST tag, and DJ artwork lookup (all three use the canonical name), so picking a short form you are happy to see elsewhere matters.

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.

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. It stores a fingerprint covering the audio stream metadata (codec, sample rate, channels, duration) and the set of tags embedded into the output tracks, along with the settings used, so TrackSplit can detect on the next run whether anything meaningful changed and skip the album if not.

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. 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, skip detection 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, or the album genre as a fallback
PUBLISHER When present in the source
COMMENT When present in the source
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)

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.

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/{Artist}/dj-artwork.jpg DJ portrait used to compose the artist cover (folder.jpg / artist.jpg). Looked up by the canonical artist name.
artists/{Artist}/fanart.jpg Fallback portrait used when dj-artwork.jpg is not present.

Re-run manifest details

.tracksplit_manifest.json records:

  • The source file path.
  • An audio-stream fingerprint from ffprobe: codec, sample rate, channels, duration, and bit rate.
  • The chapter list (timestamps and titles).
  • The set of tags embedded into the per-track output files: artist, festival, date, stage, venue, genres, comment, album artist display name, individual album artists, and their MusicBrainz IDs.
  • The output format and codec mode used.
  • The list of track filenames written.

On a subsequent run, TrackSplit loads the manifest and compares it against these fields. If nothing in that list changed, the album is skipped. Re-extraction is triggered by changes to the audio stream, chapters, or any of the embedded tags listed above. Container-level edits that do not touch the audio stream or embedded tags (such as a sibling tool rewriting MKV metadata) no longer cause spurious re-extracts. Deleting the manifest forces a full rebuild for that one album. Passing --force on the command line rebuilds everything regardless of manifests.

Folder cleanup on re-run

When regeneration is triggered, TrackSplit tidies up leftover files from the previous run automatically. It identifies old output by reading manifests, not by matching folder names.

  • 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.