@antha/audio 0.17.0 → 0.18.0

package/dist/antha-audio.mod.d.ts

@@ -1,4 +1,4 @@
-import { type PartialWithUndefined } from '@augment-vir/common';
+import { type EmptyFunction, type PartialWithUndefined } from '@augment-vir/common';
 import { AudioPlayer, type AudioPlayerOptions } from './audio-player.js';
 /**
  * State for {@link createAnthaAudioMod}.
@@ -7,13 +7,36 @@ import { AudioPlayer, type AudioPlayerOptions } from './audio-player.js';
  */
 export type AnthaAudioState = {
     audioPlayer: AudioPlayer;
-};
+} & PartialWithUndefined<{
+    audioResumeListenersCleanup: EmptyFunction;
+    audioChannelVolume: {
+        master: number;
+    } & PartialWithUndefined<{
+        channels: Record<string, number>;
+    }>;
+}>;
 /**
  * Options for {@link createAnthaAudioMod}.
  *
  * @category Internal
  */
 export type AnthaAudioModOptions = PartialWithUndefined<AudioPlayerOptions>;
+/**
+ * Resumes audio after a browser-recognized user interaction.
+ *
+ * @category Internal
+ */
+export declare function resumeAnthaAudioContext({ audioPlayer, }: Readonly<{
+    audioPlayer: AudioPlayer | undefined;
+}>): void;
+/**
+ * Attempts to resume audio when it becomes allowed due to the user inputs.
+ *
+ * @category Internal
+ */
+export declare function createAudioResumeListeners({ audioPlayer, }: Readonly<{
+    audioPlayer: AudioPlayer;
+}>): EmptyFunction;
 /**
  * A pre-built mod for playing audio files.
  *

package/dist/antha-audio.mod.js

@@ -1,5 +1,62 @@
 import { defineAnthaMod } from '@antha/engine';
+import { assertWrap, check } from '@augment-vir/assert';
+import { getObjectTypedEntries, } from '@augment-vir/common';
+import { listenToGlobal } from 'typed-event-target';
 import { AudioPlayer } from './audio-player.js';
+/**
+ * Resumes audio after a browser-recognized user interaction.
+ *
+ * @category Internal
+ */
+export function resumeAnthaAudioContext({ audioPlayer, }) {
+    void audioPlayer?.audioContext.resume().catch(() => { });
+}
+/**
+ * Attempts to resume audio when it becomes allowed due to the user inputs.
+ *
+ * @category Internal
+ */
+export function createAudioResumeListeners({ audioPlayer, }) {
+    let cleanup;
+    function resumeAudio() {
+        resumeAnthaAudioContext({
+            audioPlayer,
+        });
+        cleanup?.();
+        cleanup = undefined;
+    }
+    const cleanupCallbacks = [
+        listenToGlobal('click', resumeAudio, {
+            capture: true,
+        }),
+        listenToGlobal('keydown', resumeAudio, {
+            capture: true,
+        }),
+    ];
+    cleanup = () => {
+        cleanupCallbacks.forEach((cleanupCallback) => cleanupCallback());
+    };
+    return cleanup;
+}
+function syncChannelVolumes(state) {
+    if (!state.audioChannelVolume) {
+        state.audioChannelVolume = {
+            master: 1,
+            channels: {},
+        };
+    }
+    const audioPlayer = assertWrap.isDefined(state.audioPlayer);
+    const audioChannelVolume = state.audioChannelVolume;
+    if (!check.isApproximately(audioPlayer.gainNode.gain.value, audioChannelVolume.master, 0.00001)) {
+        audioPlayer.gainNode.gain.value = audioChannelVolume.master;
+    }
+    getObjectTypedEntries(audioPlayer.audioChannelNodes).forEach(([audioChannel, audioChannelNode,]) => {
+        const volume = audioChannelVolume.channels?.[audioChannel] ?? 1;
+        if (!check.isApproximately(audioChannelNode.gain.value, volume, 0.00001)) {
+            audioChannelNode.gain.value = volume;
+        }
+    });
+}
 /**
  * A pre-built mod for playing audio files.
  *
@@ -9,12 +66,21 @@ export function createAnthaAudioMod(audioPlayerOptions = {}) {
     return defineAnthaMod({
         modName: 'antha-audio',
         async cleanup({ state }) {
+            state.audioResumeListenersCleanup?.();
+            state.audioResumeListenersCleanup = undefined;
             await state.audioPlayer?.destroy();
         },
         execute({ state }) {
             if (!state.audioPlayer) {
                 state.audioPlayer = new AudioPlayer(audioPlayerOptions);
             }
+            syncChannelVolumes(state);
+            if (state.audioResumeListenersCleanup) {
+                return;
+            }
+            state.audioResumeListenersCleanup = createAudioResumeListeners({
+                audioPlayer: state.audioPlayer,
+            });
         },
     });
 }

package/dist/antha-background-audio.mod.d.ts

@@ -0,0 +1,28 @@
+import { type PartialWithUndefined } from '@augment-vir/common';
+import { type AnthaAudioState } from './antha-audio.mod.js';
+import { type AudioSetupParams } from './audio-player.js';
+/**
+ * State for {@link createAnthaBackgroundAudioMod}.
+ *
+ * @category Internal
+ */
+export type AnthaBackgroundAudioState = AnthaAudioState & PartialWithUndefined<{
+    currentBackgroundAudio: Readonly<AudioSetupParams>;
+}>;
+/**
+ * A mod that keeps track of a single background audio (music) file being played, and pauses the
+ * previous background audio when it gets switched. Control by setting
+ * state.currentBackgroundAudio.
+ *
+ * The background audio loops: it is played again each time it finishes. If the browser blocks
+ * playback until a user interaction, playback is retried once the audio context is running.
+ *
+ * @category Pre-Built Mods
+ */
+export declare function createAnthaBackgroundAudioMod(): import("@antha/engine").AnthaMod<NoInfer<AnthaBackgroundAudioState>>;
+/**
+ * The mod returned / created by {@link createAnthaBackgroundAudioMod}.
+ *
+ * @category Internal
+ */
+export type AnthaBackgroundAudioMod = ReturnType<typeof createAnthaBackgroundAudioMod>;

