Adding Chapters to Videos Using MKV Containers

Matroska (.mkv) is still the easiest container to carry chapters, and the mkvtoolnix command-line tools still read the same simple chapter text format they did in 2010. What changed since this was written: you no longer remux to add, replace or remove chapters, because mkvpropedit edits them in place, and mkvextract hands them back out in the same text format.

Install

sudo apt install mkvtoolnix

mkvtoolnix-gui is the graphical front end; everything below is the CLI.

Write a chapter file

One CHAPTERnn= line with the start time and one CHAPTERnnNAME= line per chapter, times as HH:MM:SS.mmm:

cat > chapters.txt <<'EOF'
CHAPTER01=00:00:00.000
CHAPTER01NAME=Intro
CHAPTER02=00:05:00.000
CHAPTER02NAME=Middle
CHAPTER03=00:15:00.000
CHAPTER03NAME=End
EOF

To take the chapters from a DVD instead of typing them, dvdxchap from the ogmtools package (still in the Ubuntu repositories) prints exactly this format from a disc, a VIDEO_TS folder or an ISO:

sudo apt install ogmtools
dvdxchap /dev/dvd > chapters.txt
dvdxchap ./VIDEO_TS/ > chapters.txt
dvdxchap video.iso > chapters.txt

Mux a new MKV with chapters

mkvmerge -o video.mkv --chapters chapters.txt video.mp4

The input can be AVI, MP4, OGM or anything else mkvmerge reads. The 2014 habit of setting a default language and switching off header compression still works and the syntax is unchanged; track IDs start at 0:

mkvmerge -o video.mkv --default-language eng --compression 0:none --compression 1:none --chapters chapters.txt video.mp4

Add or replace chapters without remuxing

This is the part missing from the 2014 text, and a reader (kaecy, 2021) pointed it out: mkvpropedit writes the chapters into the existing file in seconds and replaces whatever chapters were there, so you never end up with two chapter editions that players cannot handle.

mkvpropedit video.mkv --chapters chapters.txt

Remove the chapters with an empty file name:

mkvpropedit video.mkv --chapters ''

Check and export

mkvmerge -i video.mkv

File 'video.mkv': container: Matroska
Track ID 0: video (AVC/H.264/MPEG-4p10)
Track ID 1: audio (AAC)
Chapters: 3 entries

Export the chapters back out, as Matroska XML or as the simple text format (-s):

mkvextract video.mkv chapters chapters.xml
mkvextract video.mkv chapters -s chapters.txt

Note the modern mkvextract argument order: source file first, then the mode. mkvinfo video.mkv still dumps the whole structure, chapter atoms included, when you need to see the raw EBML.

Any player that understands Matroska chapters (VLC, mpv, Kodi, most TVs and the odd media box) lets you jump between them.

If you would like to add chapters to your video files, such as XviD, x264, OGG, etc., simply use the Matroska multimedia container format.

For those of you that have never created Matroska files, visit the Matroska website to find the right software for your platform. If you’re using Ubuntu Linux, install the mkvtoolnix package from the repositories. It contains all the tools you need to start working with MKV files.

sudo apt-get-install mkvtoolnix

The easiest method of creating your chapter definitions is with any text editor, using the following format. Feel free to change the name and time values accordingly. Save the file anywhere you can remember, e.g. chapter.txt.

CHAPTER01=00:00:00.000

CHAPTER01NAME=Chapter 01

CHAPTER02=00:05:00.000

CHAPTER02NAME=Chapter 02

CHAPTER03=00:10:00.000

CHAPTER03NAME=Chapter 03

CHAPTER04=00:15:00.000

CHAPTER04NAME=Chapter 04

CHAPTER05=00:20:00.000

CHAPTER05NAME=Chapter 05

If you want to create a chapter file from an existing DVD, dvdxchap is a great tool for the job if you’re using Linux. It’s part of the ogmtools package. For more info, check out the OGMtools project web site.

Installation and three examples of how to use the tool are below.

sudo apt-get install ogmtools
dvdxchap /dev/dvd > chapter.txt

dvdxchap ./VIDEO_TS/ > chapter.txt

dvdxchap video.iso > chapter.txt

mkvmerge is the only tool you need to create an MKV file. In the following examples, your source video file is called video.avi, and your destination file is video.mkv.

A simplified version of the mkvmerge syntax is as follows.

mkvmerge video.avi --chapters chapter.txt -o video.mkv

I typically like to set my default language to English, and also turn off header compression for all tracks since some players don’t play nicely with compression enabled. The syntax and example output is displayed below.

mkvmerge video.avi --default-language eng

