VTT chapter tagging ultimate tutorial: Learn video segmentation navigation development in 5 minutes

Catalog Navigation

1. Overview

WebVTT (Web Video Text Tracks) format is not only used to provide subtitles and captions for videos, but it is also a powerful metadata container. Among these, a very important application is defining video chapters. By adding chapter tracks to videos, you can:

Enhance User Experience: Users can see chapter markers on the video player's timeline and quickly jump to sections of interest.
Enable Non-linear Navigation: Allows users to browse video content like a table of contents in a book.
Build Dynamic UI: Can listen for chapter changes via JavaScript and dynamically update relevant information on the page (such as sidebar menus, titles, etc.). This guide provides detailed instructions on how to create and use WebVTT chapter files.

2. Core Concepts: What is a Chapter Track?

A chapter track is a special type of WebVTT track with its kind attribute set to chapters. Its main difference from subtitle tracks is:

Purpose: It is not used to display text on screen, but rather to define time periods within the video.
Content: Each chapter cue's ID serves as the chapter title, while the cue's payload is typically empty. Native browser players will parse this track and display clickable chapter markers on their control bar timelines.

3. WebVTT Chapter Syntax in Detail

The structure of a standard WebVTT chapter file is very simple.

3.1 File Header

The file must begin with WEBVTT.

WEBVTT

This can be followed by some optional metadata, but for chapters, it usually remains简洁 (concise).

3.2 Chapter Cues

Each chapter is defined by a cue block containing three parts:

Cue ID: This is the chapter's title. It is a human-readable string that will be displayed in the player's chapter menu.
Timestamp: Defines the chapter's start and end time. Format is HH:MM:SS.mmm --> HH:MM:SS.mmm.
Cue Payload: For chapters, this section is typically empty. All chapter information is provided by the ID and timestamp.Syntax Rules:

There must be a blank line between the cue ID and the timestamp.
There must also be a blank line between the timestamp and the payload (even if empty).
Chapter times should be continuous, meaning the previous chapter's end time should ideally match the next chapter's start time to avoid gaps or overlaps.

4. Complete Example

Suppose we have a video about a "Coffee Making Tutorial," and we want to divide it into three chapters: Introduction, Brewing, and Tasting.Filename: coffee-tutorial-chapters.vtt

WEBVTT
NOTE This is a chapter file for a coffee making tutorial
01. Introduction
00:00:00.000 --> 00:01:30.500
02. Brewing Steps
00:01:30.500 --> 00:04:20.000
03. Tasting and Summary
00:04:20.000 --> 00:05:15.000

Example Analysis:

WEBVTT: Standard file header.
NOTE ...: This is a comment; browsers will ignore it, but it's useful for developers.
01. Introduction: This is the first chapter's ID and its title. Users will see "01. Introduction" in the player.
00:00:00.000 --> 00:01:30.500: Defines Chapter 1 from the start of the video until 1 minute 30.5 seconds.
There is a blank line between the cue ID and timestamp, and a blank line after the timestamp (because the payload is empty).
The second chapter starts at 00:01:30.500, perfectly衔接 (connecting) with the previous chapter's end time.

Users can see chapter markers during video playback and quickly jump to sections of interest.

5. Integrating Chapters in HTML5 Pages

After creating the .vtt file, you need to associate it with the <video> element using HTML's <track> tag.Key Attributes:

kind="chapters": This is the most important attribute, telling the browser that this VTT file is for defining chapters.
src="path/to/your-file.vtt": Points to your WebVTT file.
srclang="zh": Specifies the language of the chapter titles (e.g., Chinese).
label="Chinese Chapters": Provides a human-readable label for the track, for display in the player's settings menu.HTML Example:

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <title>WebVTT Chapter Example</title>
    <style>
        /* Basic styles to center the video */
        body { display: flex; justify-content: center; align-items: center; min-height: 100vh; background-color: #f0f0f0; }
        video { max-width: 80%; box-shadow: 0 4px 8px rgba(0,0,0,0.2); }
    </style>
</head>
<body>
    <video controls width="640" poster="coffee-poster.jpg">
        <source src="coffee-tutorial.mp4" type="video/mp4">
        
        <!-- Key: Add chapter track -->
        <track kind="chapters" 
               src="coffee-tutorial-chapters.vtt" 
               srclang="zh" 
               label="Chinese Chapters">
        <!-- Fallback content for browsers that don't support the video tag -->
        Your browser does not support HTML5 video.
    </video>
</body>
</html>

When you open this page in a modern browser that supports WebVTT chapters (such as Chrome, Firefox, Edge), you will see chapter markers on the video control bar timeline; clicking them allows quick navigation.

Compared to the native video tag, zwplayer offers simpler and more friendly support for chapters. The calling method is as follows:

// Initialize player
window.mainplayer = new ZWPlayer({
    url: 'http://example.com/vod/movie.mp4',
    playerElm: '#mse',
    chapterButton: true, // Enable chapter button
});

// Load chapter information with delay
setTimeout(function () {
    if (window.mainplayer) {
        window.mainplayer.setChapters('http://example.com/chapters.vtt');
    }
}, 200);

Interface screenshot:

zwplayer js player chapter annotation interface screenshot, showing chapter menu; clicking menu items jumps to corresponding chapters

6. Best Practices and Considerations

Server MIME Type: Ensure your web server is properly configured to serve .vtt files with the MIME type text/vtt. Otherwise, browsers may not parse the file correctly. In Nginx, you can add this to the mime.types configuration: text/vtt vtt;. In Apache, you can add to the .htaccess file: AddType text/vtt .vtt.
File Encoding: Save .vtt files using UTF-8 encoding to ensure non-English characters (such as Chinese) display correctly.
Time Continuity: Ensure there are no large gaps or overlaps between chapters, which would degrade user experience. Seamless衔接 (connection) is best practice.

7. Advanced Feature Extensions

7.1 Dynamic Chapter Generation

// Automatically generate chapters based on video content
function generateChapters(videoDuration) {
    const chapters = [];
    const segmentDuration = videoDuration / 5; // Divide into 5 segments
    
    for (let i = 0; i < 5; i++) {
        const startTime = i * segmentDuration;
        const endTime = (i + 1) * segmentDuration;
        
        chapters.push({
            title: `Part ${i+1}`,
            start: startTime,
            end: endTime
        });
    }
    
    return chapters;
}

7.2 Data Analytics Integration

// Chapter viewing data analysis
player.on('chapterchange', (chapter) => {
    // Send analytics event
    analytics.track('chapter_view', {
        chapter_title: chapter.title,
        video_id: 'tutorial_001',
        timestamp: Date.now()
    });
});

8. Summary

WebVTT chapter marking is one of the key technologies for enhancing video experience. Through this guide, you can:

✅ Master WebVTT chapter syntax specifications

✅ Implement native HTML5 chapter functionality

✅ Use ZWPlayer to optimize the chapter experience

✅ Advanced usage of chapters