How to Fix Missing Video Captions on Your Website

Accessibility audits flag native <video> elements that have no captions track, and <audio> elements with no text alternative. By the end of this guide, every self-hosted video with speech on your site will load a WebVTT captions file through a <track kind="captions"> element, your audio clips will have transcripts, and you will have confirmed the fix with axe.

By Updated ⏱ 30–60 minutes per video, including caption review🎯 Intermediate● Medium impactAccessibility
Illustration: Video captions fix guide
ACCESSIBILITY · FIX GUIDE Video captions IMPACTEFFORT TIME30–60 minutes per video, including caption review LEVELIntermediate

Why it matters

Without captions, deaf and hard-of-hearing visitors miss everything said in your videos. So do the many people who watch with sound off on mobile or in public. 2 (Level A).

That makes them part of the standard referenced by the ADA, Section 508 and the European Accessibility Act, which applies to many businesses since June 2025. A transcript or caption file also gives search engines and AI assistants machine-readable text from your video. Without it, that content is invisible to them.

✕Before<video src="/media/demo.mp4"controls></video> — no <track>, so axereports "<video> elements must have✓After<video src="/media/demo.mp4"controls><track kind="captions"src="/media/demo.en.vtt" srclang="en"

What you need

Access to the page HTML, theme templates or the CMS video block
The original video files, or their URLs
A captioning tool such as YouTube Studio auto-captions, Descript, Subtitle Edit or OpenAI Whisper
Upload access to your media library or server
The axe DevTools browser extension or Chrome Lighthouse

Step-by-step fix

1

List every video and audio element that is flagged

Run axe DevTools on each page that has media, or open your audit report. Note each failing element and whether it contains speech. The check looks at native HTML5 elements only:

  • <video> must contain a <track kind="captions"> child
  • <audio> needs a text alternative, such as a transcript

Videos embedded through YouTube or Vimeo iframes are not part of this check. Handle them separately in the player's own caption settings.

Pro tip: Search your templates for `<video` and `<audio` to find media that only appears on some pages, such as product galleries or modal popups.
2

Generate a draft transcript with timestamps

Use an automatic speech-to-text tool to create a first draft. Good options are YouTube Studio (Subtitles > Add language > Auto-sync), Descript, or the open-source Whisper CLI. Whisper can write a WebVTT file directly.

Then review the draft line by line, and fix these:

  • names and product terms
  • punctuation
  • speaker changes

Add important non-speech sounds in brackets, such as [music] or [door slams].

text
pip install -U openai-whisper
whisper demo.mp4 --model medium --language en --output_format vtt --output_dir ./captions
Pro tip: Unedited auto-captions often mangle brand names and numbers. Allow about 2–3x the video length for an accurate review.
3

Save the captions as a valid WebVTT file

srt. The file must start with the line WEBVTT, followed by a blank line. mmm` timestamps with a dot, not a comma.

Keep each cue to 1–2 lines of roughly 32–42 characters. vtt`.

text
WEBVTT

00:00:00.000 --> 00:00:03.200
Welcome to Example Co.

00:00:03.400 --> 00:00:07.000
[upbeat music]
Today we'll set up your dashboard.
Pro tip: To convert an .srt file, add the WEBVTT header and replace commas in the timestamps with dots. Subtitle Edit can also do it via File > Save as > WebVTT.
4

Upload the file and serve it with the right MIME type

Upload the .vtt file next to your video, or to your media library. Browsers ignore tracks that are not served as text/vtt. If the file sits on a different domain or CDN, two more things are needed:

  • the server must send an Access-Control-Allow-Origin header
  • the <video> element needs a crossorigin attribute
nginx
# Nginx (inside the http or server block)
types { text/vtt vtt; }

# Apache (.htaccess)
AddType text/vtt .vtt
Pro tip: Check the header with: curl -I https://example.com/media/demo.en.vtt — it should show Content-Type: text/vtt.
5

Add a <track kind="captions"> to each video

Place the <track> inside the <video> element. The audit requires kind="captions". A track with kind="subtitles" or kind="descriptions" does not satisfy it.

Include these attributes:

  • srclang for the language
  • label, which appears in the player's caption menu
  • default, if you want captions on by default

Add a separate track for each extra language.

html
<video controls preload="metadata" poster="/media/demo.jpg" crossorigin="anonymous">
  <source src="https://cdn.example.com/media/demo.mp4" type="video/mp4">
  <track kind="captions" src="https://cdn.example.com/media/demo.en.vtt" srclang="en" label="English" default>
  <track kind="captions" src="https://cdn.example.com/media/demo.de.vtt" srclang="de" label="Deutsch">
