@league-of-foundry-developers/foundry-vtt-types 9.280.1 → 12.331.2-beta

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";

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

@@ -0,0 +1,191 @@
+import type { DeepPartial } from "../../../types/utils.d.mts";
+
+declare global {
+  /**
+   * The master Audio/Video controller instance.
+   * This is available as the singleton game.webrtc
+   */
+  class AVMaster {
+    constructor();
+
+    settings: AVSettings;
+
+    config: AVConfig;
+
+    /**
+     * The Audio/Video client class
+     */
+    client: InstanceType<CONFIG["WebRTC"]["clientClass"]>;
+
+    /**
+     * A flag to track whether the current user is actively broadcasting their microphone.
+     * @defaultValue `false`
+     */
+    broadcasting: boolean;
+
+    /**
+     * Flag to determine if we are connected to the signalling server or not.
+     * This is required for synchronization between connection and reconnection attempts.
+     * @defaultValue `false`
+     * @internal
+     */
+    protected _connected: boolean;
+
+    /**
+     * The cached connection promise.
+     * This is required to prevent re-triggering a connection while one is already in progress.
+     * @defaultValue `null`
+     * @internal
+     */
+    protected _connecting: Promise<boolean> | null;
+
+    /**
+     * A flag to track whether the A/V system is currently in the process of reconnecting.
+     * This occurs if the connection is lost or interrupted.
+     * @defaultValue `false`
+     * @internal
+     */
+    protected _reconnecting: boolean;
+
+    /**
+     * @defaultValue `{}`
+     * @internal
+     */
+    protected _speakingData: { speaking: boolean; volumeHistories: number[] };
+
+    /**
+     * @defaultValue `0`
+     * @internal
+     */
+    protected _pttMuteTimeout: number;
+
+    get mode(): AVSettings.AV_MODES;
+
+    /**
+     * Connect to the Audio/Video client.
+     * @returns Was the connection attempt successful?
+     */
+    connect(): Promise<boolean>;
+
+    /**
+     * Disconnect from the Audio/Video client.
+     * @returns Whether an existing connection was terminated?
+     */
+    disconnect(): Promise<boolean>;
+
+    /**
+     * Callback actions to take when the user becomes disconnected from the server.
+     */
+    reestablish(): Promise<void>;
+
+    /**
+     * Initialize the local broadcast state.
+     * @internal
+     */
+    protected _initialize(): void;
+
+    /**
+     * A user can broadcast audio if the AV mode is compatible and if they are allowed to broadcast.
+     */
+    canUserBroadcastAudio(userId: string): boolean;
+
+    /**
+     * A user can share audio if they are allowed to broadcast and if they have not muted themselves or been blocked.
+     */
+    canUserShareAudio(userId: string): boolean;
+
+    /**
+     * A user can broadcast video if the AV mode is compatible and if they are allowed to broadcast.
+     */
+    canUserBroadcastVideo(userId: string): boolean;
+
+    /**
+     * A user can share video if they are allowed to broadcast and if they have not hidden themselves or been blocked.
+     */
+    canUserShareVideo(userId: string): boolean;
+
+    /**
+     * Trigger a change in the audio broadcasting state when using a push-to-talk workflow.
+     * @param intent - The user's intent to broadcast. Whether an actual broadcast occurs will depend
+     *                 on whether or not the user has muted their audio feed.
+     */
+    broadcast(intent: boolean): void;
+
+    /**
+     * Set up audio level listeners to handle voice activation detection workflow.
+     * @param mode - The currently selected voice broadcasting mode
+     * @internal
+     */
+    protected _initializeUserVoiceDetection(mode: AVSettings.VOICE_MODES): void;
+
+    /**
+     * Activate voice detection tracking for a userId on a provided MediaStream.
+     * Currently only a MediaStream is supported because MediaStreamTrack processing is not yet supported cross-browser.
+     * @param stream - The MediaStream which corresponds to that User
+     * @param ms     - A number of milliseconds which represents the voice activation volume interval
+     *                 (default: `CONFIG.WebRTC.detectPeerVolumeInterval`)
+     */
+    activateVoiceDetection(stream: MediaStream, ms?: number): void;
+
+    /**
+     * Actions which the orchestration layer should take when a peer user disconnects from the audio/video service.
+     */
+    deactivateVoiceDetection(): void;
+
+    /**
+     * Periodic notification of user audio level
+     *
+     * This function uses the audio level (in dB) of the audio stream to determine if the user is speaking or not and
+     * notifies the UI of such changes.
+     *
+     * The User is considered speaking if they are above the decibel threshold in any of the history values.
+     * This marks them as speaking as soon as they have a high enough volume, and marks them as not speaking only after
+     * they drop below the threshold in all histories (last 4 volumes = for 200 ms).
+     *
+     * There can be more optimal ways to do this and which uses whether the user was already considered speaking before
+     * or not, in order to eliminate short bursts of audio (coughing for example).
+     *
+     * @param dbLevel - The audio level in decibels of the user within the last 50ms
+     * @internal
+     */
+    protected _onAudioLevel(dbLevel: number): void;
+
+    /**
+     * Resets the speaking history of a user
+     * If the user was considered speaking, then mark them as not speaking
+     * @internal
+     */
+    protected _resetSpeakingHistory(): void;
+
+    /**
+     * Handle activation of a push-to-talk key or button.
+     * @param context - The context data of the event
+     * @internal
+     */
+    _onPTTStart(context: KeyboardManager.KeyboardEventContext): void;
+
+    /**
+     * Handle deactivation of a push-to-talk key or button.
+     * @param context - The context data of the event
+     * @internal
+     */
+    _onPTTEnd(context: KeyboardManager.KeyboardEventContext): void;
+
+    render(): void;
+
+    /**
+     * Render the audio/video streams to the CameraViews UI.
+     * Assign each connected user to the correct video frame element.
+     */
+    onRender(): void;
+
+    /**
+     * Respond to changes which occur to AV Settings.
+     * Changes are handled in descending order of impact.
+     * @param changed - The object of changed AV settings
+     */
+    onSettingsChanged(changed: DeepPartial<AVSettings.Settings>): void;
+
+    debug(message: string): void;
+  }
+}