PixelPilot uiux-sound-design.instructions.md

Sound Design for Web Interfaces

Sound is the forgotten dimension of UX. This file covers UI audio feedback, scroll-linked sounds, data sonification, and how to make your interface feel alive through careful audio design — without being annoying.

---

CRITICAL RULES

1. Off by default — Sound must be opt-in. Auto-playing audio is hostile.
2. Respect system settings — Check prefers-reduced-motion (often correlates with audio preference).
3. Short and subtle — UI sounds are 50-200ms. Never jarring.
4. Volume control — Always provide a way to adjust or mute.
5. Accessibility — Sound is enhancement, never the only feedback.
6. Context-aware — No sounds in serious/professional contexts unless expected.

---

AUDIO CONTEXT SETUP

// audioManager.ts — Singleton for managing UI sounds

class AudioManager {
  private context: AudioContext | null = null;
  private gainNode: GainNode | null = null;
  private sounds: Map<string, AudioBuffer> = new Map();
  private enabled: boolean;
  private volume: number;

  constructor() {
    this.enabled = localStorage.getItem('ui-sounds') !== 'false';
    this.volume = parseFloat(localStorage.getItem('ui-sounds-volume') || '0.5');
  }

  private async getContext(): Promise<AudioContext> {
    if (!this.context) {
      this.context = new AudioContext();
      this.gainNode = this.context.createGain();
      this.gainNode.gain.value = this.volume;
      this.gainNode.connect(this.context.destination);
    }

    // Resume if suspended (browser autoplay policy)
    if (this.context.state === 'suspended') {
      await this.context.resume();
    }

    return this.context;
  }

  async loadSound(name: string, url: string): Promise<void> {
    try {
      const response = await fetch(url);
      const arrayBuffer = await response.arrayBuffer();
      const context = await this.getContext();
      const audioBuffer = await context.decodeAudioData(arrayBuffer);
      this.sounds.set(name, audioBuffer);
    } catch (error) {
      console.warn(`Failed to load sound: ${name}`, error);
    }
  }

  async play(name: string, options: { volume?: number; playbackRate?: number } = {}): Promise<void> {
    if (!this.enabled) return;

    const buffer = this.sounds.get(name);
    if (!buffer) {
      console.warn(`Sound not found: ${name}`);
      return;
    }

    const context = await this.getContext();
    const source = context.createBufferSource();
    source.buffer = buffer;
    source.playbackRate.value = options.playbackRate ?? 1;

    // Per-sound volume adjustment
    if (options.volume !== undefined) {
      const volumeNode = context.createGain();
      volumeNode.gain.value = options.volume;
      source.connect(volumeNode);
      volumeNode.connect(this.gainNode!);
    } else {
      source.connect(this.gainNode!);
    }

    source.start(0);
  }

  setVolume(value: number): void {
    this.volume = Math.max(0, Math.min(1, value));
    localStorage.setItem('ui-sounds-volume', String(this.volume));
    if (this.gainNode) {
      this.gainNode.gain.value = this.volume;
    }
  }

  setEnabled(enabled: boolean): void {
    this.enabled = enabled;
    localStorage.setItem('ui-sounds', String(enabled));
  }

  isEnabled(): boolean {
    return this.enabled;
  }
}

export const audio = new AudioManager();