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.

feat(content): preview audio clips in the Content Browser

esengine93bca90e8d3c
diff --git a/desktop/src/project/assetOpen.ts b/desktop/src/project/assetOpen.ts
index 76d993b61..b68a37602 100644
--- a/desktop/src/project/assetOpen.ts
+++ b/desktop/src/project/assetOpen.ts
@@ -10,6 +10,7 @@
import type { AssetType } from '@/types';
import { ProjectStore } from './ProjectStore';
import { confirmDiscard } from './discardGuard';
+import { toggleAudioPreview } from './audioPreview';
import { openAnimationClip } from '@/timeline/openClip';
import { openTileset } from '@/tileset/openTileset';
import { openMaterial } from '@/material/openMaterial';
@@ -21,6 +22,7 @@ export const ASSET_OPEN: Partial<Record<AssetType, (path: string, name: string)
if (!confirmDiscard(`Opening ${name} will discard them`)) return;
void ProjectStore.openScene(path);
},
+ audio: (path) => toggleAudioPreview(path),
animation: (path) => void openAnimationClip(path),
tileset: (path) => void openTileset(path),
material: (path) => void openMaterial(path),
diff --git a/desktop/src/project/audioPreview.ts b/desktop/src/project/audioPreview.ts
new file mode 100644
index 000000000..6ca632c85
--- /dev/null
+++ b/desktop/src/project/audioPreview.ts
@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file audioPreview.ts
+ * @brief Content Browser audio preview — play a project sound (over the
+ * `estella://` transport) without wiring an AudioSource + Play. One clip at
+ * a time; re-triggering the playing clip stops it (toggle).
+ */
+interface Player {
+ play(): Promise<void> | void;
+ pause(): void;
+ currentTime: number;
+ onended: (() => void) | null;
+}
+
+// Injectable so the toggle logic is testable without a DOM <audio> element. The
+// real element is cast at this boundary (its `onended` handler takes an Event).
+let make: (url: string) => Player = (url) => new Audio(url) as unknown as Player;
+
+/** Override the audio factory (tests). */
+export function _setAudioFactory(factory: (url: string) => Player): void {
+ make = factory;
+}
+
+let current: Player | null = null;
+let currentPath: string | null = null;
+
+export function stopAudioPreview(): void {
+ if (current) {
+ current.pause();
+ current.currentTime = 0;
+ }
+ current = null;
+ currentPath = null;
+}
+
+/** Play `path` (toggle: a second trigger on the playing clip stops it). */
+export function toggleAudioPreview(path: string): void {
+ if (currentPath === path) {
+ stopAudioPreview();
+ return;
+ }
+ stopAudioPreview();
+ const a = make(`estella://project/${path}`);
+ a.onended = () => {
+ if (current === a) stopAudioPreview();
+ };
+ current = a;
+ currentPath = path;
+ void Promise.resolve(a.play()).catch(() => stopAudioPreview());
+}
+
+/** The path of the clip currently previewing, or null. */
+export function previewingPath(): string | null {
+ return currentPath;
+}
diff --git a/desktop/tests/audio-preview.test.ts b/desktop/tests/audio-preview.test.ts
new file mode 100644
index 000000000..e080c4a30
--- /dev/null
+++ b/desktop/tests/audio-preview.test.ts
@@ -0,0 +1,49 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file Content Browser audio preview — one clip at a time, toggle to stop,
+ * switching clips stops the previous. DOM <audio> mocked via the factory.
+ */
+import { describe, it, expect, beforeEach } from 'vitest';
+import { toggleAudioPreview, stopAudioPreview, previewingPath, _setAudioFactory } from '@/project/audioPreview';
+
+function fakeAudio() {
+ const calls: string[] = [];
+ _setAudioFactory((url) => ({
+ play: () => {
+ calls.push(`play:${url}`);
+ return Promise.resolve();
+ },
+ pause: () => calls.push(`pause:${url}`),
+ currentTime: 0,
+ onended: null,
+ }));
+ return calls;
+}
+
+describe('audio preview', () => {
+ beforeEach(() => stopAudioPreview());
+
+ it('plays a clip over the estella:// transport and tracks it', () => {
+ const calls = fakeAudio();
+ toggleAudioPreview('sfx/jump.wav');
+ expect(previewingPath()).toBe('sfx/jump.wav');
+ expect(calls).toContain('play:estella://project/sfx/jump.wav');
+ });
+
+ it('re-triggering the playing clip stops it (toggle)', () => {
+ fakeAudio();
+ toggleAudioPreview('a.wav');
+ toggleAudioPreview('a.wav');
+ expect(previewingPath()).toBeNull();
+ });
+
+ it('switching to another clip stops the previous one', () => {
+ const calls = fakeAudio();
+ toggleAudioPreview('a.wav');
+ toggleAudioPreview('b.wav');
+ expect(previewingPath()).toBe('b.wav');
+ expect(calls).toContain('pause:estella://project/a.wav');
+ expect(calls).toContain('play:estella://project/b.wav');
+ });
+});