Add chapter markers to an MP4

Each container keeps chapters in its own way, but the content is always the same: a start time (and often an end time) plus a title for each section.

• MP4 and MOV: the usual form is a small text track holding one sample per chapter, linked from the video track. Apple’s players use it, and so do VLC and many others. Some files also carry an older chapter list box from Nero’s software.
• MKV and WebM: a dedicated Chapters element with editions, start and end times and names in several languages if needed.
• AVI and MPEG-TS: no standard place for chapters.

Because chapters change the track layout, they are written with ffmpeg.wasm, a build of FFmpeg that runs in your browser. It copies every stream as it is (no re-encode) and rebuilds the container with the new chapter list. On long files this takes a little longer than a plain tag edit, which only rewrites metadata boxes.

A chapter starts at the time you give it, but a player can only begin decoding from a key frame. Some players therefore land up to a second or two before the chapter. That is normal and not a fault in the chapter list.

• Start with a chapter at 0:00, even if it is just “Introduction”, so the whole video belongs to a chapter. YouTube requires the same if you reuse the list there.
• Keep titles short enough to read in a menu: “Q&A”, “Setting up the camera”, “Day 2: Lake District”.
• Use the times people will want to jump to, not every small change. For a one-hour talk, six to twelve chapters is plenty.
• Each chapter runs until the next one starts, so you only need start times.

If you are not sure where sections begin, Find scene changes in AI insights lists the cuts in the video, worked out on your device, which makes a good first draft for a recorded event.

YouTube ignores chapters embedded in an uploaded file. Its help pages say chapters come from timestamps you list in the video description, and they set three rules: the first timestamp must be 00:00, there must be at least three timestamps in ascending order, and each chapter must be at least 10 seconds long. YouTube can also make automatic chapters, but your own timestamps take priority.

              00:00 Introduction
02:15 Setting up the camera
07:40 Recording the first take
15:05 Questions
            

If you are publishing the same video both as a download and on YouTube, keep one chapter list and use it in both places: type the times into the file here, and paste them into the description in the format above.

On the command line, FFmpeg reads chapters from a small text file in its FFMETADATA format. Times here are in milliseconds because of the TIMEBASE line:

              ;FFMETADATA1
[CHAPTER]
TIMEBASE=1/1000
START=0
END=135000
title=Introduction
[CHAPTER]
TIMEBASE=1/1000
START=135000
END=460000
title=Setting up the camera
            

              ffmpeg -i talk.mp4 -i chapters.txt -map 0 -map_metadata 0 -map_chapters 1 -c copy talk-chapters.mp4
            

-map_chapters 1 takes the chapters from the second input (the text file) and -c copy keeps the streams as they are. Special characters in titles (=, ;, #, \) need a backslash in front. For MKV files, MKVToolNix replaces a file’s chapters in place with mkvpropedit film.mkv --chapters chapters.xml.

Steps in short

1. Write the chapter file with a start and end for every chapter.
2. Run the FFmpeg command above.
3. Check the result with ffprobe’s -show_chapters option or by opening it here.