suaveplan/openspec/archive/2026-05-15-superseded-enterprise-browser-audio-plugins-fx/tasks.md

Tasks: enterprise-browser-audio-plugins-fx

Change ID: enterprise-browser-audio-plugins-fx Package: @suaveplan/audio-plugins-fx Target path: browser/audio/audio-plugins-fx Prerequisite packages on Verdaccio: @suaveplan/audio-engine, @suaveplan/error, @suaveplan/types, @suaveplan/events

---

1. Scaffold

• Create browser/audio/audio-plugins-fx/ directory tree per layout in proposal.md.
• Write package.json at version 0.1.0:
  • "sideEffects": false
  • Twelve subpath exports: ./eq, ./reverb, ./delay, ./compressor, ./pitch-shifter, ./synthesizer, ./audio-analyzer, ./microphone, ./mixer, ./glados, ./game, ./audio-player
  • dependencies: @suaveplan/audio-engine workspace:^, @suaveplan/error workspace:^, @suaveplan/types workspace:^, @suaveplan/events workspace:^, standardized-audio-context catalog:browser, zod catalog:forms, @opentelemetry/api catalog:observability, tslib catalog:build
  • optionalDependencies: essentia.js (version from Bun catalog if available, else explicit)
  • devDependencies: vitest catalog:testing, @vitest/coverage-istanbul catalog:testing, @suaveplan/testing workspace:^
• Write tsconfig.json extending @suaveplan/typescript-config/library-browser.json.
• Write vitest.config.ts with pool: 'forks', fileParallelism: false.

---

2. Error codes (src/error-codes.ts)

• Define AudioFxErrorCode: DSP_INIT_FAILED, DSP_PROCESSING_FAILED, PRESET_VALIDATION_FAILED, WORKLET_REQUIRED, ESSENTIA_UNAVAILABLE, SIDECHAIN_UNAVAILABLE.
• Export registerAudioFxErrorCodes() and call eagerly.

---

3. EQ plugin (src/plugins/eq/)

• Implement EQPlugin with multi-band parametric EQ, biquad filter nodes, EQ_PRESETS.
• Split into eq-dsp.ts (filter nodes, freq/gain/Q), eq-params.ts (parameter definitions), eq-presets.ts, eq-plugin.ts.
• Add EQBand and EQPluginConfig Zod schemas.
• Write tests for each sub-module (≤500 lines each), eq-plugin.md.

---

4. Reverb plugin (src/plugins/reverb/)

• Implement ReverbPlugin with IR convolver + REVERB_DURATIONS, dry/wet mix.
• Split into reverb-dsp.ts, reverb-ir.ts (impulse response loader), reverb-presets.ts, reverb-plugin.ts.
• Write tests, reverb-plugin.md.

---

5. Delay plugin (src/plugins/delay/)

• Implement DelayPlugin with feedback loop and wet/dry mix.
• Write delay-plugin.test.ts, delay-plugin.md.

---

6. Compressor plugin (src/plugins/compressor/)

• Implement CompressorPlugin with standard Web Audio DynamicsCompressorNode params.
• Add sidechain input: CompressorPlugin.setSidechainSource(node) with SIDECHAIN_UNAVAILABLE error when not wired.
• Add mid/side processing mode.
• Write tests, compressor-plugin.md.

---

7. Pitch Shifter plugin (src/plugins/pitch-shifter/)

• Implement PitchShifterPlugin as AudioWorklet host.
• Add worklets/pitch-shifter.ts processor.
• Export resolvePitchShifterWorkletUrl() helper for Vite/Webpack: new URL('../worklets/pitch-shifter.js', import.meta.url).href.
• Add ScriptProcessorNode fallback path (in worklet-fallback.ts) when AudioWorklet unavailable.
• Write tests for both paths, pitch-shifter-plugin.md.

---

8. Synthesizer plugin (src/plugins/synthesizer/)

