@needle-tools/engine
Version:
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.
241 lines (240 loc) • 8.54 kB
TypeScript
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;
}