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.

56.7 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import type { PlatformAudioBackend, AudioBufferHandle, AudioHandle, PlayConfig, AudioDelivery, AudioLoadOptions, AudioLoadType, AudioClipTrim } from './PlatformAudioBackend';
import type { AudioMixer, BusDuckRule } from './AudioMixer';
import type { BusEffectDef } from './BusEffects';
import { defineResource } from '../ecs/resource';
import { RuntimeConfig } from '../defaults';
import { log } from '../util/logger';
import { disposeAll } from '../util/disposeAll';
import { isAudioRecipePath, renderAudioRecipe } from '../asset/audioRecipe';
import { getPlatform } from '../platform/base';

/** `./a//b.mp3` and `a/b.mp3` are one clip. */
function normalizeClipPath(path: string): string {
    return path.replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/{2,}/g, '/');
}

const hostSuspensions = new WeakMap<AudioAPI, { owners: Set<object>; sync(): void }>();

/** Internal host suspension, preserving explicit Audio.suspend/resume intent. */
export function setAudioHostSuspended(audio: AudioAPI, owner: object, suspended: boolean): void {
    const state = hostSuspensions.get(audio);
    if (!state) return;
    if (suspended) state.owners.add(owner); else state.owners.delete(owner);
    state.sync();
}

/**
 * One authored reference's residency record. Mirrors the texture pool's
 * three-state lifecycle: held (refCount > 0, pinned by Assets) →
 * evictable (refCount 0, warm cache bounded by the byte budget) →
 * evicted (backend buffer freed; a future load re-fetches).
 */
interface BufferEntry {
    handle: AudioBufferHandle;
    source: SharedAudioBuffer;
    /** Assets-held references. Direct play/preload entries stay at 0. */
    refCount: number;
}

interface SharedAudioBuffer {
    url: string;
    loading: Promise<AudioBufferHandle>;
    handle?: AudioBufferHandle;
    aliases: Set<string>;
    requests: Set<string>;
    charged: boolean;
}

interface PendingAudioBuffer {
    promise: Promise<void>;
    source: SharedAudioBuffer;
}

/** Buffer residency counters. See {@link AudioAPI.getBufferStats}. */
export interface AudioBufferStats {
    /** Authored cache entries; aliases can share one decoded allocation. */
    bufferCount: number;
    /** Unique decoded bytes resident (held + evictable entries). */
    bufferBytes: number;
    /** The effective byte budget (0 = warm cache off). */
    bufferBudget: number;
    /** Warm-cache entries (refCount 0) awaiting revive or eviction. */
    evictableCount: number;
    /** Clips played from their compressed file instead of being decoded (unique, not per alias). */
    streamedCount: number;
    /** The PCM those clips did not take, estimated from their length: what `bufferBytes` would be if they were decoded. */
    streamedSavedBytes: number;
}

/**
 * Per-app audio API. Each `App` owns an `AudioAPI` instance (created by
 * `AudioPlugin.build()`), exposed via the `Audio` resource.
 *
 * Consumed as a resource: declare `Res(Audio)` as a system param or
 * grab it with `app.getResource(Audio)` outside ECS code.
 */
/** A playing voice this API owns the volume of: base × bus gain × fade. */
/**
 * How many voices sound at once before `priority` decides. Beyond a couple of
 * dozen a listener hears loudness, not sounds, and a phone pays for every one.
 */
const DEFAULT_MAX_VOICES = 32;

/** The answer to "play this" when the pool is full and this voice lost: a handle
 *  that behaves like one whose sound already ended, so no caller special-cases it. */
function silentHandle(): AudioHandle {
    return {
        id: 0,
        stop() {}, pause() {}, resume() {},
        setVolume() {}, setPan() {}, setLoop() {}, setPlaybackRate() {},
        get isPlaying() { return false; },
        get currentTime() { return 0; },
        get duration() { return 0; },
    };
}

interface SoftVoice {
    handle: AudioHandle;
    publicHandle?: AudioHandle;
    paused: boolean;
    retired?: boolean;
    bus: string;
    base: number;
    fade: number;
    /** What this voice is worth when the pool is full — higher survives. */
    priority: number;
    /** Play order. A counter, not a clock: "older" has to be answered the same
     *  way twice for a test to pin the rule down, and two voices started in one
     *  frame share a timestamp. */
    seq: number;
}

/** One volume ramp in flight: a linear interpolation the frame loop advances. */
interface Fade {
    voice: SoftVoice;
    /** Fade FACTORS (0..1), multiplied onto the voice's base volume. */
    from: number;
    to: number;
    duration: number;
    elapsed: number;
    /** A fade-out stops its track when it reaches silence. */
    stopAtEnd: boolean;
}

/**
 * A piece of music playing as its layers: each a clip of the same length, begun on the same sample and going round
 * together, each with a level of its own that can be brought up or down while it plays. The drums come in when the
 * fight starts and the melody goes when the player is hiding, and it is one piece of music throughout.
 */
export interface MusicLayers {
    readonly names: readonly string[];
    /**
     * False where the layers could not be kept in step and the whole piece is playing in their place (a mini-game, a
     * clip played from its compressed file): {@link setLayer} then changes nothing that is heard.
     */
    readonly layered: boolean;
    /** The layers began on one sample and stay together. False where they were started one after another for want of a way to do better. */
    readonly inStep: boolean;
    /** Bring one layer to @p level, 0..1, over @p seconds (default 1; 0 is at once). */
    setLayer(name: string, level: number, seconds?: number): void;
    /** Where a layer is now, on its way or arrived. */
    layerLevel(name: string): number;
    stop(fadeOut?: number): void;
    readonly isPlaying: boolean;
}

export interface MusicLayersConfig {
    /**
     * The whole piece as one clip, played where the layers cannot be kept in step. Layers that drift are worse than no
     * layers: a mini-game plays each clip through a player of its own, and so does a clip played from its compressed
     * file. Without it the layers are started one after another there, and a warning says so.
     */
    mix?: string;
    volume?: number;
    /** Where each layer starts, 0..1. A layer not named starts at 1. */
    levels?: Readonly<Record<string, number>>;
    fadeIn?: number;
    crossFade?: number;
    /** As for playBGM: seconds every layer comes back to at its end, for a piece with an introduction. */
    loopStart?: number;
}

/** The layers of the music that is playing. */
interface LayerGroup {
    names: string[];
    voices: Map<string, AudioHandle>;
    levels: Map<string, number>;
    targets: Map<string, number>;
    /** Level a second each layer moves at toward its target. */
    rates: Map<string, number>;
    volume: number;
    stopped: boolean;
    layered: boolean;
    inStep: boolean;
}

