WebVTT (Web Video Text Tracks)

Overview

WebVTT (Web Video Text Tracks) is a web standard format for displaying timed text tracks with HTML video elements. It provides captions, subtitles, descriptions, chapters, and metadata for web video content, making videos more accessible and searchable.

File Details

• Extension: .vtt
• MIME Type: text/vtt
• Category: Subtitle
• Binary/Text: Text

Technical Specifications

File Structure

WebVTT files start with a signature and contain:

• Signature: "WEBVTT" at the beginning
• Metadata: Optional header information
• Cues: Timed text entries with timestamps
• Notes: Comments and styling information
• Regions: Positioning areas for text

Basic Syntax

WEBVTT

00:00:00.000 --> 00:00:03.000
Hello, welcome to our video!

00:00:03.000 --> 00:00:06.000
This is a subtitle example.

NOTE
This is a comment that won't be displayed.

00:00:06.000 --> 00:00:09.000
<v Speaker>This text has a voice label.

History

• 2010: First draft specification by WHATWG
• 2012: W3C adopts WebVTT as web standard
• 2013: Major browsers begin implementation
• 2015: HTML5 video track element standardized
• 2019: WebVTT becomes W3C Recommendation
• Present: Widely supported across platforms

Structure Details

File Header

WEBVTT
Kind: captions
Language: en-US

STYLE
::cue {
  background-color: black;
  color: white;
}

Cue Syntax

[cue identifier]
start time --> end time [cue settings]
cue payload text

Time Format

• Hours:Minutes:Seconds.Milliseconds
• Example: 00:01:23.456
• Hours are optional for times under 1 hour
• Milliseconds require exactly 3 digits

Code Examples

Basic WebVTT Creation (JavaScript)

class WebVTTGenerator {
    constructor() {
        this.cues = [];
        this.header = 'WEBVTT\n\n';
        this.styles = '';
        this.notes = [];
    }
    
    addCue(startTime, endTime, text, settings = {}) {
        const cue = {
            id: settings.id || `cue-${this.cues.length + 1}`,
            startTime: this.formatTime(startTime),
            endTime: this.formatTime(endTime),
            text: text,
            settings: this.formatSettings(settings)
        };
        this.cues.push(cue);
        return this;
    }
    
    addNote(text) {
        this.notes.push(`NOTE\n${text}\n`);
        return this;
    }
    
    addStyle(css) {
        this.styles += `STYLE\n${css}\n\n`;
        return this;
    }
    
    formatTime(seconds) {
        const hours = Math.floor(seconds / 3600);
        const minutes = Math.floor((seconds % 3600) / 60);
        const secs = seconds % 60;
        
        const timeString = hours > 0 
            ? `${hours.toString().padStart(2, '0')}:`
            : '';
        
        return timeString + 
               `${minutes.toString().padStart(2, '0')}:` +
               `${secs.toFixed(3).padStart(6, '0')}`;
    }
    
    formatSettings(settings) {
        const parts = [];
        
        if (settings.vertical) parts.push(`vertical:${settings.vertical}`);
        if (settings.line !== undefined) parts.push(`line:${settings.line}`);
        if (settings.position !== undefined) parts.push(`position:${settings.position}`);
        if (settings.size !== undefined) parts.push(`size:${settings.size}`);
        if (settings.align) parts.push(`align:${settings.align}`);
        
        return parts.length > 0 ? ' ' + parts.join(' ') : '';
    }
    
    generate() {
        let vtt = this.header;
        
        if (this.styles) {
            vtt += this.styles;
        }
        
        for (const note of this.notes) {
            vtt += note + '\n';
        }
        
        for (const cue of this.cues) {
            if (cue.id) {
                vtt += `${cue.id}\n`;
            }
            vtt += `${cue.startTime} --> ${cue.endTime}${cue.settings}\n`;
            vtt += `${cue.text}\n\n`;
        }
        
        return vtt;
    }
    
    save(filename) {
        const blob = new Blob([this.generate()], { type: 'text/vtt' });
        const url = URL.createObjectURL(blob);
        
        const a = document.createElement('a');
        a.href = url;
        a.download = filename;
        a.click();
        
        URL.revokeObjectURL(url);
    }
}

