SiteLint documentation and guidelines

Prerecorded video must have synchronized captions.

Description

This rule checks whether <video> elements with prerecorded content have synchronized captions via a <track> element with kind="captions" or kind="subtitles". The audit detects the presence of caption tracks automatically, but the accuracy, synchronization, and completeness of those captions must be verified manually.

Captions convey not only spoken dialogue but also meaningful sound effects, speaker identification, music cues, and other non-speech audio information. The WCAG Success Criterion 1.2.2 requires that captions be provided for all prerecorded audio content in synchronized media, except when the media is a media alternative for text and is clearly labeled as such. This rule is a semi-automated check: it identifies <video> elements and reports whether a caption <track> is present, but you must still manually review the captions for accuracy, proper timing, and inclusion of relevant non-speech information.

Disabilities impacted

  • Deaf and hard of hearing – Without captions, users who are deaf or have significant hearing loss cannot access spoken dialogue or non-speech audio cues, making video content completely inaccessible. Captions are the primary mechanism for conveying audio information in visual form.
  • Auditory processing disorders – Some individuals have difficulty processing auditory information even if their hearing sensitivity is normal. Captions provide a textual representation that supports comprehension and reduces cognitive load during video playback.
  • Cognitive disabilities – Captions aid comprehension for users with learning disabilities, attention disorders, or memory challenges by reinforcing spoken content with text. The ability to read along while listening can significantly improve information retention and understanding.
  • Non-native language speakers – Users who are not fluent in the audio language benefit from captions as a reading aid, improving comprehension of dialogue, terminology, and accents that may be difficult to follow through audio alone.

Why it matters

Video content is pervasive on the modern web – from educational tutorials and product demonstrations to news broadcasts and entertainment. The ADA and the European Accessibility Act (EAA) both recognize captions as essential for equal access to multimedia. Without captions, a significant portion of the global population is excluded from consuming video content that others take for granted.

Beyond accessibility compliance, captions improve user engagement metrics. Studies show that captioned videos have higher completion rates, better comprehension, and increased sharing. Search engines can index caption text, making video content more discoverable. Captions also benefit users in sound-sensitive environments (offices, libraries, public transit) where audio playback is not practical.

Coding problems and solutions

Common coding problems

  • Missing <track> element entirely – The <video> element is present but no <track> child element exists with caption or subtitle information.
  • Wrong kind attribute value – The <track> element uses an incorrect kind value such as "descriptions" or "chapters" instead of "captions" or "subtitles".
  • Incorrect or missing VTT file – The src attribute points to an invalid WebVTT file, a file that does not exist, or a file with syntax errors that prevents caption rendering.
  • Captions not synchronized – The timestamp cues in the WebVTT file do not align with the actual audio, causing captions to appear too early or too late.
  • Missing non-speech information – The caption file contains only spoken dialogue and omits important sound effects (e.g., [door slams], [phone ringing]), speaker identification, or musical descriptions.
  • Auto-generated captions without review – Using automated speech recognition services (e.g., YouTube auto-captions) without human review results in inaccurate captions with frequent misrecognitions, missing punctuation, and no sound-effect descriptions.
  • Captions not covering the full video duration – The WebVTT cues do not span the entire length of the video, leaving portions of the audio content uncaptioned.

How to fix it

Add a <track> element with captions

The most straightforward fix is to add a <track> child element inside the <video> element with kind="captions" (or kind="subtitles" if the track is primarily for translation) and a valid src pointing to a WebVTT file. Also provide the srclang attribute to declare the language of the captions, and use the default attribute to enable captions by default when no user preference is set.

<video controls width="640" height="360" poster="thumbnail.jpg">
  <source src="tutorial.mp4" type="video/mp4">
  <source src="tutorial.webm" type="video/webm">
  <track src="captions-en.vtt" kind="captions" srclang="en" label="English" default>
  <track src="captions-es.vtt" kind="captions" srclang="es" label="Español">
</video>
Correct example
<video controls width="640" height="360">
  <source src="tutorial.mp4" type="video/mp4">
  <source src="tutorial.webm" type="video/webm">
</video>
Incorrect example

Write accurate WebVTT captions with non-speech cues

