mgifford/accessibility-skills/audio-video

Audio/Video Accessibility Skill

Canonical source: examples/AUDIO_VIDEO_ACCESSIBILITY_BEST_PRACTICES.md in mgifford/ACCESSIBILITY.md

This skill is derived from that file. When in doubt, the example is authoritative.

Apply these rules when implementing or reviewing any audio or video content. Only load this skill if the project contains audio or video.

Core Mandate

Accessible media provides equivalent access to speech, sound, visual information, and playback controls. The required alternatives depend on whether the media is audio-only, video-only, synchronized, prerecorded, or live.

Plan captions, description, transcripts, and sign-language access before production begins. Use qualified human review — unreviewed automatic output is not an accessible final deliverable. Keep alternatives easy to find next to the media, and preserve them when media is embedded, translated, archived, or moved to another platform.

Severity Scale (this skill)

What the Media Requires (WCAG Level Matrix)

The time-based media criteria are cumulative — Level AA includes applicable Level A requirements.

No meaningful audio/visual information: video with no meaningful audio (silence, decorative music) doesn't need captions. Audio with no speech can still need a transcript if meaningful sound communicates information. Decorative video conveys no information, but continuous motion can still require pause controls. If all important visual information is already spoken, no additional audio description is needed. Document these decisions per-file rather than assuming every video has identical requirements — and do not label primary media "an alternative for text" merely to avoid captions/ description/transcript.

Critical: Never Autoplay Audible Media

<!-- Never do this -->
<video src="intro.mp4" autoplay></video>
 
<!-- Muted autoplay still needs reduced-motion handling and a pause control -->
<video src="background.mp4" autoplay muted loop playsinline
       controls aria-label="Background animation — muted by default"></video>
@media (prefers-reduced-motion: reduce) {
  video[autoplay] { display: none; }
}

WCAG 1.4.2 does not literally ban every autoplay instance — it requires a mechanism to pause/stop audio playing automatically for more than 3 seconds, or independent volume control. This project's stricter rule: do not autoplay audible media at all, to avoid interfering with screen reader speech. If sound autoplays for any reason, the stop/pause/mute control must be the first keyboard stop on the page.

Muted autoplay does not resolve every issue: meaningful audio is unavailable while muted; moving content can distract or cause physical symptoms; motion for 5+ seconds alongside other content can need pause/stop/ hide (WCAG 2.2.2); users who request reduced motion should not get automatic decorative motion regardless of a caption track existing.

Critical: Captions on Pre-recorded Video with Audio

<video controls preload="metadata" playsinline poster="training-poster.jpg">
  <source src="training.mp4" type="video/mp4">
  <track kind="captions" src="training.en.vtt" srclang="en" label="English captions" default>
  <track kind="subtitles" src="training.fr.vtt" srclang="fr" label="Sous-titres français">
  <p>Your browser cannot play this video. <a href="training.mp4">Download the video</a>.</p>
</video>

Use kind="captions" for tracks including dialogue AND meaningful non-speech audio; use kind="subtitles" for translated dialogue only — subtitles containing only dialogue are not a replacement for captions in the original language. Use only one default track per kind. Serve WebVTT as UTF-8 with the correct text/vtt media type.

Caption content must include: complete spoken dialogue/narration; speaker identification when not otherwise clear; meaningful sound effects/music cues ([door slams]); correct punctuation/capitalization preserving meaning; synchronized timing; readable cue duration/line breaks; placement avoiding important visual content. Do not remove words, simplify technical language, or censor in a way that changes meaning.

Never publish auto-generated captions without human review — a qualified person must review the complete file against the audio and correct substitutions/omissions/invented words, names/technical terms/numbers, missing negation, speaker changes, punctuation, and synchronization. Unreviewed auto-captions are at best Serious.

Open vs. closed captions: prefer closed captions (toggleable, customizable) when the platform supports them reliably. Open captions (permanently rendered) are a recognized WCAG technique and acceptable when closed captions aren't available — don't categorically reject them, but note users can't turn them off or resize them independently.

Critical: Transcript for Audio-Only Content

<figure>
  <figcaption>Episode 12: Testing with screen magnification, 34 minutes</figcaption>
  <audio controls preload="metadata" aria-label="Episode 12: Testing with screen magnification">
    <source src="episode-12.mp3" type="audio/mpeg">
    <p>Your browser cannot play this audio. <a href="episode-12.mp3">Download the episode</a>.</p>
  </audio>
</figure>
<p><a href="episode-12-transcript.html">Read the Episode 12 transcript</a>.</p>

