Extend audio-plugins-fx with the enterprise extras

Package: @suaveplan/audio-plugins-fx Status: PROPOSED Type: feature

Why

The in-flight enterprise-audio-plugins-fx change shipped 19 plugins matching the genesis-original spec: EQ, Filter, Compressor, Limiter, Gate, Reverb, Delay, Chorus, Phaser, Flanger, Tremolo, AutoFilter, Distortion, Sampler, Synthesizer, PitchShifter, Spatial, Mixer, StereoWidener. The enterprise spec at ../suaveplan/enterprise/audio-plugins-fx.md lists five further plugins that the main-branch package ships but genesis does not yet cover: AudioAnalyzer, MicrophoneSimulationPlugin, GLaDOSPlugin, GameAudioPlugin, and AudioPlayerPlugin. These plugins drive the React audio surface (visualisers, voice-effect demos), the React audio player, and the game-audio composite used by the game packages. Without them in genesis, downstream packages cannot be rebuilt at parity with main.

This change adds the five plugins on their own subpaths so consumers can tree-shake to exactly the surface they need, keeps every plugin universal-tier under the same AudioFxPlugin contract that the existing 19 already satisfy, and routes any browser-only fast paths through the optional createAudioNode / getWorkletProcessor hooks declared in the base contract.

What changes

ADDED: ./audio-analyzer subpath exporting AudioAnalyzerPlugin — tap-point analyser exposing getFrequencyData(), getWaveformData(), async getters for tempo, pitch, spectralFeatures, energy, key, plus an onAnalysisUpdate(callback) subscription and applyPreset(name) for music | speech | percussion | ambient. Pass-through processing on the audio path.
ADDED: ./microphone subpath exporting MicrophoneSimulationPlugin and createMicrophonePlugin(options) factory — source plugin (io.inputs[0].count === 0, outputs.count === 1) that synthesises a microphone-coloured signal from white-noise + oscillator + frequency-resonance-distortion + dynamics + wow-and-flutter stages, all configurable via a typed MicrophoneConfig. Includes the structured UI control descriptor (MicrophoneUISection[]) so editors can render the simulation's parameter surface without hard-coding it.
ADDED: ./glados subpath exporting GLaDOSPlugin — voice-effect chain combining pitch shift, formant shift, robotic intensity, distortion, reverb, and low-pass filtering with named presets (glados-mainline | glados-test-chamber | glados-cake-deception | wheatley | cave-johnson | robotic-generic). Insert plugin (io.inputs[0].count === outputs[0].count === "preserve").
ADDED: ./game subpath exporting GameAudioPlugin — composite plugin for game audio: spatial sources (createSpatialSource, position/orientation/Doppler/occlusion), music-layer mixing (addMusicLayer, crossfadeMusicLayers), and proximity voice chat (enableProximityVoiceChat, addVoiceChatParticipant, distance-based attenuation, bandwidth optimisation tier). Effects bus with blendable voice effects.
ADDED: ./audio-player subpath exporting AudioPlayerPlugin — source plugin that decodes an audio asset from a URL into a Float32Array PCM buffer (universal path) or routes through HTMLAudioElement.captureStream() (browser path via createAudioNode). Exposes load(url, { signal? }), play(), pause(), stop(), seek(time), setVolume, setLoop, setPlaybackRate, getState().
MODIFIED: package vite.config.ts and package.json to declare the five new subpath exports.
MODIFIED: openspec/specs/audio-plugins-fx/spec.md — folded delta adds five new Requirement blocks, each with at least one Verified by: line pointing at a real test path.

Out of scope

Browser-engine integration (@suaveplan/audio-engine-browser wiring createAudioNode into a Web Audio graph) — separate change in that package.
React bindings (@suaveplan/react-audio-analyzer-viz, @suaveplan/react-audio-player) — handled in their own packages once these plugins land.
The essentia.js optional analyser bridge from main-branch — deferred behind a peerDependenciesMeta.optional declaration in a follow-up; the universal analyser uses the built-in browser-equivalent FFT path only.
Worklet hot-reload, oversampling on Compressor/Distortion/PitchShifter, mid/side processing on EQ/Compressor/Reverb, the convolution IR library, parameter-automation lanes beyond the existing universal setParameterCurve surface — all listed in the enterprise plan's §4 enhancements, all deferred to dedicated change proposals so this one stays scoped to "add the missing plugins".
The package split into per-plugin packages (split-audio-plugins-fx) — a separate in-flight change; lands after this one once the surface is complete.

