# Videos without audio description of what they show

Source: https://easeweb.dev/learn/audio-description
Topics: Images and media > Videos describe what is shown (WCAG 1.2.3, 1.2.5)
The fix: Either rewrite the narration so it says what the picture shows, or publish a described version with the descriptions in the pauses and offer it from a button beside the player. A transcript that includes what is shown meets Level A only.
Test with: screen off, keyboard, screen reader
References: https://www.w3.org/WAI/WCAG22/Understanding/audio-description-or-media-alternative-prerecorded.html https://www.w3.org/WAI/WCAG22/Understanding/audio-description-prerecorded.html https://www.w3.org/WAI/media/av/description/ https://www.w3.org/WAI/media/av/transcripts/ https://www.w3.org/WAI/WCAG22/Techniques/general/G226 https://www.w3.org/WAI/WCAG22/Techniques/general/G173 https://www.w3.org/WAI/WCAG22/Techniques/general/G78 https://www.w3.org/WAI/WCAG22/Techniques/general/G69 https://www.w3.org/WAI/WCAG22/Techniques/failures/F113 https://www.w3.org/WAI/WCAG22/Techniques/html/H96 https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/track

This is a recreated teaching example, not a finding about a named client. The code is a starting pattern: test it in your own product. No completed assistive-technology test is claimed here.

## What happens

The coffee roaster's brewing video has captions now, and they are right. But the shop re-edited the video for social media: the amounts moved into text cards on the picture, and the narration became shorter. "Weigh it out like this" plays over a card that says 15 g coffee and 250 ml water. "Then let the water rest" plays over "Cool 30 s after boiling". "Pour slowly, and stop here" plays over "Pour in 3 stages, stop at 3:00", and the kitchen timer rings. Someone who listens without the picture hears a friendly voice, a timer, and no recipe.

## Why it fails

Success criterion 1.2.3, at Level A, asks prerecorded video with sound to give people who can't see it what the picture shows: either audio description or a full text alternative. 1.2.5, at Level AA, asks for audio description itself. Audio description is narration of what matters in the picture, such as on-screen text, actions and scene changes, fitted into the pauses in the soundtrack. When the soundtrack already says everything the picture shows, nothing more is needed. Here it doesn't: every number in the recipe is only on screen. The captions don't help, because they carry what is heard, and the soundtrack never says the amounts.

## Who is affected

Anyone who listens rather than watches meets the same gap: someone following the recipe with their eyes on the kettle, or with the video playing on a phone across the kitchen.

## What automation and AI miss

axe has no check for audio description. A scanner sees a `<video>` with a captions track and passes it, because it can't watch the picture or compare it with the speech. EaseWeb's audit lists every video for a person to review, and notes whether an audio description control, a descriptions track or a transcript sits beside it, but whether the soundtrack says what the picture shows is a judgement only someone who watches and listens can make. AI tools can draft descriptions from frames, but they don't know which details matter: they describe the beans and miss that the card's numbers are the recipe.

## Before: amounts that are only on screen

```html
<h2>How to brew our house blend</h2>
<video controls preload="metadata"
  src="brew-guide.webm" poster="brew-guide.jpg">
  <track kind="captions" srclang="en" label="English"
    src="brew-guide.en.vtt">
</video>
```

```vtt
WEBVTT

00:04.200 --> 00:06.300
Weigh it out like this.

00:10.200 --> 00:12.400
Then let the water rest.

00:15.200 --> 00:17.800
Pour slowly, and stop here.
```

The captions file is a faithful record of the soundtrack, and that is the problem: "like this" and "here" point at cards that only sighted viewers can read. The player offers no other version, so 15 grams, 250 millilitres, 30 seconds and three minutes never reach someone who can't see the picture.

## After: a narration that says what is shown

```html
<video controls preload="metadata"
  src="brew-guide.said.webm" poster="brew-guide.jpg">
  <track kind="captions" srclang="en" label="English"
    src="brew-guide.said.en.vtt">
</video>
```

```vtt
WEBVTT

00:04.200 --> 00:09.600
Use 15 grams of coffee
for 250 millilitres of water.

00:10.200 --> 00:14.600
After the water boils,
let it cool for 30 seconds.

00:15.200 --> 00:19.700
Pour in three slow stages,
and stop at three minutes.
```

The narrator says each amount while its card shows, so the one soundtrack carries everything the picture does, and there is nothing to switch on (integrated description, W3C technique G226). The cards can stay for viewers who glance at the screen. The captions follow the new narration, so they carry the amounts too.

## After: a described version beside the original

```html
<video id="brew-video" controls preload="metadata"
  src="brew-guide.webm" poster="brew-guide.jpg"
  data-described="brew-guide.described.webm">
  <track kind="captions" srclang="en" label="English"
    src="brew-guide.en.vtt" data-described="brew-guide.described.en.vtt">
</video>
<button type="button" id="describe" aria-pressed="false">
  Audio description
</button>

<script>
  const video = document.getElementById('brew-video');
  const track = video.querySelector('track');
  const plain = { video: video.getAttribute('src'), captions: track.getAttribute('src') };
  document.getElementById('describe').addEventListener('click', (event) => {
    const button = event.currentTarget;
    const on = button.getAttribute('aria-pressed') !== 'true';
    const { currentTime, paused, playbackRate } = video;
    const captions = track.track.mode;
    video.src = on ? video.dataset.described : plain.video;
    track.src = on ? track.dataset.described : plain.captions;
    // Carry on from the same moment, at the same speed, with the captions as they were.
    video.addEventListener('loadedmetadata', () => {
      video.currentTime = currentTime;
      video.playbackRate = playbackRate;
      track.track.mode = captions;
      if (!paused) video.play();
    }, { once: true });
    button.setAttribute('aria-pressed', String(on));
  });
</script>
```

