@league-of-foundry-developers/foundry-vtt-types 13.340.1 → 13.345.1-beta.20250704.94554

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

@@ -0,0 +1,509 @@
+import type { Brand, InexactPartial, MaybePromise, NullishProps, Identity } from "#utils";
+import type EventEmitterMixin from "#common/utils/event-emitter.d.mts";
+import type { AmbientSound } from "#client/canvas/placeables/_module.d.mts";
+
+declare namespace Sound {
+  interface Any extends AnySound {}
+  interface AnyConstructor extends Identity<typeof AnySound> {}
+
+  /** @internal */
+  type _ConstructorOptions = NullishProps<{
+    /**
+     * Force use of an AudioBufferSourceNode even if the audio duration is long
+     * @defaultValue `false`
+     */
+    forceBuffer: boolean;
+
+    /**
+     * A non-default audio context within which the sound should play
+     * @defaultValue `game.audio.music`
+     */
+    context: AudioContext;
+  }>;
+
+  interface ConstructorOptions extends _ConstructorOptions {}
+
+  type STATES = Brand<number, "Sound.STATES">;
+
+  interface States {
+    readonly FAILED: -1 & STATES;
+    readonly NONE: 0 & STATES;
+    readonly LOADING: 1 & STATES;
+    readonly LOADED: 2 & STATES;
+    readonly STARTING: 3 & STATES;
+    readonly PLAYING: 4 & STATES;
+    readonly PAUSED: 5 & STATES;
+    readonly STOPPING: 6 & STATES;
+    readonly STOPPED: 7 & STATES;
+  }
+
+  /** @internal */
+  type _LoadOptions = NullishProps<{
+    /**
+     * Automatically begin playback of the sound once loaded
+     * @defaultValue `false`
+     */
+    autoplay: boolean;
+  }> &
+    InexactPartial<{
+      /**
+       * Playback options passed to Sound#play, if autoplay
+       * @defaultValue `{}`
+       * @remarks Can't be `null` as it only has a parameter default
+       */
+      autoplayOptions: Sound.PlaybackOptions;
+    }>;
+
+  interface LoadOptions extends _LoadOptions {}
+
+  /**
+   * Since `Sound##playback` isn't exposed, this interface can *just* be accurate to what's allowable to pass
+   * to {@link Sound.play | `Sound#play`} or {@link Sound.stop | `#stop`}, which in reality is what's allowed
+   * by `Sound##configurePlayback`
+   *
+   * @internal
+   */
+  type _PlaybackOptions = NullishProps<{
+    /**
+     * A delay in seconds by which to delay playback
+     * @defaultValue `0`
+     * @remarks Unlike other properties of this interface, the above default is static.
+     */
+    delay: number;
+
+    /**
+     * A limited duration in seconds for which to play
+     * @defaultValue `undefined`
+     */
+    duration: number;
+
+    /**
+     * A duration in milliseconds over which to fade in playback
+     * @defaultValue `0`
+     * @remarks Unlike other properties of this interface, the above default is static.
+     */
+    fade: number;
+
+    /**
+     * Should sound playback loop?
+     * @defaultValue `false`
+     * @remarks The above default is true for initial calls, but the actual default
+     * value, if this is passed nullish or omitted, is whatever the current value is
+     */
+    loop: boolean;
+
+    /**
+     * Seconds of the AudioBuffer when looped playback should start. Only works for AudioBufferSourceNode.
+     * @defaultValue `0`
+     * @remarks The above default is true for initial calls, but the actual default
+     * value, if this is passed nullish or omitted, is whatever the current value is
+     */
+    loopStart: number;
+
+    /**
+     * Seconds of the Audio buffer when looped playback should restart. Only works for AudioBufferSourceNode.
+     * @defaultValue `undefined`
+     * @remarks The above default is true for initial calls, but the actual default
+     * value, if this is passed nullish or omitted, is whatever the current value is
+     */
+    loopEnd: number;
+
+    /**
+     * An offset in seconds at which to start playback
+     * @defaultValue `0`
+     * @remarks The above default is true for initial calls, but the actual default
+     * value, if this is passed nullish or omitted, is whatever the current value of
+     * `loopStart` is
+     */
+    offset: number;
+
+    /**
+     * A callback function attached to the source node
+     * @defaultValue `null`
+     * @remarks The above default is true for initial calls, but the actual default
+     * value, if this is passed nullish or omitted, is whatever the current value is
+     */
+    onended: ScheduleCallback | null;
+
+    /**
+     * The volume at which to play the sound
+     * @defaultValue `1.0`
+     * @remarks The above default is true for initial calls, but the actual default
+     * value, if this is passed nullish or omitted, is whatever the current value is
+     */
+    volume: number;
+  }>;
+
+  /** @remarks Default values here are what `Sound##configurePlayback` would use if passed an empty object with no prior calls */
+  interface PlaybackOptions extends _PlaybackOptions {}
+
+  /** @internal */
+  type _FadeOptions = InexactPartial<{
+    /**
+     * The duration of the fade effect in milliseconds
+     * @defaultValue `1000`
+     * @remarks Can't be `null` as it only has a parameter default
+     */
+    duration: number;
+
+    /**
+     * The type of fade easing, "linear" or "exponential"
+     * @defaultValue `"linear"`
+     * @remarks Can't be `null` as it only has a parameter default
+     */
+    type: "linear" | "exponential";
+  }> &
+    NullishProps<{
+      /**
+       * A volume level to start from, the current volume by default
+       * @defaultValue `this.gain.value`
+       */
+      from: number;
+    }>;
+
+  interface FadeOptions extends _FadeOptions {}
+
+  type ScheduleCallback = (sound: Sound) => MaybePromise<unknown>;
+}
+
+/**
+ * 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.
+ */
+declare class Sound extends EventEmitterMixin() {
+  /**
+   * 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
+   */
+  // options: not null (destructured)
+  constructor(src: string, options?: Sound.ConstructorOptions);
+
+  /**
+   * The sequence of container loading states.
+   */
+  static STATES: Sound.States;
+
+  /**
+   * The maximum duration, in seconds, for which an AudioBufferSourceNode will be used.
+   * Otherwise, a MediaElementAudioSourceNode will be used.
+   * @defaultValue `10 * 60;  // 10 Minutes`
+   */
+  static MAX_BUFFER_DURATION: number;
+
+  /**
+   * @defaultValue `["load", "play", "pause", "end", "stop"]`
+   */
+  static override emittedEvents: string[];
+
+  /**
+   * A unique integer identifier for this sound.
+   * @remarks Set via `Object.defineProperty` during construction, `writable: false, enumerable: true, configurable: false`
+   */
+  readonly id: number;
+
+  /**
+   * The audio source path.
+   * Either a relative path served by the running Foundry VTT game server or a remote URL.
+   * @remarks Set via `Object.defineProperty` during construction, `writable: false, enumerable: true, configurable: false`
+   */
+  readonly src: string;
+
+  /**
+   * The audio context within which this Sound is played.
+   * @remarks Can return `undefined` if no context was passed at construction *and* `game.audio.music` hasn't been initialized yet,
+   * which doesn't happen until the first sound is played
+   */
+  get context(): AudioContext | undefined;
+
+  /**
+   * The AudioSourceNode used to control sound playback.
+   * @remarks Returns `undefined` if the Sound has either not yet been played or has been stopped
+   */
+  get sourceNode(): AudioBufferSourceNode | MediaElementAudioSourceNode | undefined;
+
+  /**
+   * The GainNode used to control volume for this sound.
+   * @remarks Only `undefined` prior to first `play()`
+   */
+  gainNode: GainNode | undefined;
+
+  /**
+   * 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.
+   * @defaultValue `Sound.STATES.NONE`
+   */
+  protected _state: Sound.STATES;
+
+  /**
+   * 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.
+   * @remarks `undefined` if {@link Sound.gainNode | `Sound#gainNode`} is.
+   */
+  get gain(): AudioParam | undefined;
+
+  /**
+   * The AudioNode destination which is the output target for the Sound.
+   * @remarks Only `undefined` prior to first `play()`
+   */
+  destination: AudioNode | undefined;
+
+  /**
+   * 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: number);
+
+  /**
+   * The time in seconds at which playback was started.
+   * @remarks `undefined` if the Sound has either not yet been played or has been stopped
+   */
+  startTime: number | undefined;
+
+  /**
+   * The time in seconds at which playback was paused.
+   * @remarks `undefined` until the Sound is paused, and after the Sound is stopped or playback has been resumed
+   */
+  pausedTime: number | undefined;
+
+  /**
+   * The total duration of the audio source in seconds.
+   * @remarks `undefined` if the sound isn't loaded yet, or if the sourceNode type is element and also doesn't exist
+   */
+  get duration(): number | undefined;
+
+  /**
+   * The current playback time of the sound.
+   * @remarks `undefined` if the Sound has either not yet been played or has been stopped
+   */
+  get currentTime(): number | undefined;
+
+  /**
+   * Is the sound looping?
+   */
+  get loop(): boolean;
+
+  set loop(value);
+
+  /**
+   * An internal reference to some object which is managing this Sound instance.
+   * @defaultValue `null`
+   * @remarks Foundry marked `@internal`
+   *
+   * Only ever set *or* read externally by core, so not protected
+   *
+   * @privateRemarks Foundry types this as `Object|null` but the only place in Core this gets set is in `AmbientSound`, to `this`
+   */
+  _manager: AmbientSound.Implementation | null;
+
+  /**
+   * 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
+   * @returns A Promise which resolves to the Sound once it is loaded
+   */
+  // options: not null (destructured)
+  load(options?: Sound.LoadOptions): 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?: Sound.PlaybackOptions): Promise<this>;
+
+  /**
+   * @deprecated since v12, until v14
+   * @remarks "`Sound#play` now takes an object of playback options instead of positional arguments."
+   */
+  play(offset: number, onended?: Sound.ScheduleCallback | null): 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.
+   * @throws If called while the Sound isn't playing
+   */
+  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)
+   */
+  // options: not null (parameter default only, destructured where forwarded)
+  stop(options?: Sound.PlaybackOptions): 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
+   * @returns A Promise that resolves after the requested fade duration
+   */
+  // options: not null (destructured)
+  fade(volume: number, options?: Sound.FadeOptions): 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<R extends Sound.ScheduleCallback>(fn: R, playbackTime: number): Promise<Awaited<ReturnType<R>>>;
+
+  /**
+   * 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;
+
+  /**
+   * 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;
+
+  /**
+   * @deprecated since v12, will be removed in v14
+   * @remarks "`AudioContainer.LOAD_STATES` is deprecated in favor of {@linkcode Sound.STATES}"
+   */
+  static get LOAD_STATES(): Sound.States;
+
+  /**
+   * @deprecated since v12, will be removed in v14
+   * @remarks "`AudioContainer#loadState` is deprecated in favor of {@link Sound._state | `Sound#_state`}"
+   */
+  get loadState(): Sound.STATES;
+
+  /**
+   * @deprecated since v12, will be removed in v14
+   * @remarks "`Sound#container` is deprecated without replacement because the `Sound` and `AudioContainer` classes are now merged"
+   */
+  get container(): this;
+
+  /**
+   * @deprecated since v12, will be removed in v14
+   * @remarks "`Sound#node` is renamed {@link Sound.sourceNode | `Sound#sourceNode`}"
+   */
+  get node(): this["sourceNode"];
+
+  /**
+   * @deprecated since v12, will be removed in v14
+   * @remarks "`Sound#on` is deprecated in favor of {@link Sound.addEventListener | `Sound#addEventListener`}"
+   */
+  on(eventName: string, fn: EventEmitterMixin.EventListener, options?: EventEmitterMixin.AddListenerOptions): void;
+
+  /**
+   * @deprecated since v12, will be removed in v14
+   * @remarks "`Sound#off` is deprecated in favor of {@link Sound.removeEventListener | `Sound#removeEventListener`}"
+   */
+  off(eventName: string, fn: EventEmitterMixin.EventListener): void;
+
+  /**
+   * @deprecated since v12, will be removed in v14
+   * @remarks "`Sound#emit` is deprecated in favor of {@link Sound.dispatchEvent | `Sound#dispatchEvent`}"
+   *
+   * This method still takes a string, then creates an `Event` with it and passes that along to `dispatchEvent`
+   */
+  emit(eventName: string): void;
+}
+
+export default Sound;
+
+declare abstract class AnySound extends Sound {
+  constructor(...args: never);
+}

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

