115 lines
7.4 KiB
Markdown
115 lines
7.4 KiB
Markdown
# @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.
|
|
|