SiteLint documentation and guidelines

Verify audio controls

Description

This rule does not perform any automated validation. It simply reminds you to manually verify that when <audio> or <video> content plays automatically for more than 3 seconds, users have a mechanism to pause, stop, or control the volume independently from the system volume. If any audio on a Web page plays automatically for more than 3 seconds, either a mechanism is available to pause or stop the audio, or a mechanism is available to control audio volume independently from the overall system volume level. (Per WCAG Success Criterion 1.4.2.)

Auto-playing audio can interfere with screen reader speech, disorient users, and make it impossible to hear system notifications. Without an accessible stop or volume control, users who rely on assistive technology may be unable to access the page content at all.

Disabilities impacted

  • Blindness and low vision – Screen reader users depend on clear audio output from their assistive technology. Auto-playing background audio or video can drown out or compete with the screen reader voice, making navigation and reading impossible until the audio is stopped.
  • Cognitive disabilities – Unexpected sounds can cause distraction, anxiety, or sensory overload. Users with attention deficits, autism, or anxiety disorders may find auto-playing audio overwhelming and may leave the page if they cannot silence it quickly.
  • Motor disabilities – Users who rely on switch devices, voice control, or eye tracking may struggle to locate and activate a small pause button hidden among other controls. A clearly placed and keyboard-accessible mechanism is essential.

Why it matters

WCAG 1.4.2 ensures that users retain control over their listening environment. Auto-playing audio that cannot be paused or silenced violates a basic principle of user agency. This criterion applies equally to background music, video soundtracks, notifications, and any other audible content that starts without user initiation. Meeting it benefits all users, not just those with disabilities – for example, someone browsing in a quiet public space also needs to quickly mute unexpected sound.

Coding problems and solutions

Because this rule is manual-only, no code-level detection is performed. The checklist below describes what a human auditor should verify and common pitfalls to look for.

Manual verification checklist

  • No pause/stop mechanism – The most common failure: an <audio> or <video> element with autoplay that has no visible, keyboard-operable pause or stop button.
  • Volume control tied to system volume – If the only way to lower the audio is the device’s physical volume keys, users cannot silence the page audio independently. A separate in-page volume slider or mute toggle is required.
  • Hidden or inaccessible controls – The default controls attribute is present but the browser-supplied UI may be small, unstyled, or unfocusable via keyboard. Custom controls must be built with native <button> elements and proper ARIA labels.
  • Auto-playing video without user gesture – Modern browsers often block autoplay with audio, but workarounds (e.g., silent muted first, then unmuting via script) can still create a jarring experience. Verify that unmuting only happens after explicit user interaction.
  • Controls appear only on hover – Some custom media players hide the control bar until the user hovers over the player. This makes the controls inaccessible to keyboard-only or touch-screen users.

How to fix it

Provide visible pause/stop and volume controls

Ensure every auto-playing media element includes a pause or stop button and a volume or mute control that works independently from the system volume. Custom controls must be built with semantic HTML and support keyboard interaction.

Correct example
<div class="media-player">
  <video src="promo.mp4" autoplay></video>
  <button type="button" id="pauseBtn">Pause</button>
  <button type="button" id="muteBtn">Mute</button>
  <label for="volSlider">Volume</label>
  <input type="range" id="volSlider" min="0" max="1" step="0.1" value="0.5">
</div>
Incorrect example
<video src="promo.mp4" autoplay></video>
<!-- No pause, mute, or volume controls at all -->

Note that if you rely on the native controls attribute, browser default UIs vary in accessibility. Test with keyboard navigation and a screen reader to confirm that the play, pause, and volume controls are reachable and operable. When building custom controls, use native <button> elements and associate them with the media element via JavaScript. Note that the title attribute should not be used as the sole label for media controls, as its support across screen readers is inconsistent.

Use the HTML5 controls attribute as a fallback

When a custom media player is not feasible, the native controls attribute provides a basic set of play, pause, volume, and timeline controls. However, always verify that the native UI is keyboard accessible and clearly visible on the page.