• Implement full SynthesizerPlugin: oscillators (sine/square/sawtooth/triangle), ADSR envelope, voice pool (polyphony), filter.
• Split into oscillator.ts (≤300), envelope.ts (≤300), voice-pool.ts (≤300), synth-presets.ts, synthesizer-plugin.ts.
• Add SynthesizerPreset Zod schema.
• Write tests per sub-module, synthesizer-plugin.md.

---

9. Audio Analyzer plugin (src/plugins/audio-analyzer/)

• Implement AudioAnalyzerPlugin with FFT (AnalyserNode), tempo BPM estimation, key detection.
• Add essentia-bridge.ts: dynamic import('essentia.js') with try/catch; export isEssentiaAvailable(). When unavailable, key/spectral features return null.
• No @ts-expect-error; type the dynamic import result with an explicit interface.
• Write tests with and without essentia stub (real interface, not vi.mock), audio-analyzer-plugin.md.

---

10. Microphone plugin (src/plugins/microphone/)

• Implement MicrophoneSimulationPlugin + createMicrophonePlugin factory.
• Add MicrophonePreset Zod schema.
• Write tests, microphone-plugin.md.

---

11. Mixer plugin (src/plugins/mixer/)

• Implement MixerPlugin with channel strips, sends, routing, master gain.
• Fully implement send-state round-trip in mixer-sends.ts — no TODO.
• Add MixerPreset Zod schema.
• Split into channel-strip.ts (≤300), mixer-sends.ts (≤300), mixer-presets.ts, mixer-plugin.ts.
• Write regression test: applyPreset(getPreset()) round-trips sends exactly.
• Write mixer-plugin.md.

---

12. GLaDOS plugin (src/plugins/glados/)

• Implement GLaDOSPlugin with voice-effect chain (ring modulator + pitch shift + bitcrusher) and GLaDOSPreset options.
• Add Wheatley, Cave Johnson, generic robotic presets.
• Split into glados-dsp.ts, glados-presets.ts, glados-plugin.ts.
• Add GLaDOSPreset Zod schema.
• Write tests, glados-plugin.md.

---

13. Game Audio plugin (src/plugins/game/)

• Implement GameAudioPlugin: PannerNode-based 3D spatial audio, proximity voice chat (gain-by-distance), music layer system, HUD voice channel.
• Game-audio ducking bus: music auto-ducks when VoIP speaks.
• Split into spatial-audio.ts, proximity-voice.ts, music-layers.ts, game-audio-plugin.ts.
• Add GameAudioPreset Zod schema.
• Write tests per sub-module, game-audio-plugin.md.

---

14. Audio Player plugin (src/plugins/audio-player/)

• Implement AudioPlayerPlugin with load/play/pause/stop/seek, loop, playback rate, volume.
• Write audio-player-plugin.test.ts, audio-player-plugin.md.

---

15. Bundle-size snapshot tests (tests/bundle-size/)

• One snapshot test per subpath: build the entry point and assert that the emitted chunk does not contain symbols from other plugins (tree-shake isolation). Use rollup or esbuild in the test script.

---

16. Integration test (tests/integration.test.ts)

• Load all twelve plugins into a single AudioEngine instance; verify no cross-plugin contamination.
• Preset round-trip test for every plugin with a Zod schema.
• Mixer sends round-trip regression.
• PitchShifter worklet URL helper returns a URL string.

---

17. Docs

• Write .md for every plugin module (≥200 words, simple + advanced examples, API reference).
• Write README.md with purpose, subpath table, preset schema table, worklet bundling notes, deps table.

---

18. Verify and publish

• bunx turbo lint typecheck test --filter=@suaveplan/audio-plugins-fx — green.
• bunx turbo test:coverage --filter=@suaveplan/audio-plugins-fx — 100% on touched modules.
• bun run docs:check --filter=@suaveplan/audio-plugins-fx — zero errors.
• No TODO, FIXME, any, ts-ignore, ts-expect-error, vi.mock, .skip in src/.
• All twelve subpath tree-shake snapshots green.
• Mixer sends round-trip regression test passes.
• bun scripts/publish.ts --package @suaveplan/audio-plugins-fx.
• Archive to openspec/archive/2026-04-24-enterprise-browser-audio-plugins-fx/.