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): freeze fade clocks during device suspension

yhh33d8c4888ef7
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1aafc9adb..f069c102c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,8 @@ published separately; it ships inside the editor.
### Fixed
+- **Audio device suspension freezes volume fades.** Fade elapsed time stays at its current position while the device is suspended, preventing covered or interrupted playback from completing a fade-out before resume. Existing per-voice pause handling remains effective after the device resumes.
+
- **Mini-game device resume preserves manual audio pauses.** The backend resumes only live contexts that were playing when device suspension began. Repeated suspension retains the original resume set, and stopped, ended, or disposed contexts are never restarted.
- **Audio plugin cleanup belongs to each App.** Shared plugin instances release the quitting App's voices, backend, and memory/despawn subscriptions without stopping another App. Released systems stay inactive, and repeated preview shutdowns release every backend once.
diff --git a/sdk/src/audio/Audio.ts b/sdk/src/audio/Audio.ts
index 2690d4e80..d4be78c86 100644
--- a/sdk/src/audio/Audio.ts
+++ b/sdk/src/audio/Audio.ts
@@ -124,6 +124,7 @@ export class AudioAPI {
// {@link cancelFades_} stops these when it tears the animations down.
private readonly fadingOut_ = new Set<AudioHandle>();
private disposed_ = false;
+ private suspended_ = false;
private assetResolver_: ((url: string) => ArrayBuffer | null) | null = null;
private refResolver_: ((ref: string) => string) | null = null;
baseUrl = '';
@@ -469,11 +470,13 @@ export class AudioAPI {
*/
suspend(): void {
this.backend_.suspend();
+ this.suspended_ = true;
}
/** Resume the audio device after {@link suspend}. */
resume(): void {
this.backend_.resume();
+ this.suspended_ = false;
}
setMasterVolume(volume: number): void {
@@ -770,7 +773,7 @@ export class AudioAPI {
* browser's: it pauses when the game does, and it exists on a device.
*/
updateFades(dt: number): void {
- if (this.fades_.length === 0 || !(dt > 0)) return;
+ if (this.suspended_ || 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;
diff --git a/sdk/tests/audio-paused-voices.test.ts b/sdk/tests/audio-paused-voices.test.ts
index 92fb889b7..05db092c8 100644
--- a/sdk/tests/audio-paused-voices.test.ts
+++ b/sdk/tests/audio-paused-voices.test.ts
@@ -15,11 +15,30 @@ function setup() {
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;
+ }), unloadBuffer: vi.fn(), dispose: vi.fn(), suspend: vi.fn(), resume: 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('device suspension freezes fade-in elapsed time until resume', async () => {
+ const { audio, backend, handles } = setup();
+ backend.loadBuffer = vi.fn().mockResolvedValue(buffer); await audio.preload('music.wav');
+ audio.playBGM('music.wav', { fadeIn: 1 }); audio.updateFades(.25);
+ audio.suspend(); audio.updateFades(10);
+ expect(handles[0]!.setVolume).toHaveBeenLastCalledWith(.25);
+ audio.resume(); audio.updateFades(.25);
+ expect(handles[0]!.setVolume).toHaveBeenLastCalledWith(.5);
+ });
+ it('device suspension does not finish or stop an in-flight fade-out', async () => {
+ const { audio, backend, handles } = setup();
+ backend.loadBuffer = vi.fn().mockResolvedValue(buffer); await audio.preload('music.wav');
+ audio.playBGM('music.wav'); audio.stopBGM(1); audio.updateFades(.25);
+ audio.suspend(); audio.updateFades(10);
+ expect(handles[0]!.stop).not.toHaveBeenCalled();
+ expect(handles[0]!.setVolume).toHaveBeenLastCalledWith(.75);
+ audio.resume(); audio.updateFades(.75);
+ expect(handles[0]!.stop).toHaveBeenCalledOnce();
+ });
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();
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 83c08c56a..f6f3be378 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): freeze fade clocks during device suspension':
+ { note: 'Audio device suspension freezes volume fades.' },
'fix(audio): preserve manual minigame pauses on device resume':
{ note: 'Mini-game device resume preserves manual audio pauses.' },
'fix(audio): isolate plugin cleanup by app':