@league-of-foundry-developers/foundry-vtt-types 9.280.0 → 12.331.1-beta

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

@@ -0,0 +1,307 @@
+export {};
+
+declare global {
+  /**
+   * The Sound class is used to control the playback of audio sources using the Web Audio API.
+   */
+  class Sound {
+    constructor(src: string, options?: { container?: AudioContainer });
+
+    /**
+     * The numeric identifier for accessing this node
+     */
+    id: number;
+
+    /**
+     * The audio source path
+     */
+    src: string;
+
+    /**
+     * The AudioContainer which controls playback
+     */
+    container: AudioContainer;
+
+    /**
+     * The time in seconds at which playback was started
+     * @defaultValue `undefined`
+     */
+    startTime: number | undefined;
+
+    /**
+     * The time in seconds at which playback was paused
+     * @defaultValue `undefined`
+     */
+    pausedTime: number | undefined;
+
+    /**
+     * Registered event callbacks
+     * @defaultValue `{stop: {}, start: {}, end: {}, pause: {}, load: {}}`
+     */
+    events: Sound.EventCallbacks;
+
+    /**
+     * The registered event handler id for this Sound.
+     * Incremented each time a callback is registered.
+     * @defaultValue `1`
+     * @internal
+     */
+    protected _eventHandlerId: number;
+
+    /**
+     * If this Sound source is currently in the process of loading, this attribute contains a Promise that will resolve
+     * when the loading process completes.
+     * @defaultValue `undefined`
+     */
+    loading: Promise<void> | undefined;
+
+    /**
+     * A collection of scheduled events recorded as window timeout IDs
+     * @internal
+     */
+    protected _scheduledEvents: Set<number>;
+
+    /**
+     * A global audio node ID used to quickly reference a specific audio node
+     * @defaultValue `0`
+     * @internal
+     */
+    protected static _nodeId: number;
+
+    /**
+     * A convenience reference to the sound context used by the application
+     */
+    get context(): AudioContext;
+
+    /**
+     * A reference to the audio source node being used by the AudioContainer
+     */
+    get node(): AudioBufferSourceNode | MediaElementAudioSourceNode | undefined;
+
+    /**
+     * A reference to the GainNode parameter which controls volume
+     */
+    get gain(): AudioParam | undefined;
+
+    /**
+     * The current playback time of the sound
+     */
+    get currentTime(): number | undefined;
+
+    /**
+     * The total sound duration, in seconds
+     */
+    get duration(): number | undefined;
+
+    /**
+     * Is the contained audio node loaded and ready for playback?
+     */
+    get loaded(): boolean;
+
+    /**
+     * Did the contained audio node fail to load?
+     */
+    get failed(): boolean;
+
+    /**
+     * Is the audio source currently playing?
+     */
+    get playing(): boolean;
+
+    /**
+     * Is the Sound current looping?
+     */
+    get loop(): boolean;
+    set loop(looping: boolean);
+
+    /**
+     * The volume at which the Sound is playing
+     */
+    get volume(): number | undefined;
+    set volume(value: number | undefined);
+
+    /**
+     * 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
+     *                  (default: `{}`)
+     * @returns A Promise that resolves after the requested fade duration
+     */
+    fade(volume: number, options?: Sound.FadeOptions): Promise<void>;
+
+    /**
+     * Load the audio source, creating an AudioBuffer.
+     * Audio loading is idempotent, it can be requested multiple times but only the first load request will be honored.
+     * @param options - Additional options which affect resource loading
+     *                  (default: `{}`)
+     * @returns The Sound once its source audio buffer is loaded
+     */
+    load(options?: Sound.LoadOptions): Promise<Sound>;
+
+    /**
+     * Begin playback for the sound node
+     * @param options - Options which configure playback
+     *                  (default: `{}`)
+     */
+    play(options?: Sound.PlayOptions): void;
+
+    /**
+     * Pause playback, remembering the playback position in order to resume later.
+     */
+    pause(): void;
+
+    /**
+     * Stop playback, fully resetting the Sound to a non-playing state.
+     */
+    stop(): 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 once the scheduled function has been called
+     *
+     * @example Schedule audio playback changes
+     * ```typescript
+     * 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: Sound.Callback, playbackTime: number): Promise<void>;
+
+    /**
+     * Trigger registered callback functions for a specific event name.
+     * @param eventName - The event name being emitted
+     */
+    emit(eventName: Sound.EventName): void;
+
+    /**
+     * Deactivate an event handler which was previously registered for a specific event
+     * @param eventName - The event name being deactivated
+     * @param fn        - The callback ID or callback function being un-registered
+     */
+    off(eventName: Sound.EventName, fn: number | Sound.Callback): void;
+
+    /**
+     * Register an event handler to take actions for a certain Sound event.
+     * @param eventName- The event name being deactivated
+     * @param fn       - The callback function to trigger when the event occurs
+     * @param options  - Additional options that affect callback registration
+     *                   (default: `{}`)
+     */
+    on(eventName: Sound.EventName, fn: Sound.Callback, options?: Sound.OnOptions): number;
+
+    /**
+     * Register a new callback function for a certain event. For internal use only.
+     * @internal
+     */
+    protected _registerForEvent(eventName: Sound.EventName, callback: Sound.Callback): number;
+
+    /**
+     * Cancel all pending scheduled events.
+     * @internal
+     */
+    protected _clearEvents(): void;
+
+    /**
+     * Called when playback concludes naturally
+     */
+    protected _onEnd(): void;
+
+    /**
+     * Called when the audio buffer is first loaded
+     */
+    protected _onLoad(): void;
+
+    /**
+     * Called when playback is paused
+     */
+    protected _onPause(): void;
+
+    /**
+     * Called when the sound begins playing
+     */
+    protected _onStart(): void;
+
+    /**
+     * Called when playback is stopped (prior to naturally reaching the end)
+     */
+    protected _onStop(): void;
+  }
+
+  namespace Sound {
+    type Callback = (sound: Sound) => void;
+
+    type EventName = "end" | "pause" | "start" | "stop" | "load";
+
+    type EventCallbacks = Record<EventName, Partial<Record<number, Callback>>>;
+
+    type FadeType = "linear" | "exponential";
+
+    interface FadeOptions {
+      /**
+       * The duration of the fade effect in milliseconds
+       * @defaultValue `1000`
+       */
+      duration?: number;
+
+      /**
+       * A volume level to start from, the current volume by default
+       */
+      from?: number;
+
+      /**
+       * The type of fade easing, "linear" or "exponential"
+       * @defaultValue `"linear"`
+       */
+      type?: FadeType;
+    }
+
+    interface LoadOptions {
+      /**
+       * Automatically begin playback of the audio source once loaded
+       * @defaultValue `false`
+       */
+      autoplay?: boolean;
+
+      /**
+       * Additional options passed to the play method when loading is complete
+       * @defaultValue `{}`
+       */
+      autoplayOptions?: PlayOptions;
+    }
+
+    interface PlayOptions {
+      /**
+       * Whether to loop the audio automatically
+       * @defaultValue `false`
+       */
+      loop?: boolean;
+
+      /**
+       * A specific offset in seconds at which to begin playback
+       */
+      offset?: number;
+
+      /**
+       * The desired volume at which to begin playback
+       */
+      volume?: number;
+
+      /**
+       * Fade volume changes over a desired duration in milliseconds
+       * @defaultValue `0`
+       */
+      fade?: number;
+    }
+
+    interface OnOptions {
+      /**
+       * Trigger the callback once only and automatically un-register it
+       * @defaultValue `false`
+       */
+      once?: boolean;
+    }
+  }
+}

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

@@ -0,0 +1,162 @@
+import type { DeepPartial } from "../../../types/utils.d.mts";
+
+declare global {
+  /**
+   * An interface for an Audio/Video client which is extended to provide broadcasting functionality.
+   */
+  abstract class AVClient {
+    /**
+     * @param master   - The master orchestration instance
+     * @param settings - The audio/video settings being used
+     */
+    constructor(master: AVMaster, settings: AVSettings);
+
+    /**
+     * The master orchestration instance
+     */
+    master: AVMaster;
+
+    /**
+     * The active audio/video settings being used
+     */
+    settings: AVSettings;
+
+    /**
+     * Is audio broadcasting push-to-talk enabled?
+     */
+    get isVoicePTT(): boolean;
+
+    /**
+     * Is audio broadcasting always enabled?
+     */
+    get isVoiceAlways(): boolean;
+
+    /**
+     * Is audio broadcasting voice-activation enabled?
+     */
+    get isVoiceActivated(): boolean;
+
+    /**
+     * Is the current user muted?
+     */
+    get isMuted(): boolean;
+
+    /**
+     * One-time initialization actions that should be performed for this client implementation.
+     * This will be called only once when the Game object is first set-up.
+     */
+    abstract initialize(): Promise<void>;
+
+    /**
+     * Connect to any servers or services needed in order to provide audio/video functionality.
+     * Any parameters needed in order to establish the connection should be drawn from the settings object.
+     * This function should return a boolean for whether the connection attempt was successful.
+     * @returns Was the connection attempt successful?
+     */
+    abstract connect(): Promise<boolean>;
+
+    /**
+     * Disconnect from any servers or services which are used to provide audio/video functionality.
+     * This function should return a boolean for whether a valid disconnection occurred.
+     * @returns Did a disconnection occur?
+     */
+    abstract disconnect(): Promise<boolean>;
+
+    /**
+     * Provide an Object of available audio sources which can be used by this implementation.
+     * Each object key should be a device id and the key should be a human-readable label.
+     */
+    getAudioSinks(): Promise<Record<string, string>>;
+
+    /**
+     * Provide an Object of available audio sources which can be used by this implementation.
+     * Each object key should be a device id and the key should be a human-readable label.
+     */
+    getAudioSources(): Promise<Record<string, string>>;
+
+    /**
+     * Provide an Object of available video sources which can be used by this implementation.
+     * Each object key should be a device id and the key should be a human-readable label.
+     */
+    getVideoSources(): Promise<Record<string, string>>;
+
+    /**
+     * Obtain a mapping of available device sources for a given type.
+     * @param kind - The type of device source being requested
+     * @internal
+     */
+    protected _getSourcesOfType(kind: MediaDeviceKind): Promise<Record<string, string>>;
+
+    /**
+     * Return an array of Foundry User IDs which are currently connected to A/V.
+     * The current user should also be included as a connected user in addition to all peers.
+     * @returns The connected User IDs
+     */
+    abstract getConnectedUsers(): string[];
+
+    /**
+     * Provide a MediaStream instance for a given user ID
+     * @param userId - The User id
+     * @returns The MediaStream for the user, or null if the user does not have one
+     */
+    abstract getMediaStreamForUser(userId: string): MediaStream | null | undefined;
+
+    /**
+     * Provide a MediaStream for monitoring a given user's voice volume levels.
+     * @param userId - The User ID.
+     * @returns The MediaStream for the user, or null if the user does not have one.
+     * @remarks The getLevelsStreamForUser() method must be defined by an AVClient subclass and will be strictly required starting in v10
+     */
+    getLevelsStreamForUser(userId: string): MediaStream | null | undefined;
+
+    /**
+     * Is outbound audio enabled for the current user?
+     */
+    abstract isAudioEnabled(): boolean;
+
+    /**
+     * Is outbound video enabled for the current user?
+     */
+    abstract isVideoEnabled(): boolean;
+
+    /**
+     * Set whether the outbound audio feed for the current game user is enabled.
+     * This method should be used when the user marks themselves as muted or if the gamemaster globally mutes them.
+     * @param enable - Whether the outbound audio track should be enabled (true) or disabled (false)
+     */
+    abstract toggleAudio(enable: boolean): void;
+
+    /**
+     * Set whether the outbound audio feed for the current game user is actively broadcasting.
+     * This can only be true if audio is enabled, but may be false if using push-to-talk or voice activation modes.
+     * @param broadcast - Whether outbound audio should be sent to connected peers or not?
+     */
+    abstract toggleBroadcast(broadcast: boolean): void;
+
+    /**
+     * Set whether the outbound video feed for the current game user is enabled.
+     * This method should be used when the user marks themselves as hidden or if the gamemaster globally hides them.
+     * @param enable - Whether the outbound audio track should be enabled (true) or disabled (false)
+     */
+    abstract toggleVideo(enable: boolean): void;
+
+    /**
+     * Set the Video Track for a given User ID to a provided VideoElement
+     * @param userId       - The User ID to set to the element
+     * @param videoElement - The HTMLVideoElement to which the video should be set
+     */
+    abstract setUserVideo(userId: string, videoElement: HTMLVideoElement): Promise<void>;
+
+    /**
+     * Handle changes to A/V configuration settings.
+     * @param changed - The settings which have changed
+     */
+    onSettingsChanged(changed: DeepPartial<AVSettings.Settings>): void;
+
+    /**
+     * Replace the local stream for each connected peer with a re-generated MediaStream.
+     * @remarks The updateLocalStream() method must be defined by an AVClient subclass.
+     */
+    abstract updateLocalStream(): Promise<void>;
+  }
+}

package/src/foundry/client/av/clients/index.d.mts

@@ -0,0 +1 @@
+import "./simplepeer.d.mts";

package/src/foundry/client/av/clients/simplepeer.d.mts

@@ -0,0 +1,155 @@
+import type { DeepPartial } from "../../../../types/utils.d.mts";
+
+declare global {
+  /**
+   * An implementation of the AVClient which uses the simple-peer library and the Foundry socket server for signaling.
+   * Credit to bekit#4213 for identifying simple-peer as a viable technology and providing a POC implementation.
+   */
+  class SimplePeerAVClient extends AVClient {
+    /**
+     * The local Stream which captures input video and audio
+     * @defaultValue `null`
+     */
+    localStream: MediaStream | null;
+
+    /**
+     * The dedicated audio stream used to measure volume levels for voice activity detection.
+     * @defaultValue `null`
+     */
+    levelsStream: MediaStream | null;
+
+    /**
+     * A mapping of connected peers
+     */
+    peers: Map<string, SimplePeer.Instance>;
+
+    /**
+     * A mapping of connected remote streams
+     */
+    remoteStreams: Map<string, MediaStream>;
+
+    /**
+     * Has the client been successfully initialized?
+     * @defaultValue `false`
+     * @internal
+     */
+    protected _initialized: boolean;
+
+    /**
+     * Is outbound broadcast of local audio enabled?
+     * @defaultValue `false`
+     */
+    audioBroadcastEnabled: boolean;
+
+    /**
+     * The polling interval ID for connected users that might have unexpectedly dropped out of our peer network.
+     * @internal
+     */
+    protected _connectionPoll: number | null;
+
+    override connect(): Promise<boolean>;
+
+    /**
+     * Try to establish a peer connection with each user connected to the server.
+     * @internal
+     */
+    protected _connect(): Promise<SimplePeer.Instance[]>;
+
+    override disconnect(): Promise<boolean>;
+
+    override initialize(): Promise<void>;
+
+    override getConnectedUsers(): string[];
+
+    override getMediaStreamForUser(userId: string): MediaStream | null | undefined;
+
+    override getLevelsStreamForUser(userId: string): MediaStream | null | undefined;
+
+    override isAudioEnabled(): boolean;
+
+    override isVideoEnabled(): boolean;
+
+    override toggleAudio(enable: boolean): void;
+
+    override toggleBroadcast(broadcast: boolean): void;
+
+    override toggleVideo(enable: boolean): void;
+
+    override setUserVideo(userId: string, videoElement: HTMLVideoElement): Promise<void>;
+
+    /**
+     * Initialize a local media stream for the current user
+     */
+    initializeLocalStream(): Promise<MediaStream | null>;
+
+    /**
+     * Attempt to create local media streams.
+     * @param params - Parameters for the getUserMedia request.
+     * @returns The created MediaStream or an error.
+     * @internal
+     */
+    protected _createMediaStream(params: MediaStreamConstraints): Promise<MediaStream | Error>;
+
+    /**
+     * Listen for Audio/Video updates on the av socket to broker connections between peers
+     */
+    activateSocketListeners(): void;
+
+    /**
+     * Initialize a stream connection with a new peer
+     * @param userId - The Foundry user ID for which the peer stream should be established
+     * @returns A Promise which resolves once the peer stream is initialized
+     */
+    initializePeerStream(userId: string): Promise<SimplePeer.Instance>;
+
+    /**
+     * Receive a request to establish a peer signal with some other User id
+     * @param userId - The Foundry user ID who is requesting to establish a connection
+     * @param data   - The connection details provided by SimplePeer
+     */
+    receiveSignal(userId: string, data: SimplePeer.SignalData): void;
+
+    /**
+     * Connect to a peer directly, either as the initiator or as the receiver
+     * @param userId      - The Foundry user ID with whom we are connecting
+     * @param isInitiator - Is the current user initiating the connection, or responding to it?
+     *                      (default: `false`)
+     * @returns The constructed and configured SimplePeer instance
+     */
+    connectPeer(userId: string, isInitiator?: boolean): SimplePeer.Instance;
+
+    /**
+     * Create the SimplePeer instance for the desired peer connection.
+     * Modules may implement more advanced connection strategies by overriding this method.
+     * @param userId      - The Foundry user ID with whom we are connecting
+     * @param isInitiator - Is the current user initiating the connection, or responding to it?
+     * @internal
+     */
+    _createPeerConnection(userId: string, isInitiator: boolean): SimplePeer.Instance;
+
+    /**
+     * Setup the custom TURN relay to be used in subsequent calls if there is one configured.
+     * TURN credentials are mandatory in WebRTC.
+     * @param options - The SimplePeer configuration object.
+     * @internal
+     */
+    _setupCustomTURN(options: SimplePeer.Options): void;
+
+    /**
+     * Disconnect from a peer by stopping current stream tracks and destroying the SimplePeer instance
+     * @param userId - The Foundry user ID from whom we are disconnecting
+     * @returns A Promise which resolves once the disconnection is complete
+     */
+    disconnectPeer(userId: string): Promise<void>;
+
+    /**
+     * Disconnect from all current peer streams
+     * @returns A Promise which resolves once all peers have been disconnected
+     */
+    disconnectAll(): Promise<Array<void>>;
+
+    override onSettingsChanged(changed: DeepPartial<AVSettings.Settings>): Promise<void>;
+
+    override updateLocalStream(): Promise<void>;
+  }
+}

package/src/foundry/client/av/index.d.mts

@@ -0,0 +1,4 @@
+import "./client.d.mts";
+import "./clients/index.d.mts";
+import "./master.d.mts";
+import "./settings.d.mts";