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.

18.5 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import { describe, it, expect, beforeEach, vi } from 'vitest';
import { AudioAPI } from '../src/audio/Audio';
import type { PlatformAudioBackend, AudioHandle, AudioBufferHandle, PlayConfig } from '../src/audio/PlatformAudioBackend';
import type { AudioMixer } from '../src/audio/AudioMixer';
import type { AudioBus } from '../src/audio/AudioBus';

function createMockHandle(overrides: Partial<AudioHandle> = {}): AudioHandle {
    return {
        id: 1,
        stop: vi.fn(),
        pause: vi.fn(),
        resume: vi.fn(),
        setVolume: vi.fn(),
        setPan: vi.fn(),
        setLoop: vi.fn(),
        setPlaybackRate: vi.fn(),
        isPlaying: true,
        currentTime: 0,
        duration: 1.0,
        ...overrides,
    };
}

function createMockBus(name: string): AudioBus {
    return {
        name,
        volume: 1.0,
        muted: false,
        node: {} as GainNode,
        connect: vi.fn(),
        addChild: vi.fn(),
    } as unknown as AudioBus;
}

function createMockBackend(): PlatformAudioBackend {
    return {
        name: 'MockBackend',
        delivery: 'bytes',
        mixer: null,
        isReady: true,
        initialize: vi.fn().mockResolvedValue(undefined),
        ensureResumed: vi.fn().mockResolvedValue(undefined),
        loadBuffer: vi.fn().mockResolvedValue({ id: 1, duration: 2.0 }),
        loadBufferFromData: vi.fn().mockResolvedValue({ id: 2, duration: 1.0 }),
        unloadBuffer: vi.fn(),
        play: vi.fn().mockReturnValue(createMockHandle()),
        suspend: vi.fn(),
        resume: vi.fn(),
        dispose: vi.fn(),
    };
}

function createMockMixer(): AudioMixer {
    const masterBus = createMockBus('master');
    const musicBus = createMockBus('music');
    const sfxBus = createMockBus('sfx');
    const uiBus = createMockBus('ui');
    const voiceBus = createMockBus('voice');

    return {
        master: masterBus,
        music: musicBus,
        sfx: sfxBus,
        ui: uiBus,
        voice: voiceBus,
        getBus: vi.fn((name: string) => {
            const map: Record<string, AudioBus> = { master: masterBus, music: musicBus, sfx: sfxBus, ui: uiBus, voice: voiceBus };
            return map[name];
        }),
        createBus: vi.fn(),
    } as unknown as AudioMixer;
}