/**
 * How a clip made from a recipe is loaded: decoded whole. What was made is a plain .wav under a path that names no recording, so the
 * length rule that plays a long file from a media element would hand it bytes with no type to go by; and a loop that is decoded
 * comes round on the sample, which a piece of music made to loop is for.
 */
const RECIPE_LOAD: AudioLoadOptions = { loadType: 'decompress' };

export class AudioAPI {
    private readonly voiceStates_ = new WeakMap<AudioHandle, SoftVoice>();
    private readonly playbackStops_ = new Set<(generation: number) => void>();
    private readonly backend_: PlatformAudioBackend;
    private readonly mixer_: AudioMixer | null;
    private readonly bufferCache_ = new Map<string, BufferEntry>();
    private readonly loadingBuffers_ = new Map<string, PendingAudioBuffer>();
    private readonly bufferSources_ = new Map<string, SharedAudioBuffer>();
    /** refCount==0 urls in eviction order (oldest first); access re-appends. */
    private readonly evictOrder_ = new Set<string>();
    /** Urls a play is waiting on, by how many: not evictable until that play has started. */
    private readonly awaitingPlay_ = new Map<string, number>();
    /** Clips already reported as larger than the whole budget. */
    private readonly oversizeReported_ = new Set<string>();
    private residentBytes_ = 0;
    private bufferBudgetOverride_: number | null = null;
    /** Importer choices by authored path; a clip with none is `auto`. */
    private loadTypes_ = new Map<string, AudioLoadType>();
    private encoded_ = new Map<string, AudioClipTrim>();
    private bgmHandle_: AudioHandle | null = null;
    /** The music that is playing, where it is playing as layers. One or the other, never both. */
    private bgmGroup_: LayerGroup | null = null;
    private layersWarned_ = false;
    private bgmRequest_ = 0;
    private playbackEpoch_ = 0;
    private bgmVolume_ = 1.0;
    /** Volume ramps in flight, advanced by {@link updateFades} from the frame
     *  loop — NOT by requestAnimationFrame, which is a browser global a device
     *  does not have (and which would keep ramping while the game is paused). */
    private readonly fades_: Fade[] = [];

    /**
     * Bus volume / mute for a backend with no mixer GRAPH (a device, WeChat):
     * the mixer's gain nodes are one way to apply a bus, not the meaning of one,
     * so where there are no nodes the gain is folded into each voice instead —
     * at play, and again on every voice already playing when a bus changes. The
     * mixer stays authoritative wherever it exists.
     */
    private readonly softBuses_ = new Map<string, { volume: number; muted: boolean }>();
    /** Voices whose volume this API computes: base × bus gain × fade. */
    private softVoices_: SoftVoice[] = [];
    /**
     * How many voices may sound at once. There has to be a ceiling for
     * `priority` to mean anything: without one nothing is ever dropped, and the
     * field only describes an ordering that never happens.
     */
    private maxVoices_ = DEFAULT_MAX_VOICES;
    private voiceSeq_ = 0;
    // Handles mid fade-out. A cancelled fade RAF never reaches its handle.stop(),
    // so a rapid crossfade would orphan the outgoing track (playing forever) —
    // {@link cancelFades_} stops these when it tears the animations down.
    private readonly fadingOut_ = new Set<AudioHandle>();
    private disposed_ = false;
    private suspended_ = false;
    private deviceSuspended_ = false;
    private assetResolver_: ((url: string) => ArrayBuffer | null) | null = null;
    private refResolver_: ((ref: string) => string) | null = null;
    baseUrl = '';

    constructor(backend: PlatformAudioBackend, mixer: AudioMixer | null = null) {
        this.backend_ = backend;
        this.mixer_ = mixer;
        hostSuspensions.set(this, { owners: new Set(), sync: () => this.syncHostSuspension_() });
    }

    /** What this platform's backend needs in order to play a clip — asked by the
     *  asset loader, so a `url` backend is not made to wait on a fetch whose
     *  bytes it then drops. See {@link AudioDelivery}. */
    get delivery(): AudioDelivery {
        return this.backend_.delivery;
    }

    // =========================================================================
    // Buffer residency (held → evictable → evicted)
    // =========================================================================

    /** The effective warm-cache byte budget: an explicit override, else the
     *  live `RuntimeConfig.audioCacheBudget` (so build-config changes apply
     *  without plumbing). 0 disables the warm cache — a buffer is freed the
     *  moment its refCount reaches 0. */
    get bufferBudget(): number {
        return this.bufferBudgetOverride_ ?? RuntimeConfig.audioCacheBudget;
    }

    /** Override the warm-cache byte budget; `null` returns to RuntimeConfig. */
    setBufferBudget(bytes: number | null): void {
        this.bufferBudgetOverride_ = bytes === null ? null : Math.max(0, Math.floor(bytes));
        this.enforceBudget_();
    }

    /**
     * Pin a cached buffer: refCount + 1 (reviving an evictable entry back to
     * held). Returns false on a miss — the caller must load and re-acquire.
     * Every retain needs a matching {@link releaseBuffer}.
     */
    retainBuffer(url: string): boolean {
        const entry = this.bufferCache_.get(url);
        if (!entry) return false;
        entry.refCount++;
        this.evictOrder_.delete(url);
        return true;
    }

    /**
     * Unpin a buffer. At refCount 0 it becomes an evictable warm-cache entry
     * (bounded by {@link bufferBudget}) — still instantly playable and
     * revivable by {@link retainBuffer} — or is freed outright when the
     * budget is 0.
     */
    releaseBuffer(url: string): void {
        const entry = this.bufferCache_.get(url);
        if (!entry || entry.refCount === 0) return;
        if (--entry.refCount === 0) {
            if (this.bufferBudget === 0) {
                this.freeBuffer_(url, entry);
            } else {
                this.evictOrder_.add(url);
                this.enforceBudget_();
            }
        }
    }

