diff --git a/packages/core/src/runtime/init.swapScenes.test.ts b/packages/core/src/runtime/init.swapScenes.test.ts
index f4654db628..051ef01b7e 100644
--- a/packages/core/src/runtime/init.swapScenes.test.ts
+++ b/packages/core/src/runtime/init.swapScenes.test.ts
@@ -2165,7 +2165,7 @@ describe("the preview's scene window", () => {
const audio = (src: string) => ``;
it("lets a scene mounting ahead of a playing film join its mix, leaving what already plays alone", async () => {
- vi.spyOn(WebAudioTransport.prototype, "init").mockResolvedValue(true);
+ vi.spyOn(WebAudioTransport.prototype, "open").mockReturnValue(true);
const schedule = vi
.spyOn(WebAudioTransport.prototype, "scheduleMediaElementPlayback")
.mockResolvedValue(null);
diff --git a/packages/core/src/runtime/init.ts b/packages/core/src/runtime/init.ts
index 0bf20663d5..70ed796f07 100644
--- a/packages/core/src/runtime/init.ts
+++ b/packages/core/src/runtime/init.ts
@@ -666,10 +666,8 @@ export function initSandboxRuntimeModular(): void {
const clock = new TransportClock();
state.transportClock = clock;
const webAudio = new WebAudioTransport();
- let webAudioReady = false;
- void webAudio.init().then((ok) => {
- webAudioReady = ok;
- });
+ let webAudioOpened: boolean | null = null;
+ const openWebAudio = () => (webAudioOpened ??= webAudio.open());
window.__hf = window.__hf || {};
/** Hidden by an ancestor, or by the BUS this clip belongs to. The bus is
* never an ancestor — membership is on the member's `data-audio-group` — so
@@ -4513,8 +4511,10 @@ export function initSandboxRuntimeModular(): void {
const pageAnimations = seekTimelineAndAdapters(state.currentTime);
runAdapters("pause", 0, pageAnimations);
runAdapters("play");
- if (webAudioReady && !state.nativeMediaSyncDisabled && !state.webAudioMediaDisabled)
- scheduleWebAudioFor(hosts.flatMap(webAudioMediaIn), webAudio.currentGeneration());
+ const clips = hosts.flatMap(webAudioMediaIn);
+ const mayRoute =
+ clips.length > 0 && !state.nativeMediaSyncDisabled && !state.webAudioMediaDisabled;
+ if (mayRoute && openWebAudio()) scheduleWebAudioFor(clips, webAudio.currentGeneration());
};
// What a load does after scene markup changed: bindings, media, captions, the root timeline, then a redraw.
const settleChangedScenes = (
@@ -5241,7 +5241,12 @@ export function initSandboxRuntimeModular(): void {
// Schedule audio through WebAudio for sample-accurate timing.
// Falls back to HTMLMediaElement playback if WebAudio isn't ready
// or decoding fails (the syncRuntimeMedia path handles that).
- if (webAudioReady && !state.nativeMediaSyncDisabled && !state.webAudioMediaDisabled) {
+ if (
+ !state.nativeMediaSyncDisabled &&
+ !state.webAudioMediaDisabled &&
+ webAudioMediaIn(document).length > 0 &&
+ openWebAudio()
+ ) {
scheduleWebAudioForActiveClips();
}
runAdapters("play");
@@ -6554,7 +6559,7 @@ export function initSandboxRuntimeModular(): void {
changed &&
!state.nativeMediaSyncDisabled &&
!state.webAudioMediaDisabled &&
- webAudioReady &&
+ webAudioOpened === true &&
clock.isPlaying() &&
(webAudio.hasBoundedActiveSources() || webAudio.hasHandedOverSources())
) {
diff --git a/packages/core/src/runtime/init.webAudioLazy.test.ts b/packages/core/src/runtime/init.webAudioLazy.test.ts
new file mode 100644
index 0000000000..c64273cd1b
--- /dev/null
+++ b/packages/core/src/runtime/init.webAudioLazy.test.ts
@@ -0,0 +1,83 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { initSandboxRuntimeModular } from "./init";
+import { createMockTimeline, resetRuntimeFixtureDom } from "./runtimeSeekFixture.test-helpers";
+
+// Opening an AudioContext opens the audio device on the page's thread; on Windows that took up to 7 s.
+describe("the audio context opens at the first clip that needs it", () => {
+ let built = 0;
+ const original = (globalThis as Record).AudioContext;
+
+ beforeEach(() => {
+ resetRuntimeFixtureDom();
+ built = 0;
+ (globalThis as Record).AudioContext = class {
+ state = "running";
+ destination = {};
+ currentTime = 0;
+ constructor() {
+ built += 1;
+ }
+ resume = () => Promise.resolve();
+ suspend = () => Promise.resolve();
+ close = () => Promise.resolve();
+ createGain = () => ({ gain: { value: 1 }, connect() {}, disconnect() {} });
+ createMediaElementSource = () => ({ connect() {}, disconnect() {} });
+ };
+ });
+
+ afterEach(() => {
+ (globalThis as Record).AudioContext = original;
+ vi.restoreAllMocks();
+ });
+
+ const mount = (withClip: boolean) => {
+ const root = document.createElement("div");
+ root.setAttribute("data-composition-id", "main");
+ root.setAttribute("data-root", "true");
+ root.setAttribute("data-start", "0");
+ root.setAttribute("data-duration", "10");
+ root.setAttribute("data-width", "1920");
+ root.setAttribute("data-height", "1080");
+ document.body.appendChild(root);
+ if (withClip) {
+ const audio = document.createElement("audio");
+ audio.setAttribute("data-start", "0");
+ audio.setAttribute("data-duration", "10");
+ audio.setAttribute("src", "/assets/track.mp3");
+ audio.load = () => {};
+ audio.play = vi.fn(() => Promise.resolve());
+ root.appendChild(audio);
+ }
+ window.__timelines = { main: createMockTimeline(10) };
+ };
+
+ const flush = async () => {
+ for (let turn = 0; turn < 4; turn++) await Promise.resolve();
+ };
+
+ it("builds none while a page with sound only loads", async () => {
+ mount(true);
+ initSandboxRuntimeModular();
+ await flush();
+ expect(built, "a paused page built an AudioContext").toBe(0);
+ });
+
+ it("builds none when a page with no sound plays", async () => {
+ mount(false);
+ initSandboxRuntimeModular();
+ window.__player?.play();
+ await flush();
+ expect(built, "a page with no clips built an AudioContext").toBe(0);
+ });
+
+ it("builds one when a page with sound plays, however often it plays", async () => {
+ mount(true);
+ initSandboxRuntimeModular();
+ window.__player?.play();
+ await flush();
+ window.__player?.pause();
+ window.__player?.play();
+ await flush();
+ expect(built).toBe(1);
+ });
+});
diff --git a/packages/core/src/runtime/webAudioTransport.ts b/packages/core/src/runtime/webAudioTransport.ts
index c381e58543..7b13f2bfcf 100644
--- a/packages/core/src/runtime/webAudioTransport.ts
+++ b/packages/core/src/runtime/webAudioTransport.ts
@@ -297,6 +297,12 @@ export class WebAudioTransport {
private _restTimer: ReturnType | null = null;
async init(): Promise {
+ return this.open();
+ }
+
+ /** Builds the context on the calling thread: on Windows that opens the audio device and can block seconds. */
+ open(): boolean {
+ if (this._ctx) return true;
try {
this._ctx = new AudioContext();
this._ctx.onstatechange = () => this.rest();