@league-of-foundry-developers/foundry-vtt-types 13.346.0-beta.20250825015921 → 13.346.0-beta.20250825020008

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@league-of-foundry-developers/foundry-vtt-types",
-  "version": "13.346.0-beta.20250825015921",
+  "version": "13.346.0-beta.20250825020008",
   "description": "TypeScript type definitions for Foundry VTT",
   "type": "module",
   "types": "./src/index.d.mts",

package/src/configuration/configuration.d.mts

@@ -295,9 +295,9 @@ export interface SettingConfig {
   "core.disableResolutionScaling": boolean;
   "core.fontSize": number;
   "core.fpsMeter": boolean;
-  "core.globalAmbientVolume": number;
-  "core.globalInterfaceVolume": number;
-  "core.globalPlaylistVolume": number;
+  "core.globalAmbientVolume": fields.AlphaField<{ required: true; initial: 0.5 }>;
+  "core.globalInterfaceVolume": fields.AlphaField<{ required: true; initial: 0.5 }>;
+  "core.globalPlaylistVolume": fields.AlphaField<{ required: true; initial: 0.5 }>;
   "core.keybindings": Record<string, foundry.helpers.interaction.ClientKeybindings.KeybindingActionBinding[]>;
   "core.language": fields.StringField<{
     required: true;

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

@@ -16,3 +16,14 @@ type SoundCreationOptions = foundry.audio.AudioHelper.SoundCreationOptions;
 type SoundPlaybackOptions = foundry.audio.Sound.PlaybackOptions;
 
 type SoundScheduleCallback = foundry.audio.Sound.ScheduleCallback;
+
+type AnalysisDataValue = foundry.audio.AudioHelper.AnalysisDataValue;
+
+type AnalysisData = foundry.audio.AudioHelper.AnalysisData;
+
+type ContextName = foundry.audio.AudioHelper.ContextName;
+
+type BandName = foundry.audio.AudioHelper.BandName;
+
+/** @privateRemarks We have no implementation of this type to point to because it is completely unused by core as of 13.347 */
+type AnalysisNodes = unknown;

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

@@ -1,4 +1,4 @@
-import type { Identity, InexactPartial, NullishProps } from "#utils";
+import type { Identity, InexactPartial } from "#utils";
 
 /**
  * A sound effect which applies a biquad filter.
@@ -9,7 +9,6 @@ declare class BiquadFilterEffect extends BiquadFilterNode {
    * @param context - The audio context required by the BiquadFilterNode
    * @param options - Additional options which modify the BiquadFilterEffect behavior
    */
-  // options: not null (destructured)
   constructor(context: AudioContext, options?: BiquadFilterEffect.ConstructorOptions);
 
   /**
@@ -22,10 +21,12 @@ declare class BiquadFilterEffect extends BiquadFilterNode {
   /**
    * Update the state of the effect node given the active flag and numeric intensity.
    * @param options - Options which are updated
-   * @throws If `type` is set to any value in {@link BiquadFilterEffect.AllowedFilterType} other than `"highpass"` or `"lowpass"`
+   * @remarks
+   * @throws If `type` is set to any value in {@linkcode BiquadFilterEffect.AllowedFilterType} other than `"highpass"` or `"lowpass"`
    */
-  // options: not null (destructured)
   update(options?: BiquadFilterEffect.UpdateOptions): void;
+
+  #BiquadFilterEffect: true;
 }
 
 declare namespace BiquadFilterEffect {
@@ -56,16 +57,13 @@ declare namespace BiquadFilterEffect {
     /**
      * The initial intensity of the effect
      * @defaultValue `5`
-     * @remarks Can't be `null` as it only has a parameter default
      */
     intensity: number;
 
     /**
      * The filter type to apply
      * @defaultValue `"lowpass"`
-     * @remarks Can't be `null` as it only has a parameter default.
-     *
-     * Only allows a subset of {@linkcode BiquadFilterType}s
+     * @remarks Only allows a subset of {@linkcode BiquadFilterType}s
      */
     type: AllowedFilterType;
   }>;
@@ -77,7 +75,7 @@ declare namespace BiquadFilterEffect {
    */
   interface ConstructorOptions extends _ConstructorOptions, Omit<BiquadFilterOptions, "type"> {}
 
-  type _UpdateOptions = NullishProps<{
+  type _UpdateOptions = InexactPartial<{
     /**
      * A new effect intensity
      * @remarks This is ignored if it fails a `Number.isFinite` check

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

@@ -4,7 +4,7 @@ import type { Identity } from "#utils";
  * A specialized cache used for audio buffers.
  * This is an LRU cache which expires buffers from the cache once the maximum cache size is exceeded.
  */
-declare class AudioBufferCache extends Map {
+declare class AudioBufferCache extends Map<string, AudioBufferCache.Entry> {
   /**
    * Construct an AudioBufferCache providing a maximum disk size beyond which entries are expired.
    * @param cacheSize - The maximum cache size in bytes. 1GB by default.
@@ -42,10 +42,11 @@ declare class AudioBufferCache extends Map {
    * @param src    - The audio buffer source path
    * @param locked - Lock the buffer, preventing its expiration?
    */
-  // locked: not null (put directly into an Entry)
   lock(src: string, locked?: boolean): void;
 
   override toString(): string;
+
+  #AudioBufferCache: true;
 }
 
 declare namespace AudioBufferCache {

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

@@ -1,4 +1,4 @@
-import type { Identity, InexactPartial, NullishProps } from "#utils";
+import type { Identity, InexactPartial } from "#utils";
 
 declare namespace ConvolverEffect {}
 
@@ -16,7 +16,6 @@ declare class ConvolverEffect extends ConvolverNode {
    * @param context - The audio context required by the ConvolverNode
    * @param options - Additional options which modify the ConvolverEffect behavior
    */
-  // options: not null (destructured)
   constructor(context: AudioContext, options?: ConvolverEffect.ConstructorOptions);
 
   /**
@@ -30,7 +29,6 @@ declare class ConvolverEffect extends ConvolverNode {
    * Update the state of the effect node given the active flag and numeric intensity.
    * @param options - Options which are updated
    */
-  // options: not null (destructured)
   update(options?: ConvolverEffect.UpdateOptions): void;
 
   /** @privateRemarks This override only does side effects then forwards args to super, no type changes */
@@ -61,14 +59,12 @@ declare namespace ConvolverEffect {
     /**
      * The file path to the impulse response buffer to use
      * @defaultValue `"sounds/impulse-responses/ir-full.wav"`
-     * @remarks Can't be `null` as it only has a parameter default
      */
     impulseResponsePath: string;
 
     /**
      * The initial intensity of the effect
      * @defaultValue `5`
-     * @remarks Can't be `null` as it only has a parameter default
      */
     intensity: number;
   }>;
@@ -76,7 +72,7 @@ declare namespace ConvolverEffect {
   interface ConstructorOptions extends _ConstructorOptions, ConvolverOptions {}
 
   /** @internal */
-  type _UpdateOptions = NullishProps<{
+  type _UpdateOptions = InexactPartial<{
     /**
      * A new effect intensity
      * @remarks This is ignored if it fails a `Number.isFinite` check

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

@@ -1,16 +1,37 @@
 import type Sound from "./sound.d.mts";
 import type AudioBufferCache from "./cache.d.mts";
-import type { Identity, InexactPartial, IntentionalPartial, NullishProps, ValueOf } from "#utils";
+import type { Identity, InexactPartial, ValueOf } from "#utils";
 
 /**
  * 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 Game.audio | `Game#audio`}
+ * @see {@linkcode Game.audio | Game#audio}
  */
 declare class AudioHelper {
+  /** @remarks Construction will throw if {@linkcode Game.audio | game.audio} is already instantiated */
   constructor();
 
+  /**
+   * Analyzers for each context, plus an internal ticker. Each context key holds data about its {@linkcode AnalyserNode},
+   * a {@linkcode Float32Array} for FFT data, and so on.
+   * @defaultValue
+   * ```js
+   * Object.seal({
+   *   music: {active: false, node: null, dataArray: null, lastUsed: 0, db: {}, bands: {}},
+   *   environment: {active: false, node: null, dataArray: null, lastUsed: 0, db: {}, bands: {}},
+   *   interface: {active: false, node: null, dataArray: null, lastUsed: 0, db: {}, bands: {}},
+   *   analysisLoopActive: false
+   * });
+   * ```
+   */
+  analyzer: AudioHelper.AnalysisData;
+
+  /**
+   * An array containing all possible audio context names.
+   */
+  static AUDIO_CONTEXTS: ReadonlyArray<AudioHelper.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.
@@ -41,7 +62,7 @@ declare class AudioHelper {
    * Once a gesture is observed, we begin playing all elements of this Array.
    * @see {@linkcode Sound}
    * @defaultValue `[]`
-   * @remarks Foundry only populates this in one place, {@link SoundsLayer.refresh | `SoundsLayer#refresh`}
+   * @remarks Foundry only populates this in one place, {@linkcode SoundsLayer.refresh | SoundsLayer#refresh}
    */
   pending: (() => void)[];
 
@@ -59,29 +80,36 @@ declare class AudioHelper {
 
   /**
    * A singleton audio context used for playback of music
-   * @remarks Not initialized to a value, set in {@link AudioHelper._onFirstGesture | `AudioHelper#_onFirstGesture`};
-   * In practice, `undefined` until the first audio is played after page load
+   * @remarks Not initialized to a value, set in `AudioHelper##onFirstGesture`. In practice, this is `undefined` until
+   * the first audio is played after page load.
    */
   music: AudioContext | undefined;
 
   /**
    * A singleton audio context used for playback of environmental audio.
-   * @remarks Not initialized to a value, set in {@link AudioHelper._onFirstGesture | `AudioHelper#_onFirstGesture`};
-   * In practice, `undefined` until the first audio is played after page load
+   * @remarks Not initialized to a value, set in `AudioHelper##onFirstGesture`. In practice, this is `undefined` until
+   * the first audio is played after page load.
    */
   environment: AudioContext | undefined;
 
   /**
    * A singleton audio context used for playback of interface sounds and effects.
-   * @remarks Not initialized to a value, set in {@link AudioHelper._onFirstGesture | `AudioHelper#_onFirstGesture`};
-   * In practice, `undefined` until the first audio is played after page load
+   * @remarks Not initialized to a value, set in `AudioHelper##onFirstGesture`. In practice, this is `undefined` until
+   * the first audio is played after page load.
    */
   interface: AudioContext | undefined;
 
   /**
    * For backwards compatibility, AudioHelper#context refers to the context used for music playback.
    */
-  get context(): AudioContext | undefined;
+  get context(): this["music"];
+
+  /**
+   * A global mute which suppresses all 3 audio channels.
+   */
+  get globalMute(): boolean;
+
+  set globalMute(muted);
 
   /**
    * A singleton cache used for audio buffers.
@@ -115,7 +143,6 @@ declare class AudioHelper {
    * @param options - Additional options which configure playback
    * @returns The created Sound which is now playing
    */
-  // options: not null (destructured)
   play(src: string, options?: AudioHelper.PlayOptions): Promise<Sound>;
 
   /**
@@ -146,18 +173,18 @@ declare class AudioHelper {
   /**
    * Play a one-off sound effect which is not part of a Playlist
    *
-   * @param data - An object configuring the audio data to play
-   * @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 should receive the event.
-   * @returns A Sound instance which controls audio playback.
+   * @param data          - An object configuring the audio data to play
+   * @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
-   * ```typescript
+   * ```js
    * AudioHelper.play({src: "sounds/lock.wav", volume: 0.8, loop: false}, true);
    * ```
    */
-  static play(data: AudioHelper.PlayData, socketOptions?: boolean | AudioHelper.SocketOptions | null): Promise<Sound>;
+  static play(data: AudioHelper.PlayData, socketOptions?: boolean | AudioHelper.SocketOptions): Promise<Sound | void>;
 
   /**
    * Begin loading the sound for a provided source URL adding its
@@ -183,6 +210,12 @@ declare class AudioHelper {
    */
   static volumeToInput(volume: number, order?: number): number;
 
+  /**
+   * Converts a volume level to a human-readable percentage value.
+   * @param volume - Value in the interval [0, 1] of the volume level.
+   */
+  static volumeToPercentage(volume: number, options?: AudioHelper.VolumeToPercentageOptions): string;
+
   /**
    * Returns a singleton AudioContext if one can be created.
    * An audio context may not be available due to limited resources or browser compatibility
@@ -207,7 +240,6 @@ declare class AudioHelper {
    * @param smoothing - The smoothingTimeConstant to set on the audio analyser. (default: `0.1`)
    * @returns Returns whether listening to the stream was successful
    */
-  // interval, smoothing: not null (parameter default only)
   startLevelReports(
     id: string,
     stream: MediaStream,
@@ -224,13 +256,8 @@ declare class AudioHelper {
    */
   stopLevelReports(id: string): void;
 
-  /**
-   * Handle the first observed user gesture
-   * @param event   - The mouse-move event which enables playback
-   * @param resolve - The Promise resolution function
-   * @internal
-   */
-  protected _onFirstGesture(event: Event, resolve: () => void): void;
+  /** @deprecated Made hard private in v13. This warning will be removed in v14. */
+  protected _onFirstGesture(event: never, resolve: never): never;
 
   /**
    * Log a debugging message if the audio debugging flag is enabled.
@@ -239,22 +266,62 @@ declare class AudioHelper {
   debug(message: string): void;
 
   /**
-   * @deprecated since v12, will be removed in v14
-   * @remarks "`AudioHelper#getCache` is deprecated in favor of {@link AudioBufferCache | `AudioHelper#buffers#get`}"
+   * 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)
+   * @defaultValue `1000`
+   */
+  static ANALYSIS_TIMEOUT_MS: number;
+
+  /**
+   * Enable the analyzer for a given context (`music`, `environment`, `interface`), attaching an {@linkcode AnalyserNode} to its gain node if not already active.
+   */
+  enableAnalyzer(contextName: AudioHelper.ContextName, options?: AudioHelper.EnableAnalyzerOptions): void;
+
+  /**
+   * Disable the analyzer for a given context, disconnecting the {@linkcode AnalyserNode}.
+   */
+  disableAnalyzer(contextName: AudioHelper.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 {@linkcode 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).
+   * @returns The normalized band value in [0,1].
+   */
+  getBandLevel(
+    contextName: AudioHelper.ContextName,
+    bandName: AudioHelper.BandName,
+    options?: AudioHelper.GetBandLevelOptions,
+  ): 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. (default: `"all"`)
+   * @returns A number in the [0,1] range representing the loudest band value among the three contexts.
+   */
+  getMaxBandLevel(band?: AudioHelper.BandName, options?: AudioHelper.GetMaxBandLevelOptions): number;
+
+  /**
+   * @deprecated "`AudioHelper#getCache` is deprecated in favor of {@linkcode AudioBufferCache | AudioHelper#buffers#get}" (since v12, until v14)
    */
   getCache(src: string): AudioBuffer | undefined;
 
   /**
-   * @deprecated since v12, will be removed in v14
-   * @remarks "`AudioHelper#updateCache` is deprecated without replacement"
+   * @deprecated "`AudioHelper#updateCache` is deprecated without replacement" (since v12, until v14)
    */
   updateCache(src: string, playing: boolean): void;
 
   /**
-   * @deprecated since v12, will be removed in v14
-   * @remarks "`AudioHelper#setCache` is deprecated in favor of {@link AudioBufferCache | `AudioHelper#buffers#set`}"
+   * @deprecated "`AudioHelper#setCache` is deprecated in favor of {@linkcode AudioBufferCache |`AudioHelper#buffers#set}" (since v12, until v14)
    */
   setCache(src: string, buffer: AudioBuffer): void;
+
+  #AudioHelper: true;
 }
 
 declare namespace AudioHelper {
@@ -263,41 +330,109 @@ declare namespace AudioHelper {
 
   type AUDIO_MIME_TYPES = ValueOf<typeof CONST.AUDIO_FILE_EXTENSIONS>;
 
+  interface AnalysisDataValueDB {
+    /** Average dB in ~20-200 Hz */
+    bass: number;
+
+    /** Average dB in ~200-2000 Hz */
+    mid: number;
+
+    /** Average dB in ~2000-8000 Hz */
+    treble: number;
+
+    /** Average dB in ~20-20000 Hz */
+    all: number;
+  }
+
+  interface AnalysisDataValueBands {
+    /** Normalized amplitude for low frequencies. */
+    bass: number;
+
+    /** Normalized amplitude for midrange frequencies. */
+    mid: number;
+
+    /** Normalized amplitude for high frequencies. */
+    treble: number;
+
+    /** Normalized amplitude for the entire audible range. */
+    all: number;
+  }
+
+  interface AnalysisDataValue {
+    /** Whether the analyzer is currently active. */
+    active: boolean;
+
+    /** If true, the analyzer remains active and will not be disabled after inactivity */
+    keepAlive: boolean;
+
+    /** The {@linkcode AnalyserNode} for this context, or `null` if inactive. */
+    node: AnalyserNode | null;
+
+    /** The FFT frequency data buffer used by the {@linkcode AnalyserNode}. */
+    dataArray: Float32Array | null;
+
+    /** Raw average decibel values for each frequency band. */
+    db: AnalysisDataValueDB;
+
+    /** Normalized [0,1] values for the same bands. */
+    bands: AnalysisDataValueBands;
+
+    /** The timestamp when data was last requested. */
+    lastUsed: number;
+  }
+
+  interface AnalysisData {
+    /** Analysis data for the music context. */
+    music: AnalysisDataValue;
+
+    /** Analysis data for the ambient/environment context. */
+    environment: AnalysisDataValue;
+
+    /** Analysis data for the interface context. */
+    interface: AnalysisDataValue;
+
+    /** Whether the internal RAQ loop is currently running. */
+    analysisLoopActive: boolean;
+  }
+
+  /** @privateRemarks Foundry has this in a `_types` as a union of literals, but it lines up with `AUDIO_CHANNELS` so is typed thusly */
+  type ContextName = keyof typeof CONST.AUDIO_CHANNELS;
+
+  type BandName = keyof AnalysisDataValueBands;
+
   /** @internal */
   type _SoundCreationOptions = InexactPartial<{
     /**
      * Additional options passed to the play method if autoplay is true
      * @defaultValue `{}`
-     * @remarks Can't be `null` as it only has a parameter default
      */
     autoplayOptions: Sound.PlaybackOptions;
-  }> &
-    NullishProps<{
-      /**
-       * A specific AudioContext to attach the sound to
-       * @remarks Has no default, but if it's falsey, the {@linkcode Sound} constructor
-       * (where this is forwarded) will use {@link AudioHelper.music | `game.audio.music`} instead
-       */
-      context: AudioContext;
-
-      /**
-       * Reuse an existing Sound for this source?
-       * @defaultValue `true`
-       */
-      singleton: boolean;
-
-      /**
-       * Begin loading the audio immediately?
-       * @defaultValue `false`
-       */
-      preload: boolean;
-
-      /**
-       * Begin playing the audio as soon as it is ready?
-       * @defaultValue `false`
-       */
-      autoplay: boolean;
-    }>;
+
+    /**
+     * A specific AudioContext to attach the sound to
+     * @remarks Has no default, but if it's falsey, the {@linkcode Sound} constructor
+     * (where this is forwarded) will use {@linkcode AudioHelper.music | game.audio.music} instead
+     */
+    context: AudioContext;
+
+    /**
+     * Reuse an existing Sound for this source?
+     * @defaultValue `true`
+     */
+    singleton: boolean;
+
+    /**
+     * Begin loading the audio immediately?
+     * @defaultValue `false`
+     */
+    preload: boolean;
+
+    /**
+     * Begin playing the audio as soon as it is ready?
+     * @defaultValue `false`
+     */
+    autoplay: boolean;
+  }>;
 
   interface SoundCreationOptions extends _SoundCreationOptions {
     /** The source URL for the audio file */
@@ -305,18 +440,39 @@ declare namespace AudioHelper {
   }
 
   /**
-   * {@linkcode AudioHelper#play} pulls `context` out of this object then forwards the rest to {@link Sound.play | `Sound#play`}
+   * {@linkcode AudioHelper#play} pulls `context` out of this object then forwards the rest to {@linkcode Sound.play | Sound#play}
    */
   interface PlayOptions extends Pick<SoundCreationOptions, "context">, Sound.PlaybackOptions {}
 
   /** @internal */
-  type _PlayData = IntentionalPartial<{
+  type _PlayData = InexactPartial<{
     /**
-     * An audio channel in CONST.AUDIO_CHANNELS where the sound should play
+     * The volume level at which to play the audio, between 0 and 1.
+     * @defaultValue `1.0`
+     * @privateRemarks Despite the initial default being via `mergeObject`, there's a second `??` default so it's allowed to be nullish
+     */
+    volume: number;
+
+    /**
+     * Loop the audio effect and continue playing it until it is manually stopped.
+     * @defaultValue `false`
+     * @privateRemarks Despite the default being via `mergeObject`, {@linkcode Sound.PlaybackOptions.loop | Sound.PlaybackOptions["loop"]} can be nullish, therefor so can this
+     */
+    loop: boolean;
+  }>;
+
+  interface PlayData extends _PlayData {
+    /**
+     * The audio source file path, either a public URL or a local path relative to the public directory
+     */
+    src: string;
+
+    /**
+     * An audio channel in {@linkcode CONST.AUDIO_CHANNELS} where the sound should play
      * @defaultValue `"interface"`
      * @remarks Can't be nullish as the only default is provided by `mergeObject`
      */
-    channel: keyof typeof CONST.AUDIO_CHANNELS;
+    channel?: AudioHelper.ContextName;
 
     /**
      * Begin playback of the audio effect immediately once it is loaded.
@@ -329,29 +485,7 @@ declare namespace AudioHelper {
      *
      * "// Backwards compatibility, if autoplay was passed as false take no further action"
      */
-    autoplay: false;
-  }> &
-    NullishProps<{
-      /**
-       * The volume level at which to play the audio, between 0 and 1.
-       * @defaultValue `1.0`
-       * @privateRemarks Despite the initial default being via `mergeObject`, there's a second `??` default so it's allowed to be nullish
-       */
-      volume: number;
-
-      /**
-       * Loop the audio effect and continue playing it until it is manually stopped.
-       * @defaultValue `false`
-       * @privateRemarks Despite the default being via `mergeObject`, {@link Sound.PlaybackOptions.loop | `Sound.PlaybackOptions["loop"]`} can be nullish, therefor so can this
-       */
-      loop: boolean;
-    }>;
-
-  interface PlayData extends _PlayData {
-    /**
-     * The audio source file path, either a public URL or a local path relative to the public directory
-     */
-    src: string;
+    autoplay?: false;
   }
 
   interface SocketOptions {
@@ -362,6 +496,48 @@ declare namespace AudioHelper {
     recipients?: string[];
   }
 
+  /** @internal */
+  type _VolumeToPercentageOptions = InexactPartial<{
+    /**
+     * 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-value` text attribute.
+     * @defaultValue `false`
+     */
+    label: boolean;
+
+    /**
+     * The number of decimal places to round the percentage to.
+     * @defaultValue `0`
+     */
+    decimalPlaces: number;
+  }>;
+
+  interface VolumeToPercentageOptions extends _VolumeToPercentageOptions {}
+
+  /** @internal */
+  type _EnableAnalyzerOptions = InexactPartial<{
+    /**
+     * If true, this analyzer will not auto-disable after inactivity.
+     * @defaultValue `false`
+     */
+    keepAlive: boolean;
+  }>;
+
+  interface EnableAnalyzerOptions extends _EnableAnalyzerOptions {}
+
+  /** @internal */
+  type _GetBandLevelOptions = InexactPartial<{
+    /**
+     * If true, remove the real-time channel volume from the measurement.
+     * @defaultValue `false`
+     */
+    ignoreVolume: boolean;
+  }>;
+
+  interface GetBandLevelOptions extends _GetBandLevelOptions {}
+
+  interface GetMaxBandLevelOptions extends _GetBandLevelOptions {}
+
   type LevelReportCallback = (maxDecibel: number, fftArray: Float32Array) => void;
 }
 

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

@@ -1,13 +1,16 @@
-import type { Brand, InexactPartial, MaybePromise, NullishProps, Identity } from "#utils";
+import type { Brand, InexactPartial, MaybePromise, Identity, IntentionalPartial } from "#utils";
 import type EventEmitterMixin from "#common/utils/event-emitter.d.mts";
 import type { AmbientSound } from "#client/canvas/placeables/_module.d.mts";
+import type { Canvas } from "#client/canvas/_module.d.mts";
+import type { PointSoundSource } from "#client/canvas/sources/_module.d.mts";
+import type { AudioTimeout } from "./_module.d.mts";
 
 declare namespace Sound {
   interface Any extends AnySound {}
   interface AnyConstructor extends Identity<typeof AnySound> {}
 
   /** @internal */
-  type _ConstructorOptions = NullishProps<{
+  type _ConstructorOptions = InexactPartial<{
     /**
      * Force use of an AudioBufferSourceNode even if the audio duration is long
      * @defaultValue `false`
@@ -38,21 +41,19 @@ declare namespace Sound {
   }
 
   /** @internal */
-  type _LoadOptions = NullishProps<{
+  type _LoadOptions = InexactPartial<{
     /**
      * 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;
-    }>;
+
+    /**
+     * Playback options passed to Sound#play, if autoplay
+     * @defaultValue `{}`
+     */
+    autoplayOptions: Sound.PlaybackOptions;
+  }>;
 
   interface LoadOptions extends _LoadOptions {}
 
@@ -60,10 +61,9 @@ declare namespace Sound {
    * 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<{
+  type _PlaybackOptions = InexactPartial<{
     /**
      * A delay in seconds by which to delay playback
      * @defaultValue `0`
@@ -87,49 +87,54 @@ declare namespace Sound {
     /**
      * 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
+     * @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 in `this##playback`
+     * is, unless this is part of a {@linkcode foundry.canvas.layers.SoundsLayer.playAtPosition | SoundsLayer#playAtPosition} call, as that method always creates a new sound with
+     * no playback history
      */
     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
+     * @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 in `this##playback`
+     * is, unless this is part of a {@linkcode foundry.canvas.layers.SoundsLayer.playAtPosition | SoundsLayer#playAtPosition} call, as that method always creates a new sound with
+     * no playback history
      */
     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
+     * @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 in `this##playback`
+     * is, unless this is part of a {@linkcode foundry.canvas.layers.SoundsLayer.playAtPosition | SoundsLayer#playAtPosition} call, as that method always creates a new sound with
+     * no playback history
      */
     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
+     * @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` in
+     * `this##playback` is, unless this is part of a {@linkcode foundry.canvas.layers.SoundsLayer.playAtPosition | SoundsLayer#playAtPosition} call, as that method always creates
+     * a new sound with no playback history
      */
     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
+     * @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 in `this##playback`
+     * is, unless this is part of a {@linkcode foundry.canvas.layers.SoundsLayer.playAtPosition | SoundsLayer#playAtPosition} call, as that method always creates a new sound with
+     * no playback history
      */
     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
+     * @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 in `this##playback`
+     * is, unless this is part of a {@linkcode foundry.canvas.layers.SoundsLayer.playAtPosition | SoundsLayer#playAtPosition} call, as that method always creates a new sound with
+     * no playback history
      */
     volume: number;
   }>;
@@ -137,29 +142,78 @@ declare namespace Sound {
   /** @remarks Default values here are what `Sound##configurePlayback` would use if passed an empty object with no prior calls */
   interface PlaybackOptions extends _PlaybackOptions {}
 
+  /** @remarks `volume` is always overwritten in {@linkcode Sound.playAtPosition | Sound#playAtPosition}  */
+  interface PlaybackOptionsPositional extends Omit<PlaybackOptions, "volume"> {}
+
+  /** @remarks The keys omitted are generated from other data passed to {@linkcode Sound.playAtPosition | Sound#playAtPosition} */
+  interface PartialSourceData
+    extends IntentionalPartial<Omit<PointSoundSource.SourceData, "x" | "y" | "elevation" | "radius" | "walls">> {}
+
+  /** @internal */
+  type _PlayAtPositionOptions = InexactPartial<{
+    /**
+     * The maximum volume at which the effect should be played
+     * @defaultValue `1.0`
+     */
+    volume: number;
+
+    /**
+     * Should volume be attenuated by distance?
+     * @defaultValue `true`
+     */
+    easing: boolean;
+
+    /**
+     * Should the sound be constrained by walls?
+     * @defaultValue `true`
+     */
+    walls: boolean;
+
+    /**
+     * Should the sound always be played for GM users regardless of actively controlled tokens?
+     * @defaultValue `true`
+     */
+    gmAlways: boolean;
+
+    /** A base sound effect to apply to playback */
+    baseEffect: AmbientSoundDocument.Effect;
+
+    /** A muffled sound effect to apply to playback, a sound may only be muffled if it is not constrained by walls */
+    muffledEffect: AmbientSoundDocument.Effect;
+
+    /**
+     * Additional data passed to the SoundSource constructor
+     */
+    sourceData: Sound.PartialSourceData;
+
+    /**
+     * Additional options passed to {@linkcode Sound.play | Sound#play}
+     */
+    playbackOptions: Sound.PlaybackOptionsPositional;
+  }>;
+
+  interface PlayAtPositionOptions extends _PlayAtPositionOptions {}
+
   /** @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;
-    }>;
+
+    /**
+     * A volume level to start from, the current volume by default
+     * @defaultValue `this.gain.value`
+     */
+    from: number;
+  }>;
 
   interface FadeOptions extends _FadeOptions {}
 
@@ -177,7 +231,6 @@ declare class Sound extends EventEmitterMixin() {
    * @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);
 
   /**
@@ -241,7 +294,7 @@ declare class Sound extends EventEmitterMixin() {
 
   /**
    * The life-cycle state of the sound.
-   * @defaultValue `Sound.STATES.NONE`
+   * @defaultValue {@linkcode Sound.STATES.NONE}
    */
   protected _state: Sound.STATES;
 
@@ -268,7 +321,7 @@ declare class Sound extends EventEmitterMixin() {
 
   /**
    * A convenience reference to the GainNode gain audio parameter.
-   * @remarks `undefined` if {@link Sound.gainNode | `Sound#gainNode`} is.
+   * @remarks `undefined` if {@linkcode Sound.gainNode | Sound#gainNode} is.
    */
   get gain(): AudioParam | undefined;
 
@@ -325,11 +378,8 @@ declare class Sound extends EventEmitterMixin() {
   /**
    * 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`
+   * @internal
+   * @remarks Only ever set *or* read externally by core, so not protected
    */
   _manager: AmbientSound.Implementation | null;
 
@@ -338,14 +388,12 @@ declare class Sound extends EventEmitterMixin() {
    * @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>;
 
@@ -359,11 +407,60 @@ declare class Sound extends EventEmitterMixin() {
   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."
+   * @deprecated "`Sound#play` now takes an object of playback options instead of positional arguments." (since v12, until v14)
    */
   play(offset: number, onended?: Sound.ScheduleCallback | null): Promise<this>;
 
+  /**
+   * Play a one-shot Sound originating from a predefined point on the canvas.
+   * The sound plays locally for the current client only.
+   * To play a sound for all connected clients use {@linkcode foundry.canvas.layers.SoundsLayer.emitAtPosition | SoundsLayer#emitAtPosition}.
+   * A helper which does not depend on a pre-existing Sound instance is available at
+   * {@linkcode foundry.canvas.layers.SoundsLayer.playAtPosition | SoundsLayer#playAtPosition}.
+   *
+   * @param origin  - The canvas coordinates from which the sound originates
+   * @param radius  - The radius of effect in distance units
+   * @param options - Additional options which configure playback
+   * @returns A Promise which resolves to the played Sound, or null
+   *
+   * Play the sound of a trap springing
+   * @example
+   * ```js
+   * const sound = new Sound("modules/my-module/sounds/spring-trap.ogg", {context: game.audio.environment});
+   * await sound.load();
+   * const origin = {x: 5200, y: 3700};  // The origin point for the sound
+   * const radius = 30;                  // Audible in a 30-foot radius
+   * await sound.playAtPosition(origin, radius);
+   * ```
+   *
+   * A Token casts a spell
+   * @example
+   * ```js
+   * const sound = new Sound("modules/my-module/sounds/spells-sprite.ogg", {context: game.audio.environment});
+   * const origin = token.center;         // The origin point for the sound
+   * const radius = 60;                   // Audible in a 60-foot radius
+   * await sound.playAtPosition(origin, radius, {
+   *   walls: false,                      // Not constrained by walls with a lowpass muffled effect
+   *   muffledEffect: {type: "lowpass", intensity: 6},
+   *   sourceData: {
+   *     angle: 120,                      // Sound emitted at a limited angle
+   *     rotation: 270                    // Configure the direction of sound emission
+   *   }
+   *   playbackOptions: {
+   *     loopStart: 12,                   // Audio sprite timing
+   *     loopEnd: 16,
+   *     fade: 300,                      // Fade-in 300ms
+   *     onended: () => console.log("Do something after the spell sound has played")
+   *   }
+   * });
+   * ```
+   */
+  playAtPosition(
+    origin: Canvas.PossiblyElevatedPoint,
+    radius: number,
+    options?: Sound.PlayAtPositionOptions,
+  ): Promise<this | null>;
+
   /**
    * Begin playback for the configured pipeline and playback options.
    * This method is factored out so that subclass implementations of Sound can implement alternative behavior.
@@ -372,9 +469,10 @@ declare class Sound extends EventEmitterMixin() {
 
   /**
    * 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.
+   * For {@linkcode AudioBufferSourceNode} this stops playback after recording the current time.
+   * Calling {@linkcode Sound.play | Sound#play} will resume playback from the {@linkcode Sound.pauseTime | #pausedTime} unless some other offset is passed.
+   * For a {@linkcode MediaElementAudioSourceNode} this simply calls the {@linkcode HTMLAudioElement.pause | HTMLAudioElement#pause} method directly.
+   * @remarks
    * @throws If called while the Sound isn't playing
    */
   pause(): void;
@@ -392,7 +490,6 @@ declare class Sound extends EventEmitterMixin() {
    * @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>;
 
   /**
@@ -407,7 +504,6 @@ declare class Sound extends EventEmitterMixin() {
    * @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>;
 
   /**
@@ -432,6 +528,18 @@ declare class Sound extends EventEmitterMixin() {
    */
   schedule<R extends Sound.ScheduleCallback>(fn: R, playbackTime: number): Promise<Awaited<ReturnType<R>>>;
 
+  /**
+   * Cancel one scheduled event created with {@linkcode Sound.schedule | Sound#schedule}.
+   * You may pass either the {@linkcode AudioTimeout} returned internally or the Promise returned by `Sound#schedule`.
+   * @param handle - The handle to cancel.
+   */
+  unschedule(handle: AudioTimeout | { timeout: AudioTimeout }): void;
+
+  /**
+   * Cancel all events that are still scheduled for this sound.
+   */
+  unscheduleAll(): void;
+
   /**
    * 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.
@@ -458,48 +566,42 @@ declare class Sound extends EventEmitterMixin() {
   protected _disconnectPipeline(): void;
 
   /**
-   * @deprecated since v12, will be removed in v14
-   * @remarks "`AudioContainer.LOAD_STATES` is deprecated in favor of {@linkcode Sound.STATES}"
+   * @deprecated "`AudioContainer.LOAD_STATES` is deprecated in favor of {@linkcode Sound.STATES}" (since v12, until v14)
    */
   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`}"
+   * @deprecated "`AudioContainer#loadState` is deprecated in favor of {@linkcode Sound._state | Sound#_state}" (since v12, until v14)
    */
   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"
+   * @deprecated "`Sound#container` is deprecated without replacement because the `Sound` and `AudioContainer` classes are now merged" (since v12, until v14)
    */
   get container(): this;
 
   /**
-   * @deprecated since v12, will be removed in v14
-   * @remarks "`Sound#node` is renamed {@link Sound.sourceNode | `Sound#sourceNode`}"
+   * @deprecated "`Sound#node` is renamed {@linkcode Sound.sourceNode | Sound#sourceNode}" (since v12, until v14)
    */
   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`}"
+   * @deprecated "`Sound#on` is deprecated in favor of {@linkcode Sound.addEventListener | Sound#addEventListener}" (since v12, until v14)
    */
   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`}"
+   * @deprecated "`Sound#off` is deprecated in favor of {@linkcode Sound.removeEventListener | Sound#removeEventListener}" (since v12, until v14)
    */
   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`
+   * @deprecated "`Sound#emit` is deprecated in favor of {@linkcode Sound.dispatchEvent | Sound#dispatchEvent}" (since v12, until v14)
+   * @remarks This method still takes a string, then creates an `Event` with it and passes that along to `dispatchEvent`
    */
   emit(eventName: string): void;
+
+  #Sound: true;
 }
 
 export default Sound;

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

@@ -1,4 +1,4 @@
-import type { Identity, NullishProps } from "#utils";
+import type { Identity, InexactPartial } from "#utils";
 
 /**
  * A special error class used for cancellation.
@@ -56,6 +56,11 @@ declare class AudioTimeout<CallbackReturn = undefined> {
    */
   complete: Promise<CallbackReturn> | undefined;
 
+  /**
+   * Is this audio timeout cancelled?
+   */
+  get cancelled(): boolean;
+
   /**
    * Cancel an AudioTimeout by ending it early, rejecting its completion promise, and skipping any callback function.
    */
@@ -72,11 +77,12 @@ declare class AudioTimeout<CallbackReturn = undefined> {
    * @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>;
+
+  #AudioTimeout: true;
 }
 
 declare namespace AudioTimeout {
@@ -84,7 +90,7 @@ declare namespace AudioTimeout {
   interface AnyConstructor extends Identity<typeof AnyAudioTimeout> {}
 
   /** @internal */
-  type _ConstructorOptions<Return = undefined> = NullishProps<{
+  type _ConstructorOptions<Return = undefined> = InexactPartial<{
     /** @defaultValue `game.audio.music` */
     context: AudioContext;