    /** End cached and pending loads for changed source bytes. Playing sources
     *  keep their decoded data; later loads fetch fresh. Returns whether a load ended. */
    invalidateBuffer(url: string): boolean {
        const entry = this.bufferCache_.get(url);
        let source = entry?.source ?? this.loadingBuffers_.get(url)?.source;
        if (!source) {
            try { source = this.bufferSources_.get(this.resolveUrl_(url)); } catch { return false; }
        }
        if (!source) return false;
        this.backend_.invalidateSource?.(source.url);
        if (this.bufferSources_.get(source.url) === source) this.bufferSources_.delete(source.url);
        for (const alias of source.requests) {
            if (this.loadingBuffers_.get(alias)?.source === source) this.loadingBuffers_.delete(alias);
        }
        for (const alias of [...source.aliases]) {
            const cached = this.bufferCache_.get(alias);
            if (cached?.source === source) this.freeBuffer_(alias, cached);
        }
        this.releaseSource_(source);
        return true;
    }

    /**
     * Free every evictable warm-cache buffer now (memory pressure). Held
     * buffers and the budget are untouched; the cache refills as buffers are
     * released afterwards. Returns the number of unique decoded buffers freed.
     */
    trimBufferCache(): number {
        let freed = 0;
        for (const url of [...this.evictOrder_]) {
            const entry = this.bufferCache_.get(url);
            if (entry && this.freeBuffer_(url, entry)) freed++;
        }
        return freed;
    }

    /**
     * How each clip the importer was told about is held. Keyed by the clip's project-relative path, the way
     * the asset loader and `play` address it; anything absent is `auto`. A clip already loaded keeps how it
     * was loaded until it is reloaded.
     */
    setLoadTypes(types: Readonly<Record<string, AudioLoadType>> | null): void {
        this.loadTypes_ = new Map(Object.entries(types ?? {}).map(([path, type]) => [normalizeClipPath(path), type]));
    }

    /**
     * What the exporter's encoding did to each clip, keyed as {@link setLoadTypes} is. A clip named here is played
     * from past the silence encoding put before it and ended or looped at its real length. A clip already loaded
     * keeps how it was loaded.
     */
    setEncodedClips(clips: Readonly<Record<string, AudioClipTrim>> | null): void {
        this.encoded_ = new Map(Object.entries(clips ?? {}).map(([path, trim]) => [normalizeClipPath(path), trim]));
    }

    private loadOptions_(url: string): AudioLoadOptions | undefined {
        const key = normalizeClipPath(url);
        const [loadType, trim] = [this.loadTypes_.get(key), this.encoded_.get(key)];
        return loadType || trim ? { ...(loadType ? { loadType } : {}), ...(trim ? { trim } : {}) } : undefined;
    }

    /** Buffer residency counters — the observability side of the budget. */
    getBufferStats(): AudioBufferStats {
        const seen = new Set<SharedAudioBuffer>();
        let streamedCount = 0;
        let streamedSavedBytes = 0;
        for (const entry of this.bufferCache_.values()) {
            if (!entry.handle.streamed || seen.has(entry.source)) continue;
            seen.add(entry.source);
            streamedCount++;
            streamedSavedBytes += entry.handle.savedBytes ?? 0;
        }
        return {
            streamedCount, streamedSavedBytes,
            bufferCount: this.bufferCache_.size,
            bufferBytes: this.residentBytes_,
            bufferBudget: this.bufferBudget,
            evictableCount: this.evictOrder_.size,
        };
    }

    /** Register a decoded buffer as an evictable warm-cache entry. The budget
     *  is enforced against the OLD warm entries before the new one joins the
     *  eviction pool — mirroring the C++ pool's add(), where a just-created
     *  resource can't be the one evicted to make room for itself (a caller
     *  about to pin or play it would find it already gone). */
    private insertEntry_(url: string, handle: AudioBufferHandle, source: SharedAudioBuffer): void {
        const entry: BufferEntry = { handle, source, refCount: 0 };
        this.bufferCache_.set(url, entry);
        source.aliases.add(url);
        if (!source.charged) {
            source.charged = true;
            this.residentBytes_ += handle.bytes ?? 0;
            this.reportOversize_(url, handle);
            this.enforceBudget_();
        }
        this.evictOrder_.add(url);
    }

    /**
     * A clip that is larger than the whole budget cannot be kept warm: making room for it empties the cache,
     * and the next clip to load evicts it in turn, so it is decoded again every time it is played. Nothing
     * about that is visible from the game — the sound just starts late, or not at all — so it is said once.
     */
    private reportOversize_(url: string, handle: AudioBufferHandle): void {
        const bytes = handle.bytes ?? 0;
        const budget = this.bufferBudget;
        if (budget === 0 || bytes <= budget || this.oversizeReported_.has(url)) return;
        this.oversizeReported_.add(url);
        const mb = (n: number): string => (n / (1024 * 1024)).toFixed(1);
        log.warn('audio', `${url} takes ${mb(bytes)} MB decoded, more than the whole ${mb(budget)} MB audio cache `
            + '(audioCacheBudget): it is dropped as soon as another clip loads and decoded again on its next play. '
            + "Set its import to 'streaming', or raise the budget");
    }

    /** Cache lookup for playback: refreshes the LRU position of an evictable
     *  entry so frequently-played warm sounds aren't the first to go. */
    private lookupBuffer_(url: string): AudioBufferHandle | undefined {
        const entry = this.bufferCache_.get(url);
        if (!entry) return undefined;
        if (entry.refCount === 0 && this.evictOrder_.delete(url)) {
            this.evictOrder_.add(url);
        }
        return entry.handle;
    }

    private freeBuffer_(url: string, entry: BufferEntry): boolean {
        if (this.bufferCache_.get(url) !== entry) return false;
        this.bufferCache_.delete(url);
        this.evictOrder_.delete(url);
        const source = entry.source;
        source.aliases.delete(url);
        if (source.aliases.size === 0 && source.charged) {
            source.charged = false;
            this.residentBytes_ -= entry.handle.bytes ?? 0;
        }
        return this.releaseSource_(source);
    }

    private releaseSource_(source: SharedAudioBuffer): boolean {
        if (source.aliases.size || source.requests.size) return false;
        if (this.bufferSources_.get(source.url) === source) this.bufferSources_.delete(source.url);
        const handle = source.handle;
        source.handle = undefined;
        if (handle) this.backend_.unloadBuffer(handle);
        return !!handle;
    }

    /** Evict oldest warm-cache entries until resident bytes fit the budget.
     *  Held (refCount > 0) entries are never evicted. */
    private enforceBudget_(): void {
        const budget = this.bufferBudget;
        if (budget === 0) return;
        for (const url of this.evictOrder_) {
            if (this.residentBytes_ <= budget) break;
            // A play is about to start on it: evicting it now is a sound that never happens.
            if (this.awaitingPlay_.has(url)) continue;
            const entry = this.bufferCache_.get(url);
            if (entry) this.freeBuffer_(url, entry);
        }
    }