package/dist/antha-background-audio.mod.js

@@ -0,0 +1,63 @@
+import { defineAnthaMod } from '@antha/engine';
+import { log } from '@augment-vir/common';
+/**
+ * A mod that keeps track of a single background audio (music) file being played, and pauses the
+ * previous background audio when it gets switched. Control by setting
+ * state.currentBackgroundAudio.
+ *
+ * The background audio loops: it is played again each time it finishes. If the browser blocks
+ * playback until a user interaction, playback is retried once the audio context is running.
+ *
+ * @category Pre-Built Mods
+ */
+export function createAnthaBackgroundAudioMod() {
+    let lastPlayingBackgroundAudio;
+    /**
+     * Defined while `lastPlayingBackgroundAudio` should keep playing. Cleared if playback throws so
+     * a broken file isn't retried forever.
+     */
+    let pendingPlayback;
+    return defineAnthaMod({
+        modName: 'antha-background-audio-playback',
+        execute({ state }) {
+            if (!state.audioPlayer) {
+                return;
+            }
+            if (lastPlayingBackgroundAudio !== state.currentBackgroundAudio) {
+                if (lastPlayingBackgroundAudio) {
+                    state.audioPlayer.stopFile(lastPlayingBackgroundAudio);
+                }
+                lastPlayingBackgroundAudio = state.currentBackgroundAudio;
+                pendingPlayback = state.currentBackgroundAudio
+                    ? {
+                        isBlocked: false,
+                        isInFlight: false,
+                    }
+                    : undefined;
+            }
+            if (!lastPlayingBackgroundAudio ||
+                !pendingPlayback ||
+                pendingPlayback.isInFlight ||
+                (pendingPlayback.isBlocked && state.audioPlayer.audioContext.state !== 'running')) {
+                return;
+            }
+            const playback = pendingPlayback;
+            playback.isInFlight = true;
+            void state.audioPlayer
+                .play(lastPlayingBackgroundAudio)
+                /** `play` resolves once the audio finishes, so the next execute replays it. */
+                .then((didPlay) => {
+                playback.isBlocked = !didPlay;
+            })
+                .catch((error) => {
+                log.error(error);
+                if (pendingPlayback === playback) {
+                    pendingPlayback = undefined;
+                }
+            })
+                .finally(() => {
+                playback.isInFlight = false;
+            });
+        },
+    });
+}

