114 lines
8.6 KiB
Markdown
114 lines
8.6 KiB
Markdown
# Split `audio-plugins-fx` into `audio-fx-plugin-*` per-plugin packages
|
||
|
||
**Package**: `@suaveplan/audio-fx-plugin-*` (new), `@suaveplan/audio-fx-plugin-base` (new), `@suaveplan/audio-plugins-fx` (removed)
|
||
**Status**: PROPOSED
|
||
**Type**: refactor
|
||
|
||
## Why
|
||
|
||
`audio-plugins-fx` currently bundles the contract, `PluginChain`, `PluginRegistry`, `ChainSnapshot`, and 24 concrete plugins into a single package. Subpath exports give bundlers tree-shaking, but consumers still pay the full peer-dep surface, every plugin advances on the same version, and the dep graph in `MANIFEST.md` cannot distinguish a chain consumer from a reverb consumer.
|
||
|
||
Every other plugin family in the repo is split per-plugin: `network-plugin-*`, `drive-plugin-chunks`, `i18n-formatter-*`, `i18n-backend-*`, the recently-shipped `audio-ir-{family}-plugin-<name>`. Audio FX is the outlier. Splitting now — while still at `0.1.0` and before downstream consumers (`audio-engine-browser`, `react-audio`) wire against it — avoids a much larger rename later and matches the established convention.
|
||
|
||
### Naming
|
||
|
||
The new family uses the `audio-fx-plugin-*` prefix (`fx` is the family marker, distinguishing this from future `audio-ir-*`, `audio-synth-*`, etc. plugin families):
|
||
|
||
- `@suaveplan/audio-fx-plugin-base` — foundation (contract + chain + registry + error codes).
|
||
- `@suaveplan/audio-fx-plugin-<name>` — one package per concrete FX plugin.
|
||
|
||
## What changes
|
||
|
||
### Foundation (1 package)
|
||
|
||
- ADDED: `@suaveplan/audio-fx-plugin-base` — `AudioFxPlugin` contract, `AbstractAudioFxPlugin`, `PluginChain`, `ChainContext`, `AmbientState`, `BusRegistry`, `PluginRegistry`, `ChainSnapshot`, `ChainEventBus`, `ParameterSchedule`, `PresetSnapshot`, shared `AUDIO_PLUGIN.*` error-code registry. Universal-tier; consumes `@suaveplan/{audio-core, audio-transport, error, events, opentelemetry, schema-registry, types}` but has zero `@suaveplan/audio-fx-plugin-*` deps. Owns every file in the current `audio-plugins-fx/src/{base,chain,registry}/` trees plus the root `error-codes.ts`.
|
||
|
||
### Per-plugin packages (24 packages)
|
||
|
||
Each new package owns one folder from `audio-plugins-fx/src/plugins/<source-dir>/` verbatim — no DSP, parameter, or error-code changes.
|
||
|
||
| New package | Source dir | One-line description |
|
||
|---|---|---|
|
||
| `audio-fx-plugin-audio-analyzer` | `audio-analyzer/` | tap-point FFT analyser |
|
||
| `audio-fx-plugin-audio-player` | `audio-player/` | playback source plugin |
|
||
| `audio-fx-plugin-auto-filter` | `auto-filter/` | LFO-driven filter |
|
||
| `audio-fx-plugin-chorus` | `chorus/` | modulated comb / multi-voice chorus |
|
||
| `audio-fx-plugin-compressor` | `compressor/` | feed-forward compressor with sidechain input |
|
||
| `audio-fx-plugin-delay` | `delay/` | stereo delay with ping-pong + BPM sync |
|
||
| `audio-fx-plugin-distortion` | `distortion/` | waveshaping + soft/hard clip |
|
||
| `audio-fx-plugin-eq` | `eq/` | parametric / shelving / high-pass / low-pass EQ |
|
||
| `audio-fx-plugin-filter` | `filter/` | biquad / IIR / state-variable |
|
||
| `audio-fx-plugin-flanger` | `flanger/` | short-delay modulated comb |
|
||
| `audio-fx-plugin-game-audio` | `game/` | game-audio orchestration plugin (impl filename is `game-audio.ts`) |
|
||
| `audio-fx-plugin-gate` | `gate/` | noise gate with hold + linked envelope |
|
||
| `audio-fx-plugin-glados` | `glados/` | pitch-tracked vocal-style effect |
|
||
| `audio-fx-plugin-limiter` | `limiter/` | look-ahead brick-wall limiter |
|
||
| `audio-fx-plugin-microphone` | `microphone/` | source plugin simulating mic colour |
|
||
| `audio-fx-plugin-mixer` | `mixer/` | bus mixer with per-channel sends |
|
||
| `audio-fx-plugin-phaser` | `phaser/` | all-pass-bank phaser |
|
||
| `audio-fx-plugin-pitch-shifter` | `pitch-shifter/` | phase-vocoder pitch shift |
|
||
| `audio-fx-plugin-reverb` | `reverb/` | engine-pluggable reverb (FDN, Schroeder, convolution) |
|
||
| `audio-fx-plugin-sampler` | `sampler/` | sample-playback source |
|
||
| `audio-fx-plugin-spatial` | `spatial/` | HRTF-based spatial panner |
|
||
| `audio-fx-plugin-synthesizer` | `synthesizer/` | polyphonic subtractive synth |
|
||
| `audio-fx-plugin-tremolo` | `tremolo/` | amplitude-modulated tremolo |
|
||
| `audio-fx-plugin-widener` | `widener/` | stereo width / mid-side processor |
|
||
|
||
### Scaffold script (one new tooling file)
|
||
|
||
- ADDED: `scripts/split-audio-fx-plugin/scaffold.ts` — reusable helper that takes a plugin slug (`eq`, `reverb`, …) plus the source dir name, copies a per-plugin template (config files), `git mv`s the source folder, and rewrites imports. The script is committed alongside the split so the same scaffold can be reused for future `audio-fx-plugin-*` additions.
|
||
|
||
### Removals + repo plumbing
|
||
|
||
- REMOVED: `@suaveplan/audio-plugins-fx` — superseded. Package is at `0.1.0`, never published to Verdaccio. Folder `packages/audio/audio-plugins-fx/` is deleted after the moves.
|
||
- MODIFIED: `MANIFEST.md` — refreshed via `bun scripts/folder-reorg/generate-manifest.ts`.
|
||
- MODIFIED: `STATUS.md` — replace the single `audio-plugins-fx` ✅ row with 25 new ✅ rows (1 base + 24 per-plugin). Net `Migrated` count delta: +24.
|
||
- MODIFIED: `CLAUDE.md` § Packages (audio family subsection) — replace the bundled listing with the per-plugin enumeration.
|
||
- MODIFIED: `scripts/folder-reorg/assignment.yml` — every new `audio-fx-plugin-*` package maps to the `audio` plugin slot; remove the `audio-plugins-fx` entry.
|
||
|
||
## Out of scope
|
||
|
||
- New plugins beyond what `audio-plugins-fx` already ships — additions land as their own packages directly under the new layout.
|
||
- React / R3F bindings for plugins — remain in `react-audio-*` packages, untouched.
|
||
- Engine-pluggable backends (e.g. a future `audio-fx-plugin-reverb-convolution`) — possible future split, not in this change.
|
||
- Changing any plugin's runtime behavior, DSP, parameter surface, or error codes. This is a pure relocation + dep-graph refactor.
|
||
|
||
## Source mapping
|
||
|
||
> Genesis-original — no `enterprise/audio-plugins-fx.md` exists. Section retained as a pointer to the in-tree source.
|
||
|
||
| Requirement | Source path | Notes |
|
||
|---|---|---|
|
||
| base contract + chain + registry surface | `packages/audio/audio-plugins-fx/src/{base,chain,registry}/` | Moves verbatim into `audio-fx-plugin-base` |
|
||
| each concrete plugin | `packages/audio/audio-plugins-fx/src/plugins/<source-dir>/` | Moves verbatim into `audio-fx-plugin-<slug>` per the table above |
|
||
| shared error codes | `packages/audio/audio-plugins-fx/src/error-codes.ts` | Moves into `audio-fx-plugin-base/src/error-codes/`; concrete plugins import codes from `@suaveplan/audio-fx-plugin-base/error-codes` |
|
||
|
||
### Requirements with no source line
|
||
|
||
| Requirement | Justification |
|
||
|---|---|
|
||
| per-package independent versioning | New constraint introduced by the split; each plugin can graduate to `1.0.0` on its own cadence |
|
||
| `audio-fx-plugin-base` cannot depend on any `audio-fx-plugin-<name>` | Prevents cycles in the dep graph that the bundled package masked |
|
||
| scaffold script committed to `scripts/split-audio-fx-plugin/` | Future additions to the FX family use the same template — keeps shape consistent across plugins |
|
||
|
||
## Verification approach
|
||
|
||
- Per-plugin: each new package keeps its existing test suite intact under the new path. `bunx turbo test --filter=@suaveplan/audio-fx-plugin-<name>` green at 100/100/100/100 for every plugin.
|
||
- `audio-fx-plugin-base/tests/dep-graph.test.ts` — asserts the package has zero `@suaveplan/audio-fx-plugin-*` deps (other than its own name, which would be a self-dep and is also rejected).
|
||
- `scripts/folder-reorg/generate-manifest.ts` after the split — `MANIFEST.md` diff shows 25 new packages and no orphaned `audio-plugins-fx` entry.
|
||
- `rg "@suaveplan/audio-plugins-fx" packages/ apps/ scripts/ docs/ openspec/changes/ openspec/specs/` — zero hits after the migration commit (archive is allowed).
|
||
- `bunx turbo build` whole monorepo — green; catches any missed import rewrite.
|
||
|
||
## Migration impact
|
||
|
||
- **In-monorepo consumers**: `rg "@suaveplan/audio-plugins-fx" packages/ apps/` returns hits only inside the package itself (no downstream package has wired it up yet — `audio-engine-browser` and `react-audio` are still `–` in STATUS.md). The split lands before first consumer.
|
||
- **External consumers**: none — package is `0.1.0` and was never published to Verdaccio.
|
||
|
||
## Impact
|
||
|
||
### Affected dependents
|
||
|
||
Run `bunx turbo ls --filter=...@suaveplan/audio-plugins-fx` to enumerate. At proposal time, the only dependent is `audio-plugins-fx`'s own test suite — no other live package imports it. The placeholder `audio-engine-browser` is still status `–` (not yet ported) and will compose against `audio-fx-plugin-*` directly when it lands.
|
||
|
||
- No live dependents (verified by `bunx turbo ls --filter=...@suaveplan/audio-plugins-fx`).
|