Move docs/ package mirror into document-navigator plugin
Relocate the ~6k-file docs tree from the repo root into plugins/document-navigator/docs/ so the plugin is self-contained and portable. docs/superpowers/ (specs and plans) stays at the repo root. Moved via cp+rm rather than git mv because directory rename() fails with EPERM on this WSL /mnt DrvFs mount; git rename-detection pairs the identical-content files at commit time. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,114 @@
|
||||
# @suaveplan/audio-engine-browser - Browser-tier TimelineAdapter implementation: Web Audio rendering, AudioWorklet hosting, and AudioFxPlugin createAudioNode integration for the universal TimelineEngine.
|
||||
|
||||
Browser-tier `TimelineAdapter` implementation for the `@suaveplan/audio-*`
|
||||
family. Hosts Web Audio rendering, `AudioWorklet` loading, and the
|
||||
`AudioFxPlugin.createAudioNode()` integration so a universal
|
||||
`TimelineEngine` drives browser audio output through a single
|
||||
`timeline.setAdapter(new BrowserTimelineAdapter(...))` call.
|
||||
|
||||
The package is browser-tier: it may reference `AudioContext`,
|
||||
`OfflineAudioContext`, `AudioWorklet`, and `HTMLAudioElement`, but every
|
||||
such reference goes through an injectable seam (the `context` option or
|
||||
the `standardized-audio-context` shim) so the package is testable under
|
||||
`happy-dom` without a real browser.
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
## Documentation tree
|
||||
|
||||
- [adapter-introspection](./src/adapter/adapter-introspection.md) — `adapter-introspection` is a small support module that holds the `BrowserTimelineAdapter` operations that would otherwi…
|
||||
- [adapter-lifecycle](./src/adapter/adapter-lifecycle.md) — `adapter-lifecycle` is the small helper module that owns the `BrowserTimelineAdapter`'s context resolution and the `thr…
|
||||
- [adapter-track-ops](./src/adapter/adapter-track-ops.md) — `adapter-track-ops` packs every track-scoped mutation that the `BrowserTimelineAdapter` exposes — adding, removing, upd…
|
||||
- [browser-adapter](./src/adapter/browser-adapter.md) — `BrowserTimelineAdapter` is the browser-tier rendering engine of the `@suaveplan/audio-*` family. It implements the `Ti…
|
||||
- [bus-orchestrator](./src/adapter/bus-orchestrator.md) — `BusOrchestrator` is the per-adapter owner of the project-level sidechain bus graph. It wraps a single `DefaultBusRegis…
|
||||
- [fx-host](./src/adapter/fx-host.md) — `fx-host` is the small switch-board that picks the best available render path for an `AudioFxPlugin` and returns a sing…
|
||||
- [mixer-state](./src/adapter/mixer-state.md) — `mixer-state` extracts the pure mixer / ambient bookkeeping out of the `BrowserTimelineAdapter` class so the adapter fi…
|
||||
- [standardized-audio-context-bridge](./src/adapter/standardized-audio-context-bridge.md) — `standardized-audio-context-bridge` is the dynamic-import wrapper for `standardized-audio-context`'s `AudioContext` con…
|
||||
- [track-subgraph](./src/adapter/track-subgraph.md) — This module is the small, focused factory that materialises the documented per-track Web Audio chain inside `BrowserTim…
|
||||
- [decode](./src/decode/decode.md) — `decode(source, opts?)` decodes browser-tier audio bytes into a fully populated `AudioDocument` from `@suaveplan/audio-…
|
||||
- [decode](./src/decode/decode.md) — `decode(source, opts?)` decodes browser-tier audio bytes into a fully populated `AudioDocument` from `@suaveplan/audio-…
|
||||
- [error-codes](./src/error-codes/error-codes.md) — This module declares the structured error-code registry for `@suaveplan/audio-engine-browser`. Every fault path inside…
|
||||
- [error-codes](./src/error-codes/error-codes.md) — This module declares the structured error-code registry for `@suaveplan/audio-engine-browser`. Every fault path inside…
|
||||
- [fallback](./src/fallback/html5-fallback.md) — `Html5AudioFallback` is the graceful-degradation path for browsers and runtimes without the Web Audio API. It implement…
|
||||
- [html5-fallback](./src/fallback/html5-fallback.md) — `Html5AudioFallback` is the graceful-degradation path for browsers and runtimes without the Web Audio API. It implement…
|
||||
- [graph](./src/graph/web-audio-graph.md) — `WebAudioGraph` is the thin id-keyed registry that sits between `BrowserTimelineAdapter` and a `BaseAudioContext`. It e…
|
||||
- [web-audio-graph](./src/graph/web-audio-graph.md) — `WebAudioGraph` is the thin id-keyed registry that sits between `BrowserTimelineAdapter` and a `BaseAudioContext`. It e…
|
||||
- [offline](./src/offline/offline-render.md) — `renderOffline` is the bridge to non-realtime export. It wires a `BrowserTimelineAdapter` to an `OfflineAudioContext`,…
|
||||
- [offline-render](./src/offline/offline-render.md) — `renderOffline` is the bridge to non-realtime export. It wires a `BrowserTimelineAdapter` to an `OfflineAudioContext`,…
|
||||
- [worklet](./src/worklet/worklet-manager.md) — `AudioWorkletManager` is the gatekeeper for everything `AudioWorklet`- related inside `BrowserTimelineAdapter`. It vali…
|
||||
- [worklet-manager](./src/worklet/worklet-manager.md) — `AudioWorkletManager` is the gatekeeper for everything `AudioWorklet`- related inside `BrowserTimelineAdapter`. It vali…
|
||||
<!-- end:auto-docs -->
|
||||
|
||||
## Install
|
||||
|
||||
```bash
|
||||
bun add @suaveplan/audio-engine-browser
|
||||
```
|
||||
|
||||
## Quick start
|
||||
|
||||
```ts
|
||||
import { BrowserTimelineAdapter } from "@suaveplan/audio-engine-browser";
|
||||
import { TimelineEngine } from "@suaveplan/audio-timeline";
|
||||
|
||||
const adapter = new BrowserTimelineAdapter({ lookAhead: 0.1, ppqn: 960 });
|
||||
await adapter.init();
|
||||
|
||||
const timeline = new TimelineEngine();
|
||||
timeline.setAdapter(adapter);
|
||||
timeline.setTracks(myTracks);
|
||||
timeline.play();
|
||||
|
||||
// Later
|
||||
adapter.dispose();
|
||||
```
|
||||
|
||||
## Modules
|
||||
|
||||
- [`adapter/browser-adapter`](./src/adapter/browser-adapter.md) —
|
||||
`BrowserTimelineAdapter` implementing `TimelineAdapter`.
|
||||
- [`adapter/adapter-lifecycle`](./src/adapter/adapter-lifecycle.md) —
|
||||
context resolution and assertion helpers.
|
||||
- [`adapter/adapter-track-ops`](./src/adapter/adapter-track-ops.md) —
|
||||
track-scoped mutations.
|
||||
- [`adapter/adapter-introspection`](./src/adapter/adapter-introspection.md) —
|
||||
FX hosting and bus declarations.
|
||||
- [`adapter/track-subgraph`](./src/adapter/track-subgraph.md) — fixed-shape
|
||||
per-track Web Audio chain factory.
|
||||
- [`adapter/mixer-state`](./src/adapter/mixer-state.md) — solo/ambient/PDC.
|
||||
- [`adapter/bus-orchestrator`](./src/adapter/bus-orchestrator.md) —
|
||||
cycle-checked project-level bus registry.
|
||||
- [`adapter/fx-host`](./src/adapter/fx-host.md) — render-path picker for
|
||||
`AudioFxPlugin`.
|
||||
- [`graph/web-audio-graph`](./src/graph/web-audio-graph.md) — id-keyed
|
||||
Web Audio node graph with snapshot/restore.
|
||||
- [`worklet/worklet-manager`](./src/worklet/worklet-manager.md) —
|
||||
`AudioWorklet` host with allow-list and abort support.
|
||||
- [`fallback/html5-fallback`](./src/fallback/html5-fallback.md) —
|
||||
graceful-degradation `<audio>`-backed `TimelineAdapter`.
|
||||
- [`offline/offline-render`](./src/offline/offline-render.md) —
|
||||
`renderOffline(timeline, duration, sampleRate)` non-realtime export.
|
||||
- [`error-codes`](./src/error-codes.md) — `BrowserAudioError` registry.
|
||||
|
||||
## Features
|
||||
|
||||
- Universal `TimelineAdapter` contract — swap engines without
|
||||
conditional branching.
|
||||
- Fixed-shape per-track subgraph matching DAW topology.
|
||||
- DAW solo semantics, master / per-track volume / mute / pan, loop
|
||||
region, tempo.
|
||||
- Per-track `PluginChain` from `@suaveplan/audio-fx-plugin-base` with
|
||||
shared project-level `BusRegistry`.
|
||||
- Bus cycle detection (`AUDIO_ENGINE_BROWSER.BUS_CYCLE_DETECTED`) and
|
||||
topological process ordering.
|
||||
- Three FX render paths: native `AudioNode`, `AudioWorklet`,
|
||||
`ScriptProcessorNode` fallback.
|
||||
- `Html5AudioFallback` for environments without the Web Audio API.
|
||||
- Offline export via `OfflineAudioContext`.
|
||||
- Typed `BrowserAudioError` family with seven codes.
|
||||
- Real OTel: tracer (`engine_browser.init`, `engine_browser.set_tracks`,
|
||||
`engine_browser.offline_render`), counter
|
||||
(`audio_engine_browser_nodes_created_total`), histogram
|
||||
(`audio_engine_browser_offline_render_duration_ms`).
|
||||
- 100% test coverage; tests run under `happy-dom` with an injected
|
||||
context shim.
|
||||
|
||||
Reference in New Issue
Block a user