package/dist/audio-file.d.ts

@@ -176,7 +176,10 @@ export type AudioPlayback = {
     deferredPlayPromise: DeferredPromise<boolean>;
     offsetSeconds: number;
     startedAt: number;
-};
+} & PartialWithUndefined<{
+    /** Cached channel input node for this playback. */
+    inputNode: AudioNode;
+}>;
 /**
  * Allows creating an array of `AudioNode` instances ("effects") by passing the given `AudioContext`
  * to `createEffects`. The effects created by `createEffects`, if any, are then sequentially
@@ -253,6 +256,10 @@ export declare class AudioFile extends ListenTarget<AllAudioFileEvents> {
     readonly gainNode: GainNode;
     readonly sourceKey: string;
     protected readonly activeBufferSources: Map<AudioBufferSourceNode, AudioPlayback>;
+    protected readonly audioChannelOutputNodeMap: Map<AudioNode, {
+        gainNode: GainNode;
+        inputNode: AudioNode;
+    }>;
     protected readonly pausedPlaybacks: Set<AudioPlayback>;
     constructor(params: AudioFileParams);
     /**
@@ -269,7 +276,10 @@ export declare class AudioFile extends ListenTarget<AllAudioFileEvents> {
      * @returns Whether or not the audio file was actually played. The audio file will not be played
      *   if audio is currently disabled.
      */
-    play(): Promise<boolean>;
+    play({ outputNode, }?: Readonly<PartialWithUndefined<{
+        /** Sets an output node different from the default one. */
+        outputNode: AudioNode;
+    }>>): Promise<boolean>;
     /** Stops every active playback while preserving the loaded audio buffer. */
     stop(): void;
     /** Pauses every active playback while preserving its current position. */

package/dist/audio-file.js

@@ -1,5 +1,5 @@
 import { assertWrap, check } from '@augment-vir/assert';
-import { clamp, DeferredPromise, ensureArray, ensureError, makeWritable, stringify, } from '@augment-vir/common';
+import { clamp, DeferredPromise, ensureArray, ensureError, getOrSetFromMap, makeWritable, stringify, } from '@augment-vir/common';
 import { defineTypedCustomEvent, defineTypedEvent, ListenTarget } from 'typed-event-target';
 import { isCodecSupported, isFileSupported } from './codecs.js';
 import { isPlayingEnabled } from './detect-play.js';
