# Original User Request

## Initial Request — 2026-07-26T09:38:00Z

An interactive 3D web application using Three.js and Web Audio API that simulates realistic real-time spatial audio propagation (distance attenuation, directional sound cone, doppler effect, room acoustic reflections) with interactive 3D sound source controls and listener perspective.

Working directory: /pantheon/pfs/git/threejs_sound_sim
Integrity mode: demo

## Requirements

### R1. Interactive 3D Audio Environment & Navigation
Build a responsive 3D web interface using Vite, Three.js, and HTML5/CSS. Render a textured 3D room environment containing a movable 3D sound source object (with directional orientation indicators) and a listener/microphone object mapped to camera controls. Provide smooth orbit and keyboard/mouse controls to manipulate both listener and source positions in real time.

### R2. Real-Time Spatial Audio Physics Engine
Implement realistic spatial audio rendering using Web Audio API:
1. Distance Attenuation: Inverse-square / exponential distance attenuation models with configurable rolloff factors.
2. Directional Emission: Cone-based directional audio patterning (inner angle, outer angle, outer gain attenuation).
3. Doppler Pitch Shift: Dynamic frequency pitch calculation based on relative velocity vector between moving sound source and listener.
4. Room Acoustics & Occlusion: Environment reverberation simulation using ConvolverNode / impulse responses or synthetic feedback delay networks, plus acoustic attenuation when obstacles block direct line-of-sight.

### R3. Audio Dashboard & Visualizers
Provide a modern, glassmorphic UI overlay with:
1. Audio Source Controls: Preset selection (instrument sample, engine sound, synthesized tone generator), play/pause, volume master.
2. Physics & Room Controls: Sliders for source velocity, room dimensions/reverb preset, rolloff factor, and directional cone angles.
3. Spectrum & Waveform Analysis: Live canvas visualizers showing real-time frequency spectrum and oscilloscope waveform data from Web Audio AnalyserNode.

### R4. Verification & Build Suite
Provide programmatic test coverage:
1. Unit tests for spatial audio physics calculations (distance gain formulas, doppler shift equation output validation).
2. Automated build check ensuring npm run build generates an error-free production bundle.

## Acceptance Criteria

### 3D Visualization & Interaction
- [ ] 3D scene renders smoothly (60 FPS target) with room boundaries, sound source mesh, directional vector cone, and listener mesh.
- [ ] User can interactively position, drag, or rotate the sound source in 3D space.
- [ ] Camera controls allow orbiting, panning, and inspecting the acoustic environment from the listener's perspective.

### Realistic Spatial Audio Simulation
- [ ] Moving listener further from sound source reduces volume according to configured distance attenuation model.
- [ ] Dynamic relative motion between source and listener produces audible and measurable Doppler pitch shift.
- [ ] Rotating the directional sound source attenuates volume when the listener is outside the inner emission cone.
- [ ] Toggling room reverb presets dynamically changes spatial acoustic reflection parameters.

### User Interface & Analysis
- [ ] Control dashboard updates physics and audio parameters seamlessly without audio glitching.
- [ ] Frequency spectrum and oscilloscope canvases render live audio waveforms accurately.

### Programmatic Verification
- [ ] npm test passes all unit tests for spatial audio math and calculation modules.
- [ ] npm run build succeeds without build or bundling errors.