first commit

plugins/library-navigator/skills/sp-audio-engine-browser/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: sp-audio-engine-browser
+description: Browser-tier TimelineAdapter — Web Audio rendering, AudioWorklet hosting, FX plugin createAudioNode integration, HTML5 fallback, offline render. For TimelineEngine.
+---
+
+# sp-audio-engine-browser
+
+| Symbol | Kind | Responsibility |
+|---|---|---|
+| `BrowserTimelineAdapter` | Class | Browser-tier `TimelineAdapter` — connects `TimelineEngine` to Web Audio API |
+| `WebAudioGraph` | Class | Manages `AudioNode` connections, snapshots, and node lifecycle |
+| `AudioWorkletManager` | Class | Loads and manages `AudioWorklet` modules with schema-validated options |
+| `BusOrchestrator` | Class | Orchestrates audio bus routing between tracks and FX |
+| `createFxNode` | Function | Creates a Web Audio `AudioNode` from an `AudioFxPlugin` descriptor |
+| `Html5AudioFallback` | Class | Fallback audio playback using HTML5 `<audio>` when Web Audio is unavailable |
+| `renderOffline` | Function | Offline renders a timeline to an `AudioBuffer` without a real audio context |
+| `decode` | Function | Decodes audio data in the browser (wraps `AudioContext.decodeAudioData`) |
+| `AUDIO_ENGINE_BROWSER_CODES` | Constant | Error-code registry via `@suaveplan/error` `defineCodes` |
+
+**File Structure:** `packages/media/audio/audio-engine-browser/src/{adapter,graph,worklet,fallback,offline,decode,error-codes}/`
+
+**Sibling packages:**
+- `@suaveplan/audio-engine-server` — server-tier adapter (file I/O)
+- `@suaveplan/audio-timeline` — timeline engine
+- `@suaveplan/audio-fx-plugin-base` — FX plugin base
+- `@suaveplan/audio-transport` — transport sync
+
+**Patterns:**
+
+*Quick Start:*
+```ts
+import { BrowserTimelineAdapter } from "@suaveplan/audio-engine-browser";
+const adapter = new BrowserTimelineAdapter(audioContext);
+adapter.connect(timelineEngine);
+```
+
+*AudioWorklet:*
+```ts
+import { AudioWorkletManager } from "@suaveplan/audio-engine-browser/worklet/worklet-manager";
+const manager = new AudioWorkletManager(audioContext);
+await manager.loadModule("/worklets/my-processor.js");
+```
+
+*Offline render:*
+```ts
+import { renderOffline } from "@suaveplan/audio-engine-browser/offline/offline-render";
+const buffer = await renderOffline({ duration: 30, sampleRate: 48000 }, timeline);
+```
+
+**Constraints:**
+- Browser-only — depends on Web Audio API and `standardized-audio-context`
+- Subpath exports: `/adapter/browser-adapter`, `/graph/web-audio-graph`, `/worklet/worklet-manager`, `/fallback/html5-fallback`, `/offline/offline-render`, `/decode`, `/error-codes`
+- `AudioWorkletManager` validates options via `WorkletManagerOptionsSchema`
+- `Html5AudioFallback` used when Web Audio is unsupported or blocked
+- OTel instrumented for graph operations and worklet loads
+
+**Checklist:**
+- [ ] `BrowserTimelineAdapter` connects timeline to Web Audio output
+- [ ] `WebAudioGraph` correctly wires nodes and produces serializable snapshots
+- [ ] `AudioWorkletManager` loads and unloads worklet modules
+- [ ] `renderOffline` produces an `AudioBuffer` without real audio hardware
+- [ ] `Html5AudioFallback` plays audio when Web Audio is unavailable