// Usage example
const vtt = new WebVTTGenerator()
    .addNote('This is a sample subtitle file')
    .addStyle(`::cue {
        background-color: rgba(0, 0, 0, 0.8);
        color: white;
        font-family: Arial, sans-serif;
    }`)
    .addCue(0, 3, 'Welcome to our presentation!')
    .addCue(3.5, 7, 'Today we will cover WebVTT basics.')
    .addCue(7.2, 11, '<v Narrator>This is a narrator speaking.', {
        position: 50,
        align: 'center'
    })
    .addCue(11.5, 15, 'You can position text anywhere on screen.', {
        line: 85,
        position: 75,
        size: 30
    });

console.log(vtt.generate());

WebVTT Parser (Python)

import re
from dataclasses import dataclass
from typing import List, Optional, Dict

@dataclass
class WebVTTCue:
    id: Optional[str]
    start_time: str
    end_time: str
    text: str
    settings: Dict[str, str]

class WebVTTParser:
    def __init__(self):
        self.cues: List[WebVTTCue] = []
        self.styles: List[str] = []
        self.notes: List[str] = []
        self.header: str = ""
    
    def parse(self, content: str) -> None:
        """Parse WebVTT content"""
        lines = content.strip().split('\n')
        
        if not lines[0].startswith('WEBVTT'):
            raise ValueError("Invalid WebVTT file: missing WEBVTT signature")
        
        self.header = lines[0]
        i = 1
        
        # Skip empty lines after header
        while i < len(lines) and not lines[i].strip():
            i += 1
        
        while i < len(lines):
            i = self._parse_block(lines, i)
    
    def _parse_block(self, lines: List[str], start: int) -> int:
        """Parse a single block (cue, note, or style)"""
        if start >= len(lines):
            return start
        
        line = lines[start].strip()
        
        if line.startswith('NOTE'):
            return self._parse_note(lines, start)
        elif line.startswith('STYLE'):
            return self._parse_style(lines, start)
        elif '-->' in line or (start + 1 < len(lines) and '-->' in lines[start + 1]):
            return self._parse_cue(lines, start)
        else:
            # Skip unknown blocks
            return start + 1
    
    def _parse_note(self, lines: List[str], start: int) -> int:
        """Parse NOTE block"""
        i = start + 1
        note_lines = []
        
        while i < len(lines) and lines[i].strip():
            note_lines.append(lines[i])
            i += 1
        
        self.notes.append('\n'.join(note_lines))
        return i + 1
    
    def _parse_style(self, lines: List[str], start: int) -> int:
        """Parse STYLE block"""
        i = start + 1
        style_lines = []
        
        while i < len(lines) and lines[i].strip():
            style_lines.append(lines[i])
            i += 1
        
        self.styles.append('\n'.join(style_lines))
        return i + 1
    
    def _parse_cue(self, lines: List[str], start: int) -> int:
        """Parse cue block"""
        i = start
        cue_id = None
        
        # Check if first line is cue ID
        if '-->' not in lines[i]:
            cue_id = lines[i].strip()
            i += 1
        
        if i >= len(lines) or '-->' not in lines[i]:
            raise ValueError(f"Invalid cue at line {i + 1}")
        
        # Parse timing line
        timing_line = lines[i].strip()
        timing_match = re.match(r'(\S+)\s+-->\s+(\S+)(.*)$', timing_line)
        
        if not timing_match:
            raise ValueError(f"Invalid timing format at line {i + 1}")
        
        start_time = timing_match.group(1)
        end_time = timing_match.group(2)
        settings_str = timing_match.group(3).strip()
        
        # Parse settings
        settings = self._parse_settings(settings_str)
        
        # Parse cue text
        i += 1
        text_lines = []
        
        while i < len(lines) and lines[i].strip():
            text_lines.append(lines[i])
            i += 1
        
        text = '\n'.join(text_lines)
        
        cue = WebVTTCue(
            id=cue_id,
            start_time=start_time,
            end_time=end_time,
            text=text,
            settings=settings
        )
        
        self.cues.append(cue)
        return i + 1
    
    def _parse_settings(self, settings_str: str) -> Dict[str, str]:
        """Parse cue settings"""
        settings = {}
        
        for setting in settings_str.split():
            if ':' in setting:
                key, value = setting.split(':', 1)
                settings[key] = value
        
        return settings
    
    def time_to_seconds(self, time_str: str) -> float:
        """Convert WebVTT time to seconds"""
        parts = time_str.split(':')
        
        if len(parts) == 3:  # HH:MM:SS.mmm
            hours, minutes, seconds = parts
            return int(hours) * 3600 + int(minutes) * 60 + float(seconds)
        elif len(parts) == 2:  # MM:SS.mmm
            minutes, seconds = parts
            return int(minutes) * 60 + float(seconds)
        else:
            raise ValueError(f"Invalid time format: {time_str}")
    
    def get_cue_at_time(self, seconds: float) -> Optional[WebVTTCue]:
        """Get cue that should be displayed at given time"""
        for cue in self.cues:
            start = self.time_to_seconds(cue.start_time)
            end = self.time_to_seconds(cue.end_time)
            
            if start <= seconds <= end:
                return cue
        
        return None
    
    def export_srt(self) -> str:
        """Export as SRT format"""
        srt_lines = []
        
        for i, cue in enumerate(self.cues, 1):
            # Convert time format
            start_srt = self._webvtt_to_srt_time(cue.start_time)
            end_srt = self._webvtt_to_srt_time(cue.end_time)
            
            # Clean text (remove WebVTT tags)
            text = re.sub(r'<[^>]*>', '', cue.text)
            text = re.sub(r'<v[^>]*>', '', text)
            
            srt_lines.extend([
                str(i),
                f"{start_srt} --> {end_srt}",
                text,
                ""
            ])
        
        return '\n'.join(srt_lines)
    
    def _webvtt_to_srt_time(self, vtt_time: str) -> str:
        """Convert WebVTT time to SRT time format"""
        # WebVTT: 00:01:23.456
        # SRT: 00:01:23,456
        return vtt_time.replace('.', ',')

