axe-core video-caption error video element missing captions

axe-core video-caption error video element missing captions - how to fix it

TL;DR

Prerecorded video with dialogue needs synchronized captions. Add a [track kind="captions"] element pointing at a WebVTT file, for example [track kind="captions" src="/demo.en.vtt" srclang="en" label="English"]. Auto-generated captions are a start but review them for accuracy on names and terminology. Muted decorative video without meaningful audio is exempt; everything with spoken content is not.

Captioning backlogs are the norm: organizations publish videos for years, then face an audit listing dozens of uncaptioned videos. Triage by reach: caption the highest-traffic videos first, then work backward. For new videos, make captions part of the publishing checklist so the backlog never regrows.

The verbatim error looks like this:

axe-core 4.x
Rule: video-caption (critical)
"Video elements must have captions"

Element: [video src="/demo.mp4"][/video]
  No track element with kind="captions".

Steps

1. Reproduce with the single rule:

npx @axe-core/cli https://example.com/product --rules video-caption

Expected: each video without a captions track is listed.

2. Produce or obtain a caption file in WebVTT format for the video's spoken content. Auto-caption, then have a human review names, jargon, and punctuation.
3. Attach the track:

[video src="/demo.mp4" controls]
  [track kind="captions" src="/demo.en.vtt" srclang="en" label="English" default]
[/video]

Add one track per language you support.

4. Re-run the focused scan. Expected output: 0 violations for video-caption.
5. Play the video with captions on and verify timing, speaker identification, and that meaningful sound effects are captioned ('[applause]').
6. Inventory uncaptioned video across the site, not just the flagged page. Video libraries, CMS embeds, and marketing pages each hide videos:

npx @axe-core/cli https://example.com/ --rules video-caption

Run it across key templates, since one template can host many videos.

7. Build captioning into the publishing workflow: no video ships without a reviewed WebVTT file. Auto-caption on upload, human-review before publish, and store the VTT alongside the video asset.

When to use

• Axe flags video-caption on video elements.
• A product demo, webinar recording, or testimonial video has no captions.
• Deaf or hard-of-hearing users report they cannot follow video content.

When not to use

• The video is muted and purely decorative (no meaningful audio; consider whether it should be video at all).
• The content is audio-only (provide a transcript instead; that is audio-caption territory).
• The video is a live stream (live captions are the requirement there, a harder problem).

Why it happens

Captions are the only way deaf and hard-of-hearing users access spoken video content, and they also help users in noisy environments, non-native speakers, and anyone searching video content. WCAG 1.2.2 requires captions for prerecorded video. The [track] element is the native mechanism; overlaying custom div captions is fragile by comparison.

Video production and web publishing are often separate teams with separate tools. The video team delivers an MP4; the web team embeds it; nobody owns captions. The axe rule lands on the web team, but the fix requires a workflow change between the teams. Treating captions as a publishing requirement, like thumbnails, is what makes it stick.

Edge cases

• A track with kind="subtitles" instead of kind="captions" may not satisfy the rule; use kind="captions" for the deaf/hard-of-hearing track.
• Auto-captions without human review often mangle product names and terms. Review at least once per video.
• Videos inside third-party players (YouTube, Vimeo embeds) need captions enabled in the player, not a [track] element on your page.
• Do not burn captions into the video pixels; burned-in captions cannot be toggled, restyled, or read by assistive tech.
• Caption files need versioning alongside the video. A re-edited video with stale captions is worse than no captions for trust.
• Speaker identification ([Name]:) matters in interviews and panels. Auto-captioning often omits it; add it in review.
• Videos with no speech but meaningful audio (a product demo with sound effects) still need captions describing the audio.
• Caption files in WebVTT support positioning and styling cues; use them for speaker labels rather than burning names into the video.
• For videos with significant on-screen text (slides, demos), captions should include the key text, not just dialogue.
• Auto-translate caption tracks for multilingual audiences, but have a native speaker spot-check each translation.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstcnJ0DOAPH1lZKrR_euuIg

Resolved from the public thread: https://vectle.com/posts/pstcnJ0DOAPH1lZKrR_euuIg

Thread query: axe-core video-caption error video element missing captions

TL;DR: Prerecorded video with dialogue needs synchronized captions. Add a [track kind="captions"] element pointing at a WebVTT file, for example [track kind="captions" src="/demo.en.vtt" srclang="en" label="English"]. Auto-generated captions are a start but review them for accuracy on names and terminology. Muted decorative video without meaningful audio is exempt; everything with spoken content is not.