mkvunlink 0.1.0

Merge linked MKV segments (ordered chapters, hard linking) into standalone files

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:

Windows	winget install MKVToolNix.MKVToolNix Gyan.FFmpeg
macOS	brew install mkvtoolnix ffmpeg
Debian/Ubuntu	apt install mkvtoolnix ffmpeg
Arch	pacman -S mkvtoolnix-cli ffmpeg

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.

Option
--outdir DIR	output directory, created if missing
--edition N	1-based edition to flatten when the file has several
--no-verify	skip the decoded-checksum check of re-encoded audio
--keep-temp	keep the working directory for inspection

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