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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
fix(audio): retain paused voice ownership and tracked base gains
yhh87bdcd6ef021
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 17697ce41..6c32cbac5 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -16,6 +16,8 @@ published separately; it ships inside the editor.### Fixed+- **Paused voices remain owned by the audio API.** Paused handles retain their voice-budget slot, bus volume and mute updates, and disposal cleanup; stolen paused voices cannot resume outside the budget. Handle volume edits update the tracked base gain, fades stay associated with managed handles, and ended ramps stop writing to released backend voices.+- **WebAudio position stays continuous across playback-rate changes.** Rate edits anchor the accumulated position before applying the new rate, so pause/resume and loop offsets use the time actually played at each rate. A rate rejected by the backend leaves the existing clock intact; paused edits apply when playback resumes.- **Playing audio sources follow live parameter edits.** Volume, pitch and loop changes update the existing voice without restarting it. Switching spatial sound off restores base gain and centered pan; stable nonspatial sources do not resend unchanged parameters, and voice cleanup avoids copying its key list every frame.diff --git a/sdk/src/audio/Audio.ts b/sdk/src/audio/Audio.tsindex 53b7d9fa6..2690d4e80 100644--- a/sdk/src/audio/Audio.ts+++ b/sdk/src/audio/Audio.ts@@ -61,6 +61,8 @@ function silentHandle(): AudioHandle {interface SoftVoice {handle: AudioHandle;+ publicHandle?: AudioHandle;+ paused: boolean;bus: string;base: number;fade: number;@@ -563,7 +565,7 @@ export class AudioAPI {/** Re-apply after a bus (or master) changed, and forget voices that ended. */private applyBus_(busName: string): void {- this.softVoices_ = this.softVoices_.filter((v) => v.handle.isPlaying || this.fadeOf_(v) !== null);+ this.softVoices_ = this.softVoices_.filter((v) => v.paused || v.handle.isPlaying || this.fadeOf_(v) !== null);for (const voice of this.softVoices_) {if (busName === 'master' || voice.bus === busName) this.applyVoice_(voice);}@@ -599,8 +601,37 @@ export class AudioAPI {const priority = config.priority ?? 0;if (!this.makeRoomForVoice_(priority)) return silentHandle();const handle = this.backend_.play(buffer, { ...config, volume: base * this.softGain_(bus) });- this.softVoices_.push({ handle, bus, base, fade: 1, priority, seq: this.voiceSeq_++ });- return handle;+ const voice: SoftVoice = { handle, bus, base, fade: 1, paused: false, priority, seq: this.voiceSeq_++ };+ const api = this;+ const managed: AudioHandle = {+ get id() { return handle.id; },+ stop() { voice.paused = false; handle.stop(); },+ pause() {+ if (!handle.isPlaying) return;+ handle.pause();+ voice.paused = !handle.isPlaying;+ },+ resume() {+ if (!voice.paused || api.disposed_ || !api.softVoices_.includes(voice)) return;+ handle.resume();+ if (handle.isPlaying) voice.paused = false;+ },+ setVolume(volume) {+ voice.base = volume;+ if (!api.disposed_ && (voice.paused || handle.isPlaying)) api.applyVoice_(voice);+ },+ setPan(pan) { if (!api.disposed_ && (voice.paused || handle.isPlaying)) handle.setPan(pan); },+ setLoop(loop) { handle.setLoop(loop); },+ setPlaybackRate(rate) { handle.setPlaybackRate(rate); },+ get isPlaying() { return handle.isPlaying; },+ get currentTime() { return handle.currentTime; },+ get duration() { return handle.duration; },+ get onEnd() { return handle.onEnd; },+ set onEnd(callback) { handle.onEnd = callback; },+ };+ voice.publicHandle = managed;+ this.softVoices_.push(voice);+ return managed;}/**@@ -611,7 +642,7 @@ export class AudioAPI {*/private makeRoomForVoice_(priority: number): boolean {this.softVoices_ = this.softVoices_.filter(- (v) => v.handle.isPlaying || this.fadeOf_(v) !== null,+ (v) => v.paused || v.handle.isPlaying || this.fadeOf_(v) !== null,);if (this.maxVoices_ <= 0 || this.softVoices_.length < this.maxVoices_) return true;@@ -623,6 +654,7 @@ export class AudioAPI {}}if (!weakest || weakest.priority > priority) return false;+ weakest.paused = false;weakest.handle.stop();this.softVoices_ = this.softVoices_.filter((v) => v !== weakest);return true;@@ -741,15 +773,21 @@ export class AudioAPI {if (this.fades_.length === 0 || !(dt > 0)) return;for (let i = this.fades_.length - 1; i >= 0; i--) {const fade = this.fades_[i];+ if (fade.voice.paused) continue;+ if (!fade.voice.handle.isPlaying) {+ this.fadingOut_.delete(fade.voice.publicHandle ?? fade.voice.handle);+ this.fades_.splice(i, 1);+ continue;+ }fade.elapsed += dt;const t = fade.duration > 0 ? Math.min(fade.elapsed / fade.duration, 1) : 1;fade.voice.fade = fade.from + (fade.to - fade.from) * t;this.applyVoice_(fade.voice);// A track that ended (or was stopped) mid-ramp takes its fade with it.- if (t >= 1 || !fade.voice.handle.isPlaying) {+ if (t >= 1) {if (fade.stopAtEnd) {fade.voice.handle.stop();- this.fadingOut_.delete(fade.voice.handle);+ this.fadingOut_.delete(fade.voice.publicHandle ?? fade.voice.handle);}this.fades_.splice(i, 1);}@@ -767,9 +805,9 @@ export class AudioAPI {/** The tracked voice for a handle, registering one if it came from outside* the play path (a deferred handle resolved later). */private voiceOf_(handle: AudioHandle, base: number, bus: string): SoftVoice {- const found = this.softVoices_.find((v) => v.handle === handle);+ const found = this.softVoices_.find((v) => v.handle === handle || v.publicHandle === handle);if (found) return found;- const voice: SoftVoice = { handle, bus, base, fade: 1, priority: 0, seq: this.voiceSeq_++ };+ const voice: SoftVoice = { handle, bus, base, fade: 1, paused: false, priority: 0, seq: this.voiceSeq_++ };this.softVoices_.push(voice);return voice;}diff --git a/sdk/tests/audio-paused-voices.test.ts b/sdk/tests/audio-paused-voices.test.tsnew file mode 100644index 000000000..92fb889b7--- /dev/null+++ b/sdk/tests/audio-paused-voices.test.ts@@ -0,0 +1,86 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { describe, expect, it, vi } from 'vitest';+import { AudioAPI } from '../src/audio/Audio';+import type { AudioHandle, PlatformAudioBackend } from '../src/audio/PlatformAudioBackend';+function setup() {+ const handles: AudioHandle[] = [];+ const backend = { name: 'Counting', mixer: null, isReady: true,+ play: vi.fn(() => {+ let playing = true, stopped = false;+ const h: AudioHandle = { id: handles.length + 1,+ stop: vi.fn(() => { playing = false; stopped = true; }),+ pause: vi.fn(() => { playing = false; }),+ resume: vi.fn(() => { if (!stopped) playing = true; }),+ setVolume: vi.fn(), setPan: vi.fn(), setLoop: vi.fn(), setPlaybackRate: vi.fn(),+ get isPlaying() { return playing; }, currentTime: 0, duration: 1 };+ handles.push(h); return h;+ }), unloadBuffer: vi.fn(), dispose: vi.fn() } as unknown as PlatformAudioBackend;+ return { audio: new AudioAPI(backend, null), backend, handles };+}+const buffer = { id: 1, duration: 1 };+describe('paused voice ownership', () => {+ it('a paused voice remains inside its priority budget', () => {+ const { audio, backend } = setup(); audio.setMaxVoices(1);+ const h = audio.playBuffer(buffer, { priority: 9 }); h.pause();+ expect(audio.playBuffer(buffer, { priority: 1 }).isPlaying).toBe(false);+ expect(backend.play).toHaveBeenCalledTimes(1);+ h.resume(); expect(h.isPlaying).toBe(true);+ });+ it('paused voices receive bus changes and stay tracked after resume', () => {+ const { audio, handles } = setup();+ const h = audio.playBuffer(buffer, { volume: .8 }); h.pause();+ audio.setSFXVolume(.5); h.resume(); audio.setSFXVolume(.25);+ expect(handles[0]!.setVolume).toHaveBeenLastCalledWith(.2);+ });+ it('handle volume changes update base gain before later bus changes', () => {+ const { audio, handles } = setup();+ const h = audio.playBuffer(buffer, { volume: .8 }); h.setVolume(.2);+ audio.setSFXVolume(.5);+ expect(handles[0]!.setVolume).toHaveBeenLastCalledWith(.1);+ });+ it('disposing the API stops paused voices even after a bus update', () => {+ const { audio, handles } = setup();+ const h = audio.playBuffer(buffer); h.pause(); audio.setSFXVolume(.5); audio.dispose();+ expect(handles[0]!.stop).toHaveBeenCalled();+ h.resume(); expect(h.isPlaying).toBe(false);+ });+ it('a stolen paused voice cannot resume outside the voice budget', () => {+ const { audio, handles } = setup(); audio.setMaxVoices(1);+ const old = audio.playBuffer(buffer, { priority: 1 }); old.pause();+ const next = audio.playBuffer(buffer, { priority: 9 }); old.resume();+ vi.mocked(handles[0]!.setVolume).mockClear(); old.setVolume(.2);+ expect(handles[0]!.stop).toHaveBeenCalled();+ expect(handles[0]!.resume).not.toHaveBeenCalled(); expect(next.isPlaying).toBe(true);+ expect(handles[0]!.setVolume).not.toHaveBeenCalled();+ });+ it('BGM fades remain attached to the tracked voice and stop at completion', async () => {+ const { audio, backend, handles } = setup();+ backend.loadBuffer = vi.fn().mockResolvedValue(buffer); await audio.preload('music.wav');+ audio.playBGM('music.wav', { volume: .8, fadeIn: 1 }); audio.updateFades(.5);+ expect(handles[0]!.setVolume).toHaveBeenLastCalledWith(.4);+ audio.stopBGM(1); audio.updateFades(1);+ expect(handles[0]!.stop).toHaveBeenCalled();+ expect((audio as unknown as { fadingOut_: Set<AudioHandle> }).fadingOut_.size).toBe(0);+ });+ it('a stopped ramp does not write to an already released backend voice', async () => {+ const { audio, backend, handles } = setup();+ backend.loadBuffer = vi.fn().mockResolvedValue(buffer); await audio.preload('music.wav');+ audio.playBGM('music.wav', { fadeIn: 1 });+ handles[0]!.stop(); vi.mocked(handles[0]!.setVolume).mockClear(); audio.updateFades(.5);+ expect(handles[0]!.setVolume).not.toHaveBeenCalled();+ });+ it('mute and unmute affect a paused voice before it resumes', () => {+ const { audio, handles } = setup(); const h = audio.playBuffer(buffer, { volume: .8 });+ h.pause(); audio.muteBus('sfx', true);+ expect(handles[0]!.setVolume).toHaveBeenLastCalledWith(0);+ audio.muteBus('sfx', false); h.resume();+ expect(handles[0]!.setVolume).toHaveBeenLastCalledWith(.8);+ });+ it('managed handles preserve backend identity fields and completion callbacks', () => {+ const { audio, handles } = setup(); const h = audio.playBuffer(buffer), ended = vi.fn();+ h.onEnd = ended; handles[0]!.onEnd?.();+ expect(ended).toHaveBeenCalledTimes(1); expect(h.onEnd).toBe(ended);+ expect(h.id).toBe(handles[0]!.id); expect(h.duration).toBe(handles[0]!.duration);+ });+});diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex 4e8819cc4..f7ab81d5e 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -28,6 +28,8 @@ export const NOTES_FLOOR = 'v0.65.0';* the reader recognises anyway.*/export const NOTED = {+ 'fix(audio): retain paused voice ownership and tracked base gains':+ { note: 'Paused voices remain owned by the audio API.' },'fix(audio): preserve playback position across rate changes':{ note: 'WebAudio position stays continuous across playback-rate changes.' },'fix(audio): apply live source parameters without restarting voices':