Metadata-Version: 2.4
Name: mkv-chapter-helper
Version: 1.0.1
Summary: Embed chapters into an MKV file with the ability to mix timecodes and chapter names from multiple sources.
Author-email: nateify <nateify@users.noreply.github.com>
License-File: LICENSE
Keywords: automation,chaptergrabber,chapters,cli,matroska,media,mediainfo,metadata,mkv,ogm,remux,video,xml
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown

`mkv-chapter-helper` -  Add/update chapters in an MKV file with the ability to mix timecodes and chapter names from multiple sources 

# Installation
pip:

    pip install mkv-chapter-helper

pipx:

    pipx install mkv-chapter-helper

uv:

    uv tool install mkv-chapter-helper

# Description
mkv-chapter-helper allows you to choose different sources for correct timecodes and correct names for chapters to embed in an MKV file.

**Supported inputs:**
- The input MKV file or another MKV file
- TXT in OGM format or exported from MediaInfo
- XML in Matroska format: https://www.matroska.org/technical/chapters.html
- XML generated by ChapterGrabber
- MediaInfo chapters pasted into the console

If you have a need for other chapter sources, they may be converted by [chapterEditor](https://forum.doom9.org/showthread.php?t=169984).

## Use Cases

You have ripped your own movie to MKV, so the timecodes are correct, but you did not want to manually write out all chapter names

- There exists a pre-named chapters list on https://chapterdb.plex.tv/ but the timecodes do not line up
- Download the TXT from ChapterDB and specify `--names-from-ogm`

Alternatively:

- You have an MKV with no chapters, but can find them provided in a MediaInfo dump on a torrent tracker.
- You can use `--timecodes-from-mediainfo-paste` and `--names-from-mediainfo-paste` and paste the values in the console interactively.

# External Dependencies

- mkvmerge
- mkvpropedit

Path can be retrieved via one of the following:

1. Supplied by `--mkvextract-path` and/or `--mkvpropedit-path`
2. Found in `PATH`
3. Defined in the environment variables `MKVEXTRACT_PATH` and/or `MKVPROPEDIT_PATH`

# Options     

```
usage: mkv-chapter-helper [-h] (-tS | -tM FILE | -tX FILE | -tC FILE | -tO FILE | -tI FILE | -tP) (-nS | -nM FILE | -nX FILE | -nC FILE | -nO FILE | -nI FILE | -nP) [--mkvpropedit-path PATH] [--mkvextract-path PATH] input

Add/modify chapters in an MKV file

positional arguments:
  input                 MKV file to be modified

options:
  -h, --help            show this help message and exit

Timecode source (one is required):
  -tS, --timecodes-from-source
                        Use timecodes from the input MKV file
  -tM, --timecodes-from-mkv FILE
                        Use timecodes from a different MKV file
  -tX, --timecodes-from-matroska-xml FILE
                        Use timecodes from a Matroska XML file
  -tC, --timecodes-from-cg-xml FILE
                        Use timecodes from a ChapterGrabber XML file
  -tO, --timecodes-from-ogm FILE
                        Use timecodes from an OGM chapter TXT file
  -tI, --timecodes-from-mediainfo-file FILE
                        Use timecodes from a MediaInfo TXT report file
  -tP, --timecodes-from-mediainfo-paste
                        Use timecodes from pasted MediaInfo menu content

Chapter name source (one is required):
  -nS, --names-from-source
                        Use chapter names from the input MKV file
  -nM, --names-from-mkv FILE
                        Use chapter names from a different MKV file
  -nX, --names-from-matroska-xml FILE
                        Use chapter names from a Matroska XML file
  -nC, --names-from-cg-xml FILE
                        Use chapter names from a ChapterGrabber XML file
  -nO, --names-from-ogm FILE
                        Use chapter names from an OGM chapter TXT file
  -nI, --names-from-mediainfo-file FILE
                        Use chapter names from a MediaInfo TXT report file
  -nP, --names-from-mediainfo-paste
                        Use chapter names from pasted MediaInfo menu content

Tool paths (optional):
  --mkvpropedit-path PATH
                        Path to the mkvpropedit executable
  --mkvextract-path PATH
                        Path to the mkvextract executable
```