mkvunlink

Merge linked MKV segments into standalone files.

Matroska can store content once and have several files reference it, through two linking mechanisms:

• Ordered chapters with segment linking: the chapter list is a playlist whose entries can point into other files by segment UID.
• Hard linking: the segment header names a previous and/or next segment, chaining whole files together.

Players that implement linking (mpv, MPC-HC) stitch the pieces together at playback. Everything else plays the file alone, with the linked content missing. mkvunlink resolves the linked timeline the way mpv does and writes it as a single self-contained file that plays anywhere.

Requirements

MKVToolNix v52 or later and FFmpeg on PATH:

The MKVToolNix installer on Windows may not add itself to PATH; add its folder (C:\Program Files\MKVToolNix) manually.

Installation

uv tool install mkvunlink

or using pip

pip install mkvunlink

Usage

mkvunlink 'Episode 01.mkv'
mkvunlink --outdir flattened /path/to/series
mkvunlink --edition 2 'Movie.mkv'

The linked segment files must be in the same directory as the files that reference them. Output goes to ./unlinked unless --outdir is given.

Behavior

• Video and bitmap subtitles (PGS/VobSub) are stream copied.
• Audio is stream copied. Codecs mkvmerge cannot split or append (FLAC) are rebuilt with ffmpeg instead: lossless codecs are cut sample-accurately and re-encoded to the same codec, then checked against the sources by decoded checksum; lossy codecs are copied per span without re-encoding.
• Text subtitles (ASS/SRT) are merged onto the joined timeline. Styles keep their names; a style is aliased only when two sources define the same name differently. Segments typeset at a different PlayRes have their styles resampled.
• Chapters are regenerated at the joined positions with their display names in every language. Title, global tags, attachments and track metadata carry over from the main file.
• Multiple editions produce a warning; --edition selects one.

Limitations

• Segments whose video encoding parameters differ cannot be appended by mkvmerge; mkvunlink reports the error rather than transcoding video.
• WebVTT subtitles are downgraded to SRT, losing cue positioning and styling.
• A flattened file embodies one edition; run once per edition for multi-edition files.

Troubleshooting

An audio track whose header reports no sampling frequency fails the run, and PCM with a missing bit depth is stream copied per span instead of rebuilt sample-accurately. Both header fields can be repaired in place with mkvpropedit, which ships with MKVToolNix.

For example, a 48 kHz 24-bit PCM track is fixed with:

mkvpropedit broken.mkv --edit track:a1 --set sampling-frequency=48000
mkvpropedit broken.mkv --edit track:a1 --set bit-depth=24

License

MIT