Tasks: enterprise-audio-engine-browser

Change ID: enterprise-audio-engine-browser Package: @suaveplan/audio-engine-browser Target path: packages/audio/audio-engine-browser Prerequisite packages on Verdaccio: @suaveplan/audio-core, @suaveplan/audio-timeline, @suaveplan/audio-transport, @suaveplan/audio-fx-plugin-base, @suaveplan/error, @suaveplan/events

1. Scaffold

Create directory packages/audio/audio-engine-browser/ with src/, tests/, src/__benchmarks__/, and all feature subdirectories per the layout in proposal.md.
Write package.json at version 0.1.0 with "type": "module", "sideEffects": false, full exports map, deps: @suaveplan/audio-core workspace:^, @suaveplan/audio-timeline workspace:^, @suaveplan/audio-transport workspace:^, @suaveplan/audio-fx-plugin-base workspace:^, @suaveplan/error workspace:^, @suaveplan/events workspace:^, standardized-audio-context.
Write tsconfig.json extending @suaveplan/typescript-config/library.json.
Write vitest.config.ts using createTestConfig() from @suaveplan/testing/config with happy-dom environment.
Add lint, typecheck, test, test:coverage, build, docs:check scripts.

2. Types + errors

Write src/adapter/browser-adapter.types.ts — BrowserAdapterOptions.
Write src/graph/web-audio-graph.types.ts — AudioGraphSnapshot, AudioNodeType.
Write src/worklet/worklet-manager.types.ts — WorkletManagerOptions, WorkletModuleOptions.
Write co-located .md files for each types module (≥200 words).
Write src/error-codes.ts — defineCodes("AUDIO_ENGINE_BROWSER", [...]) producing AUDIO_ENGINE_BROWSER.* code strings; export BrowserAudioErrorCode, AUDIO_ENGINE_BROWSER_ERROR_METADATA, registerBrowserAudioErrorCodes(), and a BrowserAudioError class extending AudioError from @suaveplan/audio-core.
Write Zod schemas: BrowserAdapterOptionsSchema, WorkletManagerOptionsSchema, WorkletModuleOptionsSchema, AudioGraphSnapshotSchema.

3. WebAudioGraph

Implement WebAudioGraph in src/graph/web-audio-graph.ts:
- addNode, removeNode with ID-based registry.
- connect / disconnect wrapping AudioNode.connect / disconnect.
- snapshot() returns serializable AudioGraphSnapshot.
- restore(snapshot) recreates nodes and connections from a snapshot.
Write web-audio-graph.test.ts and web-audio-graph.md.

4. AudioWorkletManager

Implement AudioWorkletManager in src/worklet/worklet-manager.ts:
- addModule with URL allow-list check.
- createNode returns AudioWorkletNode.
- postMessage / onMessage for processor communication.
- isLoaded tracks loaded module URLs.
Write worklet-manager.test.ts and worklet-manager.md.

5. Html5AudioFallback

Implement Html5AudioFallback in src/fallback/html5-fallback.ts:
- Implements TimelineAdapter using HTMLAudioElement.
- Supports: play, pause, seek, volume, loop.
- No FX, no analysis, no precise scheduling.
- All other adapter methods are no-ops or throw BrowserAudioError for unsupported operations.
Write html5-fallback.test.ts and html5-fallback.md.

6. BrowserTimelineAdapter

Implement BrowserTimelineAdapter in src/adapter/browser-adapter.ts:
- init() creates AudioContext via standardized-audio-context (or uses injected context) and resumes it.
- setTracks, addTrack, removeTrack, updateTrack build per-track subgraphs: AudioBufferSourceNode → GainNode (clip) → GainNode (track) → StereoPannerNode → DynamicsCompressorNode → GainNode (master) → AnalyserNode → destination.
- play, pause, stop, seek drive AudioBufferSourceNode scheduling.
- Mute/solo logic: when any track is soloed, all non-soloed tracks have gain set to 0.
- setLoop, setMasterVolume, setTrackVolume, setTrackMute, setTrackSolo, setTrackPan, setTempo update graph parameters.
- lookAhead and ppqn exposed as readonly properties.
- dispose() closes context and releases all nodes.
Write browser-adapter.test.ts (≤500 lines): init with injected OfflineAudioContext, set tracks, play/stop, track volume/pan, mute/solo logic, loop, dispose.
Write browser-adapter.md.

7. Offline render

Implement renderOffline in src/offline/offline-render.ts:
- Creates OfflineAudioContext via standardized-audio-context.
- Instantiates BrowserTimelineAdapter with injected offline context.
- Attaches adapter to TimelineEngine, plays from 0, and returns rendered AudioBuffer.
Write offline-render.test.ts and offline-render.md.

8. FX plugin hosting

Implement createFxNode utility in src/adapter/browser-adapter.ts (or separate fx-host.ts if needed):
- AudioNode path: plugin.createAudioNode(context) returns native AudioNode chain.
- Worklet path: plugin.createWorkletProcessor() returns processor code; host wraps in AudioWorkletNode via AudioWorkletManager.
- Fallback path: ScriptProcessorNode wrapping block processor for main-thread fallback.
Write unit tests for all three FX hosting paths.

9. Benchmarks

Write src/__benchmarks__/graph.bench.ts — add 100 nodes, connect 200 edges, snapshot + restore.
Write src/__benchmarks__/worklet.bench.ts — load 10 worklet modules, create 50 nodes.

10. Integration tests

Write tests/integration.test.ts — full browser adapter lifecycle with injected OfflineAudioContext: init, set tracks with clips, play, verify graph structure, mute/solo behavior, offline render returns AudioBuffer with expected length.

11. Docs + verify + publish

All co-located .md files (≥200 words each).
Write README.md at package root.
bunx turbo lint typecheck test --filter=@suaveplan/audio-engine-browser — green.
bunx turbo test:coverage --filter=@suaveplan/audio-engine-browser — 100%.
bun scripts/publish.ts --package @suaveplan/audio-engine-browser.
Fold specs/audio-engine-browser/spec.md into openspec/specs/audio-engine-browser/spec.md.
Archive to openspec/archive/2026-05-14-enterprise-audio-engine-browser/.

6.3 KiB Raw Blame History