Add Chapters to Video with FFmpeg Metadata File

Adding chapters to your video files improves navigation and user experience, especially for long-form content. This guide provides a direct, step-by-step tutorial on how to write custom chapter markers in an external text file and merge them into your MP4 or MKV videos using FFmpeg without re-encoding.

Step 1: Create the Chapter Metadata File

FFmpeg uses a specific text format called FFMETADATA to define chapters. Create a new text file named chapters.txt and open it in any text editor.

Paste the following structure into the file:

;FFMETADATA1

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

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

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

Understanding the Metadata Fields:

• ;FFMETADATA1: This header must be at the very beginning of the file.
• [CHAPTER]: This header defines the start of a new chapter block.
• TIMEBASE: This defines the time unit. Using 1/1000 means your start and end times will be calculated in milliseconds (1 second = 1000).
• START: The starting time of the chapter (in milliseconds).
• END: The ending time of the chapter (in milliseconds).
• title: The name of the chapter that will display in media players.

Step 2: Merge the Chapters into the Video

Once your chapters.txt file is saved in the same directory as your video, open your terminal or command prompt and run the following FFmpeg command:

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

Command Breakdown:

• -i input.mp4: Specifies your original video file.
• -i chapters.txt: Specifies your external metadata text file.
• -map_metadata 1: Tells FFmpeg to write the metadata from the second input file (index 1, which is chapters.txt) into the output file.
• -codec copy: Copies the video and audio streams directly without re-encoding them. This ensures the process is completed almost instantly and without any loss in video quality.
• output.mp4: The final video file containing your custom chapter markers.