BD Audio

BD Audio plays short micro-sounds (click, hover, success, error, bump) as interaction feedback. It is headless — no UI of its own, no CSS — and site-agnostic: the mute switch arrives as an injected predicate through window.bdAudioConfig, never a global the module looks up by name. The component requires JavaScript (assets/js/bd-audio.js).

Configuration

Define window.bdAudioConfig before the script loads. Every key is optional; defaults reproduce the full five-sound build.

Key	Default	Meaning
`basePath`	`"/assets/audio/"`	Prefix for sound files. A file starting with `/` bypasses it
`sounds`	five-sound registry	Replaces the default registry wholesale — list only the sounds the site ships, as `{ file, volume }`
`masterVolume`	`1`	One knob over all per-sound volumes (0–1)
`isMuted`	`null`	Injected predicate returning `true` to silence. `null` = never muted
`gateProgrammatic`	`false`	The mute gate covers delegated attribute triggers only; `true` gates `playSound()` calls too
`attributeApi`	`true`	Attach the delegated `data-bd-audio` listeners
`hoverDebounceDelay`	`120`	Hover throttle in ms

Sounds are created lazily on first play, so a registered-but-never-played sound costs no network request.

Basic usage

<script>
  window.bdAudioConfig = {
    sounds: {
      success: { file: "success.mp3", volume: 0.08 },
      error:   { file: "error.mp3",   volume: 0.14 }
    },
    isMuted: function () { return window.mySiteIsSoundOff(); },
    gateProgrammatic: true,
    attributeApi: false
  };
</script>
<script src="/assets/js/bd-audio.js" defer></script>

Attribute API — data-bd-audio is a space-separated list:

<button class="button" data-bd-audio="click">Save</button>
<a class="button" data-bd-audio="hover" href="/work">Work</a>
<button class="button" data-bd-audio="click hover">Both</button>

JavaScript

The script exposes a singleton at window.bdAudio (created on DOMContentLoaded, idempotent across re-runs) plus window.initBdAudio for dispatcher parity.

Call	Purpose
`bdAudio.playSound(name)`	Programmatic playback — form success/error feedback
`bdAudio.setMasterVolume(v)`	Tuning: overall level, 0–1
`bdAudio.setSoundVolume(name, v)`	Tuning: one sound's base volume
`bdAudio.getAllSoundVolumes()`	Tuning: current per-sound volumes

The isMuted predicate is read at play time, never captured at init — load order between this module and the site's sound switch does not matter.

Accessibility

Sound is enhancement only — nothing may communicate through sound alone; every audio cue must accompany a visible state change.
The site owning the mute switch must expose it as a real control: a <button> with a state the user can perceive (WCAG 1.4.2 background audio control).
Respect the visitor's choice by default: gate delegated triggers through isMuted, and keep sounds silent-by-default on sites where audio was never opted into.
Keep volumes low; the defaults are tuned to sit under content.

Usage rules

Declare the exact sound set the site ships — the registry replaces the defaults wholesale
Inject the site's mute switch as the isMuted predicate
Use the attribute API for interaction sounds and playSound() for outcome feedback

Don't

Reference a site global from inside the module — configuration is the only coupling allowed
Set gateProgrammatic: false and also skip call-site gating — pick one gate location deliberately
Add sounds to interactions that fire rapidly (scroll, mousemove) — the engine throttles hover for a reason

CSS reference

BD Audio ships no CSS — it is a behaviour-only module. The sound toggle UI (button, state, storage) belongs to the consuming site.

Use in another product

The design system installs once per product:

npm install github:bydefaultstudio/design-system-dist#semver:^4.7.0

This component ships no CSS — it is behaviour only. Its behaviour ships as dist/js/bd-audio.js — copy it into the product's served assets and include it once per page:

<script src="assets/js/bd-audio.js" defer></script>