describe('AudioAPI', () => {
    let backend: PlatformAudioBackend;
    let mixer: AudioMixer;
    let audio: AudioAPI;

    beforeEach(() => {
        backend = createMockBackend();
        mixer = createMockMixer();
        audio = new AudioAPI(backend, mixer);
    });

    describe('preload', () => {
        it.each(['url', 'bytes'] as const)('releases a late %s decode instead of repopulating a disposed cache', async delivery => {
            let finish!: (buffer: AudioBufferHandle) => void;
            const load = vi.fn(() => new Promise<AudioBufferHandle>(resolve => { finish = resolve; }));
            if (delivery === 'url') backend.loadBuffer = load;
            else backend.loadBufferFromData = load;
            const pending = delivery === 'url' ? audio.preload('late.wav')
                : audio.preloadFromData('late.wav', new ArrayBuffer(8));
            const joined = delivery === 'url' ? audio.preload('late.wav')
                : audio.preloadFromData('late.wav', new ArrayBuffer(8));
            audio.dispose();
            const buffer = { id: 9, duration: 2, bytes: 1024 };
            finish(buffer);
            await Promise.all([pending, joined]);
            expect(load).toHaveBeenCalledTimes(1);
            expect(audio.getBufferHandle('late.wav')).toBeUndefined();
            expect(audio.getBufferStats()).toMatchObject({ bufferCount: 0, bufferBytes: 0 });
            expect(backend.unloadBuffer).toHaveBeenCalledTimes(1);
            expect(backend.unloadBuffer).toHaveBeenCalledWith(buffer);
        });

        it('does not ask a closed backend to decode new preloads', async () => {
            audio.dispose();
            await audio.preload('after.wav');
            await audio.preloadFromData('after.wav', new ArrayBuffer(8));
            expect(backend.loadBuffer).not.toHaveBeenCalled();
            expect(backend.loadBufferFromData).not.toHaveBeenCalled();
        });

        it('does no backend invalidation work for a source the API never held', () => {
            backend.invalidateSource = vi.fn();
            expect(audio.invalidateBuffer('unused.png')).toBe(false);
            expect(backend.invalidateSource).not.toHaveBeenCalled();
        });

        it.each(['old-first', 'new-first'] as const)('does not publish invalidated decodes when completion order is %s', async order => {
            const finish: Array<(buffer: AudioBufferHandle) => void> = [];
            const load = vi.fn(() => new Promise<AudioBufferHandle>(resolve => finish.push(resolve)));
            backend.loadBufferFromData = load;
            const old = audio.preloadFromData('edited.wav', new ArrayBuffer(8));
            expect(audio.invalidateBuffer('edited.wav')).toBe(true);
            const current = audio.preloadFromData('edited.wav', new ArrayBuffer(8));
            expect(load).toHaveBeenCalledTimes(2);
            const oldBuffer = { id: 9, duration: 1, bytes: 1024 };
            const newBuffer = { id: 10, duration: 2, bytes: 2048 };
            if (order === 'old-first') {
                finish[0](oldBuffer); await old;
                expect(audio.getBufferHandle('edited.wav')).toBeUndefined();
                const joined = audio.preloadFromData('edited.wav', new ArrayBuffer(8));
                expect(load).toHaveBeenCalledTimes(2);
                finish[1](newBuffer); await Promise.all([current, joined]);
            } else {
                finish[1](newBuffer); await current;
                finish[0](oldBuffer); await old;
            }
            expect(audio.getBufferHandle('edited.wav')).toBe(newBuffer);
            expect(audio.getBufferStats()).toMatchObject({ bufferCount: 1, bufferBytes: 2048 });
            expect(backend.unloadBuffer).toHaveBeenCalledTimes(1);
            expect(backend.unloadBuffer).toHaveBeenCalledWith(oldBuffer);
        });

        it('should load buffer via backend', async () => {
            await audio.preload('sfx.mp3');
            expect(backend.loadBuffer).toHaveBeenCalledWith('sfx.mp3');
        });

        it('should not reload already cached buffer', async () => {
            await audio.preload('sfx.mp3');
            await audio.preload('sfx.mp3');
            expect(backend.loadBuffer).toHaveBeenCalledTimes(1);
        });

        it('de-dupes CONCURRENT loads of the same url (one decode, no orphan)', async () => {
            const data = new ArrayBuffer(8);
            // Both start before either resolves — without in-flight dedup both decode.
            await Promise.all([
                audio.preloadFromData('wind.mp3', data),
                audio.preloadFromData('wind.mp3', data),
            ]);
            expect(backend.loadBufferFromData).toHaveBeenCalledTimes(1);
        });

        it('prefixes relative urls with baseUrl (legacy prefix path)', async () => {
            audio.baseUrl = 'estella://project';
            await audio.preload('assets/sfx.mp3');
            expect(backend.loadBuffer).toHaveBeenCalledWith('estella://project/assets/sfx.mp3');
        });

        // The realm's single asset resolver (uuid manifest / cooked
        // logical→staged maps) takes precedence over the baseUrl prefix, so
        // playSFX('assets/…') fetches the staged file in cooked builds.
        it('routes refs through setRefResolver when wired (cooked builds)', async () => {
            audio.baseUrl = 'estella://project';
            audio.setRefResolver((ref) => `./assets/abcd1234.${ref.split('.').pop()}`);
            await audio.preload('assets/sfx.mp3');
            expect(backend.loadBuffer).toHaveBeenCalledWith('./assets/abcd1234.mp3');
        });
    });

    describe('preloadAll', () => {
        it('should load multiple buffers in parallel', async () => {
            await audio.preloadAll(['a.mp3', 'b.mp3', 'c.mp3']);
            expect(backend.loadBuffer).toHaveBeenCalledTimes(3);
        });
    });

    describe('playSFX', () => {
        it('should play from cached buffer', async () => {
            await audio.preload('click.mp3');
            const handle = audio.playSFX('click.mp3', { volume: 0.5 });
            expect(backend.play).toHaveBeenCalledWith(
                { id: 1, duration: 2.0 },
                expect.objectContaining({ bus: 'sfx', volume: 0.5 })
            );
        });

        it('should return deferred handle for uncached buffer', () => {
            const handle = audio.playSFX('uncached.mp3');
            expect(handle.id).toBe(-1);
            expect(handle.isPlaying).toBe(false);
        });

        it('should delegate deferred handle methods after resolve', async () => {
            await audio.preload('deferred.mp3');
            const mockHandle = createMockHandle({ id: 42 });
            (backend.play as ReturnType<typeof vi.fn>).mockReturnValue(mockHandle);

            const handle = audio.playSFX('deferred.mp3');
            handle.stop();
            expect(mockHandle.stop).toHaveBeenCalled();
        });
    });

    describe('playBGM', () => {
        it('should play as looping music', async () => {
            await audio.preload('bgm.mp3');
            audio.playBGM('bgm.mp3');
            expect(backend.play).toHaveBeenCalledWith(
                { id: 1, duration: 2.0 },
                expect.objectContaining({ bus: 'music', loop: true })
            );
        });

        it('should stop previous BGM', async () => {
            await audio.preload('bgm1.mp3');
            const firstHandle = createMockHandle();
            (backend.play as ReturnType<typeof vi.fn>).mockReturnValue(firstHandle);
            audio.playBGM('bgm1.mp3');

            const secondHandle = createMockHandle();
            (backend.play as ReturnType<typeof vi.fn>).mockReturnValue(secondHandle);
            audio.playBGM('bgm1.mp3');

            expect(firstHandle.stop).toHaveBeenCalled();
        });
    });

    describe('stopBGM', () => {
        it('should stop current BGM', async () => {
            await audio.preload('bgm.mp3');
            const mockHandle = createMockHandle();
            (backend.play as ReturnType<typeof vi.fn>).mockReturnValue(mockHandle);
            audio.playBGM('bgm.mp3');
            audio.stopBGM();
            expect(mockHandle.stop).toHaveBeenCalled();
        });

        it('should do nothing if no BGM playing', () => {
            expect(() => audio.stopBGM()).not.toThrow();
        });
    });

    describe('volume controls', () => {
        it('should set master volume', () => {
            audio.setMasterVolume(0.5);
            expect(mixer.master.volume).toBe(0.5);
        });

        it('should set music volume', () => {
            audio.setMusicVolume(0.3);
            expect(mixer.music.volume).toBe(0.3);
        });

        it('should set sfx volume', () => {
            audio.setSFXVolume(0.7);
            expect(mixer.sfx.volume).toBe(0.7);
        });

        it('should set ui volume', () => {
            audio.setUIVolume(0.6);
            expect(mixer.ui.volume).toBe(0.6);
        });
    });

    describe('volume getters', () => {
        it('reads back the master volume set through the API', () => {
            audio.setMasterVolume(0.4);
            expect(audio.getMasterVolume()).toBe(0.4);
        });

        it('reads back per-category volumes', () => {
            audio.setMusicVolume(0.3);
            audio.setSFXVolume(0.7);
            audio.setUIVolume(0.6);
            expect(audio.getMusicVolume()).toBe(0.3);
            expect(audio.getSFXVolume()).toBe(0.7);
            expect(audio.getUIVolume()).toBe(0.6);
        });

        it('reads back a named bus volume', () => {
            audio.setBusVolume('sfx', 0.25);
            expect(audio.getBusVolume('sfx')).toBe(0.25);
        });

        it('reports unity volume for an unknown bus', () => {
            (mixer.getBus as ReturnType<typeof vi.fn>).mockReturnValue(undefined);
            expect(audio.getBusVolume('nope')).toBe(1);
        });

        it('reports unity volume and unmuted without a mixer', () => {
            const bare = new AudioAPI(createMockBackend(), null);
            expect(bare.getMasterVolume()).toBe(1);
            expect(bare.getMusicVolume()).toBe(1);
            expect(bare.getSFXVolume()).toBe(1);
            expect(bare.getUIVolume()).toBe(1);
            expect(bare.getBusVolume('sfx')).toBe(1);
            expect(bare.isBusMuted('sfx')).toBe(false);
        });
    });

    describe('isBusMuted', () => {
        it('reflects muteBus state', () => {
            expect(audio.isBusMuted('sfx')).toBe(false);
            audio.muteBus('sfx', true);
            expect(audio.isBusMuted('sfx')).toBe(true);
            audio.muteBus('sfx', false);
            expect(audio.isBusMuted('sfx')).toBe(false);
        });

        it('reports unmuted for an unknown bus', () => {
            (mixer.getBus as ReturnType<typeof vi.fn>).mockReturnValue(undefined);
            expect(audio.isBusMuted('nope')).toBe(false);
        });
    });

    describe('muteBus', () => {
        it('should mute specified bus', () => {
            audio.muteBus('sfx', true);
            expect(mixer.getBus).toHaveBeenCalledWith('sfx');
        });
    });

    describe('getSpectrum', () => {
        it('returns false on a backend without analysis (silent fallback)', () => {
            // the default mock backend omits getFrequencyData (like WeChat)
            expect(audio.getSpectrum(new Uint8Array(8))).toBe(false);
        });

        it('forwards to the backend analyser and fills the array', () => {
            const withAnalyser = createMockBackend();
            withAnalyser.getFrequencyData = vi.fn((o: Uint8Array) => { o.fill(200); return true; });
            const a = new AudioAPI(withAnalyser, createMockMixer());

            const out = new Uint8Array(8);
            expect(a.getSpectrum(out)).toBe(true);
            expect(withAnalyser.getFrequencyData).toHaveBeenCalledWith(out);
            expect(out.every(v => v === 200)).toBe(true);
        });
    });

    describe('dispose', () => {
        it('stops scripted and looping source voices before disposing the device', async () => {
            await audio.preload('tone.wav');
            const effect = createMockHandle(), source = createMockHandle();
            const stopped: string[] = [];
            effect.stop = vi.fn(() => { stopped.push('effect'); });
            source.stop = vi.fn(() => { stopped.push('source'); });
            backend.dispose = vi.fn(() => { stopped.push('device'); });
            vi.mocked(backend.play).mockReturnValueOnce(effect).mockReturnValueOnce(source);
            audio.playSFX('tone.wav');
            audio.playBuffer(audio.getBufferHandle('tone.wav')!, { loop: true });
            audio.dispose();
            expect(stopped).toEqual(['effect', 'source', 'device']);
        });
        it('should stop BGM and dispose backend', async () => {
            await audio.preload('bgm.mp3');
            const mockHandle = createMockHandle();
            (backend.play as ReturnType<typeof vi.fn>).mockReturnValue(mockHandle);
            audio.playBGM('bgm.mp3');

            audio.dispose();

            expect(mockHandle.stop).toHaveBeenCalled();
            expect(backend.unloadBuffer).toHaveBeenCalled();
            expect(backend.dispose).toHaveBeenCalled();
        });

        it('should clear buffer cache', async () => {
            await audio.preload('sfx.mp3');
            audio.dispose();
            expect(audio.getBufferHandle('sfx.mp3')).toBeUndefined();
        });

        it('should prevent in-flight preloads from playing after dispose', async () => {
            let resolveLoad!: (v: any) => void;
            (backend.loadBuffer as ReturnType<typeof vi.fn>).mockReturnValue(
                new Promise(r => { resolveLoad = r; })
            );

            audio.playSFX('slow.mp3');
            audio.dispose();

            resolveLoad({ id: 99, duration: 1.0 });
            await new Promise(r => setTimeout(r, 0));

            expect(backend.play).not.toHaveBeenCalledWith(
                expect.objectContaining({ id: 99 }),
                expect.anything()
            );
        });
    });

    describe('isolation', () => {
        it('two AudioAPI instances keep independent buffer caches', async () => {
            const backend2 = createMockBackend();
            const audio2 = new AudioAPI(backend2, createMockMixer());

            await audio.preload('a.mp3');
            expect(backend.loadBuffer).toHaveBeenCalledTimes(1);
            expect(backend2.loadBuffer).not.toHaveBeenCalled();

            await audio2.preload('a.mp3');
            expect(backend2.loadBuffer).toHaveBeenCalledTimes(1);
        });
    });

    describe('playTrack', () => {
        it('loads the URL verbatim (no ref resolution) and plays it on the bus', async () => {
            const backend = createMockBackend();
            const audio = new AudioAPI(backend, createMockMixer());
            audio.setRefResolver(() => { throw new Error('must not resolve'); });
            const handle = await audio.playTrack('assets/clip.esv.m4a', { bus: 'video', startOffset: 1.5, volume: 0.5 });
            expect(handle).not.toBeNull();
            expect(backend.loadBuffer).toHaveBeenCalledWith('assets/clip.esv.m4a');
            expect(backend.play).toHaveBeenCalledWith(expect.anything(), expect.objectContaining({
                bus: 'video', startOffset: 1.5, volume: 0.5,
            }));
        });

        it('creates the bus on demand and caches the buffer across plays', async () => {
            const backend = createMockBackend();
            const mixer = createMockMixer();
            (mixer.getBus as ReturnType<typeof vi.fn>).mockReturnValue(undefined);
            const audio = new AudioAPI(backend, mixer);
            await audio.playTrack('t.m4a', { bus: 'video' });
            expect(mixer.createBus).toHaveBeenCalledWith(expect.objectContaining({ name: 'video' }));
            await audio.playTrack('t.m4a', { bus: 'video' });
            expect(backend.loadBuffer).toHaveBeenCalledTimes(1);
        });

        it('resolves null when the clip cannot load', async () => {
            const backend = createMockBackend();
            (backend.loadBuffer as ReturnType<typeof vi.fn>).mockRejectedValue(new Error('404'));
            const audio = new AudioAPI(backend, createMockMixer());
            expect(await audio.playTrack('missing.m4a')).toBeNull();
        });
    });
});