Transcript content (in the same sequence as the media): title/metadata; speaker names; all dialogue and narration; meaningful sound/music information; important on-screen text; for a descriptive transcript, visual actions/expressions/demonstrations/charts/scene changes; equivalent instructions/links for any interaction in the media.

Publish as accessible HTML with a clearly named link immediately before/after the player — not only as a download or inaccessible PDF/image, and never only inside aria-label, a tooltip, or a visually-hidden element. A stable anchor URL (#transcript-ep12) makes it directly shareable and discoverable by search engines; collapsing in <details> for visual space is fine as long as the heading/anchor stay in the DOM. Keep transcript corrections synchronized with caption and media revisions.

Interactive transcripts (highlighting current passage, seek-by-timestamp) are enhancements, not substitutes for a complete linear transcript — use buttons for seek actions, give each an understandable time/topic, don't move keyboard focus as playback advances, don't force unpausable auto-scroll, respect reduced-motion, and preserve reading/copying when JS is unavailable.

Serious: Audio Descriptions for Pre-recorded Video

At Level A, WCAG 1.2.3 permits either audio description OR a complete media alternative. At Level AA, WCAG 1.2.5 requires audio description for prerecorded video content — a Level A transcript choice does not remove this AA requirement. If the main audio already communicates all important visual information, no additional description is necessary.

<track kind="descriptions" src="training.descriptions.en.vtt" srclang="en" label="English descriptions">

This <track kind="descriptions"> technique is advisory in current WCAG techniques and depends on browser/player/AT support — do not rely on it without testing; provide a supported selectable track or described version when the player can't present descriptions audibly.

Plan description during production — integrated description (speakers naturally stating names, reading on-screen text, explaining charts) is often clearest and can reduce separately-recorded description needed. Description should be objective, concise, timed around important dialogue, written by people with appropriate expertise, and reviewed with blind/low-vision users. Extended audio description (1.2.7, pausing video for more time) is Level AAA — needed only when pauses in the main audio are insufficient.

Critical: Accessible Media Player

Do not designate one player library as universally accessible — evaluate and test the specific version and configuration against the requirements below; pin dependency versions and review updates.

Start with native <audio controls>/<video controls> when they provide what's needed — native controls reduce custom code but vary by browser; test rather than assume sufficiency. A row of visually styled custom buttons is not an accessible player unless the complete behavior, state, timing, captions, description, seeking, and full-screen interaction are implemented and tested.

Controls and state: play/pause, stop, elapsed time/duration, seek, volume/mute, caption/language selection, audio-description selection, playback speed, chapters, full screen, picture-in-picture, transcript display as applicable. Every control needs an accessible name/role/state/ value — a play button can change its name to "Pause" while playing; a caption toggle can use aria-pressed when truly two-state; a timeline needs name/min/max/current-value and a useful text value (elapsed time). Do not announce every `timeupdate` event through a live region. Keep visible labels in accessible names for speech input; don't communicate selected tracks or muted state through color alone.

<div class="media-controls" role="group" aria-label="Video controls">
  <button id="play-pause" aria-label="Play" type="button">…</button>
  <label for="seek" class="visually-hidden">Seek</label>
  <input type="range" id="seek" min="0" max="100" value="0" aria-label="Seek"
         aria-valuemin="0" aria-valuemax="100" aria-valuenow="0" aria-valuetext="0 seconds">
  <button id="captions-toggle" aria-label="Enable captions" aria-pressed="false" type="button">CC</button>
</div>

Keyboard: every control reachable in logical tab order; Enter/Space operate buttons natively; arrow keys operate ranges and documented composite widgets; focus never trapped in player or full-screen; focus stays visible and unobscured by auto-hiding controls; entering/leaving full screen preserves a logical focus location; controls don't disappear while they or their descendants have focus. Single-character shortcuts must meet WCAG 2.1.4 (off/remap/scoped-to-focus) and must not intercept keys while typing in a field.

Visual/touch: text/icons meet contrast requirements; controls reflow at 400% zoom; touch targets meet WCAG 2.5.8; labels/icons remain understandable in forced-colors mode; pointer hover is never required to reveal the only path to controls; auto-hiding controls meet Content on Hover/Focus (1.4.13) and never hide the focused control.

Captions/description controls: easy to find without starting playback; current language and on/off state programmatically determinable; changing a track doesn't unexpectedly reset playback; preferences persist when promised.

Serious: Embedded and Third-Party Players

The content owner remains responsible for the experience delivered through an embed.