Files
2026-05-27 23:29:53 +01:00

6.1 KiB

Tasks — Extend audio-plugins-fx with the enterprise extras

Every checkbox MUST reflect work actually done in this change.

1. Spec authoring

  • 1.1 Read openspec/AGENTS.md Sections 13 (Verified by) and 14 (Source mapping)
  • 1.2 Draft proposal.md (this file's sibling)
  • 1.3 Draft specs/audio-plugins-fx/spec.md with five ADDED Requirement blocks
  • 1.4 Every requirement carries a **Verified by:** line naming concrete it(...) titles

2. Implementation — AudioAnalyzerPlugin

  • 2.1 mkdir -p packages/audio/audio-plugins-fx/src/plugins/audio-analyzer/schemas
  • 2.2 Author audio-analyzer.ts — tap-point analyser; getFrequencyData, getWaveformData, async getTempo/getPitch/getSpectralFeatures/getEnergy/getKey, onAnalysisUpdate(callback), applyPreset(name)
  • 2.3 Author audio-analyzer.types.ts (analysis update shape, preset enum, callback alias)
  • 2.4 Author schemas/schemas.ts (Zod for options + preset enum)
  • 2.5 Author audio-analyzer.test.ts — happy-dom not required (universal FFT path)
  • 2.6 Sibling .md docs on every .ts (≥200 words, basic + advanced examples, 6 sections)
  • 2.7 Wire subpath export in package.json + vite.config.ts

3. Implementation — MicrophoneSimulationPlugin

  • 3.1 mkdir -p packages/audio/audio-plugins-fx/src/plugins/microphone/schemas
  • 3.2 Author microphone.ts — source plugin synthesising mic-coloured audio from oscillator + filtered noise + dynamics + character + wow/flutter stages
  • 3.3 Author microphone.types.ts carrying every *Controls interface verbatim from main-branch (FrequencyControls, ResonanceControls, …, MicrophoneUISection[] shape)
  • 3.4 Author createMicrophonePlugin(options) factory matching main-branch surface
  • 3.5 Author schemas/schemas.ts (Zod for MicrophoneConfig + MicrophonePreset)
  • 3.6 Author microphone.test.ts — covers source-plugin behaviour, preset round-trip, UI section integrity
  • 3.7 Sibling .md docs on every .ts
  • 3.8 Wire subpath export in package.json + vite.config.ts

4. Implementation — GLaDOSPlugin

  • 4.1 mkdir -p packages/audio/audio-plugins-fx/src/plugins/glados/schemas
  • 4.2 Author glados.ts — voice-effect chain: pitch-shift → formant-shift → robotic-intensity tremolo → distortion → low-pass → reverb. Reuses internal building blocks (biquad filter math, etc.) without depending on sibling plugin classes
  • 4.3 Author glados.types.ts carrying GLaDOSConfig, GLaDOSPreset union, GLaDOSPresetConfig shape
  • 4.4 Author schemas/schemas.ts (Zod for options + the six built-in presets)
  • 4.5 Author glados.test.ts — preset application changes parameter values; voice chain produces non-silent output for non-silent input
  • 4.6 Sibling .md docs on every .ts
  • 4.7 Wire subpath export in package.json + vite.config.ts

5. Implementation — GameAudioPlugin

  • 5.1 mkdir -p packages/audio/audio-plugins-fx/src/plugins/game/schemas
  • 5.2 Author game-audio.ts — composite with three internal sub-systems: SpatialSourceManager, MusicLayerEngine, ProximityVoiceChat; size budget likely requires extracting these to siblings under game/spatial/, game/music/, game/voice/
  • 5.3 Author game-audio.types.ts carrying Vector3, GameVoiceEffect, SpatialAudioSource, VoiceChatParticipant, ProximityVoiceChatConfig, GameState, MusicLayer, VoiceTransformationConfig, GameAudioConfig, GameAudioMetrics, ListenerOrientation
  • 5.4 Author schemas/schemas.ts (Zod for every config + the Vector3/orientation shapes)
  • 5.5 Author game-audio.test.ts covering spatial source lifecycle, distance-based voice attenuation, music-layer crossfade
  • 5.6 Sibling .md docs on every .ts
  • 5.7 Wire subpath export in package.json + vite.config.ts

6. Implementation — AudioPlayerPlugin

  • 6.1 mkdir -p packages/audio/audio-plugins-fx/src/plugins/audio-player/schemas
  • 6.2 Author audio-player.ts — source plugin loading raw Float32 PCM via data: URL or via fetch(url, { signal }); play, pause, stop, seek, setVolume, setLoop, setPlaybackRate, getState
  • 6.3 Author audio-player.types.ts carrying AudioPlayerConfig, AudioPlayerState, AudioPlayerLoadOptions
  • 6.4 Author schemas/schemas.ts (Zod for options + load options)
  • 6.5 Author audio-player.test.ts covering load + play + stop + AbortSignal + state round-trip
  • 6.6 Sibling .md docs on every .ts
  • 6.7 Wire subpath export in package.json + vite.config.ts

7. Pre-archive verification

  • 7.1 bun run check — Biome 0 errors / 0 warnings across the whole monorepo
  • 7.2 bunx turbo lint typecheck test --filter=@suaveplan/audio-plugins-fx — green
  • 7.3 bunx turbo test:coverage --filter=@suaveplan/audio-plugins-fx — 100/100/100/100 across the package
  • 7.4 bun scripts/openspec-conformance.ts @suaveplan/audio-plugins-fx — exit 0
  • 7.5 bunx turbo build — whole-monorepo build green (catches missed import rewrites)
  • 7.6 No file over 300 lines (source) or 500 lines (test); split per game-audio plan if needed

8. Pre-archive 7-row checklist (AGENTS.md Section 13)

  • 8.1 Generics threaded; expectTypeOf assertions on every literal-type claim
  • 8.2 Zod schemas wired at every declared boundary
  • 8.3 Every new error message key thrown by at least one production path; error code reuses AUDIO_FX.* namespace
  • 8.4 Strict-mode behaviors tested on and off where applicable
  • 8.5 OTel instruments asserted where introduced
  • 8.6 Async-load idempotency tests (loadSample-style)
  • 8.7 No retroactive tick — every box above reflects work done in this change

9. Archive

  • 9.1 Fold spec delta into openspec/specs/audio-plugins-fx/spec.md (add the five new Requirement blocks)
  • 9.2 Move openspec/changes/extend-audio-plugins-fx-enterprise-extras/ → openspec/archive/<yyyy-mm-dd>-extend-audio-plugins-fx-enterprise-extras/
  • 9.3 Refresh MANIFEST.md via bun scripts/folder-reorg/generate-manifest.ts (if new dirs were added)