</video>
Pro tip: Silent decorative background loops should have no audio track at all; strip the audio in your encoder. If one is still flagged, give it captions or a short text description of the scene.
6

Give audio clips a transcript

Podcasts, voice notes and audio-only clips need a text alternative. Publish a full transcript on the same page, or link to it directly next to the player. Associate the transcript with the player using aria-describedby, or place it in an expandable section right below the player.

html
<figure>
  <figcaption id="ep12-title">Example Co Podcast, Episode 12</figcaption>
  <audio controls src="/media/ep12.mp3" aria-labelledby="ep12-title" aria-describedby="ep12-transcript"></audio>
  <details id="ep12-transcript">
    <summary>Read the transcript</summary>
    <p>Host: Welcome back to the Example Co podcast…</p>
  </details>
</figure>
Pro tip: Automated tools can't judge transcript quality, so check it yourself, including speaker names.
7

Test the captions and re-run the audit

Reload the page and play each video. Open the player's CC menu and confirm your label appears and the text stays in sync with the speech. Then run axe DevTools or Lighthouse (Accessibility category) again.

The failing video-caption and audio-caption items should no longer appear.

Pro tip: In Chrome DevTools > Network, filter by "vtt" to confirm the file loads with status 200 and isn't blocked by CORS.

Platform-specific notes

WordPress

In the block editor, select the Video block and click Text tracks in the block toolbar. Upload your .vtt file and set Kind to Captions, plus the source language and label. WordPress blocks .vtt uploads by default. Allow them with an upload_mimes filter, or upload the file over SFTP.

Shopify

Native product-media videos and most theme video sections don't offer a caption field. Upload the .vtt file under Content > Files. Then use a Custom Liquid section with your own <video> and <track kind="captions"> markup, pointing to the file URL. If the theme uses a YouTube or Vimeo embed instead, add captions in that platform.

Webflow

The Background Video element has no caption support and should be silent. For videos with speech, use an Embed element containing your own <video> and <track> markup. Host the .vtt on a server that sends text/vtt and CORS headers. Webflow Assets may not serve .vtt files correctly.

Next.js / React

Put .vtt files in /public so they are served from your own domain. In JSX, write the attributes as srcLang (camelCase) and default. Example: <track kind="captions" src="/captions/demo.en.vtt" srcLang="en" label="English" default />.

YouTube / Vimeo embeds

Iframe embeds are not tested by this check, but they still need captions for WCAG. Add or edit them in YouTube Studio (Subtitles) or in Vimeo's video settings (Distribution > Subtitles). Add cc_load_policy=1 to the YouTube embed URL to show captions by default.

Check that it worked

✅ How to verify

  • Run axe DevTools on the page and confirm no "<video> elements must have captions" or "<audio> elements must have a captions track" issues remain.
  • Play each video, open the CC menu and check that the captions display in sync and with correct text.
  • Open the .vtt URL directly or run curl -I on it, and confirm a 200 status with Content-Type: text/vtt.
  • Re-run the site audit and confirm the Video captions check passes on all pages that contain media.

⚠️ Common mistakes

  • Using kind="subtitles" or leaving out kind; the audit specifically requires kind="captions".
  • Linking an .srt file or a .vtt file served as text/plain, so the browser silently ignores the track.
  • Publishing raw auto-generated captions with wrong names and missing punctuation, which fails users even though the automated check passes.
  • Hosting captions on a CDN without CORS headers or a crossorigin attribute on the video, so the track never loads.

Is this still an issue on your site? Run a free audit — ZORO checks this and 294 other SEO, AI-visibility, accessibility and security signals, with fixes for your platform.

Check my site free

FAQ

What is the difference between captions and subtitles?

Captions assume the viewer can't hear the audio. They include dialogue plus meaningful sounds and speaker identification. Subtitles assume the viewer can hear and only translate the dialogue. For accessibility, and for this check, use kind="captions".

Are auto-generated captions good enough for WCAG?

Not on their own. WCAG requires captions to be accurate, and unedited automatic captions often contain errors. Use them as a draft, then correct them before publishing.

Do muted background videos need captions?

A truly silent, decorative video has no speech to caption. Remove its audio track entirely so it is clearly silent. If your audit still flags it, add a captions track or a short text description so the check passes.

Can I use one transcript instead of captions for a video?

A transcript helps, and it is required for audio-only content. But WCAG 1.2.2 requires synchronized captions for prerecorded video with audio, so provide both.