`standardized-audio-context-bridge`

Purpose

standardized-audio-context-bridge is the dynamic-import wrapper for standardized-audio-context's AudioContext constructor. It exists as its own file purely for testability: the package needs the dynamic import in production code, but the success branch is unreachable under happy-dom (no native Web Audio constructor) so the file is excluded from coverage via the standard /* istanbul ignore file */ directive. The failure branch is still verified by the offline-render "uses standardized-audio-context import path" test, which expects the typed BrowserAudioError(CONTEXT_FAILED).

Separating the bridge from adapter-lifecycle.ts keeps the lifecycle file fully covered without sprinkling per-line ignore comments. The bridge surface is one function: constructStandardizedContext.

Features

Single async helper that dynamically imports the shim and constructs an AudioContext with latencyHint + sampleRate.
Translates every failure into a typed BrowserAudioError(CONTEXT_FAILED) with the original error attached as cause.
Returns a { ctx, ownsContext: true } descriptor consumed verbatim by resolveContext.

Usage: Basic Example

import { constructStandardizedContext } from "@suaveplan/audio-engine-browser/adapter/standardized-audio-context-bridge";

const { ctx } = await constructStandardizedContext({});

Usage: Advanced Example

import { constructStandardizedContext } from "@suaveplan/audio-engine-browser/adapter/standardized-audio-context-bridge";

try {
    const { ctx, ownsContext } = await constructStandardizedContext({
        latencyHint: "interactive",
        sampleRate: 48000,
    });
    await ctx.resume?.();
    // hand off to the adapter, etc.
} catch (e) {
    if (e instanceof BrowserAudioError) {
        // e.code === "AUDIO_ENGINE_BROWSER.CONTEXT_FAILED"
    }
    throw e;
}

API Reference

`constructStandardizedContext(args) → Promise<{ ctx, ownsContext }>`

args.latencyHint — optional "interactive" | "balanced" | "playback".
args.sampleRate — optional sample rate.

Resolves to { ctx, ownsContext: true } on success; rejects with BrowserAudioError(CONTEXT_FAILED) on every failure (import failure, constructor throw, missing global).

Implementation Notes

The dynamic import("standardized-audio-context") is deliberate: it keeps the shim out of the import graph when the package is used with an injected context (the only mode reachable under happy-dom).
This file carries /* istanbul ignore file */. The justification is recorded in the file header: the success branch requires a real Web Audio runtime, which neither Node nor Bun nor happy-dom provides. The failure branch is still verified through the failing import path in offline-render.test.ts.
The function is the ONLY production caller of standardized-audio-context — every other code path goes through resolveContext, which falls back to this bridge only when the caller did not inject a context.

3.0 KiB Raw Blame History

standardized-audio-context-bridge