Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

fix(audio): release runtime references from finished web voices

yhhe69d027ec047
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4af072798..3d377151b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,10 @@ published separately; it ships inside the editor.
## [Unreleased]
+### Fixed
+
+- **Finished Web audio handles release their runtime references.** Stopped and naturally completed voices drop decoded buffers, sources, pool nodes and contexts after releasing their pool slot. Retaining a finished handle keeps its ID and duration available without pinning PCM; terminal controls remain harmless, while paused voices retain the state needed to resume and natural completion still notifies once.
+
## [0.87.0] - 2026-10-15
### Fixed
diff --git a/sdk/src/audio/WebAudioBackend.ts b/sdk/src/audio/WebAudioBackend.ts
index 91e3428fb..0ea4ffcf1 100644
--- a/sdk/src/audio/WebAudioBackend.ts
+++ b/sdk/src/audio/WebAudioBackend.ts
@@ -10,11 +10,12 @@ class WebAudioHandle implements AudioHandle {
readonly id: number;
onEnd?: () => void;
- private buffer_: AudioBuffer;
- private source_: AudioBufferSourceNode;
- private poolNode_: PooledAudioNode;
- private pool_: AudioPool;
- private context_: AudioContext;
+ /** Runtime references exist until Stop or natural completion; Pause retains them. */
+ private buffer_: AudioBuffer | null;
+ private source_: AudioBufferSourceNode | null;
+ private poolNode_: PooledAudioNode | null;
+ private pool_: AudioPool | null;
+ private context_: AudioContext | null;
private playing_ = true;
private stopped_ = false;
private pausedAt_ = 0;
@@ -22,6 +23,7 @@ class WebAudioHandle implements AudioHandle {
private startOffset_: number;
private playbackRate_: number;
private loop_: boolean;
+ private readonly duration_: number;
constructor(
id: number,
@@ -35,6 +37,7 @@ class WebAudioHandle implements AudioHandle {
this.id = id;
this.source_ = source;
this.buffer_ = buffer;
+ this.duration_ = buffer.duration;
this.poolNode_ = poolNode;
this.pool_ = pool;
this.context_ = context;
@@ -49,9 +52,7 @@ class WebAudioHandle implements AudioHandle {
private bindOnEnded_(source: AudioBufferSourceNode): void {
source.onended = () => {
if (!this.stopped_ && this.playing_ && source === this.source_ && !this.loop_) {
- this.playing_ = false;
- this.stopped_ = true;
- this.pool_.release(this.poolNode_);
+ this.release_();
this.onEnd?.();
}
};
@@ -59,37 +60,46 @@ class WebAudioHandle implements AudioHandle {
stop(): void {
if (this.stopped_) return;
+ this.release_();
+ }
+
+ private release_(): void {
this.stopped_ = true;
this.playing_ = false;
- this.source_.onended = null;
- this.pool_.release(this.poolNode_);
+ if (this.source_) this.source_.onended = null;
+ this.pool_!.release(this.poolNode_!);
+ this.buffer_ = null;
+ this.source_ = null;
+ this.poolNode_ = null;
+ this.pool_ = null;
+ this.context_ = null;
}
pause(): void {
if (!this.playing_ || this.stopped_) return;
this.playing_ = false;
- const elapsed = (this.context_.currentTime - this.startedAt_) * this.playbackRate_;
+ const elapsed = (this.context_!.currentTime - this.startedAt_) * this.playbackRate_;
this.pausedAt_ = this.startOffset_ + elapsed;
- if (this.loop_ && this.buffer_.duration > 0) {
- this.pausedAt_ = this.pausedAt_ % this.buffer_.duration;
+ if (this.loop_ && this.buffer_!.duration > 0) {
+ this.pausedAt_ = this.pausedAt_ % this.buffer_!.duration;
}
- this.source_.onended = null;
- try { this.source_.stop(); } catch (_) { /* already stopped */ }
- this.source_.disconnect();
+ this.source_!.onended = null;
+ try { this.source_!.stop(); } catch (_) { /* already stopped */ }
+ this.source_!.disconnect();
}
resume(): void {
if (this.playing_ || this.stopped_) return;
- const source = this.context_.createBufferSource();
+ const source = this.context_!.createBufferSource();
let startedAt: number;
try {
source.buffer = this.buffer_;
source.loop = this.loop_;
source.playbackRate.value = this.playbackRate_;
- source.connect(this.poolNode_.gain);
+ source.connect(this.poolNode_!.gain);
this.bindOnEnded_(source);
- startedAt = this.context_.currentTime;
+ startedAt = this.context_!.currentTime;
source.start(0, this.pausedAt_);
} catch (error) {
source.onended = null;
@@ -99,7 +109,7 @@ class WebAudioHandle implements AudioHandle {
}
this.source_ = source;
- this.poolNode_.source = source;
+ this.poolNode_!.source = source;
this.startOffset_ = this.pausedAt_;
this.startedAt_ = startedAt;
@@ -108,24 +118,26 @@ class WebAudioHandle implements AudioHandle {
setVolume(volume: number): void {
if (this.stopped_) return;
- this.poolNode_.gain.gain.value = volume;
+ this.poolNode_!.gain.gain.value = volume;
}
setPan(pan: number): void {
if (this.stopped_) return;
- this.poolNode_.panner.pan.value = pan;
+ this.poolNode_!.panner.pan.value = pan;
}
setLoop(loop: boolean): void {
+ if (this.stopped_) return;
this.loop_ = loop;
- this.source_.loop = loop;
+ this.source_!.loop = loop;
}
setPlaybackRate(rate: number): void {
+ if (this.stopped_) return;
if (this.playing_) {
- const now = this.context_.currentTime;
+ const now = this.context_!.currentTime;
const position = this.startOffset_ + (now - this.startedAt_) * this.playbackRate_;
- this.source_.playbackRate.value = rate;
+ this.source_!.playbackRate.value = rate;
this.startOffset_ = position;
this.startedAt_ = now;
}
@@ -139,12 +151,12 @@ class WebAudioHandle implements AudioHandle {
get currentTime(): number {
if (this.stopped_) return 0;
if (!this.playing_) return this.pausedAt_;
- const elapsed = (this.context_.currentTime - this.startedAt_) * this.playbackRate_;
+ const elapsed = (this.context_!.currentTime - this.startedAt_) * this.playbackRate_;
return this.startOffset_ + elapsed;
}
get duration(): number {
- return this.buffer_.duration;
+ return this.duration_;
}
}
diff --git a/sdk/tests/web-audio-backend.test.ts b/sdk/tests/web-audio-backend.test.ts
index 3c3230af1..c8fa4d7ae 100644
--- a/sdk/tests/web-audio-backend.test.ts
+++ b/sdk/tests/web-audio-backend.test.ts
@@ -369,6 +369,29 @@ describe('WebAudioBackend', () => {
});
describe('play', () => {
+ it.each(['stop', 'ended', 'paused-stop'])('terminal %s handles release runtime ownership and preserve scalar metadata', async kind => {
+ const { bufferHandle, mockCtx } = await initAndLoadBuffer(backend);
+ const handle = backend.play(bufferHandle, {});
+ const source = mockCtx.createBufferSource.mock.results.at(-1).value;
+ const ended = source.onended;
+ const onEnd = vi.fn();
+ handle.onEnd = onEnd;
+ if (kind === 'ended') ended();
+ else { if (kind === 'paused-stop') handle.pause(); handle.stop(); }
+ backend.unloadBuffer(bufferHandle);
+ expect(handle.isPlaying).toBe(false);
+ expect(handle.currentTime).toBe(0);
+ expect(handle.duration).toBe(1);
+ expect(source.onended).toBeNull();
+ for (const field of ['buffer_', 'source_', 'context_', 'pool_', 'poolNode_']) {
+ expect((handle as any)[field], field).toBeNull();
+ }
+ expect(() => {handle.pause();handle.resume();handle.stop();handle.setLoop(true);
+ handle.setPlaybackRate(2);handle.setVolume(.4);handle.setPan(.3);}).not.toThrow();
+ ended();
+ expect(onEnd).toHaveBeenCalledTimes(kind === 'ended' ? 1 : 0);
+ expect((backend as any).pool_.activeCount).toBe(0);
+ });
it.each(['stopped', 'ended'])('a %s handle cannot change gain or pan of a reused pool node', async kind => {
const { bufferHandle, mockCtx } = await initAndLoadBuffer(backend);
const old = backend.play(bufferHandle, {});
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index fe56cf11b..83056c85a 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -30,6 +30,8 @@ export const NOTES_FLOOR = 'v0.65.0';
export const NOTED = {
'test(nav): cover authored workshop obstacle layouts':
{ internal: 'Headless exported-workshop acceptance also loads a scene with authored obstacles enabled and verifies retained state and delivery after reopening.' },
+ 'fix(audio): release runtime references from finished web voices':
+ { note: 'Finished Web audio handles release their runtime references.' },
'chore(release): classify v0.87 feature verification':
{ internal: 'The shipped capability census maps v0.87 navigation features to the navigation corpus and names focused editor acceptance for viewport and inspector features.' },
'ci(editor): install workshop acceptance browser':