    setAssetResolver(resolver: (url: string) => ArrayBuffer | null): void {
        this.assetResolver_ = resolver;
    }

    /**
     * Route play refs through the realm's single asset resolver — the same
     * channel every other asset type resolves through (uuid manifest, cooked
     * logical→staged maps, project base). Takes precedence over the legacy
     * `baseUrl` prefix, so `playSFX('assets/…')` works in cooked builds whose
     * content-addressed staging renamed the physical files.
     */
    setRefResolver(resolver: ((ref: string) => string) | null): void {
        this.refResolver_ = resolver;
    }

    private resolveUrl_(url: string): string {
        if (this.refResolver_) return this.refResolver_(url);
        if (!this.baseUrl || url.startsWith('/') || url.startsWith('http://') || url.startsWith('https://')) {
            return url;
        }
        return `${this.baseUrl}/${url}`;
    }

    /** Coalesce authored requests through their captured physical source. */
    private async ensureBuffer_(
        url: string, load: (source: string) => Promise<AudioBufferHandle>, sourceUrl?: string,
    ): Promise<void> {
        if (this.disposed_) return;
        if (this.bufferCache_.has(url)) return;
        // De-dupe concurrent loads of the same url — without this, two preloads
        // (esp. the loadBufferFromData path, which has no backend-side dedup)
        // both decode and orphan one AudioBuffer.
        const inFlight = this.loadingBuffers_.get(url);
        if (inFlight) return inFlight.promise;
        const resolved = sourceUrl ?? this.resolveUrl_(url);
        let source = this.bufferSources_.get(resolved);
        let start: (() => void) | undefined;
        if (!source) {
            let accept!: (buffer: AudioBufferHandle) => void, reject!: (error: unknown) => void;
            source = {
                url: resolved, aliases: new Set(), requests: new Set(), charged: false,
                loading: new Promise<AudioBufferHandle>((resolve, fail) => { accept = resolve; reject = fail; }),
            };
            const owned = source;
            this.bufferSources_.set(resolved, owned);
            start = () => {
                try {
                    void Promise.resolve(load(resolved)).then(buffer => { owned.handle = buffer; accept(buffer); }, reject);
                } catch (error) { reject(error); }
            };
        }
        const shared = source;
        shared.requests.add(url);
        let receipt!: PendingAudioBuffer;
        const promise = (async () => {
            try {
                const buffer = await shared.loading;
                if (this.disposed_ || this.loadingBuffers_.get(url) !== receipt) return;
                if (!this.bufferCache_.has(url)) this.insertEntry_(url, buffer, shared);
            } finally {
                if (this.loadingBuffers_.get(url) === receipt) this.loadingBuffers_.delete(url);
                shared.requests.delete(url);
                this.releaseSource_(shared);
            }
        })();
        receipt = { promise, source: shared };
        this.loadingBuffers_.set(url, receipt);
        // Install both ownership records before a backend can reenter the API.
        start?.();
        await promise;
    }

    /**
     * The `.wav` of a clip that is a recipe (an `.essound`, an `.esmusic`): its source read as any clip is, by the resolver that
     * holds a package's inlined files or from where the path resolves to, and made by `esengine/sound` (see asset/audioRecipe.ts).
     */
    private recipeClip_(url: string, resolved: string, given?: ArrayBuffer): Promise<ArrayBuffer> {
        return renderAudioRecipe(url, async (path) => {
            if (path === url && given) return given;
            const held = this.assetResolver_?.(path);
            if (held) return held;
            return getPlatform().readFile(path === url ? resolved : this.resolveUrl_(path));
        });
    }

    async preload(url: string): Promise<void> {
        if (this.disposed_ || this.bufferCache_.has(url)) return;
        if (isAudioRecipePath(url)) {
            // Made, then handed to the backend as the bytes of a file, which every backend that decodes already reads.
            await this.ensureBuffer_(url, async source => this.backend_.loadBufferFromData(source, await this.recipeClip_(url, source), RECIPE_LOAD));
            return;
        }
        if (this.assetResolver_) {
            const data = this.assetResolver_(url);
            if (data) {
                return this.preloadFromData(url, data);
            }
        }
        const options = this.loadOptions_(url);
        await this.ensureBuffer_(url, source => (options ? this.backend_.loadBuffer(source, options) : this.backend_.loadBuffer(source)));
    }

    /**
     * Load `url` for a play that is waiting on it and start that play, as one step: the clip cannot be
     * evicted between arriving and being played, which is what a load finishing beside it used to do to a
     * clip larger than the budget. Says so when the clip is not there to play after all, instead of the
     * silence that left a game with no music and nothing in its log.
     */
    private async loadThenPlay_(url: string, what: string, play: (buffer: AudioBufferHandle) => void): Promise<void> {
        this.awaitingPlay_.set(url, (this.awaitingPlay_.get(url) ?? 0) + 1);
        try {
            await this.preload(url);
            if (this.disposed_) return;
            const buffer = this.lookupBuffer_(url);
            if (buffer) play(buffer);
            else log.warn('audio', `${what} did not play: ${url} loaded, but was gone from the audio cache before it could start`);
        } catch (err) {
            log.warn('audio', `Failed to preload ${what}: ${url}`, err);
        } finally {
            const left = (this.awaitingPlay_.get(url) ?? 1) - 1;
            if (left > 0) this.awaitingPlay_.set(url, left);
            else this.awaitingPlay_.delete(url);
        }
    }

    async preloadAll(urls: string[]): Promise<void> {
        await Promise.all(urls.map(url => this.preload(url)));
    }

    /**
     * Cache `url`'s clip from bytes the caller already holds. `url` is the
     * AUTHORED path this API is addressed by (the key `retainBuffer` and
     * `getBufferHandle` take); the backend is handed the RESOLVED source, which
     * for a `url`-delivery backend is the only thing it plays.
     */
    async preloadFromData(url: string, data: ArrayBuffer): Promise<void> {
        if (isAudioRecipePath(url)) {
            // The bytes of a recipe are its source, not a recording: handed to a decoder they are refused, and the clip was silent.
            await this.ensureBuffer_(url, async source => this.backend_.loadBufferFromData(source, await this.recipeClip_(url, source, data), RECIPE_LOAD));
            return;
        }
        const options = this.loadOptions_(url);
        await this.ensureBuffer_(url, source => (options
            ? this.backend_.loadBufferFromData(source, data, options) : this.backend_.loadBufferFromData(source, data)));
    }

