Stats
Actions
Tags
From grimoire
Provides patterns for audio/video autoplay with accessible pause, stop, or mute controls per WCAG 1.4.2. Use when adding auto-playing media to ensure screen reader compatibility.
How this skill is triggered — by the user, by Claude, or both
Slash command
/grimoire:apply-audio-controlsThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Provide a mechanism to pause, stop, or mute any audio that plays automatically — so screen
Provide a mechanism to pause, stop, or mute any audio that plays automatically — so screen reader users can hear their AT output and users in quiet environments can silence the page.
Adopted by: WCAG 2.1 SC 1.4.2 (Level A) is required by Section 508 (US), EU EN 301 549,
and UK PSBAR 2018 — Level A means it is the baseline accessibility floor. All major browsers
block audio autoplay by default (Chrome 66+, Firefox 66+, Safari 11+) as a direct response to
this accessibility and user experience problem. The W3C Media Accessibility User Requirements
document identifies audio control as a core screen reader compatibility requirement.
Impact: Screen reader users navigate by listening. Auto-playing audio — even at low volume —
overlaps with screen reader speech, making page content inaudible. Users with hearing impairments
who rely on visual feedback cannot tell where audio is coming from. WebAIM's 2024 survey found that
auto-playing audio was rated the #3 most annoying accessibility barrier by screen reader users.
Why best: The alternative — <audio autoplay> with no controls — has no legitimate use case
that outweighs the accessibility cost. Browser autoplay blocking means most auto-playing audio
fails silently in modern browsers anyway. Starting muted with user-initiated unmute is the correct
pattern for background audio; visible controls are required for any audio that does play.
Sources: W3C WCAG 2.1 SC 1.4.2 (2018); W3C Media Accessibility User Requirements; WebAIM Screen Reader Survey 2024; Chrome Autoplay Policy (2018)
<!-- Wrong — audio autoplays, conflicts with screen readers -->
<audio autoplay src="background-music.mp3"></audio>
<video autoplay src="promo.mp4"></video>
<!-- Right — audio does not autoplay -->
<audio controls src="background-music.mp3">
<p>Your browser does not support audio playback.</p>
</audio>
<!-- Right — video autoplays but starts muted; user must unmute -->
<video autoplay muted playsinline controls src="promo.mp4">
<track kind="captions" src="promo.vtt" srclang="en" label="English">
</video>
muted + autoplay satisfies 1.4.2 because there is no audio output until the user
explicitly unmutes. Native controls provides the user mechanism.
If autoplay audio is unavoidable (e.g., audio serves as a live alert), place the pause/mute control as the very first focusable element on the page — before any other content:
<body>
<!-- First focusable element is the audio control — before navigation, before content -->
<div id="audio-control-bar">
<button id="mute-audio" type="button" aria-pressed="false">
Mute background audio
</button>
<audio id="bg-audio" autoplay loop src="ambient.mp3"></audio>
</div>
<nav><!-- navigation --></nav>
<main><!-- content --></main>
</body>
const muteBtn = document.getElementById('mute-audio');
const audio = document.getElementById('bg-audio');
muteBtn.addEventListener('click', () => {
audio.muted = !audio.muted;
muteBtn.setAttribute('aria-pressed', String(audio.muted));
muteBtn.textContent = audio.muted ? 'Unmute background audio' : 'Mute background audio';
});
"First in tab order" means a screen reader user pressing Tab immediately reaches the mute control — before they encounter any content obscured by the audio.
SC 1.4.2 is satisfied by either: (a) pause/stop, (b) mute, or (c) volume control independent of system volume. For background audio or ambient sound:
<label for="bg-volume">Background audio volume</label>
<input type="range" id="bg-volume" min="0" max="1" step="0.1" value="0.5"
aria-valuemin="0" aria-valuemax="100" aria-valuenow="50"
aria-valuetext="50%">
const volumeSlider = document.getElementById('bg-volume');
const bgAudio = document.getElementById('bg-audio');
volumeSlider.addEventListener('input', (e) => {
bgAudio.volume = parseFloat(e.target.value);
const pct = Math.round(e.target.value * 100);
volumeSlider.setAttribute('aria-valuenow', pct);
volumeSlider.setAttribute('aria-valuetext', `${pct}%`);
});
Modern browsers block autoplay with sound. Handle the blocked autoplay case:
const audio = document.getElementById('bg-audio');
audio.play().catch((error) => {
if (error.name === 'NotAllowedError') {
// Autoplay blocked by browser — show a play button instead
document.getElementById('play-prompt').removeAttribute('hidden');
}
});
<!-- Fallback for blocked autoplay -->
<div id="play-prompt" hidden>
<button id="start-audio" type="button">Play background audio</button>
</div>
This handles the common case where developers rely on autoplay but browsers silently block it — resulting in neither audio playing nor controls being visible.
Background audio with no controls attribute and no custom controls. The audio plays,
no UI element exists to stop it, and keyboard users cannot reach any control. Always add
either native controls or a custom mute button.
Mute button that appears only after audio starts playing. If the mute control renders after a JavaScript-controlled delay, keyboard users may hear audio for several seconds before they can silence it. Render the control before audio starts.
Volume slider without aria-valuetext. A range input with values 0–1 announces "0.5"
to screen readers. Use aria-valuenow (numeric) + aria-valuetext ("50%") so the value
is meaningful when announced.
npx claudepluginhub jeffreytse/grimoire --plugin grimoireDesigns accessible video/audio with captions, transcripts, and audio descriptions. Guides creation and review of multimedia for accessibility compliance.
Adds TTS read-aloud, MP3 audio player, and voice CRO triggers to any website. Zero dependencies, progressive enhancement. Use when implementing audio features on static or dynamic sites.
Audits and improves web accessibility following WCAG 2.2 guidelines, including POUR principles, alt text for images/icons, color contrast, and focus states. Use for a11y audits and compliance.