Skip to content

FAQ

Do I need CrateDigger to use TrackSplit?

No. TrackSplit works on any video file that has chapter markers and an audio stream.

Without CrateDigger you still get a properly split, tagged album: one file per chapter, numbered tracks, cover art, and whatever metadata the source file carries. With CrateDigger-tagged sources you also get canonical artist names, festival and venue details, MusicBrainz IDs for every artist, and per-track genre. That richer metadata is what lets Jellyfin and Lyrion link artists, albums, and collaborators correctly across your library.

See Getting Started for more on how the two tools work together.

My video has no chapters. What happens?

If the video has a readable duration, TrackSplit produces a single-track album covering the whole file. If it cannot read the duration either, the file is skipped with a warning.

If you expected chapters but there are none, the source may have had them stripped by a downloader or remuxer. CrateDigger can identify recordings and embed chapter markers automatically. You can also add chapters manually with MKVToolNix.

Why is there no 00 - Intro track even though the first chapter starts after 0:00?

If the gap between the start of the file and the first chapter is less than 5 seconds, TrackSplit folds that audio into track 1 instead of creating a standalone intro track. This avoids very short "Intro" files that are not musically meaningful. Gaps of 5 seconds or longer still produce a 00 - Intro track.

A file was skipped even though I expected it to be processed. Why?

Two common reasons:

  1. The output is already up to date. TrackSplit keeps a record of the last run in each album folder (the manifest). If the identity, audio, chapters, metadata, and format are all unchanged, the album is skipped. Pass --force to rebuild it anyway.
  2. No audio stream or zero duration. TrackSplit warns and moves on.

Re-run with --verbose to see which reason triggered.

Why doesn't reorganizing my CrateDigger library re-split everything anymore?

TrackSplit now identifies each album by the stable CrateDigger 1001Tracklists ID (CRATEDIGGER_1001TL_ID) embedded in the source MKV, not by the source file path. When you reorganize your library (move files to a new folder, rename the library root, or restructure year/artist subdirectories), the identity stays the same. TrackSplit finds the album by its ID, notes that the path changed, updates the stored path in the manifest, and moves on without re-splitting or re-tagging anything.

For sources that do not carry the CrateDigger ID tag, TrackSplit falls back to 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)) and chapter boundaries. This is less precise: if the audio or chapters differ from the stored fingerprint, a re-split follows as before. Re-enriching the source with a current CrateDigger version embeds the stable ID and removes this ambiguity.

When does TrackSplit re-split vs. just re-tag or rename?

TrackSplit always chooses the cheapest operation that brings the album up to date:

  • Skip: nothing changed. The album folder and all track files stay exactly as they are.
  • Path refresh only: the source MKV moved or was renamed, but the recording is the same (same CrateDigger ID or audio fingerprint). The manifest is updated to record the new path. No audio files or tags change.
  • Retag: per-track or album-level metadata changed (label, genre, MBIDs, artist spelling, etc.). The existing audio files are opened and their tag blocks are rewritten. Audio data is not touched and no new audio file is written.
  • Rename + retag: a track title or performer changed. The track file is renamed to match the new title and its tags are rewritten. Audio is not re-extracted.
  • Move + retag: the album folder name changed (because the artist, festival, venue, or stage name changed). The album folder is moved to its new location and tags are rewritten inside it. Audio is not re-extracted.
  • Full re-split: the audio itself must change. This happens when: the audio stream changed (re-encode, different codec, different sample rate, channels, or time base), the output format or codec mode changed, the number of tracks changed, or a chapter boundary (start or end time) moved.

A full re-split is always the most expensive path. TrackSplit only takes it when the audio output would genuinely differ from what is already on disk.

Can I delete .tracksplit_manifest.json?

Yes. It is only used by TrackSplit to decide whether to skip an album on the next run. Delete it to force a full rebuild of that album. You do not need to back it up, and your music server ignores it entirely.

Does TrackSplit modify my source videos?

No. TrackSplit only reads your source files. All output goes to the directory you specify with --output, or your current working directory if you omit it. Your source videos are never touched.

Can I change the folder or filename template?

Not yet. For CrateDigger-tagged sources the album folder is named Festival Year (Stage) when a festival tag is present, or Venue Year (or Location Year when only a location tag is present) for venue recordings without a festival name. Plain chaptered videos use the source filename. The album folder is always placed inside an Artist/ folder. Track filenames follow NN - Title. The template is fixed in the current release.

Does it need the internet?

No. TrackSplit is fully offline. It reads metadata from your source files and does all processing locally. No API keys, no external lookups.

Parallel mode is slow on my disk. What do I do?

Try --workers 1 first. On spinning disks and network shares, sequential processing is usually faster because parallel writes cause expensive disk seeks.

On fast SSDs, the default (roughly logical_cores / 4, between 2 and 12) is a good starting point. You can push it higher if your sources use Opus audio, because in that case TrackSplit copies the audio directly without re-encoding and CPU usage per worker is near zero. If your sources require re-encoding (FLAC output or Opus from a lossy source), raising workers beyond the default risks overloading your CPU.

See Troubleshooting for a full breakdown.

How do Jellyfin and Lyrion show multi-artist tracks?

TrackSplit writes a multi-value ARTISTS tag listing every individual contributor alongside the display ARTIST string. It also writes a positionally-aligned MUSICBRAINZ_ARTISTID tag so each artist links to their own page. Both Jellyfin and Lyrion read these tags and surface every collaborator, not just the headliner.

If you upgraded TrackSplit and re-ran it against existing albums, trigger a library rescan in your music server so it picks up the updated tags.

Does TrackSplit produce gapless output?

Yes, for both output formats, subject to player support.

FLAC: gapless in any player that handles FLAC correctly.

Opus: gapless in players that support gapless playback, such as Symfonium and mpv. TrackSplit inserts the necessary warmup frame and sets the correct pre_skip value so the decoder trims it cleanly at each boundary. The Jellyfin mobile app does not support gapless playback and introduces a 1-2s gap between tracks regardless of file content. That gap is a player-side limitation and cannot be fixed at the file level.

How does TrackSplit differ from CrateDigger?

They do different jobs and work best together. CrateDigger builds a video library: it identifies recordings, embeds chapter markers and metadata, generates posters, and syncs with Kodi. TrackSplit reads that video library and produces a parallel music library of tagged FLAC or Opus albums for music servers like Jellyfin and Lyrion.

Because they share the same artist names, festival spellings, and MusicBrainz IDs, the same set shows up consistently whether you are browsing your video library or your music library.

What is the yellow "!" message on startup?

That message means a newer release of TrackSplit is available on GitHub. The line shows the new version number and an upgrade command suited to your install method.

To upgrade, run the command printed in the notice. The three common variants are:

  • pipx: pipx upgrade tracksplit
  • uv: uv tool upgrade tracksplit
  • pip: pip install --upgrade git+https://github.com/Rouzax/TrackSplit.git

To silence the notice, set TRACKSPLIT_NO_UPDATE_CHECK=1 in your environment (the values true and yes are also accepted, case-insensitively). The notice is already suppressed automatically whenever stdout is not a terminal, such as in pipes, redirects, cron jobs, and CI environments.

The check involves no telemetry. It is a standard read-only request to the GitHub Releases API, results are cached locally for 24 hours, and the check never delays or blocks your run. If the network is unreachable, TrackSplit continues silently.