@7h3laughingman/foundry-types 13.351.0

package/src/client/audio/helper.d.mts

@@ -0,0 +1,306 @@
+import { BandName, ContextName, SoundCreationOptions } from "./_types.mjs";
+import AudioBufferCache from "./cache.mjs";
+import Sound from "./sound.mjs";
+
+/**
+ * A helper class to provide common functionality for working with the Web Audio API.
+ * https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API
+ * A singleton instance of this class is available as game#audio.
+ * @see {@link foundry.Game#audio}
+ */
+export default class AudioHelper {
+    constructor();
+
+    /**
+     * An array containing all possible audio context names.
+     */
+    static AUDIO_CONTEXTS: readonly ContextName[];
+
+    /**
+     * The Native interval for the AudioHelper to analyse audio levels from streams
+     * Any interval passed to startLevelReports() would need to be a multiple of this value.
+     */
+    static levelAnalyserNativeInterval: number;
+
+    /**
+     * The cache size threshold after which audio buffers will be expired from the cache to make more room.
+     * 1 gigabyte, by default.
+     */
+    static THRESHOLD_CACHE_SIZE_BYTES: number;
+
+    /**
+     * Audio Context singleton used for analysing audio levels of each stream
+     * Only created if necessary to listen to audio streams.
+     */
+    static #analyzerContext: AudioContext;
+
+    /**
+     * The set of singleton Sound instances which are shared across multiple uses of the same sound path.
+     */
+    sounds: Map<string, WeakRef<Sound>>;
+
+    /**
+     * Get a map of the Sound objects which are currently playing.
+     */
+    playing: Map<number, Sound>;
+
+    /**
+     * A user gesture must be registered before audio can be played.
+     * This Array contains the Sound instances which are requested for playback prior to a gesture.
+     * Once a gesture is observed, we begin playing all elements of this Array.
+     * @see {@link Sound}
+     */
+    pending: Function[];
+
+    /**
+     * A Promise which resolves once the game audio API is unlocked and ready to use.
+     */
+    unlock: Promise<void>;
+
+    /**
+     * A flag for whether video playback is currently locked by awaiting a user gesture
+     */
+    locked: boolean;
+
+    /**
+     * A singleton audio context used for playback of music.
+     */
+    music: AudioContext;
+
+    /**
+     * A singleton audio context used for playback of environmental audio.
+     */
+    environment: AudioContext;
+
+    /**
+     * A singleton audio context used for playback of interface sounds and effects.
+     */
+    interface: AudioContext;
+
+    /**
+     * For backwards compatibility, AudioHelper#context refers to the context used for music playback.
+     */
+    get context(): AudioContext;
+
+    /**
+     * A singleton cache used for audio buffers.
+     */
+    buffers: AudioBufferCache;
+
+    /**
+     * A global mute which suppresses all 3 audio channels.
+     */
+    get globalMute(): boolean;
+
+    set globalMute(muted);
+
+    /**
+     * Create a Sound instance for a given audio source URL
+     * @param options Sound creation options
+     */
+    create(options?: SoundCreationOptions): Sound;
+
+    /**
+     * Test whether a source file has a supported audio extension type
+     * @param src A requested audio source path
+     * @returns Does the filename end with a valid audio extension?
+     */
+    static hasAudioExtension(src: string): boolean;
+
+    /* -------------------------------------------- */
+
+    /**
+     * Given an input file path, determine a default name for the sound based on the filename
+     * @param src An input file path
+     * @returns A default sound name for the path
+     */
+    static getDefaultSoundName(src: string): string;
+
+    /**
+     * Play a single Sound by providing its source.
+     * @param src            The file path to the audio source beingplayed
+     * @param options Additional options which configure playback
+     * @param options.context A specific AudioContext within which to play
+     * @returns The created Sound which is now playing
+     */
+    play(src: string, options?: { context?: AudioContext }): Promise<Sound>;
+
+    /**
+     * Register an event listener to await the first mousemove gesture and begin playback once observed.
+     * @returns The unlocked audio context
+     */
+    awaitFirstGesture(): Promise<void>;
+
+    /**
+     * Request that other connected clients begin preloading a certain sound path.
+     * @param src The source file path requested for preload
+     * @returns A Promise which resolves once the preload is complete
+     */
+    preload(src: string): Promise<Sound>;
+
+    /* -------------------------------------------- */
+    /*  Settings and Volume Controls                */
+    /* -------------------------------------------- */
+
+    /**
+     * Register client-level settings for global volume controls.
+     */
+    static registerSettings(): void;
+
+    /* -------------------------------------------- */
+    /*  Socket Listeners and Handlers               */
+    /* -------------------------------------------- */
+
+    /**
+     * Open socket listeners which transact ChatMessage data
+     */
+    static _activateSocketListeners(socket: io.Socket): void;
+
+    /**
+     * Play a one-off sound effect which is not part of a Playlist
+     * @param data An object configuring the audio data toplay.
+     * @param data.src The audio source file path, either a public URL or a local path relative to the public directory.
+     * @param data.channel An audio channel in CONST.AUDIO_CHANNELS where the sound should play. Default: `"interface"`.
+     * @param data.volume The volume level at which to play the audio, between 0 and 1. Default: `1`.
+     * @param data.autoplay Begin playback of the audio effect immediately once it is loaded. Default: `false`.
+     * @param data.loop Loop the audio effect and continue playing it until it is manually stopped. Default: `false`.
+     * @param socketOptions Options which only apply when emitting playback over websocket. As a boolean, emits (true)
+     *                      or does not emit (false) playback to all other clients. As an object, can configure which
+     *                      recipients (an array of User IDs) should receive the event (all clients by default).
+     *                      Default: `false`.
+     * @returns A Sound instance which controls audio playback, or nothing if `data.autoplay` is false.
+     *
+     * @example Play the sound of a locked door for all players
+     * ```js
+     * AudioHelper.play({src: "sounds/lock.wav", volume: 0.8, loop: false}, true);
+     * ```
+     */
+    static play(
+        data: { src: string; channel?: string; volume?: number; autoplay?: boolean; loop?: boolean },
+        socketOptions: boolean | { recipients: string[] },
+    ): Sound | void;
+
+    /**
+     * Begin loading the sound for a provided source URL adding its
+     * @param src            The audio source path topreload
+     * @returns The created and loaded Sound ready for playback
+     */
+    static preloadSound(src: string): Promise<Sound>;
+
+    /**
+     * Returns the volume value based on a range input volume control's position.
+     * This is using an exponential approximation of the logarithmic nature of audio level perception
+     * @param value Value between [0, 1] of the range input
+     * @param order The exponent of the curve
+     */
+    static inputToVolume(value: number | string, order?: number): number;
+
+    /**
+     * Counterpart to inputToVolume()
+     * Returns the input range value based on a volume
+     * @param volume Value between [0, 1of the volume level
+     * @param order The exponent of the curve
+     */
+    static volumeToInput(volume: number, order?: number): number;
+
+    /**
+     * Converts a volume level to a human-readable percentage value.
+     * @param volume Value in the interval [0, 1of the volume level.
+     * @param options.label Prefix the returned tooltip with a localized 'Volume: ' label. This should be used if the
+     *                      returned string is intended for assistive technologies, such as the aria-valuetext
+     *                      attribute.
+     * @param options.decimalPlaces The number of decimal places to round the percentage to.
+     */
+    static volumeToPercentage(volume: number, options?: { label?: boolean; decimalPlaces?: number }): string;
+
+    /* -------------------------------------------- */
+    /*  Audio Stream Analysis                       */
+    /* -------------------------------------------- */
+
+    /**
+     * Returns a singleton AudioContext if one can be created.
+     * An audio context may not be available due to limited resources or browser compatibility
+     * in which case null will be returned
+     *
+     * @returns A singleton AudioContext or null if one is not available
+     */
+    getAnalyzerContext(): AudioContext;
+
+    /**
+     * Registers a stream for periodic reports of audio levels.
+     * Once added, the callback will be called with the maximum decibel level of
+     * the audio tracks in that stream since the last time the event was fired.
+     * The interval needs to be a multiple of AudioHelper.levelAnalyserNativeInterval which defaults at 50ms
+     *
+     * @param id An id to assign to this report. Can be used to stop reports
+     * @param stream The MediaStream instance to report activity on.
+     * @param callback  The callback function to call with the decibel level. `callback(dbLevel)`
+     * @param interval The interval at which to produce reports.
+     * @param smoothing The smoothingTimeConstant to set on the audio analyser.
+     * @returns Returns whether listening to the stream was successful
+     */
+    startLevelReports(id: string, stream: MediaStream, callback: Function, interval?: number, smoothing?: number): boolean;
+
+    /**
+     * Stop sending audio level reports
+     * This stops listening to a stream and stops sending reports.
+     * If we aren't listening to any more streams, cancel the global analyser timer.
+     * @param id The id of the reports that passed to startLevelReports.
+     */
+    stopLevelReports(id: string): void;
+
+    /* -------------------------------------------- */
+    /*  Event Handlers                              */
+    /* -------------------------------------------- */
+
+    /**
+     * Log a debugging message if the audio debugging flag is enabled.
+     * @param message The message to log
+     */
+    debug(message: string): void;
+
+    /* -------------------------------------------- */
+    /*  Public Analyzer Methods and Properties      */
+    /* -------------------------------------------- */
+
+    /**
+     * A static inactivity threshold for audio analysis, in milliseconds.
+     * If no band value is requested for a channel within this duration,
+     * the analyzer is disabled to conserve resources (unless the analyzer is enabled with the `keepAlive=true` option)
+     */
+    static ANALYSIS_TIMEOUT_MS: number;
+
+    /**
+     * Enable the analyzer for a given context (music, environment, interface),
+     * attaching an AnalyserNode to its gain node if not already active.
+     * @param options.keepAlive If true, this analyzer will not auto-disable after inactivity.
+     */
+    enableAnalyzer(contextName: ContextName, options?: { keepAlive?: boolean }): void;
+
+    /**
+     * Disable the analyzer for a given context, disconnecting the AnalyserNode.
+     */
+    disableAnalyzer(contextName: ContextName): void;
+
+    /**
+     * Returns a normalized band value in [0,1].
+     * Optionally, we can subtract the actual gainNode (global) volume from the measurement.
+     * - Important:
+     *   - Local gain applied to {@link foundry.audio.Sound} source can't be ignored.
+     *   - If this method needs to activate the analyzer, the latter requires a brief warm-up.
+     *     One or two frames may be needed before it produces meaningful values (instead of returning 0).
+     * @param options.ignoreVolume If true, remove the real-time channel volume from the measurement.
+     * @returns The normalized band value in [0,1].
+     */
+    getBandLevel(contextName: ContextName, bandName: BandName, options?: { ignoreVolume?: boolean }): number;
+
+    /**
+     * Retrieve a single "peak" analyzer value across the three main audio contexts (music, environment, interface).
+     * This takes the maximum of the three normalized [0,1] values for a given frequency band.
+     * @param band The frequency band for which to retrieve an analyzer value.
+     * @param options
+     * @param options.ignoreVolume If true, remove the real-time channel volume from the measurement.
+     * @returns A number in the [0,1] range representing the loudest band value among the three contexts.
+     */
+    getMaxBandLevel(band?: BandName, options?: { ignoreVolume?: boolean }): number;
+}

