@datamoc/mw_games 0.17.1 → 0.18.0

package/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to `mwg` are documented here. Format follows
 [Semantic Versioning](https://semver.org/) as of this first release - a 0.y.z version means
 the public API may still change between minor versions.
 
+## [0.18.0] - 2026-09-25
+
+### Added
+
+- `audio.parseMidi` keeps program-change, control-change and pitch-bend events and reports
+  the controller-111 loop marker as `loopStartTick`; `scheduleMidi` notes carry their channel
+  voice (`MidiVoice`: program, bank, gain, pan) and `midiLoopStart` resolves the marker to seconds.
+- `audio.renderMidiToBuffer` renders a parsed MIDI file to stereo PCM frames, offline and
+  deterministic, voiced by an optional game-supplied `SoundFont` or the built-in waveform
+  synth, with the loop region attached.
+- `audio.parseSoundFont` reads SoundFont 2 bytes into layered preset voices.
+- `audio.Channel` (a seekable buffered WebAudio voice with volume, pitch, pan and a loop
+  region) and `audio.AudioBus` (independent BGM/BGS loops, ME jingles that suspend and resume
+  the BGM, overlapping SE one-shots, save and replay with playheads, plain-data snapshots).
 ## [0.17.1] - 2026-09-25
 
 ### Fixed

package/dist/audio/Channels.d.ts

@@ -0,0 +1,198 @@
+/**
+ * Buffered WebAudio voices for music and jingles: a `Channel` plays one looping track
+ * with volume, pitch, pan, a loop region and a seekable playhead, and an `AudioBus`
+ * wires channels into the four lifetimes a role-playing game needs from its audio.
+ * BGM and BGS are two independent looping streams, ME is an interrupting jingle that
+ * pauses the BGM and resumes it where it left off, SE is overlapping one-shots, each
+ * with its own volume, pitch and pan per play.
+ *
+ * The browser owns the clock and the nodes, so both classes take the pieces they
+ * cannot build themselves as injectables: the `AudioContext` in the constructor and,
+ * for the bus, a `load` function turning a kind and a name into a decoded buffer.
+ * Tests hand in fakes for both, the same way `Sound` and `Music` take `create()`.
+ */
+/** seconds within a buffer: the region a looping track repeats */
+export interface LoopRegion {
+    start: number;
+    end: number;
+}
+export interface ChannelPlayOptions {
+    /** level, 0 to 1 */
+    volume?: number;
+    /** playback ratio, 1 unchanged, above 1 higher and faster */
+    pitch?: number;
+    /** stereo position, -1 (left) to 1 (right) */
+    pan?: number;
+    /** start offset in seconds */
+    pos?: number;
+    /** region to repeat, null repeats the whole buffer */
+    loop?: LoopRegion | null;
+    /** false plays once through for jingles; true repeats */
+    repeat?: boolean;
+}
+/** plain-data playback state: parameters plus playhead, without the buffer */
+export interface ChannelState {
+    volume: number;
+    pitch: number;
+    pan: number;
+    pos: number;
+}
+/**
+ * One buffered voice: a decoded track with a loop region and a playhead the game can
+ * read and move. Replaying the same buffer restarts it; changing parameters mid-play
+ * never does.
+ *
+ * @example
+ * ```ts
+ * import { Channel } from '@datamoc/mw_games/audio';
+ *
+ * declare const context: AudioContext;
+ * declare const buffer: AudioBuffer;
+ *
+ * const channel = new Channel(context);
+ * channel.play(buffer, { volume: 0.8, pitch: 1, pan: 0, loop: { start: 1, end: 4 } });
+ * console.log(channel.position());
+ * channel.stop();
+ * ```
+ */
+export declare class Channel {
+    private readonly context;
+    private readonly destination;
+    private source;
+    private gainNode;
+    private pannerNode;
+    private buffer;
+    private params;
+    private loopRegion;
+    private repeat;
+    private startedAt;
+    private offset;
+    constructor(context: AudioContext, destination?: AudioNode);
+    get isPlaying(): boolean;
+    get duration(): number;
+    /** starts the buffer with these parameters, stopping whatever played before */
+    play(buffer: AudioBuffer, options?: ChannelPlayOptions): void;
+    /** retunes the playing voice in place: no restart, no seek */
+    update(params: {
+        volume?: number;
+        pitch?: number;
+        pan?: number;
+    }): void;
+    /** stops the voice, fading out over `fadeSeconds` first when positive */
+    stop(fadeSeconds?: number): void;
+    /** seconds into the buffer, wrapping inside the loop region while it repeats */
+    position(): number;
+    /** moves the playhead, restarting the voice when it plays */
+    seek(pos: number): void;
+    /** plain-data state for saves and transfers: parameters plus playhead */
+    state(): ChannelState;
+    /** applies plain-data state, restarting the voice at its playhead when it plays */
+    restore(state: ChannelState): void;
+    private clearNodes;
+}
+export type BusKind = 'bgm' | 'bgs' | 'me' | 'se';
+/**
+ * A named track request in role-playing units: volume 0 to 100, pitch 50 to 150
+ * percent, pan -100 to 100, an optional resume position in seconds.
+ */
+export interface BusTrack {
+    name: string;
+    volume?: number;
+    pitch?: number;
+    pan?: number;
+    pos?: number;
+}
+/** a resolved track request: every parameter filled in, ready to store or restore */
+export interface SavedBusTrack {
+    name: string;
+    volume: number;
+    pitch: number;
+    pan: number;
+    pos: number;
+}
+/** a decoded track: its buffer plus the region it repeats, if any */
+export interface LoadedTrack {
+    buffer: AudioBuffer;
+    loop?: LoopRegion | null;
+}
+/** turns a kind and a name into a decoded buffer, or null when it cannot */
+export type BusLoader = (kind: BusKind, name: string) => Promise<LoadedTrack | null>;
+/** plain-data bus state for saves and transfers: tracks plus memorized ones */
+export interface BusSnapshot {
+    bgm: SavedBusTrack | null;
+    bgs: SavedBusTrack | null;
+    savedBgm: SavedBusTrack | null;
+    savedBgs: SavedBusTrack | null;
+}
+export interface AudioBusOptions {
+    destination?: AudioNode;
+    load?: BusLoader;
+}
+/**
+ * The four audio lifetimes of a role-playing game over two `Channel` voices: BGM and
+ * BGS loop independently, an ME jingle suspends the BGM and resumes it where it left
+ * off, SE plays overlapping one-shots. Replaying the current track only retunes it;
+ * save and replay memorize a track with its playhead for menus and transfers.
+ *
+ * @example
+ * ```ts
+ * import { AudioBus } from '@datamoc/mw_games/audio';
+ *
+ * declare const context: AudioContext;
+ *
+ * const bus = new AudioBus(context, { load: (_kind, _name) => Promise.resolve(null) });
+ * void bus.playBgm({ name: 'town', volume: 90, pitch: 100, pan: 0 });
+ * console.log(bus.snapshot());
+ * ```
+ */
+export declare class AudioBus {
+    private readonly context;
+    private readonly destination;
+    private readonly load;
+    private readonly bgmChannel;
+    private readonly bgsChannel;
+    private readonly tracks;
+    private readonly saved;
+    private readonly requests;
+    private me;
+    private meToken;
+    private suspendedBgm;
+    private readonly seNodes;
+    constructor(context: AudioContext, options?: AudioBusOptions);
+    /** loops this BGM, or retunes it when it already loops */
+    playBgm(track: BusTrack): Promise<void>;
+    /** loops this BGS, or retunes it when it already loops */
+    playBgs(track: BusTrack): Promise<void>;
+    stopBgm(): void;
+    stopBgs(): void;
+    fadeOutBgm(seconds?: number): void;
+    fadeOutBgs(seconds?: number): void;
+    /** the intended track with its live playhead, or the one an ME suspended */
+    currentTrack(kind: 'bgm' | 'bgs'): SavedBusTrack | null;
+    /** memorizes the playing BGM with its playhead; replay restores it */
+    saveBgm(): SavedBusTrack | null;
+    /** memorizes the playing BGS with its playhead; replay restores it */
+    saveBgs(): SavedBusTrack | null;
+    replayBgm(): Promise<void>;
+    replayBgs(): Promise<void>;
+    /**
+     * Plays a jingle once, suspending the BGM and resuming it where it left off when
+     * the jingle ends. A BGM started mid-jingle takes over instead of being resumed over.
+     */
+    playMe(track: BusTrack): Promise<void>;
+    /** stops the jingle, resuming the suspended BGM unless told not to */
+    stopMe(resume?: boolean): void;
+    /** plays one overlapping sound effect */
+    playSe(track: BusTrack): Promise<void>;
+    stopSe(): void;
+    stopAll(): void;
+    /** plain-data bus state for saves and transfers */
+    snapshot(): BusSnapshot;
+    /** replays plain-data bus state, reloading every named track */
+    restore(state: BusSnapshot | null | undefined): void;
+    private static normalize;
+    private playLoop;
+    private stopMeNodes;
+    private finishMe;
+}
+//# sourceMappingURL=Channels.d.ts.map

package/dist/audio/Channels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Channels.d.ts","sourceRoot":"","sources":["../../src/audio/Channels.ts"],"names":[],"mappings":"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"}

package/dist/audio/Channels.js

@@ -0,0 +1,456 @@
+/**
+ * Buffered WebAudio voices for music and jingles: a `Channel` plays one looping track
+ * with volume, pitch, pan, a loop region and a seekable playhead, and an `AudioBus`
+ * wires channels into the four lifetimes a role-playing game needs from its audio.
+ * BGM and BGS are two independent looping streams, ME is an interrupting jingle that
+ * pauses the BGM and resumes it where it left off, SE is overlapping one-shots, each
+ * with its own volume, pitch and pan per play.
+ *
+ * The browser owns the clock and the nodes, so both classes take the pieces they
+ * cannot build themselves as injectables: the `AudioContext` in the constructor and,
+ * for the bus, a `load` function turning a kind and a name into a decoded buffer.
+ * Tests hand in fakes for both, the same way `Sound` and `Music` take `create()`.
+ */
+/** one wired voice: a buffer source through a gain and an optional stereo panner */
+function wireVoice(context, destination, buffer, volume, pitch, pan) {
+    const source = context.createBufferSource();
+    source.buffer = buffer;
+    source.playbackRate.value = pitch;
+    const gain = context.createGain();
+    gain.gain.value = volume;
+    let panner = null;
+    if (typeof context.createStereoPanner === 'function') {
+        panner = context.createStereoPanner();
+        panner.pan.value = pan;
+        source.connect(gain);
+        gain.connect(panner);
+        panner.connect(destination);
+    }
+    else {
+        source.connect(gain);
+        gain.connect(destination);
+    }
+    return { source, gain, panner };
+}
+/**
+ * One buffered voice: a decoded track with a loop region and a playhead the game can
+ * read and move. Replaying the same buffer restarts it; changing parameters mid-play
+ * never does.
+ *
+ * @example
+ * ```ts
+ * import { Channel } from '@datamoc/mw_games/audio';
+ *
+ * declare const context: AudioContext;
+ * declare const buffer: AudioBuffer;
+ *
+ * const channel = new Channel(context);
+ * channel.play(buffer, { volume: 0.8, pitch: 1, pan: 0, loop: { start: 1, end: 4 } });
+ * console.log(channel.position());
+ * channel.stop();
+ * ```
+ */
+export class Channel {
+    constructor(context, destination) {
+        this.source = null;
+        this.gainNode = null;
+        this.pannerNode = null;
+        this.buffer = null;
+        this.params = { volume: 1, pitch: 1, pan: 0 };
+        this.loopRegion = null;
+        this.repeat = true;
+        this.startedAt = 0;
+        this.offset = 0;
+        this.context = context;
+        this.destination = destination ?? context.destination;
+    }
+    get isPlaying() {
+        return this.source !== null;
+    }
+    get duration() {
+        return this.buffer?.duration ?? 0;
+    }
+    /** starts the buffer with these parameters, stopping whatever played before */
+    play(buffer, options = {}) {
+        this.stop();
+        const volume = options.volume ?? 1;
+        const pitch = options.pitch ?? 1;
+        const pan = options.pan ?? 0;
+        const { source, gain, panner } = wireVoice(this.context, this.destination, buffer, volume, pitch, pan);
+        const loop = options.loop ?? null;
+        const repeat = options.repeat ?? true;
+        source.loop = repeat;
+        if (loop) {
+            source.loopStart = loop.start;
+            source.loopEnd = loop.end;
+        }
+        if (!repeat) {
+            const started = source;
+            source.onended = () => {
+                if (this.source === started)
+                    this.clearNodes();
+            };
+        }
+        this.source = source;
+        this.gainNode = gain;
+        this.pannerNode = panner;
+        this.buffer = buffer;
+        this.params = { volume, pitch, pan };
+        this.loopRegion = loop;
+        this.repeat = repeat;
+        this.offset = Math.min(Math.max(0, options.pos ?? 0), Math.max(0, buffer.duration - 0.001));
+        this.startedAt = this.context.currentTime;
+        source.start(0, this.offset);
+    }
+    /** retunes the playing voice in place: no restart, no seek */
+    update(params) {
+        if (params.volume !== undefined)
+            this.params.volume = params.volume;
+        if (params.pitch !== undefined)
+            this.params.pitch = params.pitch;
+        if (params.pan !== undefined)
+            this.params.pan = params.pan;
+        if (!this.source || !this.gainNode)
+            return;
+        const now = this.context.currentTime;
+        this.gainNode.gain.setTargetAtTime(this.params.volume, now, 0.02);
+        this.source.playbackRate.value = this.params.pitch;
+        if (this.pannerNode)
+            this.pannerNode.pan.value = this.params.pan;
+    }
+    /** stops the voice, fading out over `fadeSeconds` first when positive */
+    stop(fadeSeconds = 0) {
+        const resumeAt = this.position();
+        const source = this.source;
+        const gain = this.gainNode;
+        this.clearNodes();
+        this.offset = resumeAt;
+        if (!source)
+            return;
+        try {
+            if (fadeSeconds > 0 && gain) {
+                const now = this.context.currentTime;
+                gain.gain.cancelScheduledValues(now);
+                gain.gain.setValueAtTime(gain.gain.value, now);
+                gain.gain.linearRampToValueAtTime(0, now + fadeSeconds);
+                source.stop(now + fadeSeconds + 0.02);
+            }
+            else {
+                source.stop();
+            }
+        }
+        catch {
+            //already stopped
+        }
+    }
+    /** seconds into the buffer, wrapping inside the loop region while it repeats */
+    position() {
+        if (!this.source || !this.buffer)
+            return this.offset;
+        const elapsed = Math.max(0, this.context.currentTime - this.startedAt) * this.params.pitch;
+        let pos = this.offset + elapsed;
+        if (this.repeat && this.duration > 0) {
+            const start = this.loopRegion?.start ?? 0;
+            const end = this.loopRegion?.end ?? this.buffer.duration;
+            if (end > start && pos >= end)
+                pos = start + ((pos - start) % (end - start));
+        }
+        return pos;
+    }
+    /** moves the playhead, restarting the voice when it plays */
+    seek(pos) {
+        this.restore({ ...this.state(), pos });
+    }
+    /** plain-data state for saves and transfers: parameters plus playhead */
+    state() {
+        return { ...this.params, pos: this.position() };
+    }
+    /** applies plain-data state, restarting the voice at its playhead when it plays */
+    restore(state) {
+        const buffer = this.buffer;
+        this.update({ volume: state.volume, pitch: state.pitch, pan: state.pan });
+        if (buffer && this.source) {
+            this.play(buffer, {
+                volume: state.volume,
+                pitch: state.pitch,
+                pan: state.pan,
+                pos: state.pos,
+                loop: this.loopRegion,
+                repeat: this.repeat,
+            });
+        }
+        else {
+            this.offset = Math.max(0, state.pos);
+        }
+    }
+    clearNodes() {
+        if (this.source)
+            this.source.onended = null;
+        this.source = null;
+        this.gainNode = null;
+        this.pannerNode = null;
+    }
+}
+function clampBus(value, low, high, fallback) {
+    const n = Number(value);
+    return Math.min(high, Math.max(low, Number.isFinite(n) ? n : fallback));
+}
+/**
+ * The four audio lifetimes of a role-playing game over two `Channel` voices: BGM and
+ * BGS loop independently, an ME jingle suspends the BGM and resumes it where it left
+ * off, SE plays overlapping one-shots. Replaying the current track only retunes it;
+ * save and replay memorize a track with its playhead for menus and transfers.
+ *
+ * @example
+ * ```ts
+ * import { AudioBus } from '@datamoc/mw_games/audio';
+ *
+ * declare const context: AudioContext;
+ *
+ * const bus = new AudioBus(context, { load: (_kind, _name) => Promise.resolve(null) });
+ * void bus.playBgm({ name: 'town', volume: 90, pitch: 100, pan: 0 });
+ * console.log(bus.snapshot());
+ * ```
+ */
+export class AudioBus {
+    constructor(context, options = {}) {
+        this.tracks = { bgm: null, bgs: null };
+        this.saved = { bgm: null, bgs: null };
+        this.requests = { bgm: 0, bgs: 0 };
+        this.me = null;
+        this.meToken = 0;
+        this.suspendedBgm = null;
+        this.seNodes = new Set();
+        this.context = context;
+        this.destination = options.destination ?? context.destination;
+        this.load = options.load ?? (async () => null);
+        this.bgmChannel = new Channel(context, this.destination);
+        this.bgsChannel = new Channel(context, this.destination);
+    }
+    /** loops this BGM, or retunes it when it already loops */
+    playBgm(track) {
+        return this.playLoop('bgm', track);
+    }
+    /** loops this BGS, or retunes it when it already loops */
+    playBgs(track) {
+        return this.playLoop('bgs', track);
+    }
+    stopBgm() {
+        this.requests.bgm++;
+        this.tracks.bgm = null;
+        this.suspendedBgm = null;
+        this.bgmChannel.stop();
+    }
+    stopBgs() {
+        this.requests.bgs++;
+        this.tracks.bgs = null;
+        this.bgsChannel.stop();
+    }
+    fadeOutBgm(seconds = 1) {
+        this.requests.bgm++;
+        this.tracks.bgm = null;
+        this.suspendedBgm = null;
+        this.bgmChannel.stop(Math.max(0, seconds));
+    }
+    fadeOutBgs(seconds = 1) {
+        this.requests.bgs++;
+        this.tracks.bgs = null;
+        this.bgsChannel.stop(Math.max(0, seconds));
+    }
+    /** the intended track with its live playhead, or the one an ME suspended */
+    currentTrack(kind) {
+        const track = this.tracks[kind];
+        if (track) {
+            const channel = kind === 'bgm' ? this.bgmChannel : this.bgsChannel;
+            return { ...track, pos: channel.isPlaying ? channel.position() : track.pos };
+        }
+        return kind === 'bgm' ? this.suspendedBgm : null;
+    }
+    /** memorizes the playing BGM with its playhead; replay restores it */
+    saveBgm() {
+        this.saved.bgm = this.currentTrack('bgm');
+        return this.saved.bgm;
+    }
+    /** memorizes the playing BGS with its playhead; replay restores it */
+    saveBgs() {
+        this.saved.bgs = this.currentTrack('bgs');
+        return this.saved.bgs;
+    }
+    replayBgm() {
+        if (!this.saved.bgm)
+            return Promise.resolve();
+        return this.playBgm(this.saved.bgm);
+    }
+    replayBgs() {
+        if (!this.saved.bgs)
+            return Promise.resolve();
+        return this.playBgs(this.saved.bgs);
+    }
+    /**
+     * Plays a jingle once, suspending the BGM and resuming it where it left off when
+     * the jingle ends. A BGM started mid-jingle takes over instead of being resumed over.
+     */
+    async playMe(track) {
+        const me = AudioBus.normalize(track);
+        const token = ++this.meToken;
+        this.stopMeNodes();
+        if (!me.name)
+            return;
+        const loaded = await this.load('me', me.name);
+        if (token !== this.meToken || !loaded)
+            return;
+        const remembered = this.currentTrack('bgm');
+        if (remembered) {
+            this.suspendedBgm = remembered;
+            this.requests.bgm++;
+            this.bgmChannel.stop();
+            this.tracks.bgm = null;
+        }
+        const { source } = wireVoice(this.context, this.destination, loaded.buffer, me.volume / 100, me.pitch / 100, me.pan / 100);
+        this.me = { source, token };
+        source.onended = () => {
+            if (this.me?.token === token)
+                this.finishMe();
+        };
+        source.start(0);
+    }
+    /** stops the jingle, resuming the suspended BGM unless told not to */
+    stopMe(resume = true) {
+        this.stopMeNodes();
+        if (resume)
+            this.finishMe();
+    }
+    /** plays one overlapping sound effect */
+    async playSe(track) {
+        const se = AudioBus.normalize(track);
+        if (!se.name)
+            return;
+        const loaded = await this.load('se', se.name);
+        if (!loaded)
+            return;
+        const { source } = wireVoice(this.context, this.destination, loaded.buffer, se.volume / 100, se.pitch / 100, se.pan / 100);
+        const node = { source };
+        this.seNodes.add(node);
+        source.onended = () => {
+            this.seNodes.delete(node);
+        };
+        source.start(0);
+    }
+    stopSe() {
+        for (const node of this.seNodes) {
+            node.source.onended = null;
+            try {
+                node.source.stop();
+            }
+            catch {
+                //already ended
+            }
+        }
+        this.seNodes.clear();
+    }
+    stopAll() {
+        this.requests.bgm++;
+        this.requests.bgs++;
+        this.tracks.bgm = null;
+        this.tracks.bgs = null;
+        this.suspendedBgm = null;
+        this.bgmChannel.stop();
+        this.bgsChannel.stop();
+        this.stopMeNodes();
+        this.stopSe();
+    }
+    /** plain-data bus state for saves and transfers */
+    snapshot() {
+        return {
+            bgm: this.currentTrack('bgm'),
+            bgs: this.currentTrack('bgs'),
+            savedBgm: this.saved.bgm,
+            savedBgs: this.saved.bgs,
+        };
+    }
+    /** replays plain-data bus state, reloading every named track */
+    restore(state) {
+        if (!state || typeof state !== 'object')
+            return;
+        this.saved.bgm = state.savedBgm ?? null;
+        this.saved.bgs = state.savedBgs ?? null;
+        if (state.bgm)
+            void this.playBgm(state.bgm);
+        if (state.bgs)
+            void this.playBgs(state.bgs);
+    }
+    static normalize(track) {
+        return {
+            name: String(track?.name || ''),
+            volume: clampBus(track?.volume, 0, 100, 90),
+            pitch: clampBus(track?.pitch, 10, 400, 100),
+            pan: clampBus(track?.pan, -100, 100, 0),
+            pos: Math.max(0, Number(track?.pos) || 0),
+        };
+    }
+    async playLoop(kind, input) {
+        const channel = kind === 'bgm' ? this.bgmChannel : this.bgsChannel;
+        const wanted = AudioBus.normalize(input);
+        if (!wanted.name) {
+            this.requests[kind]++;
+            this.tracks[kind] = null;
+            if (kind === 'bgm')
+                this.suspendedBgm = null;
+            channel.stop();
+            return;
+        }
+        const current = this.tracks[kind];
+        //Replaying the current track only retunes it, even while it still loads.
+        if (current && current.name === wanted.name && !(wanted.pos > 0)) {
+            this.tracks[kind] = { ...wanted, pos: 0 };
+            channel.update({ volume: wanted.volume / 100, pitch: wanted.pitch / 100, pan: wanted.pan / 100 });
+            return;
+        }
+        //A BGM requested mid-jingle replaces the suspended one instead of racing it.
+        if (kind === 'bgm' && this.me) {
+            this.requests.bgm++;
+            this.suspendedBgm = wanted;
+            this.tracks.bgm = null;
+            channel.stop();
+            return;
+        }
+        const request = ++this.requests[kind];
+        channel.stop();
+        this.tracks[kind] = { ...wanted, pos: 0 };
+        const loaded = await this.load(kind, wanted.name);
+        if (request !== this.requests[kind])
+            return;
+        if (!loaded) {
+            this.tracks[kind] = null;
+            return;
+        }
+        channel.play(loaded.buffer, {
+            volume: wanted.volume / 100,
+            pitch: wanted.pitch / 100,
+            pan: wanted.pan / 100,
+            pos: wanted.pos,
+            loop: loaded.loop ?? null,
+        });
+    }
+    stopMeNodes() {
+        const me = this.me;
+        this.me = null;
+        if (!me)
+            return;
+        me.source.onended = null;
+        try {
+            me.source.stop();
+        }
+        catch {
+            //already ended
+        }
+    }
+    finishMe() {
+        this.me = null;
+        const resume = this.suspendedBgm;
+        this.suspendedBgm = null;
+        if (resume && !this.tracks.bgm)
+            void this.playBgm(resume);
+    }
+}
+//# sourceMappingURL=Channels.js.map