@antha/audio 0.0.1

package/LICENSE-CC0

@@ -0,0 +1,121 @@
+CC0 1.0 Universal
+
+Creative Commons Legal Code
+
+    CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
+    LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
+    ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
+    INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
+    REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
+    PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
+    THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
+    HEREUNDER.
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator
+and subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for
+the purpose of contributing to a commons of creative, cultural and
+scientific works ("Commons") that the public can reliably and without fear
+of later claims of infringement build upon, modify, incorporate in other
+works, reuse and redistribute as freely as possible in any form whatsoever
+and for any purposes, including without limitation commercial purposes.
+These owners may contribute to the Commons to promote the ideal of a free
+culture and the further production of creative, cultural and scientific
+works, or to gain reputation or greater distribution for their Work in
+part through the use and efforts of others.
+
+For these and/or other purposes and motivations, and without any
+expectation of additional consideration or compensation, the person
+associating CC0 with a Work (the "Affirmer"), to the extent that he or she
+is an owner of Copyright and Related Rights in the Work, voluntarily
+elects to apply CC0 to the Work and publicly distribute the Work under its
+terms, with knowledge of his or her Copyright and Related Rights in the
+Work and the meaning and intended legal effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not
+limited to, the following:
+
+  i. the right to reproduce, adapt, distribute, perform, display,
+     communicate, and translate a Work;
+ ii. moral rights retained by the original author(s) and/or performer(s);
+iii. publicity and privacy rights pertaining to a person's image or
+     likeness depicted in a Work;
+ iv. rights protecting against unfair competition in regards to a Work,
+     subject to the limitations in paragraph 4(a), below;
+  v. rights protecting the extraction, dissemination, use and reuse of data
+     in a Work;
+ vi. database rights (such as those arising under Directive 96/9/EC of the
+     European Parliament and of the Council of 11 March 1996 on the legal
+     protection of databases, and under any national implementation
+     thereof, including any amended or successor version of such
+     directive); and
+vii. other similar, equivalent or corresponding rights throughout the
+     world based on applicable law or treaty, and any national
+     implementations thereof.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention
+of, applicable law, Affirmer hereby overtly, fully, permanently,
+irrevocably and unconditionally waives, abandons, and surrenders all of
+Affirmer's Copyright and Related Rights and associated claims and causes
+of action, whether now known or unknown (including existing as well as
+future claims and causes of action), in the Work (i) in all territories
+worldwide, (ii) for the maximum duration provided by applicable law or
+treaty (including future time extensions), (iii) in any current or future
+medium and for any number of copies, and (iv) for any purpose whatsoever,
+including without limitation commercial, advertising or promotional
+purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
+member of the public at large and to the detriment of Affirmer's heirs and
+successors, fully intending that such Waiver shall not be subject to
+revocation, rescission, cancellation, termination, or any other legal or
+equitable action to disrupt the quiet enjoyment of the Work by the public
+as contemplated by Affirmer's express Statement of Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason
+be judged legally invalid or ineffective under applicable law, then the
+Waiver shall be preserved to the maximum extent permitted taking into
+account Affirmer's express Statement of Purpose. In addition, to the
+extent the Waiver is so judged Affirmer hereby grants to each affected
+person a royalty-free, non transferable, non sublicensable, non exclusive,
+irrevocable and unconditional license to exercise Affirmer's Copyright and
+Related Rights in the Work (i) in all territories worldwide, (ii) for the
+maximum duration provided by applicable law or treaty (including future
+time extensions), (iii) in any current or future medium and for any number
+of copies, and (iv) for any purpose whatsoever, including without
+limitation commercial, advertising or promotional purposes (the
+"License"). The License shall be deemed effective as of the date CC0 was
+applied by Affirmer to the Work. Should any part of the License for any
+reason be judged legally invalid or ineffective under applicable law, such
+partial invalidity or ineffectiveness shall not invalidate the remainder
+of the License, and in such case Affirmer hereby affirms that he or she
+will not (i) exercise any of his or her remaining Copyright and Related
+Rights in the Work or (ii) assert any associated claims and causes of
+action with respect to the Work, in either case contrary to Affirmer's
+express Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+ a. No trademark or patent rights held by Affirmer are waived, abandoned,
+    surrendered, licensed or otherwise affected by this document.
+ b. Affirmer offers the Work as-is and makes no representations or
+    warranties of any kind concerning the Work, express, implied,
+    statutory or otherwise, including without limitation warranties of
+    title, merchantability, fitness for a particular purpose, non
+    infringement, or the absence of latent or other defects, accuracy, or
+    the present or absence of errors, whether or not discoverable, all to
+    the greatest extent permissible under applicable law.
+ c. Affirmer disclaims responsibility for clearing rights of other persons
+    that may apply to the Work or any use thereof, including without
+    limitation any person's Copyright and Related Rights in the Work.
+    Further, Affirmer disclaims responsibility for obtaining any necessary
+    consents, permissions or other rights required for any use of the
+    Work.
+ d. Affirmer understands and acknowledges that Creative Commons is not a
+    party to this document and has no duty or obligation with respect to
+    this CC0 or use of the Work.