    /**
     * Play a fully-RESOLVED clip URL on an explicit bus (created on demand
     * under master). Unlike playSFX/playBGM this applies no ref resolution —
     * the caller already holds the final URL (the video system's audio track
     * derives it from the resolved video source). Null when the clip can't
     * load; loaded buffers share the residency cache.
     */
    async playTrack(url: string, config: PlayConfig = {}): Promise<AudioHandle | null> {
        if (this.disposed_) return null;
        const epoch = this.playbackEpoch_;
        try {
            await this.ensureBuffer_(url, source => this.backend_.loadBuffer(source), url);
        } catch {
            return null;
        }
        if (this.disposed_ || epoch !== this.playbackEpoch_) return null;
        const buffer = this.lookupBuffer_(url);
        if (!buffer) return null;
        if (config.bus) this.ensureBus(config.bus);
        return this.playVoice_(buffer, config);
    }

    playSFX(url: string, config?: {
        volume?: number;
        pitch?: number;
        pan?: number;
        priority?: number;
    }): AudioHandle {
        const epoch = this.playbackEpoch_;
        const playConfig = {
            bus: 'sfx',
            volume: config?.volume,
            playbackRate: config?.pitch,
            pan: config?.pan,
            priority: config?.priority ?? 0,
        };
        const buffer = this.lookupBuffer_(url);
        if (!buffer) {
            const pending = this.createDeferredHandle_(playConfig.volume ?? 1);
            void this.loadThenPlay_(url, 'audio', buf => {
                if (epoch !== this.playbackEpoch_ || pending.cancelled) return;
                pending.resolve(overrides => this.playVoice_(buf, { ...playConfig, ...overrides }));
            });
            return pending;
        }
        return this.playVoice_(buffer, playConfig);
    }

    /**
     * Background music: one piece at a time, round and round. `fadeIn` brings it up over that many seconds and
     * `crossFade` brings it up as the piece before goes down. `loopStart` is for a piece with an introduction:
     * the file plays from its top once, and each time it reaches its end it comes back to that many seconds in,
     * so the introduction is heard once and what follows it goes round.
     */
    playBGM(url: string, config?: {
        volume?: number;
        fadeIn?: number;
        crossFade?: number;
        loopStart?: number;
    }): void {
        const request = ++this.bgmRequest_;
        const play = (buffer: AudioBufferHandle) => {
            if (this.disposed_ || request !== this.bgmRequest_) return;
            this.cancelFades_();

            const targetVolume = config?.volume ?? 1.0;
            const oldVolume = this.bgmVolume_;
            this.bgmVolume_ = targetVolume;

            this.retireMusic_(config?.crossFade, oldVolume);
            const fadeInDuration = config?.fadeIn ?? config?.crossFade;

            this.bgmHandle_ = this.playVoice_(buffer, {
                bus: 'music',
                volume: targetVolume,
                loop: true,
                ...(config?.loopStart && config.loopStart > 0 ? { loopStart: config.loopStart } : {}),
            });

            if (fadeInDuration) {
                this.fadeIn_(this.bgmHandle_, fadeInDuration, targetVolume);
            }
        };

        const buffer = this.lookupBuffer_(url);
        if (buffer) {
            play(buffer);
        } else {
            void this.loadThenPlay_(url, 'BGM', play);
        }
    }

    /** What was playing as music goes: at once, or down over @p fade seconds. Its layers go with it. */
    private retireMusic_(fade: number | undefined, volume: number): void {
        const out = (handle: AudioHandle, from: number): void => {
            if (fade && fade > 0) this.fadeOut_(handle, fade, from);
            else handle.stop();
        };
        if (this.bgmHandle_) out(this.bgmHandle_, volume);
        this.bgmHandle_ = null;
        const group = this.bgmGroup_;
        this.bgmGroup_ = null;
        if (group) {
            group.stopped = true;
            for (const [name, handle] of group.voices) out(handle, group.volume * (group.levels.get(name) ?? 1));
        }
    }

    /**
     * Background music as layers: every clip begun on the same sample and looping together, each with a level of its
     * own. `layers` names them, `{ drums: 'a_drums.wav', melody: 'a_melody.wav' }`, and they must be as long as one
     * another, which the stems of one piece are. It takes the place of whatever music was playing, as playBGM does,
     * and stopBGM ends it.
     *
     * Layers are only music while they are in step. Where the backend decodes its clips they are, to the sample; where
     * it cannot promise it and `mix` names the whole piece as one clip, that plays instead.
     */
    playLayers(layers: Readonly<Record<string, string>>, config: MusicLayersConfig = {}): MusicLayers {
        const request = ++this.bgmRequest_;
        const names = Object.keys(layers);
        const level = (v: number | undefined): number => Math.max(0, Math.min(1, v ?? 1));
        const group: LayerGroup = {
            names, voices: new Map(), rates: new Map(), volume: config.volume ?? 1, stopped: false, layered: true, inStep: true,
            levels: new Map(names.map((n) => [n, level(config.levels?.[n])])),
            targets: new Map(names.map((n) => [n, level(config.levels?.[n])])),
        };
        const api = this;

        const start = (): void => {
            if (this.disposed_ || request !== this.bgmRequest_ || group.stopped) return;
            const buffers = names.map((n) => this.lookupBuffer_(layers[n]!));
            if (buffers.some((b) => !b)) {
                log.warn('audio', `music layers did not play: ${names.filter((_, i) => !buffers[i]).join(', ')} loaded, but gone from the audio cache before they could start`);
                return;
            }
            // In step where each clip is decoded and the backend starts voices on a clock; not where each is a player of its own.
            const inStep = this.backend_.delivery === 'bytes' && buffers.every((b) => !b!.streamed);
            if (!inStep && config.mix) {
                group.layered = false;
                group.inStep = false;
                this.playBGM(config.mix, { volume: group.volume, fadeIn: config.fadeIn, crossFade: config.crossFade, loopStart: config.loopStart });
                return;
            }
            if (!inStep && !this.layersWarned_) {
                this.layersWarned_ = true;
                log.warn('audio', 'music layers cannot be kept in step here (clips are played from their files); they are started one after another and may drift. Give playLayers a `mix` to play the whole piece instead');
            }
            this.cancelFades_();
            const oldVolume = this.bgmVolume_;
            this.bgmVolume_ = group.volume;
            this.retireMusic_(config.crossFade, oldVolume);
            // What was asked of a layer before it began is where it begins.
            for (const n of names) group.levels.set(n, group.targets.get(n)!);
            const together = {};
            const fadeIn = config.fadeIn ?? config.crossFade;
            names.forEach((name, i) => {
                const volume = group.volume * group.levels.get(name)!;
                const handle = this.playVoice_(buffers[i]!, {
                    bus: 'music', volume, loop: true, together,
                    ...(config.loopStart && config.loopStart > 0 ? { loopStart: config.loopStart } : {}),
                });
                group.voices.set(name, handle);
                if (fadeIn) this.fadeIn_(handle, fadeIn, volume);
            });
            group.inStep = inStep;
            this.bgmGroup_ = group;
        };

        const missing = names.filter((n) => !this.lookupBuffer_(layers[n]!));
        if (missing.length === 0) start();
        else {
            void Promise.all(missing.map((n) => this.preload(layers[n]!)))
                .then(start, (err) => log.warn('audio', `Failed to preload music layers: ${missing.map((n) => layers[n]).join(', ')}`, err));
        }

        return {
            names,
            get layered() { return group.layered; },
            get inStep() { return group.inStep; },
            setLayer(name, to, seconds = 1) {
                if (!group.targets.has(name)) return;
                const target = level(to);
                group.targets.set(name, target);
                const from = group.levels.get(name)!;
                if (!(seconds > 0) || group.voices.size === 0) {
                    group.levels.set(name, target);
                    group.rates.delete(name);
                    api.applyLayer_(group, name);
                } else group.rates.set(name, Math.abs(target - from) / seconds);
            },
            layerLevel(name) { return group.levels.get(name) ?? 0; },
            stop(fadeOut) {
                group.stopped = true;
                // Only if it is still the music: a piece that has since been replaced is not stopped a second time.
                if (api.bgmGroup_ === group || (!group.layered && request + 1 === api.bgmRequest_)) api.stopBGM(fadeOut);
            },
            get isPlaying() {
                if (!group.layered) return api.bgmHandle_?.isPlaying ?? false;
                for (const handle of group.voices.values()) if (handle.isPlaying) return true;
                return false;
            },
        };
    }