The described version is the same video with a second voice in the pauses: "15 grams of coffee, 250 millilitres of water" after "weigh it out like this", and so on for each card (W3C technique G173). The button sits right after the player, says what it does, and reports whether it is on. Switching keeps the place, the speed and whether captions show, so someone who turns it on halfway doesn't start again, and it swaps in the described version's own captions file. This works as shown only while the described file has the same timing as the original; if it was edited longer to make room, start it from the beginning or map the times.

## After: a descriptive transcript, at Level A only

```html
<video controls preload="metadata"
  src="brew-guide.webm" poster="brew-guide.jpg">
  <track kind="captions" srclang="en" label="English"
    src="brew-guide.en.vtt">
</video>
<details>
  <summary>Transcript, with what the video shows</summary>
  <p>Narrator: Here’s how to brew our house blend.</p>
  <p>Narrator: Weigh it out like this.</p>
  <p>On screen: 15 g coffee, 250 ml water.</p>
  <p>Narrator: Then let the water rest.</p>
  <p>On screen: Cool 30 s after boiling.</p>
  <p>Narrator: Pour slowly, and stop here.</p>
  <p>On screen: Pour in 3 stages, stop at 3:00.</p>
  <p>[Kitchen timer rings]</p>
</details>
```

A transcript right beside the player, with what is shown written in its place, gives the whole recipe as text, and meets 1.2.3 as an alternative for time-based media (G69). It is not audio description, so it does not meet 1.2.5: a blind viewer has to stop the video and read, and the video itself still says "like this". It is also the only fix that reaches people who are both deaf and blind, through a braille display, so keep it even after adding one of the other fixes.

## Which option to use

The first two pass both criteria; the transcript passes Level A only. Writing the description into the narration gives one video that works for everyone, with no second file and no switch to find, and the captions come with it. It costs a new recording, and it suits how-to, product and training videos, where saying the amount aloud helps every viewer. A described version leaves the original untouched, which suits a finished film, a brand video whose script can't change, or a story a narrator would interrupt; it costs a second file and a control. Add the descriptive transcript to either, but not instead of them, on a site that aims for Level AA.

## Implementation decisions

Where the video plays changes how the described version reaches viewers:

- Your own `<video>`: a second file and a button, as above. A second audio track inside one file (W3C technique G78) is cleaner, but browsers don't offer a way to choose audio tracks, so it needs a player that does.
- An embedded YouTube, Vimeo or Wistia player: if the platform lets you add a described audio track to the video, use it; if not, publish the described version as its own video and link to it right under the embed.
- A custom player with its own buttons: put the audio description button in the control bar beside captions, named and reachable from the keyboard.

A `<track kind="descriptions">` file is not a fix on its own. Browsers load its cues but don't read them aloud, and W3C lists it only as advisory (H96). Some accessible players voice description cues with speech synthesis; it counts only when the player you ship does that, and it still has to fit the pauses.

Describe what someone needs to follow the video and can't get from the sound: on-screen text, numbers, actions, who appears, and changes of place. Use the present tense, say what is shown rather than what it means, and don't describe what the narration already says. When a pause is too short, shorten the description, rewrite the narration, or edit a longer described version; pausing the video to fit a description is extended audio description (1.2.7, AAA).

The described version needs its own captions file, with the descriptions in it as well as the narration, each marked with who is speaking: it is a different soundtrack, and its captions should carry all of it. Switch the file with the video, as the script above does. A video with no sound at all is covered by 1.2.1 instead, in [podcasts and silent videos with no transcript](/learn/transcripts), and a talking head whose picture adds nothing the speech doesn't say needs no description.

## Verify the fix

1. Cover the screen, or turn it away, and play the whole video in the version you are fixing. Write down every amount, name and instruction you hear, then compare the list with what the picture shows. With the transcript fix, read the transcript instead.
2. Listen to where the descriptions fall. Each sits in a pause, finishes before the next line of narration, and never covers a sound that matters, such as the timer.
3. Using only the keyboard, and then a screen reader with the screen covered, find the audio description button or link beside the player, turn it on and off, and check that the screen reader says whether it is pressed and that the video keeps its place. With the narration fix, check there is nothing to switch on, and that no control promises a description that isn't there.
4. Turn captions on in each version. The captions match the version that is playing: the described version's include the descriptions, marked as the describer's, and stay on after switching.

Record the OS, browser and assistive-technology versions, the build, the date, and the actual result of each step. Repeat whenever the video, its narration or the described version is replaced.

## Limits

This is a starting pattern, not a guarantee for every application. Whether a description is needed, and what it should say, depends on the video: this guide can't judge that for you. Captions for the speech are a separate requirement, covered in [videos without captions, or with unchecked automatic ones](/learn/video-captions). Test the complete journey with the people who will watch it, in the players and platforms the video really plays in.

---

Get this guide in your coding agent: MCP https://easeweb.dev/mcp (setup at https://easeweb.dev/services/developers)