# Usage example
vtt_content = """WEBVTT

NOTE
This is a sample WebVTT file

00:00:00.000 --> 00:00:03.000
Hello, world!

00:00:03.500 --> 00:00:07.000
<v Speaker>This is a speaker.

subtitle-1
00:00:07.500 --> 00:00:11.000 line:85% position:50% align:center
Positioned subtitle text.
"""

parser = WebVTTParser()
parser.parse(vtt_content)

print(f"Found {len(parser.cues)} cues")
for cue in parser.cues:
    print(f"{cue.start_time} - {cue.end_time}: {cue.text}")

# Get cue at specific time
cue_at_5_seconds = parser.get_cue_at_time(5.0)
if cue_at_5_seconds:
    print(f"At 5 seconds: {cue_at_5_seconds.text}")

HTML5 Integration

<!DOCTYPE html>
<html>
<head>
    <title>WebVTT Example</title>
</head>
<body>
    <video width="640" height="360" controls>
        <source src="video.mp4" type="video/mp4">
        
        <!-- Subtitles track -->
        <track kind="subtitles" src="subtitles-en.vtt" srclang="en" label="English" default>
        <track kind="subtitles" src="subtitles-es.vtt" srclang="es" label="Español">
        
        <!-- Captions track (includes sound effects) -->
        <track kind="captions" src="captions-en.vtt" srclang="en" label="English Captions">
        
        <!-- Chapters track -->
        <track kind="chapters" src="chapters.vtt" srclang="en" label="Chapters">
        
        <!-- Descriptions track (for visually impaired) -->
        <track kind="descriptions" src="descriptions.vtt" srclang="en" label="Audio Descriptions">
        
        Your browser does not support the video tag.
    </video>

    <script>
        const video = document.querySelector('video');
        const tracks = video.textTracks;
        
        // Listen for cue changes
        for (let i = 0; i < tracks.length; i++) {
            tracks[i].addEventListener('cuechange', function() {
                const activeCues = this.activeCues;
                
                for (let j = 0; j < activeCues.length; j++) {
                    console.log('Active cue:', activeCues[j].text);
                }
            });
        }
        
        // Programmatically control tracks
        function enableSubtitles(language) {
            for (let i = 0; i < tracks.length; i++) {
                const track = tracks[i];
                if (track.kind === 'subtitles') {
                    track.mode = track.language === language ? 'showing' : 'disabled';
                }
            }
        }
        
        // Enable English subtitles
        enableSubtitles('en');
    </script>
