skills/plugins/document-navigator/docs/media/audio/audio-engine-browser/README.md

@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.

Documentation tree

• adapter-introspection — adapter-introspection is a small support module that holds the BrowserTimelineAdapter operations that would otherwi…
• adapter-lifecycle — adapter-lifecycle is the small helper module that owns the BrowserTimelineAdapter's context resolution and the `thr…
• adapter-track-ops — adapter-track-ops packs every track-scoped mutation that the BrowserTimelineAdapter exposes — adding, removing, upd…
• browser-adapter — BrowserTimelineAdapter is the browser-tier rendering engine of the @suaveplan/audio-* family. It implements the `Ti…
• bus-orchestrator — BusOrchestrator is the per-adapter owner of the project-level sidechain bus graph. It wraps a single `DefaultBusRegis…
• fx-host — fx-host is the small switch-board that picks the best available render path for an AudioFxPlugin and returns a sing…
• mixer-state — mixer-state extracts the pure mixer / ambient bookkeeping out of the BrowserTimelineAdapter class so the adapter fi…
• standardized-audio-context-bridge — standardized-audio-context-bridge is the dynamic-import wrapper for standardized-audio-context's AudioContext con…
• track-subgraph — This module is the small, focused factory that materialises the documented per-track Web Audio chain inside `BrowserTim…
• decode — decode(source, opts?) decodes browser-tier audio bytes into a fully populated AudioDocument from `@suaveplan/audio-…
  • decode — decode(source, opts?) decodes browser-tier audio bytes into a fully populated AudioDocument from `@suaveplan/audio-…
• error-codes — This module declares the structured error-code registry for @suaveplan/audio-engine-browser. Every fault path inside…
  • error-codes — This module declares the structured error-code registry for @suaveplan/audio-engine-browser. Every fault path inside…
• fallback — Html5AudioFallback is the graceful-degradation path for browsers and runtimes without the Web Audio API. It implement…
  • html5-fallback — Html5AudioFallback is the graceful-degradation path for browsers and runtimes without the Web Audio API. It implement…
• graph — WebAudioGraph is the thin id-keyed registry that sits between BrowserTimelineAdapter and a BaseAudioContext. It e…
  • web-audio-graph — WebAudioGraph is the thin id-keyed registry that sits between BrowserTimelineAdapter and a BaseAudioContext. It e…
• offline — renderOffline is the bridge to non-realtime export. It wires a BrowserTimelineAdapter to an OfflineAudioContext,…
  • offline-render — renderOffline is the bridge to non-realtime export. It wires a BrowserTimelineAdapter to an OfflineAudioContext,…
• worklet — AudioWorkletManager is the gatekeeper for everything AudioWorklet- related inside BrowserTimelineAdapter. It vali…
  • worklet-manager — AudioWorkletManager is the gatekeeper for everything AudioWorklet- related inside BrowserTimelineAdapter. It vali…

Install

bun add @suaveplan/audio-engine-browser

Quick start

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 — BrowserTimelineAdapter implementing TimelineAdapter.
• adapter/adapter-lifecycle — context resolution and assertion helpers.
• adapter/adapter-track-ops — track-scoped mutations.
• adapter/adapter-introspection — FX hosting and bus declarations.
• adapter/track-subgraph — fixed-shape per-track Web Audio chain factory.
• adapter/mixer-state — solo/ambient/PDC.
• adapter/bus-orchestrator — cycle-checked project-level bus registry.
• adapter/fx-host — render-path picker for AudioFxPlugin.
• graph/web-audio-graph — id-keyed Web Audio node graph with snapshot/restore.
• worklet/worklet-manager — AudioWorklet host with allow-list and abort support.
• fallback/html5-fallback — graceful-degradation <audio>-backed TimelineAdapter.
• offline/offline-render — renderOffline(timeline, duration, sampleRate) non-realtime export.
• error-codes — 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.