@needle-tools/engine/lib/engine/engine_audio.d.ts

Needle Engine is a web-based runtime for 3D apps. It runs on your machine for development with great integrations into editors like Unity or Blender - and can be deployed onto any device! It is flexible, extensible and networking and XR are built-in.

/**
 * @internal
 * Ensure the audio context is resumed if it gets suspended or interrupted */
export declare function ensureAudioContextIsResumed(): void;
/**
 * Represents an audio clip that can be loaded and played independently.
 * The AudioClip class encapsulates the URL of the audio resource and provides
 * methods for playback control (play, pause, stop) and querying duration.
 */
export declare class AudioClip {
    readonly url: string;
    /**
     * Creates a new AudioClip instance with the specified URL.
     * @param url The URL of the audio resource to load. This can be a path to an audio file or a MediaStream URL.
     */
    constructor(url: string);
    /** Whether the clip is currently playing.
     * @returns `true` if the clip is actively playing audio.
     */
    get isPlaying(): boolean;
    /**
     * The total duration of the audio clip in seconds.
     * Loads the audio metadata if not already available.
     * @returns A promise that resolves with the duration in seconds.
     */
    getDuration(): Promise<number>;
    /**
     * Plays the audio clip from the current position.
     * @returns A promise that resolves when playback finishes, or rejects on error.
     * If the clip is looping, the promise will never resolve on its own – call {@link stop} or {@link pause} to end playback.
     */
    play(): Promise<void>;
    /**
     * Pauses playback at the current position.
     * Call {@link play} to resume.
     */
    pause(): void;
    /**
     * Stops playback and resets the position to the beginning.
     */
    stop(): void;
    /** Whether the clip should loop when reaching the end. */
    get loop(): boolean;
    set loop(value: boolean);
    /** Playback volume from 0 (silent) to 1 (full). */
    get volume(): number;
    set volume(value: number);
    /** Current playback position in seconds. */
    get currentTime(): number;
    set currentTime(value: number);
    /** Normalized playback progress from 0 to 1.
     * @returns The current playback position as a value between 0 and 1, or 0 if the duration is unknown.
     */
    get progress(): number;
    /**
     * Seeks to a normalized position (0–1) in the clip.
     * @param position A value between 0 (start) and 1 (end).
     */
    seek(position: number): void;
    /** The underlying HTMLAudioElement, or `undefined` if not yet created.
     * Use this to connect the element to the Web Audio API via `createMediaElementSource()`.
     * @returns The HTMLAudioElement if the clip has been loaded or played, otherwise `undefined`.
     */
    get audioElement(): HTMLAudioElement | undefined;
    private _audioElement?;
    private _duration?;
    private _loadPromise?;
    private _loop;
    private _volume;
    /** Lazily creates and loads the shared HTMLAudioElement. */
    private ensureAudioElement;
}