@@ -160,6 +160,7 @@ export class AudioFile extends ListenTarget {
     gainNode;
     sourceKey;
     activeBufferSources = new Map();
+    audioChannelOutputNodeMap = new Map();
     pausedPlaybacks = new Set();
     constructor(params) {
         super();
@@ -214,7 +215,7 @@ export class AudioFile extends ListenTarget {
      * @returns Whether or not the audio file was actually played. The audio file will not be played
      *   if audio is currently disabled.
      */
-    async play() {
+    async play({ outputNode, } = {}) {
         const audioBuffer = await this.load();
         if (!this.isAudioAllowed) {
             makeWritable(this).isAudioAllowed = await isPlayingEnabled(this.audioContext);
@@ -234,6 +235,24 @@ export class AudioFile extends ListenTarget {
             deferredPlayPromise: new DeferredPromise(),
             offsetSeconds: 0,
             startedAt: this.audioContext.currentTime,
+            ...(outputNode
+                ? {
+                    inputNode: getOrSetFromMap(this.audioChannelOutputNodeMap, outputNode, () => {
+                        const gainNode = this.audioContext.createGain();
+                        gainNode.gain.value = clamp(this.params.volume ?? 1, {
+                            min: 0,
+                            max: 1,
+                        });
+                        gainNode.connect(outputNode);
+                        const outputNodes = {
+                            gainNode,
+                            inputNode: setupEffects(this.audioContext, gainNode, this.params.createEffects).outputNode,
+                        };
+                        this.audioChannelOutputNodeMap.set(outputNode, outputNodes);
+                        return outputNodes;
+                    }).inputNode,
+                }
+                : {}),
         };
         this.startPlayback(playback);
         return playback.deferredPlayPromise.promise;
@@ -292,6 +311,13 @@ export class AudioFile extends ListenTarget {
                 delete this.audioCache[this.urlOrBase64];
             }
         }
+        this.audioChannelOutputNodeMap.forEach((outputNodes) => {
+            if (outputNodes.inputNode !== outputNodes.gainNode) {
+                outputNodes.inputNode.disconnect();
+            }
+            outputNodes.gainNode.disconnect();
+        });
+        this.audioChannelOutputNodeMap.clear();
         this.outputNode.disconnect();
         this.audioCache = {};
         this.loadPromise = undefined;
@@ -357,7 +383,7 @@ export class AudioFile extends ListenTarget {
     startPlayback(playback) {
         const bufferSource = this.audioContext.createBufferSource();
         bufferSource.buffer = playback.audioBuffer;
-        bufferSource.connect(this.outputNode);
+        bufferSource.connect(playback.inputNode ?? this.outputNode);
         playback.startedAt = this.audioContext.currentTime;
         this.activeBufferSources.set(bufferSource, playback);
         bufferSource.addEventListener('ended', () => {

package/dist/audio-player.d.ts

@@ -22,7 +22,12 @@ export type AudioLoadProgressCallback = (params: AudioLoadProgressCallbackParams
  *
  * @category Internal
  */
-export type AudioPlayerOptions = Pick<AudioFileParams, 'fetch' | 'volume' | 'createEffects'>;
+export type AudioPlayerOptions = Pick<AudioFileParams, 'fetch' | 'volume' | 'createEffects'> & PartialWithUndefined<{
+    /** Used to pre-populate audio channel gain nodes. The channel name mapped to its volume. */
+    initChannels: {
+        [ChannelName in string]: number;
+    };
+}>;
 /**
  * Inputs for playing audio.
  *
@@ -36,6 +41,8 @@ export type AudioSetupParams = Readonly<Pick<AudioFileParams, 'sources' | 'volum
  */
 export declare class AudioPlayer extends ListenTarget<AllAudioFileEvents> {
     protected readonly options: Readonly<PartialWithUndefined<AudioPlayerOptions>>;
+    /** Gain nodes for audio channels created by {@link AudioPlayer.play}. */
+    readonly audioChannelNodes: Record<string, GainNode>;
     readonly audioFiles: {
         [SourceKey in string]: AudioFile;
     };
@@ -52,8 +59,13 @@ export declare class AudioPlayer extends ListenTarget<AllAudioFileEvents> {
     /** Controls volume for all audio files. Modify `gain.value` on this to change playback volume. */
     readonly gainNode: GainNode;
     constructor(options?: Readonly<PartialWithUndefined<AudioPlayerOptions>>);
-    /** Play an audio file. */
-    play(params: Readonly<AudioSetupParams>): Promise<boolean>;
+    /** Plays audio, optionally routing this playback through a named channel. */
+    play({ audioChannel, ...audioSetup }: Readonly<AudioSetupParams & PartialWithUndefined<{
+        /** Routes this playback through a named channel gain node. */
+        audioChannel: string;
+    }>>): Promise<boolean>;
+    /** Gets a channel gain node, creating it with `volume` when necessary. */
+    protected getAudioChannelNode(audioChannel: string, volume: number): GainNode;
     /** Create a new {@link AudioFile} instance at the given `key` and set it up. */
     protected setupAudioFile(params: Readonly<AudioSetupParams>): AudioFile;
     /** Unloads all the attached files. */

package/dist/audio-player.js

@@ -1,4 +1,4 @@
-import { awaitedBlockingMap, clamp, getObjectTypedValues, makeWritable, } from '@augment-vir/common';
+import { awaitedBlockingMap, clamp, getObjectTypedEntries, getObjectTypedValues, getOrSet, makeWritable, } from '@augment-vir/common';
 import { ListenTarget } from 'typed-event-target';
 import { AudioFile, createAudioSourceKey, PlayingEnabledEvent, setupEffects, } from './audio-file.js';
 /**
@@ -8,6 +8,8 @@ import { AudioFile, createAudioSourceKey, PlayingEnabledEvent, setupEffects, } f
  */
 export class AudioPlayer extends ListenTarget {
     options;
+    /** Gain nodes for audio channels created by {@link AudioPlayer.play}. */
+    audioChannelNodes = {};
     audioFiles = {};
     audioContext = new AudioContext();
     audioCache = {};
@@ -31,10 +33,30 @@ export class AudioPlayer extends ListenTarget {
         });
         this.gainNode.connect(this.audioContext.destination);
         this.outputNode = setupEffects(this.audioContext, this.gainNode, options.createEffects).outputNode;
+        getObjectTypedEntries(options.initChannels || {}).forEach(([channelName, volume,]) => {
+            this.getAudioChannelNode(channelName, volume);
+        });
+    }
+    /** Plays audio, optionally routing this playback through a named channel. */
+    async play({ audioChannel, ...audioSetup }) {
+        const audioFile = this.setupAudioFile(audioSetup);
+        return audioChannel == undefined
+            ? audioFile.play()
+            : audioFile.play({
+                outputNode: this.getAudioChannelNode(audioChannel, 1),
+            });
     }
-    /** Play an audio file. */
-    async play(params) {
-        return this.setupAudioFile(params).play();
+    /** Gets a channel gain node, creating it with `volume` when necessary. */
+    getAudioChannelNode(audioChannel, volume) {
+        return getOrSet(this.audioChannelNodes, audioChannel, () => {
+            const audioChannelNode = this.audioContext.createGain();
+            audioChannelNode.gain.value = clamp(volume, {
+                min: 0,
+                max: 1,
+            });
+            audioChannelNode.connect(this.outputNode);
+            return audioChannelNode;
+        });
     }
     /** Create a new {@link AudioFile} instance at the given `key` and set it up. */
     setupAudioFile(params) {
@@ -157,6 +179,9 @@ export class AudioPlayer extends ListenTarget {
             await audioFile.destroy();
             delete this.audioCache[audioFile.sourceKey];
         }));
+        getObjectTypedValues(this.audioChannelNodes).forEach((audioChannelNode) => {
+            audioChannelNode.disconnect();
+        });
         await this.audioContext.close();
         this.isDestroyed = true;
     }

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from './antha-audio.mod.js';
+export * from './antha-background-audio.mod.js';
 export * from './audio-file.js';
 export * from './audio-player.js';
 export * from './codecs.js';

package/dist/index.js

@@ -1,4 +1,5 @@
 export * from './antha-audio.mod.js';
+export * from './antha-background-audio.mod.js';
 export * from './audio-file.js';
 export * from './audio-player.js';
 export * from './codecs.js';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@antha/audio",
-    "version": "0.17.0",
+    "version": "0.18.0",
     "description": "An Antha mod for handling audio.",
     "keywords": [
         "vir",
@@ -37,7 +37,7 @@
         "@augment-vir/common": "^32.3.0"
     },
     "devDependencies": {
-        "@antha/engine": "^0.17.0",
+        "@antha/engine": "^0.18.0",
         "@augment-vir/test": "^32.3.0",
         "@web/dev-server-esbuild": "^2.0.0",
         "@web/test-runner": "^1.0.0",
@@ -46,7 +46,7 @@
         "typed-event-target": "^4.3.3"
     },
     "peerDependencies": {
-        "@antha/engine": "^0.17.0",
+        "@antha/engine": "^0.18.0",
         "element-vir": "^27",
         "typed-event-target": "^4.3.3"
     },