Video captions: track elements and embedded players

What captions are

Captions carry the dialogue and the meaningful sounds of a video as timed text. They are what makes a video usable without audio, for a deaf or hard of hearing viewer and for everyone watching with the sound off.

For a native <video> they come from a <track> element pointing at a WebVTT file. WCAG success criterion 1.2.2 Captions (Prerecorded), Level A, requires them for prerecorded video with audio.

What squirrel checks

Two check names, at rule severity warning.

• video-captions runs when the page has at least one <video>. It warns with N video(s) without caption tracks for any <video> with no track[kind="captions"] and no track[kind="subtitles"], listing each by the first 50 characters of its src, or of its first <source>’s src, or as inline video when neither exists. With every video covered it passes as All videos have caption tracks, and the check’s details record videosChecked (videos that needed captions) and decorativeSkipped.
  • Decorative videos are skipped, see below. When every video is decorative the check passes as No videos need captions (N decorative skipped).
• video-embeds returns info with N embedded video(s) detected and the value Verify captions are enabled in embed settings when the page has an <iframe> whose src contains youtube, vimeo or wistia.
• With neither native video nor a recognized embed, one info check reports No videos detected.

Decorative videos

A video is treated as decorative, and skipped, when it is aria-hidden="true", or when it is muted, has no controls, and has autoplay or loop. That is the markup of a background or hero loop, which has no audio for the viewer to caption (WCAG 1.2.2 covers synchronized media with audio). A video with controls, or that is not muted, or that is muted with neither autoplay nor loop, is still checked. This is a heuristic: muted does not prove there is no audio track, so a video that a script unmutes should carry captions or be left out of the exemption by adding controls. video/video-accessible uses the same check.

squirrel cannot see inside a third-party player, so the embed check is a prompt rather than a verdict. Confirm captions in the platform’s own settings.

How to fix it

<video controls>
  <source src="/demo.mp4" type="video/mp4">
  <track kind="captions" src="/demo-en.vtt" srclang="en" label="English" default>
</video>

Add one <track> per language, and mark the default one. kind="captions" is for viewers who cannot hear the audio, so it carries sound effects and speaker changes alongside the dialogue. kind="subtitles" carries the dialogue only, transcribed or translated, for viewers who can hear but need the words.

Automatic captions from a hosting platform are a starting point, not a finish. Review them for names, jargon and numbers, which is where they fail most.

Enable / disable

Disable this rule

[rules]
disable = ["a11y/video-captions"]

Disable all Accessibility rules

[rules]
disable = ["a11y/*"]

Enable only this rule

[rules]
enable = ["a11y/video-captions"]

enable replaces the default ["*"], so this is the only rule selected. Leave disable out: a rule that matches any disable pattern is skipped even when enable names it. Only an enabled setting under a rule’s own [rule_options] table overrides both lists.

Related rules

• video/video-accessible: the same native caption-track presence check, reported differently and with no embed detection.
• a11y/frame-title: naming the iframe an embedded player sits in.
• a11y/object-alt: alternative content for other embedded media.
• video/video-schema: the structured data that describes the same video to search engines.

Accessibility findings ship in every audit next to the SEO, performance and agent experience rules. See Website security scan with AI for how an agent works through a report.

References

• The track element, MDN
• Understanding SC 1.2.2 Captions (Prerecorded), W3C
• Captions and subtitles, W3C WAI

Check your site

Run squirrel audit https://example.com and open the Accessibility section of the report. Native videos are reported by source file, embeds only as a prompt to check the player. Signed-out local audits need no account and cost nothing. Signed-in audits spend credits.