    /** A layer's level written to its voice: the piece's volume times the layer's own. */
    private applyLayer_(group: LayerGroup, name: string): void {
        const handle = group.voices.get(name);
        const voice = handle && this.voiceStates_.get(handle);
        if (!voice) return;
        voice.base = group.volume * group.levels.get(name)!;
        if (voice.paused || voice.handle.isPlaying) this.applyVoice_(voice);
    }

    stopAll(): void {
        this.bgmRequest_++;
        const generation = ++this.playbackEpoch_;
        const voices = this.softVoices_;
        this.softVoices_ = [];
        this.bgmHandle_ = null;
        if (this.bgmGroup_) this.bgmGroup_.stopped = true;
        this.bgmGroup_ = null;
        this.fades_.length = 0;
        this.fadingOut_.clear();
        const stopped = new Set<AudioHandle>();
        const actions: Array<() => void> = [];
        for (const voice of voices) {
            voice.paused = false; voice.retired = true;
            if (!stopped.has(voice.handle)) {
                stopped.add(voice.handle);
                actions.push(() => voice.handle.stop());
            }
        }
        for (const callback of this.playbackStops_) actions.push(() => callback(generation));
        disposeAll(actions, action => action());
    }

    /** @internal Generation boundary for pending playback intents. */
    get playbackGeneration(): number { return this.playbackEpoch_; }

    /** @internal Terminal and paused ownership comes from the global voice pool. */
    getVoiceState(handle: AudioHandle): 'playing' | 'paused' | 'ended' | 'stopped' | 'untracked' {
        const voice = this.voiceStates_.get(handle);
        if (!voice) return 'untracked';
        if (voice.retired) return 'stopped';
        return voice.paused ? 'paused' : voice.handle.isPlaying ? 'playing' : 'ended';
    }

    /** @internal Stop pending consumers after every old backend voice was stopped. */
    onPlaybackStop(callback: (generation: number) => void): () => void {
        this.playbackStops_.add(callback);
        return () => { this.playbackStops_.delete(callback); };
    }

    stopBGM(fadeOut?: number): void {
        this.bgmRequest_++;
        if (!this.bgmHandle_ && !this.bgmGroup_) {
            if (!(fadeOut && fadeOut > 0)) this.cancelFades_();
            return;
        }
        this.cancelFades_();
        this.retireMusic_(fadeOut, this.bgmVolume_);
    }

    /**
     * Suspend the whole audio device (every voice, every bus) without touching
     * any volume the user set — the device-level pause a fullscreen takeover
     * (a rewarded ad, an OS interruption) wants, where per-bus volumes would
     * fight the mixer's own state. Balanced by {@link resume}.
     */
    suspend(): void {
        this.backend_.suspend();
        this.suspended_ = true;
        this.deviceSuspended_ = true;
    }

    /** Resume the audio device after {@link suspend}. */
    resume(): void {
        this.suspended_ = false;
        if (!hostSuspensions.get(this)?.owners.size) {
            this.backend_.resume(); this.deviceSuspended_ = false;
        }
    }

    private syncHostSuspension_(): void {
        const suspended = this.suspended_ || !!hostSuspensions.get(this)?.owners.size;
        if (this.disposed_ || suspended === this.deviceSuspended_) return;
        this.deviceSuspended_ = suspended;
        if (suspended) this.backend_.suspend(); else this.backend_.resume();
    }

    setMasterVolume(volume: number): void {
        if (this.mixer_) {
            this.mixer_.master.volume = volume;
            return;
        }
        this.setSoftBus_('master', { volume });
    }

    setMusicVolume(volume: number): void {
        if (this.mixer_) {
            this.mixer_.music.volume = volume;
            return;
        }
        this.setSoftBus_('music', { volume });
    }

    setSFXVolume(volume: number): void {
        if (this.mixer_) {
            this.mixer_.sfx.volume = volume;
            return;
        }
        this.setSoftBus_('sfx', { volume });
    }

    setUIVolume(volume: number): void {
        if (this.mixer_) {
            this.mixer_.ui.volume = volume;
            return;
        }
        this.setSoftBus_('ui', { volume });
    }

    /** Mixerless backends (WeChat/Null) report unity volume and unmuted —
     *  the read-side mirror of the volume setters' silent no-op there. */
    getMasterVolume(): number {
        return this.mixer_?.master.volume ?? 1;
    }

