Chapters

Player SDK

Normal

doug.jpg

twitter-brands.svg

Doug Twitter

Doug Sillars

Tutorials

JavaScript

When reading a book, chapters help the reader understand a change has taken place - perhaps a new narrator, or a different point of view is used in each chapter.


Chapters in videos can be used in much the same way. If you need a specific moment in a long video, chapter titles may help you quickly find the part of the video you were looking for.  Here at api.video, we have a native chapter ability in our video player:

In the above version of Big Buck Bunny, I have added several chapters.  This is done with a VTT file.  It looks like this:

```
WEBVTT

1
00:00:34.000 --> 00:01:17.000
Bunny wakes up.

2
00:01:17.000 --> 00:02:30.000
Butterfly 1

3
00:02:30.000 --> 00:04:12.000
Plotting
4
00:04:12.000 --> 00:05:15.000
Construction

5
00:05:15.000 --> 00:05:42.000
Bow

6
00:05:42.000 --> 00:06:35.000
Falling Stuff

7
00:06:35.000 --> 00:07:42.000
Flying Squirrel


8
00:07:42.000 --> 00:09:41.000
Kite

9
00:09:41.000 --> 00:09:42.000
Post Credits

```

These intervals in the VTT file are shown as sections on the playback line at the bottom of the player, and clicking the chapter button lists them all.

## But what if you want an External button?

Super easy.  Using the Player SDK, you can seek to any time you wish.  So, as an example, you can create a series of buttons:

```
    <button id ="bunnyWakes">Bunny wakes</button><br/>
        <button id ="Butterfly">Butterfly</button><br/>
        <button id ="Plotting">Plotting</button><br/>
        <button id ="Construction">Construction</button><br/>
        <button id ="Bow">Bow</button><br/>
        <button id ="Falling">Falling Stuff</button><br/>
        <button id ="FlyingSquirrel">FlyingSquirrel</button><br/>
        <button id ="Kite">Kite</button><br/>
        <button id ="Post">Post Credits</button><br/>
```

Now, we can use an eventListener on these buttons, and using the api.video Player SDK, we can seek to the required time.  Here's the JavaScript that makes this magic happen:

```
      window.player = new PlayerSdk("#target", { 
            id: "vi1UQBDAMqAPCRxB3dmw1thc", 
            autoplay:true,
            muted:true
        });
        
        window.onload = function(){
            document.getElementById("bunnyWakes").addEventListener("click", function() {
                player.setCurrentTime(34);
            });
            document.getElementById("Butterfly").addEventListener("click", function() {
                player.setCurrentTime(77);
            });
            document.getElementById("Plotting").addEventListener("click", function() {
                player.setCurrentTime(150);
            });
            document.getElementById("Construction").addEventListener("click", function() {
                player.setCurrentTime(252);
            });
            document.getElementById("Bow").addEventListener("click", function() {
                player.setCurrentTime(315);
            });
            document.getElementById("Falling").addEventListener("click", function() {
                player.setCurrentTime(342);
            });
            document.getElementById("FlyingSquirrel").addEventListener("click", function() {
                player.setCurrentTime(395);
            });
            document.getElementById("Kite").addEventListener("click", function() {
                player.setCurrentTime(462);
            });
            document.getElementById("Post").addEventListener("click", function() {
                player.setCurrentTime(581);
            });

        }
```

First, we create a player with the player SDK, and insert the Big Buck Bunny video.  Then the eventlisteners work as fastforward/rewind buttons to the exact starting points of each chapter.  Note that the VTT file is in HH:MM:SS.000 time format, while the player.setCurrentTime is in seconds.

With these buttons (and a little CSS to make them pretty), you can build a web interface to your videos that incorporate a chapter skipping functionality, just like inside the api.video player.



medium_1599px-chapteronesign.jpeg

small_1599px-chapteronesign.jpeg

thumbnail_1599px-chapteronesign.jpeg

1599px-chapteronesign.jpeg

Video Chapters: Using external buttons for controls

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:

small_chapters.png

thumbnail_chapters.png

chapters.png

**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](https://docs.api.video/reference/post_videos-videoid-chapters-language)!

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

large_chapters.png

medium_chapters.png

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](https://api.video/blog/tutorials/how-to-add-captions-to-your-videos) 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:

thumbnail_capture-d-ecran-2020-07-29-a-16-11-38.png

capture-d-ecran-2020-07-29-a-16-11-38.png

I ran the VTT file through a [VTT validator](https://quuz.org/webvtt/) to ensure all the formatting was correct, and then uploaded to api.video using the api command:

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](https://api.video/blog/tutorials/authentication-tutorial), 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.

Conclusion:

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](https://community.api.video) to let us know!

Adding chapters to your videos

Featured article

# api.video blog

Blog

Follow the api.video Blog to explore tutorials, video use cases, and learn about on-demand and live-streaming video updates.