Source mapping

REQUIRED. This change derives from ../suaveplan/enterprise/audio-plugins-fx.md plus the implementation under ../suaveplan/packages/browser/audio-plugins-fx/src/plugins/<name>/.

Requirement	Source lines	Notes
Audio analyzer plugin	`enterprise/audio-plugins-fx.md` §1 line 11; `packages/browser/audio-plugins-fx/src/plugins/audio-analyzer/audio-analyzer.ts:28-870`	Reworded for universal tier; FFT path stays, essentia bridge deferred
Microphone simulation plugin	`enterprise/audio-plugins-fx.md` §1 line 11; `packages/browser/audio-plugins-fx/src/plugins/microphone/microphone.ts:10-490`	UI section descriptor preserved verbatim
GLaDOS voice-effect plugin	`enterprise/audio-plugins-fx.md` §1 line 11; `packages/browser/audio-plugins-fx/src/plugins/glados/glados.ts:21-700`	Preset set expanded per §4.7 (Wheatley, Cave Johnson, robotic-generic)
Game audio plugin	`enterprise/audio-plugins-fx.md` §1 line 11; `packages/browser/audio-plugins-fx/src/plugins/game/game-audio.ts:22-820`	Composite of spatial + music-layer + proximity-voice surfaces
Audio player plugin	`enterprise/audio-plugins-fx.md` §1 line 11; `packages/browser/audio-plugins-fx/src/plugins/audio-player/audio-player.ts:18-413`	Universal decode path replaces HTMLAudioElement-only impl from main

Requirements with no source line

Requirement	Justification
`AbortSignal` on every async load entry point	Aligns with the genesis-side `loadImpulseResponse` / `loadSample` precedent — no main-branch equivalent because main's `load(url)` ignores abort
Universal-tier purity (no browser globals on the `BlockProcessor` path)	New constraint introduced by the genesis package design; the main-branch plugins assume an `AudioContext` and are not portable
Zod boundary validation on every plugin's options + preset shape	Already required by the existing `enterprise-audio-plugins-fx` change for the first 19 plugins; this extension keeps the policy consistent

Verification approach

Each new plugin lands with the same five-file co-location pattern the existing 19 already use: <name>.ts (implementation), <name>.types.ts, <name>.test.ts, <name>.md, plus schemas/{schemas.ts, schemas.md, index.ts} and index.ts. Tests run under vitest with no mocks — the audio path uses real Float32Array arithmetic, the URL loaders use data: URLs the same way ReverbPlugin.loadImpulseResponse already does, and any browser-only paths are exercised via happy-dom polyfills.

src/plugins/audio-analyzer/audio-analyzer.test.ts — covers analyzer surface (FFT, presets, callback subscription).
src/plugins/microphone/microphone.test.ts — covers source-plugin behaviour (output non-silent, options validated, UI section descriptor preserved).
src/plugins/glados/glados.test.ts — covers voice-chain wiring, parameter setters, preset application.
src/plugins/game/game-audio.test.ts — covers spatial source lifecycle, music-layer crossfade, proximity-voice attenuation.
src/plugins/audio-player/audio-player.test.ts — covers load / play / stop / seek / loop / playbackRate, AbortSignal handling.
bunx turbo test:coverage --filter=@suaveplan/audio-plugins-fx — must hit 100/100/100/100 on every new module the same way the existing 19 do.

Migration impact

None — additive only. The five new subpath exports do not modify or remove any existing export. Consumers of the existing 19 plugins continue to work without changes. The split-audio-plugins-fx change (in-flight) will relocate every plugin including these five into its own package, but the API surface stays stable across that move.

8.3 KiB Raw Permalink Blame History