@needle-tools/engine 4.7.2-alpha → 4.7.2-next.6f2cd71

package/lib/engine-components/AudioSource.d.ts

@@ -1,217 +1,217 @@
-import { PositionalAudio } from "three";
-import { Behaviour } from "./Component.js";
-/**
- * Defines how audio volume attenuates over distance from the listener.
- */
-export declare enum AudioRolloffMode {
-    /**
-     * Logarithmic rolloff provides a natural, real-world attenuation where volume decreases
-     * exponentially with distance.
-     */
-    Logarithmic = 0,
-    /**
-     * Linear rolloff provides a straightforward volume reduction that decreases at a constant
-     * rate with distance.
-     */
-    Linear = 1,
-    /**
-     * Custom rolloff allows for defining specialized distance-based attenuation curves.
-     * Note: Custom rolloff is not fully implemented in this version.
-     */
-    Custom = 2
-}
-/**
- * Plays audio clips in the scene, with support for spatial positioning.
- *
- * The AudioSource component can play audio files or media streams with
- * options for spatial blending, volume control, looping, and more.
- *
- * When a page loses visibility (tab becomes inactive), audio will automatically
- * pause unless {@link playInBackground} is set to true. On mobile devices, audio always
- * pauses regardless of this setting. When the page becomes visible again,
- * previously playing audio will resume.
- *
- * AudioSource also responds to application mute state changes. When the application
- * is muted, the volume is set to 0. When unmuted, the volume
- * returns to its previous value.
- *
- * @category Multimedia
- * @group Components
- */
-export declare class AudioSource extends Behaviour {
-    /**
-     * Checks if the user has interacted with the page to allow audio playback.
-     * Audio playback often requires a user gesture first due to browser autoplay policies.
-     * This is the same as calling {@link Application.userInteractionRegistered}.
-     *
-     * @returns Whether user interaction has been registered to allow audio playback
-     */
-    static get userInteractionRegistered(): boolean;
-    /**
-     * Registers a callback that will be executed once the user has interacted with the page,
-     * allowing audio playback to begin.
-     * This is the same as calling {@link Application.registerWaitForInteraction}.
-     *
-     * @param cb - The callback function to execute when user interaction is registered
-     */
-    static registerWaitForAllowAudio(cb: Function): void;
-    /**
-     * The audio clip to play. Can be a URL string pointing to an audio file or a {@link MediaStream} object.
-     */
-    clip: string | MediaStream;
-    /**
-     * When true, the audio will automatically start playing when the component is enabled.
-     * When false, you must call play() manually to start audio playback.
-     * @default false
-     */
-    playOnAwake: boolean;
-    /**
-     * When true, the audio clip will be loaded during initialization rather than when play() is called.
-     * This can reduce playback delay but increases initial loading time.
-     * @default true
-     */
-    preload: boolean;
-    /**
-     * When true, audio will continue playing when the browser tab loses focus.
-     * When false, audio will pause when the tab is minimized or not active.
-     * @default true
-     */
-    playInBackground: boolean;
-    /**
-     * Indicates whether the audio is currently playing.
-     *
-     * @returns True if the audio is playing, false otherwise
-     */
-    get isPlaying(): boolean;
-    /**
-     * The total duration of the current audio clip in seconds.
-     *
-     * @returns Duration in seconds or undefined if no clip is loaded
-     */
-    get duration(): number | undefined;
-    /**
-     * The current playback position as a normalized value between 0 and 1.
-     * Can be set to seek to a specific position in the audio.
-     */
-    get time01(): number;
-    set time01(val: number);
-    /**
-     * The current playback position in seconds.
-     * Can be set to seek to a specific time in the audio.
-     */
-    get time(): number;
-    set time(val: number);
-    /**
-     * When true, the audio will repeat after reaching the end.
-     * When false, audio will play once and stop.
-     * @default false
-     */
-    get loop(): boolean;
-    set loop(val: boolean);
-    /**
-     * Controls how the audio is positioned in space.
-     * Values range from 0 (2D, non-positional) to 1 (fully 3D positioned).
-     * Note: 2D playback is not fully supported in the current implementation.
-     */
-    get spatialBlend(): number;
-    set spatialBlend(val: number);
-    /**
-     * The minimum distance from the audio source at which the volume starts to attenuate.
-     * Within this radius, the audio plays at full volume regardless of distance.
-     */
-    get minDistance(): number;
-    set minDistance(val: number);
-    /**
-     * The maximum distance from the audio source beyond which the volume no longer decreases.
-     * This defines the outer limit of the attenuation curve.
-     */
-    get maxDistance(): number;
-    set maxDistance(val: number);
-    private _spatialBlend;
-    private _minDistance;
-    private _maxDistance;
-    /**
-     * Controls the overall volume/loudness of the audio.
-     * Values range from 0 (silent) to 1 (full volume).
-     * @default 1
-     */
-    get volume(): number;
-    set volume(val: number);
-    private _volume;
-    /**
-     * Controls the playback rate (speed) of the audio.
-     * Values greater than 1 increase speed, values less than 1 decrease it.
-     * This affects both speed and pitch of the audio.
-     * @default 1
-     */
-    set pitch(val: number);
-    get pitch(): number;
-    /**
-     * Determines how audio volume decreases with distance from the listener.
-     * @default AudioRolloffMode.Logarithmic
-     * @see {@link AudioRolloffMode}
-     */
-    rollOffMode: AudioRolloffMode;
-    private _loop;
-    private sound;
-    private helper;
-    private wasPlaying;
-    private audioLoader;
-    private shouldPlay;
-    private _lastClipStartedLoading;
-    private _audioElement;
-    /**
-     * Returns the underlying {@link PositionalAudio} object, creating it if necessary.
-     * The audio source needs a user interaction to be initialized due to browser autoplay policies.
-     *
-     * @returns The three.js PositionalAudio object or null if unavailable
-     */
-    get Sound(): PositionalAudio | null;
-    /**
-     * Indicates whether the audio source is queued to play when possible.
-     * This may be true before user interaction has been registered.
-     *
-     * @returns Whether the audio source intends to play
-     */
-    get ShouldPlay(): boolean;
-    /**
-     * Returns the Web Audio API context associated with this audio source.
-     *
-     * @returns The {@link AudioContext} or null if not available
-     */
-    get audioContext(): AudioContext | undefined;
-    /** @internal */
-    awake(): void;
-    /** @internal */
-    onEnable(): void;
-    /** @internal */
-    onDisable(): void;
-    private onVisibilityChanged;
-    private onApplicationMuteChanged;
-    private createAudio;
-    private __onAllowAudioCallback;
-    private applySpatialDistanceSettings;
-    private onNewClip;
-    /**
-     * Plays the audio clip or media stream.
-     * If no argument is provided, plays the currently assigned clip.
-     *
-     * @param clip - Optional audio clip or {@link MediaStream} to play
-     */
-    play(clip?: string | MediaStream | undefined): void;
-    /**
-     * Pauses audio playback while maintaining the current position.
-     * Use play() to resume from the paused position.
-     */
-    pause(): void;
-    /**
-     * Stops audio playback completely and resets the playback position to the beginning.
-     * Unlike pause(), calling play() after stop() will start from the beginning.
-     */
-    stop(): void;
-    private _lastContextTime;
-    private _hasEnded;
-    private _needUpdateSpatialDistanceSettings;
-    /** @internal */
-    update(): void;
-}
+import { PositionalAudio } from "three";
+import { Behaviour } from "./Component.js";
+/**
+ * Defines how audio volume attenuates over distance from the listener.
+ */
+export declare enum AudioRolloffMode {
+    /**
+     * Logarithmic rolloff provides a natural, real-world attenuation where volume decreases
+     * exponentially with distance.
+     */
+    Logarithmic = 0,
+    /**
+     * Linear rolloff provides a straightforward volume reduction that decreases at a constant
+     * rate with distance.
+     */
+    Linear = 1,
+    /**
+     * Custom rolloff allows for defining specialized distance-based attenuation curves.
+     * Note: Custom rolloff is not fully implemented in this version.
+     */
+    Custom = 2
+}
+/**
+ * Plays audio clips in the scene, with support for spatial positioning.
+ *
+ * The AudioSource component can play audio files or media streams with
+ * options for spatial blending, volume control, looping, and more.
+ *
+ * When a page loses visibility (tab becomes inactive), audio will automatically
+ * pause unless {@link playInBackground} is set to true. On mobile devices, audio always
+ * pauses regardless of this setting. When the page becomes visible again,
+ * previously playing audio will resume.
+ *
+ * AudioSource also responds to application mute state changes. When the application
+ * is muted, the volume is set to 0. When unmuted, the volume
+ * returns to its previous value.
+ *
+ * @category Multimedia
+ * @group Components
+ */
+export declare class AudioSource extends Behaviour {
+    /**
+     * Checks if the user has interacted with the page to allow audio playback.
+     * Audio playback often requires a user gesture first due to browser autoplay policies.
+     * This is the same as calling {@link Application.userInteractionRegistered}.
+     *
+     * @returns Whether user interaction has been registered to allow audio playback
+     */
+    static get userInteractionRegistered(): boolean;
+    /**
+     * Registers a callback that will be executed once the user has interacted with the page,
+     * allowing audio playback to begin.
+     * This is the same as calling {@link Application.registerWaitForInteraction}.
+     *
+     * @param cb - The callback function to execute when user interaction is registered
+     */
+    static registerWaitForAllowAudio(cb: Function): void;
+    /**
+     * The audio clip to play. Can be a URL string pointing to an audio file or a {@link MediaStream} object.
+     */
+    clip: string | MediaStream;
+    /**
+     * When true, the audio will automatically start playing when the component is enabled.
+     * When false, you must call play() manually to start audio playback.
+     * @default false
+     */
+    playOnAwake: boolean;
+    /**
+     * When true, the audio clip will be loaded during initialization rather than when play() is called.
+     * This can reduce playback delay but increases initial loading time.
+     * @default true
+     */
+    preload: boolean;
+    /**
+     * When true, audio will continue playing when the browser tab loses focus.
+     * When false, audio will pause when the tab is minimized or not active.
+     * @default true
+     */
+    playInBackground: boolean;
+    /**
+     * Indicates whether the audio is currently playing.
+     *
+     * @returns True if the audio is playing, false otherwise
+     */
+    get isPlaying(): boolean;
+    /**
+     * The total duration of the current audio clip in seconds.
+     *
+     * @returns Duration in seconds or undefined if no clip is loaded
+     */
+    get duration(): number | undefined;
+    /**
+     * The current playback position as a normalized value between 0 and 1.
+     * Can be set to seek to a specific position in the audio.
+     */
+    get time01(): number;
+    set time01(val: number);
+    /**
+     * The current playback position in seconds.
+     * Can be set to seek to a specific time in the audio.
+     */
+    get time(): number;
+    set time(val: number);
+    /**
+     * When true, the audio will repeat after reaching the end.
+     * When false, audio will play once and stop.
+     * @default false
+     */
+    get loop(): boolean;
+    set loop(val: boolean);
+    /**
+     * Controls how the audio is positioned in space.
+     * Values range from 0 (2D, non-positional) to 1 (fully 3D positioned).
+     * Note: 2D playback is not fully supported in the current implementation.
+     */
+    get spatialBlend(): number;
+    set spatialBlend(val: number);
+    /**
+     * The minimum distance from the audio source at which the volume starts to attenuate.
+     * Within this radius, the audio plays at full volume regardless of distance.
+     */
+    get minDistance(): number;
+    set minDistance(val: number);
+    /**
+     * The maximum distance from the audio source beyond which the volume no longer decreases.
+     * This defines the outer limit of the attenuation curve.
+     */
+    get maxDistance(): number;
+    set maxDistance(val: number);
+    private _spatialBlend;
+    private _minDistance;
+    private _maxDistance;
+    /**
+     * Controls the overall volume/loudness of the audio.
+     * Values range from 0 (silent) to 1 (full volume).
+     * @default 1
+     */
+    get volume(): number;
+    set volume(val: number);
+    private _volume;
+    /**
+     * Controls the playback rate (speed) of the audio.
+     * Values greater than 1 increase speed, values less than 1 decrease it.
+     * This affects both speed and pitch of the audio.
+     * @default 1
+     */
+    set pitch(val: number);
+    get pitch(): number;
+    /**
+     * Determines how audio volume decreases with distance from the listener.
+     * @default AudioRolloffMode.Logarithmic
+     * @see {@link AudioRolloffMode}
+     */
+    rollOffMode: AudioRolloffMode;
+    private _loop;
+    private sound;
+    private helper;
+    private wasPlaying;
+    private audioLoader;
+    private shouldPlay;
+    private _lastClipStartedLoading;
+    private _audioElement;
+    /**
+     * Returns the underlying {@link PositionalAudio} object, creating it if necessary.
+     * The audio source needs a user interaction to be initialized due to browser autoplay policies.
+     *
+     * @returns The three.js PositionalAudio object or null if unavailable
+     */
+    get Sound(): PositionalAudio | null;
+    /**
+     * Indicates whether the audio source is queued to play when possible.
+     * This may be true before user interaction has been registered.
+     *
+     * @returns Whether the audio source intends to play
+     */
+    get ShouldPlay(): boolean;
+    /**
+     * Returns the Web Audio API context associated with this audio source.
+     *
+     * @returns The {@link AudioContext} or null if not available
+     */
+    get audioContext(): AudioContext | undefined;
+    /** @internal */
+    awake(): void;
+    /** @internal */
+    onEnable(): void;
+    /** @internal */
+    onDisable(): void;
+    private onVisibilityChanged;
+    private onApplicationMuteChanged;
+    private createAudio;
+    private __onAllowAudioCallback;
+    private applySpatialDistanceSettings;
+    private onNewClip;
+    /**
+     * Plays the audio clip or media stream.
+     * If no argument is provided, plays the currently assigned clip.
+     *
+     * @param clip - Optional audio clip or {@link MediaStream} to play
+     */
+    play(clip?: string | MediaStream | undefined): void;
+    /**
+     * Pauses audio playback while maintaining the current position.
+     * Use play() to resume from the paused position.
+     */
+    pause(): void;
+    /**
+     * Stops audio playback completely and resets the playback position to the beginning.
+     * Unlike pause(), calling play() after stop() will start from the beginning.
+     */
+    stop(): void;
+    private _lastContextTime;
+    private _hasEnded;
+    private _needUpdateSpatialDistanceSettings;
+    /** @internal */
+    update(): void;
+}