Correct example
<audio src="background-music.mp3" autoplay controls></audio>
Incorrect example
<!-- No controls attribute and no custom controls -->
<audio src="background-music.mp3" autoplay></audio>

Allow users to mute or pause before content starts

Ideal practice: do not autoplay media at all. If autoplay is required, place the pause and mute controls before the media element in the DOM order so keyboard users encounter them first, or provide a Play button that requires explicit user activation.

Correct example
<button type="button" id="playBtn">Play video</button>
<video id="myVideo" src="demo.mp4"></video>

<script>
  const playButton = globalThis.document.getElementById('playBtn');
  const video = globalThis.document.getElementById('myVideo');

  playButton.addEventListener('click', () => {
    video.play();
  });
</script>
Incorrect example
<!-- Starts playing immediately with no prior user interaction -->
<video src="demo.mp4" autoplay></video>

Set a maximum autoplay duration before requiring interaction

If audio must play automatically, limit it to a short duration (3 seconds or less) or provide a timed pause that triggers automatically. Use the timeupdate event to pause after a threshold and surface the play button again.

Correct example
<video id="timedVideo" src="teaser.mp4" autoplay></video>
<button type="button" id="resumeBtn" style="display:none">Resume playback</button>

<script>
  const timedVideo = globalThis.document.getElementById('timedVideo');
  const resumeBtn = globalThis.document.getElementById('resumeBtn');
  const handleTimeUpdate = () => {
    if (timedVideo.currentTime >= 3) {
      timedVideo.pause();
      resumeBtn.style.display = 'inline-block';
      resumeBtn.focus();
      timedVideo.removeEventListener('timeupdate', handleTimeUpdate);
    }
  };

  timedVideo.addEventListener('timeupdate', handleTimeUpdate);

  resumeBtn.addEventListener('click', () => {
    resumeBtn.style.display = 'none';
    timedVideo.play();
  });
</script>
Incorrect example
<!-- Audio plays indefinitely with no pause mechanism -->
<audio src="loop.mp3" autoplay loop></audio>

Implement a global mute toggle for the page

On pages with multiple media elements or background audio, provide a single, persistent mute or volume control that affects all audio on the page. Store the user’s preference in sessionStorage to persist across navigations.

Correct example
<button type="button" id="globalMute" aria-pressed="false">
  Mute page
</button>

<script>
  const muteButton = globalThis.document.getElementById('globalMute');
  const allMedia = globalThis.document.querySelectorAll('audio, video');
  let isMuted = false;

  muteButton.addEventListener('click', () => {
    isMuted = !isMuted;
    for (const media of allMedia) {
      media.muted = isMuted;
    }
    muteButton.setAttribute('aria-pressed', String(isMuted));
    muteButton.textContent = isMuted ? 'Unmute page' : 'Mute page';
  });
</script>
Incorrect example
<!-- Multiple auto-playing elements with no centralized control -->
<audio src="bg.mp3" autoplay></audio>
<video src="ad.mp4" autoplay></video>

Known Limitations

  • Manual-only rule – This rule does not automatically detect whether a pause or volume mechanism actually works. It only identifies elements that may need manual review. A human must test each flagged element with keyboard and screen reader to confirm compliance.
  • Shadow DOM – Media elements nested inside shadow roots are not traversed by the rule’s selector. Auditors must manually inspect any custom web component that encapsulates an <audio> or <video> element.
  • Dynamically inserted media – Content loaded after the initial page render (e.g., via fetch, WebSocket, or lazy loading) will not be re-scanned. A separate scan or manual check is required for dynamically injected media elements.
  • Third-party embeds – Iframes hosting external media players (YouTube, Vimeo, SoundCloud) are opaque to this rule. The auditor must navigate into each iframe to verify that the embedded player provides accessible controls.
  • Single-page applications – Client-side routing that swaps DOM trees may add new media elements without triggering a re-audit. Auditors should re-run the rule after each significant view change.

Resources

Rule

  • Audit: accessibility
  • Standard: WCAG
  • Level: A
  • Success Criteria: 1.4.2
  • Rule ID: audio-control