    getMusicVolume(): number {
        return this.mixer_?.music.volume ?? 1;
    }

    getSFXVolume(): number {
        return this.mixer_?.sfx.volume ?? 1;
    }

    getUIVolume(): number {
        return this.mixer_?.ui.volume ?? 1;
    }

    /** Unity (1) for an unknown bus. */
    getBusVolume(busName: string): number {
        if (this.mixer_) return this.mixer_.getBus(busName)?.volume ?? 1;
        return this.softBuses_.get(busName)?.volume ?? 1;
    }

    isBusMuted(busName: string): boolean {
        if (this.mixer_) return this.mixer_.getBus(busName)?.muted ?? false;
        return this.softBuses_.get(busName)?.muted ?? false;
    }

    /** Record a bus change for a mixerless backend and push it to live voices —
     *  what a gain node would have done to the tracks already playing. */
    private setSoftBus_(busName: string, change: { volume?: number; muted?: boolean }): void {
        const bus = this.softBuses_.get(busName) ?? { volume: 1, muted: false };
        if (change.volume !== undefined) bus.volume = change.volume;
        if (change.muted !== undefined) bus.muted = change.muted;
        this.softBuses_.set(busName, bus);
        this.applyBus_(busName);
    }

    /** The gain a mixerless backend folds into a voice: its bus, times master. */
    private softGain_(busName: string): number {
        if (this.mixer_) return 1;   // the graph already applies it
        const gainOf = (name: string): number => {
            const bus = this.softBuses_.get(name);
            if (!bus) return 1;
            return bus.muted ? 0 : bus.volume;
        };
        return busName === 'master' ? gainOf('master') : gainOf(busName) * gainOf('master');
    }

    /** Push a voice's computed volume to the backend. */
    private applyVoice_(voice: SoftVoice): void {
        voice.handle.setVolume(voice.base * this.softGain_(voice.bus) * voice.fade);
    }

    /** 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.paused || v.handle.isPlaying || this.fadeOf_(v) !== null);
        for (const voice of this.softVoices_) {
            if (busName === 'master' || voice.bus === busName) this.applyVoice_(voice);
        }
    }

    private fadeOf_(voice: SoftVoice): Fade | null {
        return this.fades_.find((f) => f.voice === voice) ?? null;
    }

    /** Play through the backend as a tracked voice, so bus gain and fades have
     *  one place to act — on every platform, mixer graph or not. */
    /**
     * Play an already-resolved buffer. The one door every voice comes through —
     * a scripted `playSFX`, a `playBGM`, an `AudioSource` in the scene — so the
     * bus gain a backend without a mixer graph cannot apply, and the voice cap
     * `priority` is measured against, are decided once for all of them.
     */
    playBuffer(buffer: AudioBufferHandle, config?: PlayConfig): AudioHandle {
        if (config?.bus) this.ensureBus(config.bus);
        return this.playVoice_(buffer, config ?? {});
    }

    /** The voice ceiling; 0 or less means no cap. @see playBuffer */
    setMaxVoices(max: number): void {
        this.maxVoices_ = Number.isFinite(max) ? Math.floor(max) : DEFAULT_MAX_VOICES;
    }

    get maxVoices(): number { return this.maxVoices_; }

