Documentation menu

Accessibility & Consent

Acoustic feedback is only valuable when it is welcome. Pue JS is designed so that the respectful behaviour is the default one, and this page documents the guarantees it provides and the responsibilities that remain with you.

Autoplay policy

Browsers block audio until the user has interacted with the page. Pue JS works with this policy rather than around it:

  • start() called during a user gesture resolves with the emitter in the running state.
  • start() called outside a gesture leaves the emitter suspended. No error is thrown.
  • With autoUnlock: true (the default), a suspended emitter resumes on the next pointerdown, keydown or touchend.

Set autoUnlock: false if you want acoustic feedback to be enabled exclusively through an explicit control.

Reduced motion

Users who set prefers-reduced-motion: reduce have asked for fewer sensory effects. When respectReducedMotion is true (the default), the emitter stays silent for these users and reacts live if the preference changes.

TypeScript
createEmitter(window, {  // Only disable this if acoustic feedback is the explicit purpose of the page.  respectReducedMotion: true,});

Provide a control

WCAG 2.2 success criterion 1.4.2 requires a mechanism to stop audio that plays automatically. Individual emissions are short, but a sustained scroll produces a continuous stream. Always expose a visible toggle, and persist the user's choice.

TSX
"use client"; import { usePue } from "@puejs/react"; export function AcousticToggle(): React.JSX.Element {  const { state, start, stop } = usePue({ preset: "discreet" });  const enabled = state !== "idle";   return (    <button aria-pressed={enabled} onClick={() => (enabled ? stop() : start())} type="button">      Acoustic feedback    </button>  );}

Background tabs

Emitters never emit while the document is hidden. No emission is ever produced for a tab the user is not looking at.

Screen readers

Emissions are rendered through Web Audio and do not interfere with the speech output of assistive technologies. However, simultaneous audio streams increase cognitive load. Consider the discreet preset, or disabling acoustic feedback entirely, when your analytics indicate assistive technology usage.

Checklist

  • Acoustic feedback is opt-in, behind a visible control.
  • The control's state is announced through aria-pressed.
  • The user's choice is persisted across sessions.
  • respectReducedMotion is left enabled.
  • Gain stays at or below the default volume of 0.8.