| name | audio-video |
| description | Load this skill whenever the project contains audio or video content, media players, podcasts, video embeds, or any <audio>/<video> elements. Under no circumstances publish audio or video without captions, transcripts, and audio descriptions where required. Absolutely always apply WCAG 1.2 criteria for time-based media.
|
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
All users must access the full meaning of multimedia through alternative formats
and accessible controls — including people who are Deaf/hard of hearing,
blind/low vision, DeafBlind, or have cognitive or motor disabilities.
Severity Scale (this skill)
| Level | Meaning |
|---|
| Critical | Media content completely inaccessible to a disability group |
| Serious | Access significantly impaired; workaround unreasonable to expect |
| Moderate | Access degraded but partially available |
| Minor | Best-practice gap; marginal impact on access |
Critical: Never Autoplay Audio
Never use autoplay on <video> or <audio> that plays sound.
Autoplaying audio that cannot be immediately stopped is Critical (WCAG 1.4.2,
Level A) — it interferes directly with screen readers, which use audio as their
primary output channel. It can also cause severe distress for users with
sensory processing conditions.
<video src="intro.mp4" autoplay></video>
<audio src="ambient.mp3" autoplay></audio>
<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; }
}
If sound autoplays for any reason, a mechanism to stop, pause, or mute it
must be the first keyboard stop on the page, reachable before any
other content.
Critical: Captions on Pre-recorded Video with Audio
Synchronised captions are required on all pre-recorded video that contains
a spoken or audio track. Missing captions are Critical — Deaf and
hard-of-hearing users cannot access the audio content at all.
Use WebVTT format via the native <track> element:
<video controls>
<source src="video.mp4" type="video/mp4">
<track kind="captions"
src="captions-en.vtt"
srclang="en"
label="English captions"
default>
<track kind="captions"
src="captions-fr.vtt"
srclang="fr"
label="Captions en français">
</video>
Caption quality requirements:
- Accurate transcription of all dialogue
- Speaker identification when speakers are not visually apparent
- Relevant non-speech audio:
[door slams], [tense music], [applause]
- Correct punctuation, capitalisation, and synchronised timing
- Never publish auto-generated captions without human review.
Unreviewed auto-captions are at best Serious — errors in captions
can actively mislead. Review and correct before publishing.
Critical: Transcript for Audio-Only Content
A text transcript is required for all audio-only content (podcasts, recordings,
narrated slideshows). Missing transcript is Critical — Deaf users have no
access to the content at all, and DeafBlind users who use braille displays
need a text transcript, not captions.
<figure>
<audio controls>
<source src="episode.mp3" type="audio/mpeg">
Your browser does not support audio playback.
<a href="episode.mp3">Download the audio file</a>
</audio>
<figcaption>
Episode 12: Accessible Web Forms
<a href="#transcript-ep12">Read the transcript</a>
</figcaption>
</figure>
<section id="transcript-ep12" aria-labelledby="transcript-heading">
<h2 id="transcript-heading">Transcript: Episode 12</h2>
<p><strong>Host:</strong> Welcome to the accessibility podcast.</p>
<p><em>[Intro music fades]</em></p>
</section>
Transcript must include: speaker identification, all dialogue, relevant
non-speech sounds, and description of important visual content (for video).
Make transcripts directly linkable and searchable — a stable anchor URL
(#transcript-ep12) allows users to share the transcript directly, and
exposes it to search engines. Collapsing the transcript in a <details>
element is acceptable for visual space, but the section heading and anchor
must still be present in the DOM.
Serious: Audio Descriptions for Pre-recorded Video
Audio descriptions or a text alternative are required for all pre-recorded
video. Missing audio description is Serious — blind users cannot access
information conveyed only visually (actions, on-screen text, scene changes,
facial expressions).
<video controls>
<source src="video.mp4" type="video/mp4">
<track kind="captions"
src="captions-en.vtt"
srclang="en"
label="English captions">
<track kind="descriptions"
src="audio-descriptions-en.vtt"
srclang="en"
label="Audio descriptions">
</video>
Audio description content must cover: actions and movement, characters and
their expressions, scene changes, on-screen text not spoken aloud, and visual
cues essential to understanding the content.
When the pauses in the main audio track are insufficient for audio description,
provide an extended audio description version or a full text alternative.
Serious: Accessible Media Player
The media player must be fully keyboard operable with visible focus indicators.
An inaccessible media player is Serious — keyboard and AT users cannot
control playback at all.
Recommended: Able Player
Able Player is the recommended
open-source accessible media player. It provides captions, audio descriptions,
keyboard access, and screen reader announcements out of the box.
Hosting requirement: Able Player requires self-hosting its JavaScript and
CSS assets. It cannot be loaded from a CDN without first downloading the files
from the Able Player repository.
Copy /build/ableplayer.min.js and /build/ableplayer.min.css into your
project's asset directory.
<link rel="stylesheet" href="/assets/ableplayer.min.css">
<script src="/assets/ableplayer.min.js"></script>
<video id="video1" data-able-player preload="auto">
<source type="video/mp4" src="video.mp4">
<track kind="captions"
src="captions-en.vtt"
srclang="en"
label="English captions">
<track kind="descriptions"
src="descriptions-en.vtt"
srclang="en"
label="Audio descriptions">
</video>
Minimum requirements for any media player
Any player — native <video controls> or custom — must provide:
- Full keyboard access for all controls (play, pause, seek, volume, fullscreen, captions toggle)
- Visible focus indicators on all interactive elements
- Accessible names for all icon-only buttons
- Play/pause/volume/seek/fullscreen state announced to screen readers
- Caption enable/disable and customisation (size, colour, background)
- Transcript link or inline transcript display
Custom controls pattern
If implementing custom controls:
<div class="media-controls" role="group" aria-label="Video controls">
<button id="play-pause" aria-label="Play" type="button">
<svg aria-hidden="true" focusable="false"></svg>
</button>
<label for="seek" class="visually-hidden">Seek</label>
<input type="range" id="seek"
min="0" max="100" value="0" step="1"
aria-label="Seek"
aria-valuemin="0" aria-valuemax="100" aria-valuenow="0"
aria-valuetext="0 seconds">
<label for="volume" class="visually-hidden">Volume</label>
<input type="range" id="volume"
min="0" max="100" value="100" step="5"
aria-label="Volume"
aria-valuemin="0" aria-valuemax="100" aria-valuenow="100">
<button id="captions-toggle" aria-label="Enable captions"
aria-pressed="false" type="button">CC</button>
<button id="fullscreen" aria-label="Enter fullscreen" type="button">
<svg aria-hidden="true" focusable="false"></svg>
</button>
</div>
Always update aria-valuenow and aria-valuetext on seek and volume inputs
as values change. Update aria-label on play/pause when state changes.
Update aria-pressed and aria-label on captions toggle when state changes.
Moderate: Live Captions (WCAG 1.2.4 AA)
Live video must provide captions where technically feasible. This is Moderate
rather than Critical because "technically feasible" provides legitimate scope
for live content — a truly live, unscripted broadcast has different constraints
from a scripted livestream. Document your reasoning if captions are not provided.
For planned live events: prepare and use scripted captions or CART
(Communication Access Realtime Translation) captioning services.
Moderate: WCAG 1.4.2 Audio Control
If any audio plays automatically for more than 3 seconds, the user must be able
to pause or stop it, or control the volume independently of the system volume.
This is distinct from the autoplay prohibition: it applies even when the user
has initiated playback.
<button type="button" id="mute-toggle"
aria-label="Mute background audio"
aria-pressed="false">
<svg aria-hidden="true" focusable="false"></svg>
</button>
Minor: Sign Language (WCAG 1.2.6 — Level AAA)
WCAG 1.2.6 requires sign language interpretation for all pre-recorded audio
content. This is Level AAA and therefore not required for AA conformance,
but it is the highest-quality accommodation for Deaf users who use sign language
as their primary language. Consider providing sign language videos for high-
priority content (safety information, onboarding, key announcements).
Sign language interpretation is a separate track or video, not a caption
overlay. If provided, it should be available as a toggleable picture-in-picture
panel or a separate video stream.
Definition of Done Checklist
Key WCAG Criteria
- 1.2.1 Audio-only and Video-only Pre-recorded (A) — Critical if absent
- 1.2.2 Captions Pre-recorded (A) — Critical if absent
- 1.2.3 Audio Description or Media Alternative Pre-recorded (A)
- 1.2.4 Captions Live (AA)
- 1.2.5 Audio Description Pre-recorded (AA) — Serious if absent
- 1.2.6 Sign Language Pre-recorded (AAA) — not required for AA; recommended for high-priority content
- 1.4.2 Audio Control (A) — Critical if autoplaying audio cannot be stopped
References
Standards horizon: WCAG 3.0 is expected to preserve the substance of
1.2.x time-based media requirements. No breaking changes to captions or
audio description requirements are currently proposed.
Monitor: https://www.w3.org/TR/wcag-3.0/