    private playVoice_(buffer: AudioBufferHandle, config: PlayConfig): AudioHandle {
        if (this.disposed_) return silentHandle();
        const bus = config.bus ?? 'sfx';
        const base = config.volume ?? 1;
        const priority = config.priority ?? 0;
        if (!this.makeRoomForVoice_(priority)) return silentHandle();
        const handle = this.backend_.play(buffer, { ...config, volume: base * this.softGain_(bus) });
        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() { if (!voice.retired) { voice.retired = true; 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.voiceStates_.set(managed, voice);
        this.softVoices_.push(voice);
        return managed;
    }

    /**
     * Drop the least valuable voice if the pool is full, so a new one of
     * @p priority can sound. False when the new voice is the least valuable
     * itself. Ties go to the OLDER voice, which is what keeps a repeated sound
     * audible: every shot of a machine gun is worth the same.
     */
    private makeRoomForVoice_(priority: number): boolean {
        this.softVoices_ = this.softVoices_.filter(
            (v) => v.paused || v.handle.isPlaying || this.fadeOf_(v) !== null,
        );
        if (this.maxVoices_ <= 0 || this.softVoices_.length < this.maxVoices_) return true;

        let weakest: SoftVoice | null = null;
        for (const v of this.softVoices_) {
            if (!weakest || v.priority < weakest.priority
                || (v.priority === weakest.priority && v.seq < weakest.seq)) {
                weakest = v;
            }
        }
        if (!weakest || weakest.priority > priority) return false;
        weakest.paused = false;
        weakest.retired = true;
        weakest.handle.stop();
        this.softVoices_ = this.softVoices_.filter((v) => v !== weakest);
        return true;
    }

    muteBus(busName: string, muted: boolean): void {
        if (!this.mixer_) {
            this.setSoftBus_(busName, { muted });
            return;
        }
        const bus = this.mixer_.getBus(busName);
        if (bus) {
            bus.muted = muted;
        }
    }

    /**
     * Whether this backend has a mixer graph at all. @experimental
     *
     * The fact behind every `false` the bus calls below return, reported once so a
     * reader does not have to infer a capability from a failed write. Without one,
     * {@link applyAudioProjectConfig} applies `maxVoices` and stops before the bus
     * list — so an authored mixer is not partly applied, it is not applied.
     */
    hasMixerGraph(): boolean {
        return this.mixer_ !== null;
    }

    /** Ensure a named bus exists (creating it under `parent` ?? master).
     *  False on backends without a mixer graph. */
    ensureBus(name: string, parent?: string): boolean {
        if (!this.mixer_) return false;
        if (!this.mixer_.getBus(name)) {
            this.mixer_.createBus({ name, ...(parent ? { parent } : {}) });
        }
        return true;
    }

    setBusVolume(busName: string, volume: number): void {
        if (!this.mixer_) {
            this.setSoftBus_(busName, { volume });
            return;
        }
        const bus = this.mixer_.getBus(busName);
        if (bus) {
            bus.volume = volume;
        }
    }

    /** Replace a bus's DSP insert chain. No-op (false) on backends without a
     *  WebAudio graph (WeChat/Null) — same degradation as the volume APIs. */
    setBusEffects(busName: string, effects: BusEffectDef[]): boolean {
        const bus = this.mixer_?.getBus(busName);
        if (!bus) return false;
        bus.setEffects(effects);
        return true;
    }

    getBusEffects(busName: string): BusEffectDef[] {
        return this.mixer_?.getBus(busName)?.effects ?? [];
    }

    /** Install (or clear with null) sidechain ducking on `target` — e.g. duck
     *  'music' to 30% while 'voice' carries signal. */
    setBusDucking(target: string, rule: BusDuckRule | null): boolean {
        return this.mixer_?.setDucking(target, rule) ?? false;
    }

    getBusDucking(target: string): BusDuckRule | null {
        return this.mixer_?.getDucking(target) ?? null;
    }

    /** Advance duck envelopes (driven per-frame by AudioUpdateSystem). */
    updateDucking(): void {
        this.mixer_?.updateDucking();
    }

    getBufferHandle(url: string): AudioBufferHandle | undefined {
        return this.lookupBuffer_(url);
    }

    /** Fill `out` with the master output's frequency spectrum (0-255 per bin,
     *  low→high) for visualizers. Returns false on backends without analysis
     *  (e.g. WeChat) — callers should treat that as silence. */
    getSpectrum(out: Uint8Array): boolean {
        return this.backend_.getFrequencyData?.(out) ?? false;
    }

    dispose(): void {
        this.disposed_ = true;
        // Scripted effects and AudioSource voices also belong to this device.
        // Closing a Web Audio context alone leaves their handles marked playing,
        // and a different backend may require explicit stops before disposal.
        disposeAll([() => this.stopAll(), () => this.playbackStops_.clear(), () => {
            this.loadingBuffers_.clear();
            try { disposeAll([...this.bufferCache_], ([url, entry]) => { this.freeBuffer_(url, entry); }); }
            finally { this.bufferCache_.clear(); this.bufferSources_.clear(); this.evictOrder_.clear(); this.residentBytes_ = 0; }
        }, () => this.backend_?.dispose()], action => action());
    }

    /**
     * Advance every fade by `dt` seconds — called once a frame by the audio
     * system, which is what makes a fade the game's clock rather than the
     * browser's: it pauses when the game does, and it exists on a device.
     */
    updateFades(dt: number): void {
        if (this.suspended_ || !(dt > 0)) return;
        // The layers of the music, each on its way to where it was last told to be.
        const group = this.bgmGroup_;
        if (group && group.rates.size > 0) {
            for (const [name, rate] of group.rates) {
                const [now, target] = [group.levels.get(name)!, group.targets.get(name)!];
                const next = now < target ? Math.min(target, now + rate * dt) : Math.max(target, now - rate * dt);
                group.levels.set(name, next);
                if (next === target) group.rates.delete(name);
                this.applyLayer_(group, name);
            }
        }
        if (this.fades_.length === 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) {
                if (fade.stopAtEnd) {
                    fade.voice.handle.stop();
                    this.fadingOut_.delete(fade.voice.publicHandle ?? fade.voice.handle);
                }
                this.fades_.splice(i, 1);
            }
        }
    }

    private fadeIn_(handle: AudioHandle, duration: number, targetVolume: number): void {
        const voice = this.voiceOf_(handle, targetVolume, 'music');
        voice.base = targetVolume;
        voice.fade = 0;
        this.applyVoice_(voice);
        this.fades_.push({ voice, from: 0, to: 1, duration, elapsed: 0, stopAtEnd: false });
    }

    /** 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 || v.publicHandle === handle);
        if (found) return found;
        const voice: SoftVoice = { handle, bus, base, fade: 1, paused: false, priority: 0, seq: this.voiceSeq_++ };
        this.softVoices_.push(voice);
        return voice;
    }

    /** Cancel every in-flight fade AND stop the tracks that were fading out — a
     *  cancelled fade would otherwise never reach their `stop()`. */
    private cancelFades_(): void {
        this.fades_.length = 0;
        for (const h of this.fadingOut_) h.stop();
        this.fadingOut_.clear();
    }

    private fadeOut_(handle: AudioHandle, duration: number, startVolume: number): void {
        this.fadingOut_.add(handle);
        const voice = this.voiceOf_(handle, startVolume, 'music');
        this.fades_.push({ voice, from: voice.fade, to: 0, duration, elapsed: 0, stopAtEnd: true });
    }

    private createDeferredHandle_(baseVolume: number): AudioHandle & {
        readonly cancelled: boolean;
        resolve(start: (overrides: PlayConfig) => AudioHandle): void;
    } {
        let real: AudioHandle | null = null;
        let stopped = false, paused = false, endAssigned = false;
        let ended: (() => void) | undefined;
        const overrides: PlayConfig = {};
        return {
            get id() { return real?.id ?? -1; },
            get cancelled() { return stopped; },
            stop() { if (!stopped) { stopped = true; real?.stop(); } },
            pause() { if (!stopped) { paused = true; real?.pause(); } },
            resume() { if (!stopped) { paused = false; real?.resume(); } },
            setVolume(v) { if (!stopped) { overrides.volume = v; real?.setVolume(v); } },
            setPan(p) { if (!stopped) { overrides.pan = p; real?.setPan(p); } },
            setLoop(l) { if (!stopped) { overrides.loop = l; real?.setLoop(l); } },
            setPlaybackRate(r) { if (!stopped) { overrides.playbackRate = r; real?.setPlaybackRate(r); } },
            get isPlaying() { return real?.isPlaying ?? false; },
            get currentTime() { return real?.currentTime ?? 0; },
            get duration() { return real?.duration ?? 0; },
            get onEnd() { return real ? real.onEnd : ended; },
            set onEnd(callback) {
                ended = callback;
                endAssigned = true;
                if (real) real.onEnd = callback;
            },
            resolve(start) {
                if (stopped || real) return;
                const next = start(paused ? { ...overrides, volume: 0 } : overrides);
                if (stopped) { next.stop(); return; }
                real = next;
                if (endAssigned) real.onEnd = ended;
                if (paused) {
                    real.pause();
                    real.setVolume(overrides.volume ?? baseVolume);
                }
            },
        };
    }
}

/** Resource handle for the per-app audio API. */
/**
 * Playback, buses and mixing, as `Res(Audio)` hands it over.
 *
 * `@beta`: a certified run now drives a loop and reads the master bus's analyser,
 * so a break here is noticed — but the corpus reaches a handful of twenty-three
 * audio symbols, which is thin evidence for freezing the shape.
 *
 * @beta
 */
export const Audio = defineResource<AudioAPI>(null!, 'Audio');