Usage
TrackSplit takes a video file or a directory of video files and writes one tagged album per input.
Synopsis
INPUT_PATH is either a video file or a directory. Recognised video extensions: .mkv, .mp4, .webm, .avi, .mov, .m2ts, .ts, .flv.
Options
| Flag | Description |
|---|---|
--output, -o PATH |
Output directory. Defaults to the current working directory. |
--force |
Regenerate even if the per-album manifest matches. |
--format, -f {auto,flac,opus} |
Output codec. auto picks FLAC for lossless sources and Opus for lossy. |
--workers, -w N |
Parallel workers for directory mode. Default scales with CPU: logical_cores // 4, clamped to [2, 12] (so 2 on a dual-core laptop, 4 on a 16-thread workstation, 10 on a 40-thread server). Set 1 for sequential; raise for stream-copy batches (see Troubleshooting). |
--dry-run |
Probe and plan without writing anything. Pairs well with --verbose. |
--verbose, -v |
INFO-level logging. Shows the current step and file. |
--debug |
DEBUG-level logging. Includes full command lines and subprocess details. |
--check |
Probe ffmpeg/ffprobe/mkvextract and exit. |
--help, -h |
Show the auto-generated help. |
Examples
Single file, sensible defaults:
Batch a folder into a music library:
Force Opus output regardless of source:
Preview what would happen without writing anything:
Rebuild an album even if nothing changed:
Serial processing on a slow disk:
Progress display
- Single file: a spinner shows the current pipeline step (probing, extracting, splitting, tagging, saving) and ends with a one-line summary naming the album directory and track count.
- Directory: a live progress bar shows
completed/total, with one spinner line per active worker. A summary panel at the end breaks down processed / skipped / failed / cancelled counts.
Errors and cancellation
Failures that have a known cause (missing tool, disk full, FFmpeg subprocess error) are printed as a one-line reason. Full tracebacks are kept behind --debug.
Pressing Ctrl+C sets a cancellation flag, kills in-flight FFmpeg subprocesses, and reports any in-flight files as cancelled in the summary.