Skip to content
Vispero CORADocs

Videos need captions

  • Rule: axe/video-caption
  • Checks: <video> elements must have captions
  • WCAG: 1.2.2
  • Fix class: manual: A fix needs a person to work out what to change, beyond authored text or a visual decision.

Who it affects

Section titled “Who it affects”
  • People who are deaf or hard of hearing.

How to fix it

Section titled “How to fix it”

A video with speech or meaningful sound has no captions

Section titled “A video with speech or meaningful sound has no captions”

Add a WebVTT captions file through <track kind="captions">. It must hold what is said, who says it, and the sounds that matter, in time with the audio, written or checked against the recording itself.

<video controls src="onboarding.mp4">
  <track kind="captions" src="onboarding.en.vtt" srclang="en" label="English">
</video>

The captions are burned into the picture or loaded by the player

Section titled “The captions are burned into the picture or loaded by the player”

Check that they cover all speech and meaningful sound and stay in time with it. If they do, the video meets WCAG 1.2.2 and nothing needs to change.

The video has no sound, such as a silent background loop

Section titled “The video has no sound, such as a silent background loop”

Captions are not needed. If the video conveys information, describe it in text nearby, since WCAG 1.2.1 asks for an alternative to video without sound.

Fixes that fail

Section titled “Fixes that fail”

Marking the captions file kind="subtitles"

Section titled “Marking the captions file kind="subtitles"”

Subtitles are meant for people who can hear and usually carry only the dialogue. axe keeps asking until the track is marked captions, and the file must carry the speakers and sounds captions need.

Pointing a captions track at an empty or placeholder file

Section titled “Pointing a captions track at an empty or placeholder file”

axe sees the track and stops asking, but people get no captions.

Publishing machine captions without checking them

Section titled “Publishing machine captions without checking them”

Speech recognition gets names, terms and speakers wrong and misses meaningful sounds. Correct them against the audio first.

More on the rule

Section titled “More on the rule”

axe-core’s documentation of the rule

CORA’s fix guidance adapts content from accessibility-agents, under the MIT License: see its notice.