--compression -1:none --chapters chapter.txt -o video.mkv

mkvmerge v4.2.0 ('No Talking') built on Jul 28 2010 16:47:39

'video.avi': Using the AVI demultiplexer. Opening file. This may take some time depending on the file's size.

'video.avi' track 0: Using the MPEG-4 part 2 video output module.

'video.avi' track 1: Using the MPEG audio output module.

The file 'video.mkv' has been opened for writing.

'video.avi' track 0: Extracted the aspect ratio information from the MPEG4 layer 2 video data and set the display dimensions to 712/416.

Progress: 100%

The cue entries (the index) are being written...

Muxing took 30 seconds.

That’s really all there is to it. Now any media player that supports MKV chapters will allow you to navigate them. My favorites are VLC, Mplayer, and my Western Digital media player, the WD TV Live Plus.

Verify the contents of your MKV using mkvmerge or mkvinfo.

mkvmerge -i video.mkv

File 'video.mkv': container: Matroska

Track ID 1: video (V_MS/VFW/FOURCC, XVID)

Track ID 2: audio (A_MPEG/L3)

Chapters: 13 entries
mkvinfo video.mkv

+ EBML head

|+ EBML version: 1

|+ EBML read version: 1

|+ EBML maximum ID length: 4

|+ EBML maximum size length: 8

|+ Doc type: matroska

|+ Doc type version: 2

|+ Doc type read version: 2

+ Segment, size 1325519138

|+ Seek head (subentries will be skipped)

|+ EbmlVoid (size: 4029)

|+ Segment information

| + Timecode scale: 1000000

| + Muxing application: libebml v1.0.0 + libmatroska v1.0.0

| + Writing application: mkvmerge v4.2.0 ('No Talking') built on Jul 28 2010 16:47:39

| + Duration: 5004.680s (01:23:24.680)

| + Date: Thu Aug 5 00:26:03 2010 UTC

| + Segment UID: 0x81 0x4b 0xc4 0xf1 0xf4 0x5b 0x6d 0xda 0xc5 0x40 0xc1 0x03 0x3f 0x36 0x0f 0xd9

|+ Segment tracks

| + A track

| + Track number: 1

| + Track UID: 1318207700

| + Track type: video

| + Lacing flag: 0

| + MinCache: 1

| + Codec ID: V_MS/VFW/FOURCC

| + CodecPrivate, length 40 (FourCC: XVID, 0x44495658)

| + Default duration: 40.000ms (25.000 fps for a video track)

| + Video track

| + Pixel width: 480

| + Pixel height: 416

| + Display width: 712

| + Display height: 416

| + A track

| + Track number: 2

| + Track UID: 3206714560

| + Track type: audio

| + Codec ID: A_MPEG/L3

| + Default duration: 24.000ms (41.667 fps for a video track)

| + Audio track

| + Sampling frequency: 48000

| + Channels: 2

|+ EbmlVoid (size: 1099)

|+ Chapters

| + EditionEntry

| + EditionFlagHidden: 0

| + EditionFlagDefault: 0

| + EditionUID: 585228242

| + ChapterAtom

| + ChapterUID: 4059317607

| + ChapterTimeStart: 00:00:00.000000000

| + ChapterFlagHidden: 0

| + ChapterFlagEnabled: 1

| + ChapterDisplay

| + ChapterString: Chapter 01

| + ChapterLanguage: eng

| + ChapterAtom

| + ChapterUID: 3065648262

| + ChapterTimeStart: 00:05:00.000000000

| + ChapterFlagHidden: 0

| + ChapterFlagEnabled: 1

| + ChapterDisplay

| + ChapterString: Chapter 02

| + ChapterLanguage: eng

| + ChapterAtom

| + ChapterUID: 2388361707

| + ChapterTimeStart: 00:10:00.000000000

| + ChapterFlagHidden: 0

| + ChapterFlagEnabled: 1

| + ChapterDisplay

| + ChapterString: Chapter 03

| + ChapterLanguage: eng

| + ChapterAtom

| + ChapterUID: 1448933008

| + ChapterTimeStart: 00:15:00.000000000

| + ChapterFlagHidden: 0

| + ChapterFlagEnabled: 1

| + ChapterDisplay

| + ChapterString: Chapter 04

| + ChapterLanguage: eng

| + ChapterAtom

| + ChapterUID: 1319721142

| + ChapterTimeStart: 00:20:00.000000000

| + ChapterFlagHidden: 0

| + ChapterFlagEnabled: 1

| + ChapterDisplay

| + ChapterString: Chapter 05

| + ChapterLanguage: eng

|+ EbmlVoid (size: 101)

|+ Cluster