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 (3D) positioning.
 *
 * **Browser autoplay policies:**
 * Web browsers require user interaction before playing audio. Use
 * `AudioSource.userInteractionRegistered` to check if playback is allowed,
 * or `registerWaitForAllowAudio()` to queue playback until interaction occurs.
 *
 * **Spatial audio:**
 * Set `spatialBlend` to 1 for full 3D positioning, or 0 for 2D (non-spatial).
 * Requires an {@link AudioListener} in the scene (typically on the camera).
 *
 * **Visibility handling:**
 * Audio automatically pauses when the tab is hidden unless `playInBackground = true`.
 * On mobile, audio always pauses in background regardless of this setting.
 *
 * @example Play audio on button click
 * ```ts
 * onClick() {
 *   const audio = this.getComponent(AudioSource);
 *   audio.play();
 * }
 * ```
 *
 * @example Wait for user interaction
 * ```ts
 * AudioSource.registerWaitForAllowAudio(() => {
 *   this.getComponent(AudioSource)?.play();
 * });
 * ```
 *
 * @summary Plays audio clips from files or media streams
 * @category Multimedia
 * @group Components
 * @see {@link AudioListener} for the audio receiver component
 * @see {@link AudioRolloffMode} for distance attenuation options
 * @see {@link Voip} for voice communication
 * @see {@link PlayableDirector} for timeline-based audio
 * @link https://engine.needle.tools/samples/?overlay=samples&tag=audio
 * @link https://spatial-audio-zubckswmztj.needle.run/
 */
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;
}