Metadata-Version: 2.4
Name: mkvunlink
Version: 0.1.0
Summary: Merge linked MKV segments (ordered chapters, hard linking) into standalone files
Project-URL: Repository, https://github.com/JanitorialMess/mkvunlink
Project-URL: Issues, https://github.com/JanitorialMess/mkvunlink/issues
Author: JanitorialMess
License-Expression: MIT
License-File: LICENSE
Keywords: matroska,mkv,mkvmerge,ordered-chapters,segment-linking
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Video :: Conversion
Requires-Python: >=3.9
Requires-Dist: pysubs2>=1.6
Description-Content-Type: text/markdown

# 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](https://mkvtoolnix.download/) v52 or later and
[FFmpeg](https://ffmpeg.org/) 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