A proper WebVTT file must include timestamps, the spoken dialogue, and descriptions of meaningful sounds. Speaker identification should be included when multiple speakers are present. The cues should be broken into readable segments (typically 1–2 lines per cue, roughly 32–40 characters per line).

WEBVTT

00:00:01.000 --> 00:00:04.500
[gentle piano music playing]

00:00:05.000 --> 00:00:08.200
Dr. Martinez: Welcome to today's
lecture on accessible design.

00:00:08.500 --> 00:00:12.000
[audience applause]
Thank you all for being here.
Correct example
WEBVTT

00:00:01.000 --> 00:00:04.500

00:00:05.000 --> 00:00:08.200
Welcome to todays lecture on accessible design

00:00:08.500 --> 00:00:12.000
Thank you all for being here
Incorrect example

Programmatically validate caption presence and syntax

Use JavaScript to detect <video> elements and verify that at least one <track> child with kind="captions" or kind="subtitles" exists. You can also attempt to load the VTT file to check for fetch errors or parse basic structure.

const validateVideoCaptions = async (videoElement) => {
  const tracks = videoElement.querySelectorAll('track[kind="captions"], track[kind="subtitles"]');

  if (tracks.length === 0) {
    console.warn('Video is missing a caption track', videoElement);
    return false;
  }

  for (const track of tracks) {
    if (track.src.length === 0) {
      console.warn('Caption track has an empty src attribute', track);
      continue;
    }

    try {
      const response = await globalThis.fetch(track.src, { method: 'HEAD' });

      if (response.status !== 200) {
        console.warn(`Caption file not found: ${track.src}`);
        continue;
      }

      return true;
    } catch (err) {
      console.error('Failed to validate caption track', err);
    }
  }

  return false;
};
Correct example
const checkVideo = (video) => {
  const tracks = video.querySelectorAll('track');

  if (tracks.length > 0) {
    return true;
  }

  return false;
};
Incorrect example

Use a captioning service or tool to generate quality captions

For production content, use dedicated captioning tools or professional services that produce properly formatted WebVTT files. Many media players and hosting platforms provide built-in caption editors. Always review auto-generated captions for accuracy, punctuation, speaker identification, and sound-effect descriptions before publishing.

Recommended workflow:

  1. Transcribe the audio using a professional service or a reliable speech-to-text tool
  2. Add speaker identification and sound-effect descriptions
  3. Break the text into readable segments with accurate timestamps
  4. Export as a valid WebVTT file
  5. Link the VTT file using the <track> element
  6. Play back the video with captions enabled and verify accuracy and synchronization
Correct workflow

Inadequate approach:

  1. Upload video to a platform and rely entirely on auto-generated captions without review
  2. Publish the video without any caption verification
Incorrect workflow

Known Limitations

  • Automated accuracy check is not possible – The rule can detect the presence of a <track> element but cannot programmatically verify that the captions are correct, synchronized, or complete. Human review is required for these aspects.
  • Dynamically injected videos – If a <video> element is added to the DOM via JavaScript after the initial page load (common in SPAs and media players), it may not be detected unless the audit re-scans the updated DOM.
  • Videos inside Shadow DOM – Video content embedded within Shadow DOM boundaries may not be traversed unless the audit tool explicitly traverses shadow roots.
  • External video players and iframes – Videos hosted on third-party platforms (YouTube, Vimeo) and embedded via iframes expose limited access to their internal <track> elements due to cross-origin restrictions, making automated validation unreliable.
  • Programmatic TextTracks – Captions added via the JavaScript TextTrack API (using video.addTextTrack()) instead of declarative <track> elements may go undetected by DOM-based checks.
  • Subtitle-only tracks – A <track> with kind="subtitles" typically translates only spoken dialogue and omits non-speech audio cues, which may not satisfy the WCAG requirement for captions. The rule flags both kinds, but you must confirm whether the subtitle track includes descriptive information beyond speech.
  • Media served without CORS headers – VTT files hosted on a different origin that lacks appropriate CORS headers may fail to load, causing captions to silently fail.

Resources

Rule

  • Audit: accessibility
  • Standard: WCAG
  • Level: A
  • Success Criteria: 1.2.2
  • Rule ID: captions-prerecorded