mkv-chapter-helper.py - Embed chapters into an MKV file with the ability to mix timecodes and chapter names from multiple sources

Installation

pip 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.

Common use case:

• 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
• Simply use --timecodes-mkv to use the existing timescodes in your MKV file and then download the ChapterDB txt file and use --timecodes-txt-file

Note: The XML download from ChapterDB is not in the correct format for this script. Only download TXT from ChapterDB.

Alternative use-case: the chapters are not found on ChapterDB, but the correct chapters are found in a private torrent tracker via provided Mediainfo dump. There are options to get timecodes or names from Mediainfo.

Not Supported:

• Using a text file generated by Mediainfo. It only supports copy and paste input. Multi-line paste should work across terminals.
• Any text file format other than OGM
• Any XML file format other than the Matroska standard outlined here: https://www.matroska.org/technical/chapters.html
• Getting timecodes/names from another MKV file than the one you are manipulating

As an alternative to the last bullet point, you can extract XML chapters from another MKV file via mkvextract or MKVToolnix-GUI and then use one of the XML flags

External Dependencies

• mkvmerge
• mkvpropedit

Both must be in PATH as you run the script

Options

You can view the arguments by running mkv-chapter-helper --help

usage: mkv-chapter-helper [-h] (--timecodes-mkv | --timecodes-mediainfo | --timecodes-xml-file TIMECODES_XML_FILE | --timecodes-txt-file TIMECODES_TXT_FILE)
                          (--names-mkv | --names-mediainfo | --names-xml-file NAMES_XML_FILE | --names-txt-file NAMES_TXT_FILE)
                          input

Add/modify chapters in an MKV file

positional arguments:
  input                 MKV file to manipulate

options:
  -h, --help            show this help message and exit
  --timecodes-mkv, -tk  Use timecodes from input MKV file
  --timecodes-mediainfo, -tm
                        Use timecodes from Mediainfo
  --timecodes-xml-file TIMECODES_XML_FILE, -tx TIMECODES_XML_FILE
                        Use timecodes from input XML file
  --timecodes-txt-file TIMECODES_TXT_FILE, -tt TIMECODES_TXT_FILE
                        Use timecodes from input TXT file (OGM format only)
  --names-mkv, -nk      Use names from input MKV file
  --names-mediainfo, -nm
                        Use names from Mediainfo
  --names-xml-file NAMES_XML_FILE, -nx NAMES_XML_FILE
                        Use names from input XML file
  --names-txt-file NAMES_TXT_FILE, -nt NAMES_TXT_FILE
                        Use names from input TXT file (OGM format only)