logo api.video

Adding chapters to your videos

April 3, 2020 - Doug Sillars in Chapters

When uploading a long video, it can be hard for your viewers to scan to the area of the video they are interested in. Rather than chop your video into smaller segments (and breaking up the continuity of the entire video), you can use chapters to denote placeholders in your video so that your viewers can ‘skip ahead’ or ‘skip back’ to pertinent sections that they want to watch again.

As an example for this post, I’m going to share a video my daughter made for her astronomy class. In order to show the distance from the sun to the various planets in the Solar System, she used her GPS and walked through our neighborhood placing the planets. The distance between each planet was scaled based on the size of the sun in her model. It is a good study of logarithmic distances:

Video chapter

The video was 35 minutes long. We knew that her teacher would not watch this, so we edited the video so that all of the walking bits were 3x faster than when she was standing at each planet. It was still 13 minutes long. This seemed like a prime example of a video suited for chapters, since it was hard to know when a planet was being placed.


Chapters are markers that appear in the video timeline, and help the viewer see different sections of your video.

Add chapters to videos

In this screenshot, we can see that we are at the “Saturn” section in the video, both from the content on the screen, but also by the annotation on the playback bar. We can also guess that the next chapters are for Uranus, and the last chapter is marking Neptune. (The chapters for the closer-in planets are under the playback bar)

How do we add chapters? With api.video, we simply create a VTT file (the same format that is used for captions with time markers and names for each chapter. In my daughters video, we only named the sections near the planets and left the time traveling space blank:

video timeframe

I ran the VTT file through a VTT validator to ensure all the formatting was correct, and then uploaded to api.video using the api command:

curl -X POST https://ws.api.video/videos/vi16NDdXmGxk5QSggW54qw0v/chapters/en  -H 'Authorization: Bearer {access_token}' -F file=@/path/to/planets.vtt

After the /video/ path in the URL os the videoId that the captions are associated with, and the en and the end means that they are in english. I used my access token read about how to get your api.video access token, and then finally the path the to planets.vtt file on my local computer.

That’s it! Frankly, the chapter markers on the playback timeline show the logarithmic nature of the distances in the solar system almost as well as my daughter’s video.


For longer videos, your viewers might be interested in skipping to different sections of the video. Providing chapter markers makes this easier for them. What are your experiences with adding or using chapters in videos? Leave us a note in our developer community to let us know!


Doug Sillars

Head of Developer Relations

Doug Twitter