@@ -0,0 +1,101 @@
+import type { Identity, NullishProps } from "#utils";
+
+/**
+ * A special error class used for cancellation.
+ * @privateRemarks Yes this is a straight up empty class extension by Foundry used exclusively internally
+ */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+declare class AudioTimeoutCancellation extends Error {}
+
+/**
+ * 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();
+ * }
+ * ```
+ */
+declare class AudioTimeout<CallbackReturn = undefined> {
+  /**
+   * 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
+   */
+  // options: not null (destructured)
+  constructor(delayMS: number, options?: AudioTimeout.ConstructorOptions<CallbackReturn>);
+
+  /**
+   * 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<CallbackReturn> | undefined;
+
+  /**
+   * 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
+   */
+  // options: not null (destructured where forwarded)
+  static wait<CallbackReturn = undefined>(
+    delayMS: number,
+    options?: AudioTimeout.ConstructorOptions<CallbackReturn>,
+  ): Promise<CallbackReturn>;
+}
+
+declare namespace AudioTimeout {
+  interface Any extends AnyAudioTimeout {}
+  interface AnyConstructor extends Identity<typeof AnyAudioTimeout> {}
+
+  /** @internal */
+  type _ConstructorOptions<Return = undefined> = NullishProps<{
+    /** @defaultValue `game.audio.music` */
+    context: AudioContext;
+
+    callback: () => Return;
+  }>;
+
+  interface ConstructorOptions<Return = undefined> extends _ConstructorOptions<Return> {}
+}
+
+export default AudioTimeout;
+
+declare abstract class AnyAudioTimeout extends AudioTimeout<unknown> {
+  constructor(...args: never);
+}