package/LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 electrovir
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,11 @@
+# @antha/audio
+
+A pre-built [Antha](https://www.npmjs.com/package/antha) mod for handling audio.
+
+Demo: https://electrovir.github.io/antha/demo/audio
+
+## Install
+
+```sh
+npm i @antha/audio
+```

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

@@ -0,0 +1,28 @@
+import { type PartialWithUndefined } from '@augment-vir/common';
+import { AudioPlayer, type AudioPlayerOptions } from './audio-player.js';
+/**
+ * State for {@link createAnthaAudioMod}.
+ *
+ * @category Internal
+ */
+export type AnthaAudioState = {
+    audioPlayer: AudioPlayer;
+};
+/**
+ * Options for {@link createAnthaAudioMod}.
+ *
+ * @category Internal
+ */
+export type AnthaAudioModOptions = PartialWithUndefined<AudioPlayerOptions>;
+/**
+ * A pre-built mod for playing audio files.
+ *
+ * @category Pre-Built Mods
+ */
+export declare function createAnthaAudioMod(audioPlayerOptions?: Readonly<AnthaAudioModOptions>): import("@antha/engine").AnthaMod<NoInfer<AnthaAudioState>>;
+/**
+ * The mod created by {@link createAnthaAudioMod}.
+ *
+ * @category Internal
+ */
+export type AnthaAudioMod = ReturnType<typeof createAnthaAudioMod>;

package/dist/antha-audio.mod.js

@@ -0,0 +1,20 @@
+import { defineAnthaMod } from '@antha/engine';
+import { AudioPlayer } from './audio-player.js';
+/**
+ * A pre-built mod for playing audio files.
+ *
+ * @category Pre-Built Mods
+ */
+export function createAnthaAudioMod(audioPlayerOptions = {}) {
+    return defineAnthaMod({
+        modName: 'antha-audio',
+        async cleanup({ state }) {
+            await state.audioPlayer?.destroy();
+        },
+        execute({ state }) {
+            if (!state.audioPlayer) {
+                state.audioPlayer = new AudioPlayer(audioPlayerOptions);
+            }
+        },
+    });
+}

package/dist/audio-file.d.ts

@@ -0,0 +1,277 @@
+import { type PartialWithUndefined, type SelectFrom } from '@augment-vir/common';
+import { ListenTarget } from 'typed-event-target';
+import { type Codec } from './codecs.js';
+/**
+ * Accepted types for the {@link AudioFile} source param `AudioFileParams.sources`).
+ *
+ * @category Internal
+ */
+export type AudioFileSource = 
+/** The URL of the audio file. The codec will be determined automatically by the file name. */
+string | {
+    url: string;
+    /** Force a specific codec for this file. */
+    codec: Codec;
+};
+/**
+ * Init params for {@link AudioFile}. When {@link AudioFile} instances are constructed internally by
+ * `AudioPlayer`, only a subset of these parameters can be / must be manually provided.
+ *
+ * @category Internal
+ */
+export type AudioFileParams = Readonly<{
+    /**
+     * An array of possible source file URLs. The first one that is supported by the current
+     * browser will be used.
+     */
+    sources: ReadonlyArray<AudioFileSource> | AudioFileSource;
+} & PartialWithUndefined<{
+    /**
+     * Override the used `fetch` implementation.
+     *
+     * @default globalThis.fetch
+     */
+    fetch: (url: string) => Promise<Pick<Response, 'arrayBuffer'>>;
+    /** A value between `0` and `1` to control volume. */
+    volume: number;
+    outputNode: AudioNode;
+    audioContext: BaseAudioContext;
+    audioCache: AudioFileCache;
+    /**
+     * Any audio nodes to chain together. They will automatically be connected together in
+     * sequential order.
+     */
+    createEffects: (audioContext: BaseAudioContext) => ReadonlyArray<AudioNode> | undefined | void;
+}>>;
+/**
+ * Create a key for a given audio file config as a cache key.
+ *
+ * @category Internal
+ */
+export declare function createAudioSourceKey(params: Readonly<SelectFrom<AudioFileParams, {
+    volume: true;
+    sources: true;
+}>>): string;
+declare const AudioFilePlayEndEvent_base: (new (eventInitDict?: EventInit) => Event & import("typed-event-target").TypedEvent<"audio-file-play-end">) & Pick<{
+    new (type: string, eventInitDict?: EventInit): Event;
+    prototype: Event;
+    readonly NONE: 0;
+    readonly CAPTURING_PHASE: 1;
+    readonly AT_TARGET: 2;
+    readonly BUBBLING_PHASE: 3;
+}, "prototype" | "NONE" | "CAPTURING_PHASE" | "AT_TARGET" | "BUBBLING_PHASE"> & Pick<import("typed-event-target").TypedEvent<"audio-file-play-end">, "type">;
+/**
+ * Emitted when an {@link AudioFile} finishes playing.
+ *
+ * @category Events
+ */
+export declare class AudioFilePlayEndEvent extends AudioFilePlayEndEvent_base {
+}
+declare const AudioFilePlayStartEvent_base: (new (eventInitDict?: EventInit) => Event & import("typed-event-target").TypedEvent<"audio-file-play-start">) & Pick<{
+    new (type: string, eventInitDict?: EventInit): Event;
+    prototype: Event;
+    readonly NONE: 0;
+    readonly CAPTURING_PHASE: 1;
+    readonly AT_TARGET: 2;
+    readonly BUBBLING_PHASE: 3;
+}, "prototype" | "NONE" | "CAPTURING_PHASE" | "AT_TARGET" | "BUBBLING_PHASE"> & Pick<import("typed-event-target").TypedEvent<"audio-file-play-start">, "type">;
+/**
+ * Emitted when an {@link AudioFile} starts playing.
+ *
+ * @category Events
+ */
+export declare class AudioFilePlayStartEvent extends AudioFilePlayStartEvent_base {
+}
+declare const AudioFileDestroyedEvent_base: (new (eventInitDict?: EventInit) => Event & import("typed-event-target").TypedEvent<"audio-file-destroyed">) & Pick<{
+    new (type: string, eventInitDict?: EventInit): Event;
+    prototype: Event;
+    readonly NONE: 0;
+    readonly CAPTURING_PHASE: 1;
+    readonly AT_TARGET: 2;
+    readonly BUBBLING_PHASE: 3;
+}, "prototype" | "NONE" | "CAPTURING_PHASE" | "AT_TARGET" | "BUBBLING_PHASE"> & Pick<import("typed-event-target").TypedEvent<"audio-file-destroyed">, "type">;
+/**
+ * Emitted when an {@link AudioFile} is destroyed.
+ *
+ * @category Events
+ */
+export declare class AudioFileDestroyedEvent extends AudioFileDestroyedEvent_base {
+}
+declare const AudioFileLoadEvent_base: (new (eventInitDict?: EventInit) => Event & import("typed-event-target").TypedEvent<"audio-file-load">) & Pick<{
+    new (type: string, eventInitDict?: EventInit): Event;
+    prototype: Event;
+    readonly NONE: 0;
+    readonly CAPTURING_PHASE: 1;
+    readonly AT_TARGET: 2;
+    readonly BUBBLING_PHASE: 3;
+}, "prototype" | "NONE" | "CAPTURING_PHASE" | "AT_TARGET" | "BUBBLING_PHASE"> & Pick<import("typed-event-target").TypedEvent<"audio-file-load">, "type">;
+/**
+ * Emitted when an {@link AudioFile} is loaded.
+ *
+ * @category Events
+ */
+export declare class AudioFileLoadEvent extends AudioFileLoadEvent_base {
+}
+declare const AudioFileErrorEvent_base: (new (eventInitDict: {
+    bubbles?: boolean;
+    cancelable?: boolean;
+    composed?: boolean;
+    detail: Error;
+}) => import("typed-event-target").TypedCustomEvent<Error, "audio-file-error">) & Pick<{
+    new (type: string, eventInitDict?: EventInit): Event;
+    prototype: Event;
+    readonly NONE: 0;
+    readonly CAPTURING_PHASE: 1;
+    readonly AT_TARGET: 2;
+    readonly BUBBLING_PHASE: 3;
+}, "prototype" | "NONE" | "CAPTURING_PHASE" | "AT_TARGET" | "BUBBLING_PHASE"> & Pick<import("typed-event-target").TypedCustomEvent<Error, "audio-file-error">, "type">;
+/**
+ * Emitted when an {@link AudioFile} encounters an error.
+ *
+ * @category Events
+ */
+export declare class AudioFileErrorEvent extends AudioFileErrorEvent_base {
+}
+declare const PlayingEnabledEvent_base: (new (eventInitDict?: EventInit) => Event & import("typed-event-target").TypedEvent<"playing-enabled">) & Pick<{
+    new (type: string, eventInitDict?: EventInit): Event;
+    prototype: Event;
+    readonly NONE: 0;
+    readonly CAPTURING_PHASE: 1;
+    readonly AT_TARGET: 2;
+    readonly BUBBLING_PHASE: 3;
+}, "prototype" | "NONE" | "CAPTURING_PHASE" | "AT_TARGET" | "BUBBLING_PHASE"> & Pick<import("typed-event-target").TypedEvent<"playing-enabled">, "type">;
+/**
+ * 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 declare class PlayingEnabledEvent extends PlayingEnabledEvent_base {
+}
+/**
+ * All events that can be emitted from an {@link AudioFile} instance.
+ *
+ * @category Internal
+ */
+export type AllAudioFileEvents = AudioFilePlayEndEvent | AudioFilePlayStartEvent | AudioFileLoadEvent | AudioFileErrorEvent | PlayingEnabledEvent;
+/**
+ * Type interface for the audio file cache.
+ *
+ * @category Internal
+ */
+export type AudioFileCache = {
+    [UrlOrBase64 in string]: Promise<{
+        /** Current audio files that are using this url. */
+        using: Set<AudioFile>;
+        buffer: AudioBuffer;
+    }>;
+};
+/**
+ * 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 declare function setupEffects(audioContext: Readonly<BaseAudioContext>, originalOutputNode: Readonly<AudioNode>, createEffects: AudioFileParams['createEffects']): {
+    /** The node that all future playback should be connected to. */
+    outputNode: AudioNode;
+};
+/**
+ * An individual audio file.
+ *
+ * @category Internal
+ */
+export declare class AudioFile extends ListenTarget<AllAudioFileEvents> {
+    private readonly 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.
+     */
+    readonly urlOrBase64: string;
+    /**
+     * - `undefined` indicates that loading has not yet started (or has been unloaded).
+     * - `Promise` means that loading has begun (and might be finished).
+     */
+    protected loadPromise: ReturnType<typeof this.load> | undefined;
+    /**
+     * 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`.
+     */
+    protected readonly outputNode: AudioNode;
+    /**
+     * `AudioContext` for creating and playing audio nodes. This is automatically provided by a
+     * parent `AudioPlayer`.
+     */
+    protected readonly audioContext: BaseAudioContext;
+    /**
+     * 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.
+     */
+    protected readonly audioCache: AudioFileCache;
+    /**
+     * Internal fetch implementation to use. This can be overridden with `AudioFileParams.fetch`.
+     *
+     * @default globalThis.fetch
+     */
+    protected readonly fetch: NonNullable<AudioFileParams['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.
+     */
+    readonly isAudioAllowed: boolean;
+    /**
+     * 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}.
+     */
+    readonly isDestroyed: boolean;
+    readonly gainNode: GainNode;
+    readonly sourceKey: string;
+    constructor(params: AudioFileParams);
+    /**
+     * 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(): ReturnType<typeof this.loadAudioBuffer>;
+    /**
+     * 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.
+     */
+    play(): Promise<boolean>;
+    /** Destroys this audio file entirely; it cannot be used anymore. */
+    destroy(): Promise<void>;
+    /**
+     * 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.
+     */
+    protected loadAudioBuffer(): Promise<AudioBuffer>;
+    /** Load the audio file's `ArrayBuffer` from its base64 encoded source string. */
+    protected loadBase64(): ArrayBuffer;
+    /** Load the audio file's `ArrayBuffer` from its source URL. */
+    protected loadFromUrl(): Promise<ArrayBuffer>;
+}
+export {};