package/src/client/audio/sound.d.mts

@@ -0,0 +1,289 @@
+import { EventEmitter } from "./../../common/utils/event-emitter.mjs";
+import { SoundPlaybackOptions, SoundScheduleCallback } from "./_types.mjs";
+
+type SoundState = (typeof Sound.STATES)[keyof typeof Sound.STATES];
+
+/**
+ * A container around an AudioNode which manages sound playback in Foundry Virtual Tabletop.
+ * Each Sound is either an AudioBufferSourceNode (for short sources) or a MediaElementAudioSourceNode (for long ones).
+ * This class provides an interface around both types which allows standardized control over playback.
+ */
+export default class Sound extends EventEmitter {
+    /**
+     * Construct a Sound by providing the source URL and other options.
+     * @param src     The audio source path, either a relative path or a remote URL
+     * @param options Additional options which configure the Sound
+     * @param options.context      A non-default audio context within which the sound should play
+     * @param options.forceBuffer  Force use of an AudioBufferSourceNode even if the audio duration is long
+     */
+    constructor(src: string, options?: { context?: AudioContext; forceBuffer?: boolean });
+
+    /**
+     * The sequence of container loading states.
+     */
+    static STATES: {
+        FAILED: -1;
+        NONE: 0;
+        LOADING: 1;
+        LOADED: 2;
+        STARTING: 3;
+        PLAYING: 4;
+        PAUSED: 5;
+        STOPPING: 6;
+        STOPPED: 7;
+    };
+
+    /**
+     * The maximum duration, in seconds, for which an AudioBufferSourceNode will be used.
+     * Otherwise, a MediaElementAudioSourceNode will be used.
+     */
+    static MAX_BUFFER_DURATION: number;
+
+    static override emittedEvents: string[];
+
+    /**
+     * A unique integer identifier for this sound.
+     */
+    id: number;
+
+    /**
+     * The audio source path.
+     * Either a relative path served by the running Foundry VTT game server or a remote URL.
+     */
+    src: string;
+
+    /**
+     * The audio context within which this Sound is played.
+     */
+    get context(): AudioContext;
+
+    /**
+     * The AudioSourceNode used to control sound playback.
+     */
+    get sourceNode(): AudioBufferSourceNode | MediaElementAudioSourceNode;
+
+    /**
+     * The GainNode used to control volume for this sound.
+     */
+    gainNode: GainNode;
+
+    /**
+     * An AudioBuffer instance, if this Sound uses an AudioBufferSourceNode for playback.
+     */
+    buffer: AudioBuffer | null;
+
+    /**
+     * An HTMLAudioElement, if this Sound uses a MediaElementAudioSourceNode for playback.
+     */
+    element: HTMLAudioElement | null;
+
+    /**
+     * The life-cycle state of the sound.
+     */
+    protected _state: SoundState;
+
+    /**
+     * Has the audio file been loaded either fully or for streaming.
+     */
+    get loaded(): boolean;
+
+    /**
+     * Did the audio file fail to load.
+     */
+    get failed(): boolean;
+
+    /**
+     * Is this sound currently playing?
+     */
+    get playing(): boolean;
+
+    /**
+     * Does this Sound use an AudioBufferSourceNode?
+     * Otherwise, the Sound uses a streamed MediaElementAudioSourceNode.
+     */
+    get isBuffer(): boolean;
+
+    /**
+     * A convenience reference to the GainNode gain audio parameter.
+     */
+    get gain(): AudioParam | undefined;
+
+    /**
+     * The AudioNode destination which is the output target for the Sound.
+     */
+    destination: AudioNode;
+
+    /**
+     * A pipeline of AudioNode instances to be applied to Sound playback.
+     */
+    effects: AudioNode[];
+
+    /**
+     * The currently playing volume of the sound.
+     * Undefined until playback has started for the first time.
+     */
+    get volume(): number | undefined;
+
+    set volume(value);
+    /**
+     * The time in seconds at which playback was started.
+     */
+    startTime: number;
+
+    /**
+     * The time in seconds at which playback was paused.
+     */
+    pausedTime: number;
+
+    /**
+     * The total duration of the audio source in seconds.
+     */
+    get duration(): number;
+
+    /**
+     * The current playback time of the sound.
+     */
+    get currentTime(): number;
+
+    /**
+     * Is the sound looping?
+     */
+    get loop(): boolean;
+
+    set loop(value);
+
+    /**
+     * An internal reference to some object which is managing this Sound instance.
+     * @internal
+     */
+    _manager: object | null;
+
+    /* -------------------------------------------- */
+    /*  Life-Cycle Methods                          */
+    /* -------------------------------------------- */
+
+    /**
+     * Load the audio source and prepare it for playback, either using an AudioBuffer or a streamed HTMLAudioElement.
+     * @param options Additional options which affect resource loading
+     * @param options.autoplay        Automatically begin playback of the sound once loaded
+     * @param options.autoplayOptions Playback options passed to Sound#play, if autoplay
+     * @returns A Promise which resolves to the Sound once it is loaded
+     */
+    load(options?: { autoplay?: boolean; autoplayOptions?: SoundPlaybackOptions }): Promise<this>;
+
+    /**
+     * An inner method which handles loading so that it can be de-duplicated under a single shared Promise resolution.
+     * This method is factored out to allow for subclasses to override loading behavior.
+     * @returns A Promise which resolves once the sound is loaded
+     * @throws An error if loading failed for any reason
+     */
+    protected _load(): Promise<void>;
+
+    /**
+     * Begin playback for the Sound.
+     * This method is asynchronous because playback may not start until after an initially provided delay.
+     * The Promise resolves *before* the fade-in of any configured volume transition.
+     * @param options Options which configure the beginning of sound playback
+     * @returns A Promise which resolves once playback has started (excluding fade)
+     */
+    play(options?: SoundPlaybackOptions): Promise<this>;
+
+    /**
+     * Begin playback for the configured pipeline and playback options.
+     * This method is factored out so that subclass implementations of Sound can implement alternative behavior.
+     */
+    protected _play(): void;
+
+    /**
+     * Pause playback of the Sound.
+     * For AudioBufferSourceNode this stops playback after recording the current time.
+     * Calling Sound#play will resume playback from the pausedTime unless some other offset is passed.
+     * For a MediaElementAudioSourceNode this simply calls the HTMLAudioElement#pause method directly.
+     */
+    pause(): void;
+
+    /**
+     * Pause playback of the Sound.
+     * This method is factored out so that subclass implementations of Sound can implement alternative behavior.
+     */
+    protected _pause(): void;
+
+    /**
+     * Stop playback for the Sound.
+     * This method is asynchronous because playback may not stop until after an initially provided delay.
+     * The Promise resolves *after* the fade-out of any configured volume transition.
+     * @param options Options which configure the stopping of sound playback
+     * @returns A Promise which resolves once playback is fully stopped (including fade)
+     */
+    stop(options?: SoundPlaybackOptions): Promise<this>;
+
+    /**
+     * Stop playback of the Sound.
+     * This method is factored out so that subclass implementations of Sound can implement alternative behavior.
+     */
+    protected _stop(): void;
+
+    /**
+     * Fade the volume for this sound between its current level and a desired target volume.
+     * @param volume  The desired target volume level between 0 and 1
+     * @param options Additional options that configure the fade operation
+     * @param options.duration The duration of the fade effect in milliseconds
+     * @param options.from     A volume level to start from, the current volume by default
+     * @param options.type     The type of fade easing, "linear" or "exponential"
+     * @returns A Promise that resolves after the requested fade duration
+     */
+    fade(volume: number, options?: { duration?: number; from?: number; type?: "linear" | "exponential" }): Promise<void>;
+
+    /**
+     * Wait a certain scheduled duration within this sound's own AudioContext.
+     * @param duration The duration to wait in milliseconds
+     * @returns A promise which resolves after the waited duration
+     */
+    wait(duration: number): Promise<void>;
+
+    /**
+     * Schedule a function to occur at the next occurrence of a specific playbackTime for this Sound.
+     * @param fn           A function that will be called with this Sound as its single argument
+     * @param playbackTime The desired playback time at which the function should be called
+     * @returns A Promise which resolves to the returned value of the provided function once it has been evaluated.
+     *
+     * @example Schedule audio playback changes
+     * ```js
+     * sound.schedule(() => console.log("Do something exactly 30 seconds into the track"), 30);
+     * sound.schedule(() => console.log("Do something next time the track loops back to the beginning"), 0);
+     * sound.schedule(() => console.log("Do something 5 seconds before the end of the track"), sound.duration - 5);
+     * ```
+     */
+    schedule(fn: SoundScheduleCallback, playbackTime: number): Promise<unknown>;
+
+    /**
+     * Update the array of effects applied to a Sound instance.
+     * Optionally a new array of effects can be assigned. If no effects are passed, the current effects are re-applied.
+     * @param effects An array of AudioNode effects to apply
+     */
+    applyEffects(effects?: AudioNode[]): void;
+
+    /* -------------------------------------------- */
+    /*  Helper Methods                              */
+    /* -------------------------------------------- */
+
+    /**
+     * Create any AudioNode instances required for playback of this Sound.
+     */
+    protected _createNodes(): void;
+
+    /**
+     * Create the audio pipeline used to play this Sound.
+     * The GainNode is reused each time to link volume changes across multiple playbacks.
+     * The AudioSourceNode is re-created every time that Sound#play is called.
+     */
+    protected _connectPipeline(): void;
+
+    /**
+     * Disconnect the audio pipeline once playback is stopped.
+     * Walk backwards along the Sound##pipeline from the Sound#destination, disconnecting each node.
+     */
+    protected _disconnectPipeline(): void;
+}
+
+export {};