</body>
</html>

Tools and Applications

Subtitle Editors

• Aegisub: Advanced subtitle editor with WebVTT support
• Subtitle Edit: Free Windows subtitle editor
• Jubler: Cross-platform subtitle editor
• Gaupol: Linux subtitle editor

Video Platforms

• YouTube: Supports WebVTT for closed captions
• Vimeo: WebVTT subtitle upload
• HTML5 video: Native browser support
• Video.js: Popular web video player

Conversion Tools

# FFmpeg can extract and convert subtitles
ffmpeg -i video.mkv -map 0:s:0 subtitles.vtt

# Convert SRT to WebVTT
ffmpeg -i subtitles.srt subtitles.vtt

# Add WebVTT subtitles to video
ffmpeg -i video.mp4 -i subtitles.vtt -c copy -c:s webvtt output.mkv

Online Tools

• WebVTT Validator: W3C validation service
• Subtitle converters: Online format conversion
• Caption generators: Auto-caption services
• Timing adjusters: Sync subtitle timing

Best Practices

Accessibility Guidelines

• Provide accurate captions for all spoken content
• Include sound effects and music descriptions
• Use appropriate reading speeds (160-200 words per minute)
• Ensure proper contrast and visibility

Technical Guidelines

WEBVTT

STYLE
::cue {
    font-family: Arial, sans-serif;
    font-size: 18px;
    color: white;
    background-color: rgba(0, 0, 0, 0.8);
    padding: 4px;
}

::cue(.speaker1) {
    color: #FFD700;
}

::cue(.speaker2) {
    color: #87CEEB;
}

NOTE
Use consistent styling throughout the file

00:00:00.000 --> 00:00:03.000
<c.speaker1>John:</c> Hello everyone!

00:00:03.500 --> 00:00:06.000
<c.speaker2>Mary:</c> Nice to meet you all.

Performance Optimization

• Keep cue durations appropriate (2-6 seconds)
• Avoid overlapping cues unless necessary
• Use efficient positioning settings
• Minimize styling complexity

Security Considerations

Content Validation

function sanitizeWebVTT(content) {
    // Remove potentially harmful content
    const cleaned = content
        .replace(/<script[^>]*>.*?<\/script>/gi, '')
        .replace(/javascript:/gi, '')
        .replace(/on\w+\s*=/gi, '');
    
    return cleaned;
}

function validateWebVTT(content) {
    const issues = [];
    
    if (!content.startsWith('WEBVTT')) {
        issues.push('Missing WEBVTT signature');
    }
    
    // Check for reasonable file size
    if (content.length > 1024 * 1024) {  // 1MB
        issues.push('File too large');
    }
    
    // Validate time formats
    const timeRegex = /(\d{2}:)?\d{2}:\d{2}\.\d{3}/g;
    const timeMatches = content.match(timeRegex);
    
    if (timeMatches) {
        for (const time of timeMatches) {
            const parts = time.split(':');
            const seconds = parseFloat(parts[parts.length - 1]);
            
            if (seconds >= 60) {
                issues.push(`Invalid time format: ${time}`);
            }
        }
    }
    
    return issues;
}

XSS Prevention

• Sanitize user-generated WebVTT content
• Validate time formats and cue structure
• Escape HTML content in cue text
• Implement content security policies

WebVTT provides a powerful, standardized way to add accessible text tracks to web videos, supporting multiple languages, styling options, and precise timing control while maintaining broad browser compatibility.