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.