package/src/client/audio/timeout.d.mts

@@ -0,0 +1,71 @@
+export interface AudioTimeoutOptions {
+    context?: AudioContext;
+    callback?: () => unknown;
+}
+
+/**
+ * A framework for scheduled audio events with more precise and synchronized timing than using window.setTimeout.
+ * This approach creates an empty audio buffer of the desired duration played using the shared game audio context.
+ * The onended event of the AudioBufferSourceNode provides a very precise way to synchronize audio events.
+ * For audio timing, this is preferable because it avoids numerous issues with window.setTimeout.
+ *
+ * @example Using a callback function
+ * ```js
+ * function playForDuration(sound, duration) {
+ *   sound.play();
+ *   const wait = new AudioTimeout(duration, {callback: () => sound.stop()})
+ * }
+ * ```
+ *
+ * @example Using an awaited Promise
+ * ```js
+ * async function playForDuration(sound, duration) {
+ *   sound.play();
+ *   const timeout = new AudioTimeout(delay);
+ *   await timeout.complete;
+ *   sound.stop();
+ * }
+ * ```
+ *
+ * @example Using the wait helper
+ * ```js
+ * async function playForDuration(sound, duration) {
+ *   sound.play();
+ *   await AudioTimeout.wait(duration);
+ *   sound.stop();
+ * }
+ * ```
+ */
+export default class AudioTimeout {
+    /**
+     * Create an AudioTimeout by providing a delay and callback.
+     * @param delayMS A desired delay timing in milliseconds
+     * @param options Additional options which modify timeout behavior
+     */
+    constructor(delayMS: number, options?: AudioTimeoutOptions);
+
+    /**
+     * Is the timeout complete?
+     * This can be used to await the completion of the AudioTimeout if necessary.
+     * The Promise resolves to the returned value of the provided callback function.
+     */
+    complete: Promise<unknown>;
+
+    /**
+     * Cancel an AudioTimeout by ending it early, rejecting its completion promise, and skipping any callback function.
+     */
+    cancel(): void;
+
+    /**
+     * End the timeout, either on schedule or prematurely. Executing any callback function
+     */
+    end(): void;
+
+    /**
+     * Schedule a task according to some audio timeout.
+     * @param delayMS A desired delay timing in milliseconds
+     * @param options Additional options which modify timeout behavior
+     * @returns A promise which resolves as a returned value of the callback or void
+     */
+    static wait(delayMS: number, options?: AudioTimeoutOptions): Promise<unknown>;
+}

package/src/client/av/_module.d.mts

@@ -0,0 +1,7 @@
+/** @module av */
+
+export * as clients from "./clients/_module.mjs";
+
+export { default as AVClient } from "./client.mjs";
+export { default as AVMaster } from "./master.mjs";
+export { default as AVSettings } from "./settings.mjs";