Add Chapters to Video with FFmpeg and Text File

Adding chapter markers to your videos improves navigation and user experience for your viewers. This guide provides a direct, step-by-step walkthrough on how to write custom chapter metadata into a simple text file and merge it directly into a video file using the powerful command-line tool FFmpeg.

Step 1: Create the Metadata Text File

FFmpeg uses a specific metadata format to define chapters. Open a plain text editor (like Notepad, TextEdit, or VS Code) and create a new file named chapters.txt.

Paste the following template into the file:

;FFMETADATA1
title=My Video

[CHAPTER]
TIMEBASE=1/1000
START=0
END=15000
title=Introduction

[CHAPTER]
TIMEBASE=1/1000
START=15000
END=45000
title=Getting Started

[CHAPTER]
TIMEBASE=1/1000
START=45000
END=120000
title=Conclusion

Understanding the Metadata Format:

• ;FFMETADATA1: This header tells FFmpeg that this is a metadata file. It must be on the very first line.
• [CHAPTER]: This header defines the start of a new chapter.
• TIMEBASE=1/1000: This defines the time unit. Using 1/1000 means the times are calculated in milliseconds (1 second = 1000).
• START: The start time of the chapter in milliseconds (e.g., 15000 is 15 seconds).
• END: The end time of the chapter in milliseconds.
• title: The display name of the chapter.

Save and close the chapters.txt file in the same folder as your video.

Step 2: Merge the Chapters into the Video

To merge the metadata file into your video without re-encoding (which ensures no loss of video quality and takes only a few seconds), use the FFmpeg command line.

Open your terminal or command prompt, navigate to the folder containing your video and chapters.txt, and run the following command:

ffmpeg -i input.mp4 -i chapters.txt -map_metadata 1 -c copy output.mp4

Command Breakdown:

• -i input.mp4: Specifies your original video file as the first input (index 0).
• -i chapters.txt: Specifies your metadata file as the second input (index 1).
• -map_metadata 1: Tells FFmpeg to write the global and chapter metadata from the second input (index 1, the text file) to the output file.
• -c copy: Copies the video and audio streams without re-encoding them.
• output.mp4: The name of your new video file containing the chapters.

Once the command finishes running, you will have a new video file called output.mp4 with your custom chapters embedded. You can verify the chapters by playing the video in media players like VLC or MPC-HC.