@antha/audio 0.0.1

package/dist/audio-file.js

@@ -0,0 +1,318 @@
+import { assertWrap, check } from '@augment-vir/assert';
+import { clamp, DeferredPromise, ensureArray, ensureError, 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';
+/**
+ * Create a key for a given audio file config as a cache key.
+ *
+ * @category Internal
+ */
+export function createAudioSourceKey(params) {
+    return ensureArray(params.sources)
+        .map((source) => {
+        if (check.isString(source)) {
+            return source;
+        }
+        else {
+            return [
+                source.url,
+                source.codec,
+            ].join(',');
+        }
+    })
+        .concat(`v=${params.volume ?? 1}`)
+        .join(';');
+}
+/**
+ * Emitted when an {@link AudioFile} finishes playing.
+ *
+ * @category Events
+ */
+export class AudioFilePlayEndEvent extends defineTypedEvent('audio-file-play-end') {
+}
+/**
+ * Emitted when an {@link AudioFile} starts playing.
+ *
+ * @category Events
+ */
+export class AudioFilePlayStartEvent extends defineTypedEvent('audio-file-play-start') {
+}
+/**
+ * Emitted when an {@link AudioFile} is destroyed.
+ *
+ * @category Events
+ */
+export class AudioFileDestroyedEvent extends defineTypedEvent('audio-file-destroyed') {
+}
+/**
+ * Emitted when an {@link AudioFile} is loaded.
+ *
+ * @category Events
+ */
+export class AudioFileLoadEvent extends defineTypedEvent('audio-file-load') {
+}
+/**
+ * Emitted when an {@link AudioFile} encounters an error.
+ *
+ * @category Events
+ */
+export class AudioFileErrorEvent extends defineTypedCustomEvent()('audio-file-error') {
+}
+/**
+ * When this event is fired, it indicates that we've detected that playing sounds has now been
+ * enabled in the current session.
+ *
+ * @category Events
+ */
+export class PlayingEnabledEvent extends defineTypedEvent('playing-enabled') {
+}
+/**
+ * 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
+ * connected to each other and finally to the `originalOutputNode`. If effects are created, the
+ * first one is returned as `outputNode` so all future playback can be routed through all the
+ * effects. If no effects were created, `originalOutputNode` is returned as `outputNode`.
+ *
+ * Some possible connection chains:
+ *
+ * - 3 effects created: `effects[0]` (`outputNode`) -> `effects[1]` -> `effects[2]` ->
+ *   `originalOutputNode`
+ * - 1 effect created: `effects[0]` (`outputNode`) -> `originalOutputNode`
+ * - No effects created: `originalOutputNode` (`outputNode`)
+ *
+ * @category Internal
+ */
+export function setupEffects(audioContext, originalOutputNode, createEffects) {
+    const effects = createEffects?.(audioContext);
+    if (!effects || !check.isLengthAtLeast(effects, 1)) {
+        return {
+            outputNode: originalOutputNode,
+        };
+    }
+    effects.forEach((effect, index, effects) => {
+        const nextEffect = effects[index + 1];
+        if (nextEffect) {
+            effect.connect(nextEffect);
+        }
+        else {
+            /** Connect the last effect to the original output node. */
+            effect.connect(originalOutputNode);
+        }
+    });
+    return {
+        outputNode: effects[0],
+    };
+}
+/**
+ * An individual audio file.
+ *
+ * @category Internal
+ */
+export class AudioFile extends ListenTarget {
+    params;
+    /**
+     * The url or base64 string chosen from the originally provided list of sources that is most
+     * compatible with the current browser. This is what will be played.
+     */
+    urlOrBase64;
+    /**
+     * - `undefined` indicates that loading has not yet started (or has been unloaded).
+     * - `Promise` means that loading has begun (and might be finished).
+     */
+    loadPromise;
+    /**
+     * The `AudioNode` that all playback should route to. If effects are provided, this will be the
+     * first effect (because it'll sequentially route through all of the following effects,
+     * eventually into the final volume `GainNode`). If no effects are provided, this will simply be
+     * the internal volume `GainNode`.
+     */
+    outputNode;
+    /**
+     * `AudioContext` for creating and playing audio nodes. This is automatically provided by a
+     * parent `AudioPlayer`.
+     */
+    audioContext;
+    /**
+     * Cache of all loaded audio files. When an {@link AudioFile} instance is part of an
+     * `AudioPlayer`, this cache will be provided by the parent `AudioPlayer` and shared between all
+     * {@link AudioFile} instances.
+     */
+    audioCache;
+    /**
+     * Internal fetch implementation to use. This can be overridden with `AudioFileParams.fetch`.
+     *
+     * @default globalThis.fetch
+     */
+    fetch;
+    /**
+     * If `true`, indicates that this {@link AudioFile} instance (or another instance within the same
+     * `AudioPlayer`) has detected that the current browser session is allowing audio playback. Most
+     * browsers these days block audio on initial page load until the user has interacted with the
+     * page.
+     */
+    isAudioAllowed = false;
+    /**
+     * Indicates if the {@link AudioFile} has been destroyed. If it has, this file should not be
+     * interacted with anymore. This is set by running {@link AudioFile.destroy}.
+     */
+    isDestroyed = false;
+    gainNode;
+    sourceKey;
+    constructor(params) {
+        super();
+        this.params = params;
+        this.sourceKey = createAudioSourceKey(params);
+        const chosenSource = ensureArray(params.sources).find((source) => {
+            if (check.isString(source)) {
+                return isFileSupported(source);
+            }
+            else {
+                return isCodecSupported(source.codec);
+            }
+        });
+        if (!chosenSource) {
+            const error = new Error(`No valid audio source files found in: ${stringify(params.sources)}`);
+            this.dispatch(new AudioFileErrorEvent({
+                detail: error,
+            }));
+            throw error;
+        }
+        this.urlOrBase64 = check.isString(chosenSource) ? chosenSource : chosenSource.url;
+        this.audioContext = params.audioContext || params.outputNode?.context || new AudioContext();
+        this.audioCache = params.audioCache || {};
+        this.fetch = params.fetch || globalThis.fetch.bind(globalThis);
+        this.gainNode = this.audioContext.createGain();
+        this.gainNode.gain.value = clamp(params.volume ?? 1, {
+            min: 0,
+            max: 1,
+        });
+        this.gainNode.connect(params.outputNode || this.audioContext.destination);
+        this.outputNode = setupEffects(this.audioContext, this.gainNode, params.createEffects).outputNode;
+    }
+    /**
+     * Load the audio file so it's ready to play. This will automatically be called on the first
+     * {@link AudioFile.play} call, but doing so will introduce latency to the first play.
+     */
+    load() {
+        if (this.loadPromise) {
+            return this.loadPromise;
+        }
+        else {
+            this.loadPromise = this.loadAudioBuffer();
+            return this.loadPromise;
+        }
+    }
+    /**
+     * Play the audio file. If the audio file has not been loaded yet, it will be loaded before
+     * playing. If audio playing is disabled (which these days is often the case until the user
+     * interacts with the page), the file will not play. This resolves when the audio file has
+     * finished playing.
+     *
+     * @returns Whether or not the audio file was actually played. The audio file will not be played
+     *   if audio is currently disabled.
+     */
+    async play() {
+        const audioBuffer = await this.load();
+        if (!this.isAudioAllowed) {
+            makeWritable(this).isAudioAllowed = await isPlayingEnabled(this.audioContext);
+            if (this.isAudioAllowed) {
+                this.dispatch(new PlayingEnabledEvent());
+            }
+            else {
+                /**
+                 * If playing is still blocked, don't play anything (to prevent the audio output
+                 * from getting filled up with tons of overlapping plays).
+                 */
+                return false;
+            }
+        }
+        const deferredPlayPromise = new DeferredPromise();
+        const bufferSource = this.audioContext.createBufferSource();
+        bufferSource.buffer = audioBuffer;
+        bufferSource.connect(this.outputNode);
+        bufferSource.addEventListener('ended', () => {
+            deferredPlayPromise.resolve(true);
+            this.dispatch(new AudioFilePlayEndEvent());
+        });
+        this.dispatch(new AudioFilePlayStartEvent());
+        bufferSource.start();
+        return deferredPlayPromise.promise;
+    }
+    /** Destroys this audio file entirely; it cannot be used anymore. */
+    async destroy() {
+        if (this.isDestroyed) {
+            /** Already destroyed. */
+            return;
+        }
+        makeWritable(this).isDestroyed = true;
+        super.destroy();
+        const cacheEntry = await this.audioCache[this.urlOrBase64];
+        if (cacheEntry) {
+            cacheEntry.using.delete(this);
+            if (!cacheEntry.using.size) {
+                delete this.audioCache[this.urlOrBase64];
+            }
+        }
+        this.outputNode.disconnect();
+        this.audioCache = {};
+        this.loadPromise = undefined;
+        delete this.outputNode;
+        delete this.audioCache;
+    }
+    /**
+     * Load the audio file's `AudioBuffer` through one of the following:
+     *
+     * - Retrieving it from the cache (if it exists) using {@link AudioFile.urlOrBase64}
+     * - Parsing the base64 encoded source string (if the source string is encoded base64)
+     * - Fetching the file URL from the internet
+     *
+     * If a cache entry for this file does not already exist, this will create one.
+     */
+    async loadAudioBuffer() {
+        try {
+            const cacheEntry = this.audioCache[this.urlOrBase64];
+            if (cacheEntry) {
+                const resolvedCacheEntry = await cacheEntry;
+                resolvedCacheEntry.using.add(this);
+                return resolvedCacheEntry.buffer;
+            }
+            const deferredCacheEntryPromise = new DeferredPromise();
+            /**
+             * We have to set the cache entry before we do anything async so other audio files
+             * loaded at the same time with the same url see the cache entry.
+             */
+            this.audioCache[this.urlOrBase64] = deferredCacheEntryPromise.promise;
+            const arrayBuffer = /^data:[^;]+;base64,/.test(this.urlOrBase64)
+                ? this.loadBase64()
+                : await this.loadFromUrl();
+            const audioBuffer = await this.audioContext.decodeAudioData(arrayBuffer);
+            deferredCacheEntryPromise.resolve({
+                using: new Set([this]),
+                buffer: audioBuffer,
+            });
+            this.dispatch(new AudioFileLoadEvent());
+            return audioBuffer;
+        }
+        catch (caught) {
+            const error = ensureError(caught);
+            this.dispatch(new AudioFileErrorEvent({
+                detail: error,
+            }));
+            throw error;
+        }
+    }
+    /** Load the audio file's `ArrayBuffer` from its base64 encoded source string. */
+    loadBase64() {
+        const data = atob(assertWrap.isDefined(this.urlOrBase64.split(',')[1], 'Invalid base64 audio string/'));
+        const dataView = new Uint8Array(data.length);
+        for (let i = 0; i < data.length; ++i) {
+            dataView[i] = assertWrap.isDefined(data.codePointAt(i), `Invalid base64 audio string at ${i}.`);
+        }
+        return dataView.buffer;
+    }
+    /** Load the audio file's `ArrayBuffer` from its source URL. */
+    async loadFromUrl() {
+        return await (await this.fetch(this.urlOrBase64)).arrayBuffer();
+    }
+}

package/dist/audio-player.d.ts

@@ -0,0 +1,73 @@
+import { type MaybePromise, type PartialWithUndefined } from '@augment-vir/common';
+import { ListenTarget } from 'typed-event-target';
+import { AudioFile, type AllAudioFileEvents, type AudioFileCache, type AudioFileParams } from './audio-file.js';
+/**
+ * Params for {@link AudioLoadProgressCallback}
+ *
+ * @category Internal
+ */
+export type AudioLoadProgressCallbackParams = {
+    total: number;
+    loaded: number;
+    finished: boolean;
+};
+/**
+ * Progress callback used by `load` in {@link AudioPlayer} when loading multiple files.
+ *
+ * @category Internal
+ */
+export type AudioLoadProgressCallback = (params: AudioLoadProgressCallbackParams) => MaybePromise<void>;
+/**
+ * Options for {@link AudioPlayer}.
+ *
+ * @category Internal
+ */
+export type AudioPlayerOptions = Pick<AudioFileParams, 'fetch' | 'volume' | 'createEffects'>;
+/**
+ * Inputs for playing audio.
+ *
+ * @category Internal
+ */
+export type AudioSetupParams = Readonly<Pick<AudioFileParams, 'sources' | 'volume' | 'fetch' | 'createEffects'>>;
+/**
+ * An audio manager which handles keeping track of, loading, and playing multiple audio files.
+ *
+ * @category Main
+ */
+export declare class AudioPlayer extends ListenTarget<AllAudioFileEvents> {
+    protected readonly options: Readonly<PartialWithUndefined<AudioPlayerOptions>>;
+    readonly audioFiles: {
+        [SourceKey in string]: AudioFile;
+    };
+    readonly audioContext: AudioContext;
+    readonly audioCache: AudioFileCache;
+    readonly isDestroyed: boolean;
+    readonly outputNode: AudioNode;
+    /**
+     * If `true`, indicates that an internal {@link AudioFile} instance has detected that the current
+     * browser session is allowing audio playback. Most browsers these days block audio on initial
+     * page load until the user has interacted with the page.
+     */
+    readonly isAudioAllowed: boolean;
+    /** 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>;
+    /** 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. */
+    unloadFiles(files: ReadonlyArray<Readonly<AudioSetupParams>>): Promise<void>;
+    /** Load a batch of audio files. */
+    loadFiles(files: ReadonlyArray<Readonly<AudioSetupParams>>, options?: Readonly<PartialWithUndefined<{
+        progressCallback: AudioLoadProgressCallback;
+        /**
+         * If `true`, all loading is handled in serial instead of parallel.
+         *
+         * @default false
+         */
+        serial: boolean;
+    }>>): Promise<AudioFile[]>;
+    /** Destroy and cleanup this {@link AudioPlayer} and all child {@link AudioFile} instances. */
+    destroy(): Promise<void>;
+}

package/dist/audio-player.js

@@ -0,0 +1,112 @@
+import { awaitedBlockingMap, clamp, makeWritable, } from '@augment-vir/common';
+import { ListenTarget } from 'typed-event-target';
+import { AudioFile, createAudioSourceKey, PlayingEnabledEvent, setupEffects, } from './audio-file.js';
+/**
+ * An audio manager which handles keeping track of, loading, and playing multiple audio files.
+ *
+ * @category Main
+ */
+export class AudioPlayer extends ListenTarget {
+    options;
+    audioFiles = {};
+    audioContext = new AudioContext();
+    audioCache = {};
+    isDestroyed = false;
+    outputNode;
+    /**
+     * If `true`, indicates that an internal {@link AudioFile} instance has detected that the current
+     * browser session is allowing audio playback. Most browsers these days block audio on initial
+     * page load until the user has interacted with the page.
+     */
+    isAudioAllowed = false;
+    /** Controls volume for all audio files. Modify `gain.value` on this to change playback volume. */
+    gainNode;
+    constructor(options = {}) {
+        super();
+        this.options = options;
+        this.gainNode = this.audioContext.createGain();
+        this.gainNode.gain.value = clamp(options.volume ?? 1, {
+            min: 0,
+            max: 1,
+        });
+        this.gainNode.connect(this.audioContext.destination);
+        this.outputNode = setupEffects(this.audioContext, this.gainNode, options.createEffects).outputNode;
+    }
+    /** Play an audio file. */
+    async play(params) {
+        return this.setupAudioFile(params).play();
+    }
+    /** Create a new {@link AudioFile} instance at the given `key` and set it up. */
+    setupAudioFile(params) {
+        const sourceKey = createAudioSourceKey(params);
+        const existingAudioFile = this.audioFiles[sourceKey];
+        if (existingAudioFile) {
+            return existingAudioFile;
+        }
+        const audioFile = new AudioFile({
+            fetch: this.options.fetch,
+            ...params,
+            audioCache: this.audioCache,
+            audioContext: this.audioContext,
+            outputNode: this.outputNode,
+        });
+        this.audioFiles[sourceKey] = audioFile;
+        audioFile.listenToAll((event) => {
+            if (event instanceof PlayingEnabledEvent && !this.isAudioAllowed) {
+                /** If any audio file detects that playing is enabled, notify all audio files. */
+                makeWritable(this).isAudioAllowed = true;
+                Object.values(this.audioFiles).forEach((audioFile) => {
+                    makeWritable(audioFile).isAudioAllowed = true;
+                });
+            }
+            /** Pass all child audio events. */
+            this.dispatch(event);
+        });
+        return audioFile;
+    }
+    /** Unloads all the attached files. */
+    async unloadFiles(files) {
+        await Promise.all(files.map(async (file) => {
+            const sourceKey = createAudioSourceKey(file);
+            await this.audioFiles[sourceKey]?.destroy();
+            delete this.audioFiles[sourceKey];
+        }));
+    }
+    /** Load a batch of audio files. */
+    async loadFiles(files, options = {}) {
+        let loadedCount = 0;
+        const setupFile = async (file) => {
+            const audioFile = this.setupAudioFile(file);
+            await audioFile.load();
+            if (options.progressCallback) {
+                loadedCount++;
+                void options.progressCallback({
+                    finished: loadedCount >= files.length,
+                    loaded: loadedCount,
+                    total: files.length,
+                });
+            }
+            return audioFile;
+        };
+        if (options.serial) {
+            return await awaitedBlockingMap(files, setupFile);
+        }
+        else {
+            return await Promise.all(files.map(setupFile));
+        }
+    }
+    /** Destroy and cleanup this {@link AudioPlayer} and all child {@link AudioFile} instances. */
+    async destroy() {
+        if (this.isDestroyed) {
+            return;
+        }
+        super.destroy();
+        await Promise.all(Object.values(this.audioFiles).map(async (audioFile) => {
+            delete this.audioFiles[audioFile.sourceKey];
+            await audioFile.destroy();
+            delete this.audioCache[audioFile.sourceKey];
+        }));
+        await this.audioContext.close();
+        this.isDestroyed = true;
+    }
+}