@babylonjs/lite 1.4.0 → 1.5.0

package/index.d.ts

@@ -699,6 +699,16 @@ export declare function attachRotationGizmoToNode(gizmo: RotationGizmo, node: Sc
 /** Attach all scale sub-gizmos to a node, or detach them with `null`. */
 export declare function attachScaleGizmoToNode(gizmo: ScaleGizmo, node: SceneNode | null): void;
 
+/**
+ * Attaches a spatial sound/bus — or the engine's listener — to a world
+ * transform. The position/rotation follow the target on each
+ * {@link updateSpatialAudio} (or auto-update) tick.
+ * @param target - A `StaticSound`, `AudioBus`, or the `AudioEngine` (listener).
+ * @param worldTarget - The transform to follow.
+ * @param type - Which transform components to follow. Defaults to `"positionAndRotation"`.
+ */
+export declare function attachSpatialTarget(target: AudioGraphHost | AudioEngine, worldTarget: SpatialTarget, type?: SpatialAttachmentType): void;
+
 /**
  * Attaches a manager to a sprite renderer's update hooks so its animations advance each frame.
  * @param renderer - Sprite renderer whose update loop drives the manager.
@@ -729,6 +739,132 @@ export declare function attachSpriteAnimationsToScene(scene: SceneContext, manag
  */
 export declare function attachVat(engine: EngineContext, mesh: Mesh, baked: VatBakeResult, clip?: string): VatHandle;
 
+/** Options for {@link enableAnalyzer}. */
+export declare interface AudioAnalyzerOptions {
+    /** FFT window size (a power of two, `32`–`32768`). Defaults to `2048`. */
+    fftSize?: number;
+    /** Minimum power value for the dB range, in dBFS. Defaults to `-100`. */
+    minDecibels?: number;
+    /** Maximum power value for the dB range, in dBFS. Defaults to `-30`. */
+    maxDecibels?: number;
+    /** Time-averaging constant in `[0, 1]`. Defaults to `0.8`. */
+    smoothing?: number;
+}
+
+/** A generic mixer bus. Pure state — drive it with the bus functions. */
+export declare interface AudioBus {
+    /** Bus name. */
+    readonly name: string;
+
+/** Options for {@link createAudioBusAsync}. */
+export declare interface AudioBusOptions {
+    /** Initial volume. Defaults to `1`. */
+    volume?: number;
+    /** Output bus. Defaults to the engine's default main bus. */
+    outBus?: PrimaryAudioBus;
+}
+
+/**
+ * A Babylon Lite audio engine. Pure state — operate on it with the audio
+ * functions (`createSoundAsync`, `setMasterVolume`, `disposeAudioEngine`, …).
+ */
+export declare interface AudioEngine {
+    /** Current context state. Always `"running"` for an offline context. */
+    readonly state: AudioEngineState;
+    /** The audio context's current time, in seconds. */
+    readonly currentTime: number;
+    /** Fires whenever {@link state} changes. */
+    readonly onStateChanged: AudioSignal<AudioEngineState>;
+    /** Fires on every qualifying user gesture (click), not just the first. */
+    readonly onUserGesture: AudioSignal<void>;
+
+/** Options for {@link createAudioEngineAsync}. */
+export declare interface AudioEngineOptions {
+    /**
+     * The audio context to use. Pass an `OfflineAudioContext` for deterministic,
+     * faster-than-realtime rendering (used by the audio test suite). When omitted
+     * a real-time `AudioContext` is created.
+     */
+    audioContext?: BaseAudioContext;
+    /** Master output volume. Defaults to `1`. */
+    volume?: number;
+    /** Default parameter ramp smoothing, in seconds. Defaults to `0.01`. */
+    parameterRampDuration?: number;
+    /** Auto-resume the context on user interaction (click). Defaults to `true`. */
+    resumeOnInteraction?: boolean;
+    /** Auto-resume the context if the browser pauses playback. Defaults to `true`. */
+    resumeOnPause?: boolean;
+    /** Retry interval (ms) for `resumeOnPause`. Defaults to `1000`. */
+    resumeOnPauseRetryInterval?: number;
+}
+
+/** Audio context state, mirroring the Web Audio `AudioContextState` plus `"interrupted"`. */
+export declare type AudioEngineState = "running" | "suspended" | "closed" | "interrupted";
+
+/** A sound, source, or bus that can carry spatial, stereo, or analyzer sub-nodes. */
+export declare type AudioGraphHost = StaticSound | StreamingSound | AudioBus | AudioInputSource;
+
+/**
+ * A sound fed by a live or external Web Audio input node (e.g. a microphone).
+ * Accepted anywhere an {@link AudioGraphHost} is — enable spatial, stereo, or
+ * analyzer features on it directly.
+ */
+export declare interface AudioInputSource {
+    /** The source name. */
+    readonly name: string;
+
+/**
+ * Audio parameter ramping — faithful port of Babylon.js AudioV2
+ * `audioUtils._GetAudioParamCurveValues` + `_WebAudioParameterComponent`,
+ * re-shaped to pure functions + a small pure-state wrapper.
+ *
+ * The exponential/logarithmic normalized curves are cached via lazy-init
+ * (never at module scope) so this module has zero import-time side effects.
+ * The curve math is copied verbatim from AudioV2 to preserve identical output.
+ */
+/** Ramp shape used when changing an audio parameter (volume, pan, position…). */
+export declare type AudioRampShape = "none" | "linear" | "exponential" | "logarithmic";
+
+/**
+ * Lightweight event signal — Babylon Lite's tree-shakable replacement for the
+ * core `Observable`. Pure state + standalone-ish callback set. No module-level
+ * side effects: the callback set is created lazily on first `add`.
+ *
+ * Behavioural parity with the subset of `Observable` the audio engine uses:
+ * `add`, `addOnce`, `removeCallback`, `notifyObservers`, `clear`, `hasObservers`.
+ */
+/** Public read surface of a signal — consumers can only subscribe. */
+export declare interface AudioSignal<T> {
+    /** Subscribe. Returns an unsubscribe function. */
+    add(callback: (value: T) => void): () => void;
+    /** Subscribe for a single notification. Returns an unsubscribe function. */
+    addOnce(callback: (value: T) => void): () => void;
+}
+
+/** Visualizer state. Pure state — driven by the visualizer functions. */
+export declare interface AudioVisualizer {
+    /** The canvas being drawn to. */
+    readonly canvas: HTMLCanvasElement;
+
+/** What to draw in the visualizer. */
+export declare type AudioVisualizerMode = "bars" | "waveform" | "both";
+
+/** Options for {@link createAudioVisualizer}. */
+export declare interface AudioVisualizerOptions {
+    /** FFT window size (a power of two). Defaults to `2048`. */
+    fftSize?: number;
+    /** Analyzer time-averaging constant in `[0, 1]`. Defaults to `0.8`. */
+    smoothing?: number;
+    /** What to draw. Defaults to `"both"`. */
+    mode?: AudioVisualizerMode;
+    /** Canvas background fill. Defaults to `"#101014"`. */
+    backgroundColor?: string;
+    /** Frequency-bar color. Defaults to `"#4fc3f7"`. */
+    barColor?: string;
+    /** Waveform line color. Defaults to `"#ffffff"`. */
+    waveformColor?: string;
+}
+
 /** A single arrow-shaped gizmo that translates its attached node along one axis. */
 export declare interface AxisDragGizmo {
     /** The root node — gizmo follows its `attachedNode` by copying world translation. */
@@ -1518,6 +1654,36 @@ export declare function createAnimationTask(update: AnimationTaskUpdate, options
 /** Create a bare ArcRotateCamera with given params. Pure data, no scene knowledge. */
 export declare function createArcRotateCamera(alpha: number, beta: number, radius: number, target: Vec3): ArcRotateCamera;
 
+/**
+ * Creates a generic mixer bus routed to another bus (defaulting to the engine's
+ * default main bus). Multiple sounds/buses can be routed through a bus to mix
+ * and control their combined volume.
+ * @param engine - The audio engine.
+ * @param name - A name for the bus.
+ * @param options - Bus options.
+ * @returns A promise that resolves with the ready bus.
+ */
+export declare function createAudioBusAsync(engine: AudioEngine, name: string, options?: AudioBusOptions): Promise<AudioBus>;
+
+/**
+ * Creates and initializes an audio engine.
+ * @param options - Engine options.
+ * @returns A promise that resolves with the ready-to-use engine.
+ */
+export declare function createAudioEngineAsync(options?: AudioEngineOptions): Promise<AudioEngine>;
+
+/**
+ * Creates a real-time visualizer that taps the host's analyzer and draws to the
+ * given canvas. Enables the analyzer on the host if it is not already enabled.
+ * Call {@link startAudioVisualizer} to begin the animation loop.
+ * @param host - A `StaticSound`, `StreamingSound`, `AudioBus`, or input source.
+ * @param canvas - The destination 2D canvas.
+ * @param options - Visualizer options.
+ * @returns The visualizer handle; dispose it with {@link disposeAudioVisualizer}.
+ * @throws If a 2D context cannot be obtained from the canvas.
+ */
+export declare function createAudioVisualizer(host: AudioGraphHost, canvas: HTMLCanvasElement, options?: AudioVisualizerOptions): AudioVisualizer;
+
 /** Build an axis-drag gizmo and attach it to the given utility layer.  Call
  *  `attachAxisDragGizmoToNode` to bind it to a node so it follows + drives it. */
 export declare function createAxisDragGizmo(engine: EngineContext, layer: UtilityLayer, options: AxisDragGizmoOptions): AxisDragGizmo;
@@ -1961,6 +2127,17 @@ export declare function createMeshFromCsg2(engine: EngineContext, solid: Csg2Sol
  *  No material is assigned — the caller must set mesh.material before adding to scene. */
 export declare function createMeshFromData(engine: EngineContext, name: string, positions: Float32Array, normals: Float32Array, indices: Uint32Array, uvs?: Float32Array, uvs2?: Float32Array, tangents?: Float32Array, colors?: Float32Array): Mesh;
 
+/**
+ * Requests microphone access and wraps the resulting stream as a sound source.
+ * The source does not auto-connect to the main bus by default (to avoid
+ * feedback); attach an analyzer or set an `outBus` to use it.
+ * @param engine - The audio engine.
+ * @param options - Source options.
+ * @returns A promise that resolves with the ready microphone source.
+ * @throws If microphone access is denied or unavailable.
+ */
+export declare function createMicrophoneSoundSourceAsync(engine: AudioEngine, options?: SoundSourceOptions): Promise<AudioInputSource>;
+
 /** Create morph target GPU data from parsed glTF targets.
  *  @param engine       - Engine context (provides GPU device)
  *  @param targets      - Array of `{positions, normals}` deltas per target
@@ -2264,6 +2441,35 @@ export declare function createShaderNormalMaterialView(source: ShaderMaterial, c
  *  @returns A bilinear-sampled `Texture2D` backed by a tiny GPU texture. */
 export declare function createSolidTexture2D(engine: EngineContext, r: number, g: number, b: number, a?: number): Texture2D;
 
+/**
+ * Creates a buffer-backed sound, routed to the given output bus (or the
+ * engine's default main bus).
+ * @param engine - The audio engine.
+ * @param source - An `AudioBuffer`, `ArrayBuffer`, URL, URL list, or `SoundBuffer`.
+ * @param options - Sound options.
+ * @returns A promise that resolves with the ready sound.
+ */
+export declare function createSoundAsync(engine: AudioEngine, source: SoundSource, options?: StaticSoundOptions): Promise<StaticSound>;
+
+/**
+ * Loads and decodes audio into a reusable {@link SoundBuffer}.
+ * @param engine - The audio engine.
+ * @param source - An `AudioBuffer`, `ArrayBuffer`, URL, or URL list.
+ * @param options - Decode options.
+ * @returns A promise that resolves with the decoded buffer.
+ */
+export declare function createSoundBufferAsync(engine: AudioEngine, source: SoundSource, options?: SoundBufferOptions): Promise<SoundBuffer>;
+
+/**
+ * Wraps an arbitrary Web Audio node as a sound source, routed to the given
+ * output bus (or the engine's default main bus).
+ * @param engine - The audio engine.
+ * @param node - The input node to wrap (its output is routed through the graph).
+ * @param options - Source options.
+ * @returns A promise that resolves with the ready source.
+ */
+export declare function createSoundSourceAsync(engine: AudioEngine, node: AudioNode, options?: SoundSourceOptions): Promise<AudioInputSource>;
+
 /** Create a sphere mesh. Caller must assign material. */
 export declare function createSphere(engine: EngineContext, options?: SphereOptions): Mesh;
 
@@ -2337,6 +2543,16 @@ export declare function createStandardMaterial(): StandardMaterialProps;
  *  The view references the source; material state is never copied. */
 export declare function createStandardNoColorMaterialView(source: StandardMaterialProps): MaterialView;
 
+/**
+ * Creates a streaming, media-element-backed sound routed to the given output bus
+ * (or the engine's default main bus). Requires a real-time `AudioContext`.
+ * @param engine - The audio engine.
+ * @param source - A URL, a list of candidate URLs, or an `HTMLMediaElement`.
+ * @param options - Streaming sound options.
+ * @returns A promise that resolves with the ready sound.
+ */
+export declare function createStreamingSoundAsync(engine: AudioEngine, source: StreamingSoundSource, options?: StreamingSoundOptions): Promise<StreamingSound>;
+
 /**
  * Create an auxiliary rendering surface bound to an existing engine. The surface
  * configures its own `GPUCanvasContext` against `engine._device` and is appended to
@@ -2428,6 +2644,15 @@ export declare function createUniformEffectRenderTask(config: UniformEffectRende
  */
 export declare function createUniformEffectWrapper(engine: EngineContext, options: UniformEffectWrapperOptions): UniformEffectWrapper;
 
+/**
+ * Creates and mounts the unmute button. It is shown while the engine's context
+ * is not `"running"` and hidden once it resumes; clicking it unlocks the engine.
+ * @param engine - The audio engine to unlock.
+ * @param options - UI options (parent element).
+ * @returns The UI handle; dispose it with {@link disposeUnmuteUI}.
+ */
+export declare function createUnmuteUI(engine: AudioEngine, options?: UnmuteUIOptions): UnmuteUI;
+
 /** Create a utility layer attached to the given engine + main scene.
  *  The returned `scene` shares the main scene's camera so view + projection
  *  remain in sync without manual mirroring.  The utility scene renders with a
@@ -2636,6 +2861,13 @@ export declare interface DepthOfFieldPostProcessTaskConfig extends PostProcessTa
     depthNotNormalized?: boolean;
 }
 
+/**
+ * Detaches a spatial sound/bus — or the engine's listener — from its world
+ * transform.
+ * @param target - A `StaticSound`, `AudioBus`, or the `AudioEngine` (listener).
+ */
+export declare function detachSpatialTarget(target: AudioGraphHost | AudioEngine): void;
+
 export declare interface DirectionalLight extends LightBase {
     readonly lightType: "directional";
     direction: ObservableVec3;
@@ -2653,6 +2885,23 @@ export declare interface DiscOptions {
     arc?: number;
 }
 
+/** Disposes a generic bus, releasing its sub-graph. */
+export declare function disposeAudioBus(bus: AudioBus): void;
+
+/**
+ * Disposes the audio engine: stops all sounds, tears down global hooks, and
+ * closes the (non-offline) audio context.
+ * @param engine - The audio engine to dispose.
+ */
+export declare function disposeAudioEngine(engine: AudioEngine): void;
+
+/**
+ * Stops the render loop and releases the visualizer. The underlying analyzer tap
+ * stays on the host (dispose the host to release it).
+ * @param viz - The visualizer handle.
+ */
+export declare function disposeAudioVisualizer(viz: AudioVisualizer): void;
+
 /** Dispose the gizmo: remove meshes, unregister pointer-drag, drop materials. */
 export declare function disposeAxisDragGizmo(gizmo: AxisDragGizmo, layer: UtilityLayer): void;
 
@@ -2733,6 +2982,16 @@ export declare function disposeScaleGizmo(gizmo: ScaleGizmo, layer: UtilityLayer
 /** Release all GPU resources owned by this scene. */
 export declare function disposeScene(scene: SceneContext): void;
 
+/** Disposes the sound, stopping playback and releasing its graph. */
+export declare function disposeSound(sound: StaticSound): void;
+
+/**
+ * Disposes a sound source, stopping any microphone tracks and releasing its
+ * graph.
+ * @param source - The sound source.
+ */
+export declare function disposeSoundSource(source: AudioInputSource): void;
+
 /**
  * Detaches a binding created by {@link attachSpriteAnimationsToScene} or
  * {@link attachSpriteAnimationsToRenderer}. Safe to call more than once.
@@ -2748,6 +3007,9 @@ export declare function disposeSpriteAnimationBinding(binding: SpriteAnimationBi
  */
 export declare function disposeSpriteRenderer(sr: SpriteRenderer): void;
 
+/** Disposes the sound, stopping playback and releasing its graph and preloaded instances. */
+export declare function disposeStreamingSound(sound: StreamingSound): void;
+
 /** Remove and unconfigure an auxiliary surface from its engine. Rendering contexts
  *  registered on this surface are dropped from its list but not disposed — call their
  *  own disposers (e.g. `disposeScene`) separately.
@@ -2770,6 +3032,12 @@ export declare function disposeTextRenderer(tr: TextRenderer): void;
 /** Destroy the uniform buffer and clear cached GPU objects owned by the uniform effect wrapper. */
 export declare function disposeUniformEffectWrapper(wrapper: UniformEffectWrapper): void;
 
+/**
+ * Removes the unmute button and its styles and unsubscribes from engine state.
+ * @param ui - The UI handle.
+ */
+export declare function disposeUnmuteUI(ui: UnmuteUI): void;
+
 /** Dispose the utility layer's underlying scene. Idempotent. */
 export declare function disposeUtilityLayer(utility: UtilityLayer): void;
 
@@ -2879,6 +3147,15 @@ export declare interface EffectWrapperOptions {
     blend?: GPUBlendState;
 }
 
+/**
+ * Enables (or reconfigures) frequency/amplitude analysis on a sound or bus,
+ * building the analyzer tap on first use. Pulls the analyzer module only when
+ * called.
+ * @param host - A `StaticSound`, `StreamingSound`, or `AudioBus`.
+ * @param options - Analyzer options (fftSize, dB range, smoothing).
+ */
+export declare function enableAnalyzer(host: AudioGraphHost, options?: AudioAnalyzerOptions): void;
+
 /** Enable advanced animation blending for a manager. Kept opt-in so manual-only weights do not pay for skeletal mixing code. */
 export declare function enableAnimationBlending(manager: AnimationManager): void;
 
@@ -2993,6 +3270,22 @@ export declare function enableRenderTaskTransmission(task: RenderTask, engine: E
 /** Enable scene-color transmission for every render task currently registered in a scene. PBR materials are marked for linear transmission, and a trailing image-processing task is appended when needed. */
 export declare function enableSceneTransmission(scene: SceneContext, engine: EngineContext): void;
 
+/**
+ * Enables (or reconfigures) 3D spatial audio on a sound or bus, building the
+ * panner sub-node on first use. Pulls the spatial module only when called.
+ * @param host - A `StaticSound` or `AudioBus`.
+ * @param options - Spatial options (position, distance model, cone, attach, …).
+ */
+export declare function enableSpatial(host: AudioGraphHost, options?: SpatialSoundOptions): void;
+
+/**
+ * Enables (or reconfigures) stereo panning on a sound or bus, building the
+ * stereo sub-node on first use. Pulls the stereo module only when called.
+ * @param host - A `StaticSound`, `StreamingSound`, or `AudioBus`.
+ * @param options - Stereo options (pan).
+ */
+export declare function enableStereo(host: AudioGraphHost, options?: StereoSoundOptions): void;
+
 /** Enable or disable GPU frustum culling for an existing thin-instanced mesh.
  *
  * Call this after `setThinInstances()`/`addThinInstance()` and before `registerScene()`.
@@ -3533,6 +3826,24 @@ export declare function getBillboardSpriteHandleIndex(handle: BillboardSpriteHan
  *  When several joints share a name, the first in joint order is returned. */
 export declare function getBoneByName(skeleton: Skeleton, name: string): Bone | undefined;
 
+/**
+ * Writes the current frequency-domain data as unsigned bytes into `out`,
+ * building the analyzer tap on first use. `out` should be sized to the
+ * analyzer's `frequencyBinCount` (`fftSize / 2`).
+ * @param host - A `StaticSound`, `StreamingSound`, or `AudioBus`.
+ * @param out - Destination buffer; values are written in place.
+ */
+export declare function getByteFrequencyData(host: AudioGraphHost, out: Uint8Array): void;
+
+/**
+ * Writes the current time-domain (waveform) data as unsigned bytes into `out`,
+ * building the analyzer tap on first use. Each sample is centered on `128`.
+ * `out` should be sized to the analyzer's `fftSize`.
+ * @param host - A `StaticSound`, `StreamingSound`, or `AudioBus`.
+ * @param out - Destination buffer; values are written in place.
+ */
+export declare function getByteTimeDomainData(host: AudioGraphHost, out: Uint8Array): void;
+
 /** Get the world-space position of a camera. */
 export declare function getCameraPosition(camera: Camera): Vec3;
 
@@ -3559,15 +3870,36 @@ export declare function getEffectiveAspectRatio(camera: Camera | null | undefine
  */
 export declare function getEffectivePitchMax(limits: GeospatialLimits, currentRadius: number): number;
 
+/**
+ * Writes the current frequency-domain data as floats (in dBFS) into `out`,
+ * building the analyzer tap on first use. `out` should be sized to the
+ * analyzer's `frequencyBinCount` (`fftSize / 2`).
+ * @param host - A `StaticSound`, `StreamingSound`, or `AudioBus`.
+ * @param out - Destination buffer; values are written in place.
+ */
+export declare function getFloatFrequencyData(host: AudioGraphHost, out: Float32Array): void;
+
 /** Read the current floating-origin offset from a scene as a `Vec3`. The
  *  offset is the active camera's world position. Returns the zero vector
  *  when no camera is set (typical headless/precompute case). For non-LWR
  *  engines this module is not imported, so the function is unreachable. */
 export declare function getFloatingOriginOffset(scene: SceneContext): Vec3;
 
+/**
+ * Writes the current time-domain (waveform) data as floats in `[-1, 1]` into
+ * `out`, building the analyzer tap on first use. `out` should be sized to the
+ * analyzer's `fftSize`.
+ * @param host - A `StaticSound`, `StreamingSound`, or `AudioBus`.
+ * @param out - Destination buffer; values are written in place.
+ */
+export declare function getFloatTimeDomainData(host: AudioGraphHost, out: Float32Array): void;
+
 /** Get the scene's frame graph. Always non-null — created in `createSceneContext`. */
 export declare function getFrameGraph(scene: SceneContext): FrameGraph;
 
+/** The master output volume. */
+export declare function getMasterVolume(engine: AudioEngine): number;
+
 /** Get the current seed used by Recast's randomized queries. */
 export declare function getNavigationRandomSeed(plugin: NavigationPlugin): number;
 
@@ -4307,6 +4639,11 @@ export declare function loadSPZ(scene: SceneContext, url: string): Promise<Gauss
  *  @returns A promise resolving to the uploaded `Texture2D`. */
 export declare function loadTexture2D(engine: EngineContext, url: string, opts?: Texture2DOptions): Promise<Texture2D>;
 
+/** A main audio bus. Sounds route here by default. Pure state — drive it with the bus functions. */
+export declare interface MainBus {
+    /** Bus name. */
+    readonly name: string;
+
 /** Force the container's GPU light state to re-upload next frame. Call after mutating a light's
  *  position / range / intensity / diffuse in place (e.g. animated lights such as drifting fireflies),
  *  since those edits don't bump the container version on their own. */
@@ -4978,6 +5315,12 @@ export declare interface Pass {
 /** Pause playback of an animation group. */
 export declare function pauseAnimation(group: AnimationGroup): void;
 
+/** Pauses all of the sound's instances. */
+export declare function pauseSound(sound: StaticSound): void;
+
+/** Pauses all of the sound's instances. */
+export declare function pauseStreamingSound(sound: StreamingSound): void;
+
 /** User-facing properties for a physically based (metallic-roughness) material.
  *  Create one manually via `createPbrMaterial()` or let `loadGltf()` build it.
  *  Optional sub-feature objects (clearcoat, sheen, anisotropy, subsurface) are
@@ -5649,6 +5992,14 @@ export declare function playBillboardSpriteAnimation(manager: SpriteAnimationMan
  */
 export declare function playBillboardSpriteIndexAnimation(manager: SpriteAnimationManager, system: BillboardSpriteSystem, index: number, from: number, to: number, loop: boolean, delayMs: number, options?: PlaySpriteAnimationOptions): SpriteFrameAnimation;
 
+/**
+ * Plays the sound. Spawns a new instance per call (subject to `maxInstances`).
+ * A paused sound is resumed instead.
+ * @param sound - The sound to play.
+ * @param options - Per-play overrides.
+ */
+export declare function playSound(sound: StaticSound, options?: StaticSoundPlayOptions): void;
+
 /**
  * Plays a frame animation on a 2D sprite addressed by its stable handle.
  * The handle is resolved each tick, so the animation survives swap-remove reindexing.
@@ -5683,6 +6034,15 @@ export declare interface PlaySpriteAnimationOptions {
 /** Replay an animation; omit options to keep callbacks/removal, pass options to overwrite them, or `{}` to clear them. */
 export declare function playSpriteFrameAnimation(animation: SpriteFrameAnimation, from?: number, to?: number, loop?: boolean, delayMs?: number, options?: PlaySpriteAnimationOptions): void;
 
+/**
+ * Plays the streaming sound. Reuses a preloaded instance when available,
+ * otherwise spawns a new one (subject to `maxInstances`). A paused sound is
+ * resumed instead.
+ * @param sound - The sound to play.
+ * @param options - Per-play overrides.
+ */
+export declare function playStreamingSound(sound: StreamingSound, options?: StreamingSoundPlayOptions): void;
+
 /** A texture + sampler pair contributed by a plugin. `texture`/`sampler` are the
  *  WGSL variable names used by the plugin's custom code; the engine wires up the
  *  GPU bindings in declaration order from {@link MaterialPlugin.bindTextures}. */
@@ -5866,12 +6226,21 @@ declare interface PostProcessVec2_2 {
     y: number;
 }
 
+/** Preloads a single instance of the sound and resolves once it can play through. */
+export declare function preloadStreamingInstanceAsync(sound: StreamingSound): Promise<void>;
+
+/** Preloads the given number of instances and resolves once all can play through. */
+export declare function preloadStreamingInstancesAsync(sound: StreamingSound, count: number): Promise<void>;
+
 /** Something that runs before the main render pass (shadow maps, compute, etc.). */
 export declare interface PrePassRenderable {
     /** Execute pre-pass work (e.g., render shadow depth map + blur). Returns the number of GPU draw calls issued. */
     execute(encoder: GPUCommandEncoder, engine: EngineContext): number;
 }
 
+/** A bus that sounds or other buses can output to (the engine main bus or a generic {@link AudioBus}). */
+export declare type PrimaryAudioBus = AudioBus | MainBus;
+
 /** A reusable, target-independent set of compiled property tracks with a total duration. */
 export declare interface PropertyAnimationClip {
     readonly name: string;
@@ -5942,6 +6311,14 @@ export declare function quatFromLookDirectionRH(forward: Vec3, up: Vec3): Quat;
  */
 export declare function quatFromRotationMatrix(matrix: Mat4): Quat;
 
+/** Options for ramping an audio parameter's value. */
+export declare interface RampOptions {
+    /** Ramp time, in seconds. Clamped to at least the engine's `parameterRampDuration`. */
+    duration?: number;
+    /** Ramp shape. Defaults to `"linear"`. */
+    shape?: AudioRampShape;
+}
+
 /** A ray defined by origin, direction, and length. */
 declare interface Ray {
     origin: [number, number, number];
@@ -6175,6 +6552,14 @@ export declare interface Renderable {
     bind(engine: EngineContext, target: RenderTargetSignature): DrawBinding;
 }
 
+/**
+ * Draws a single visualizer frame from the current analyzer data. Safe to call
+ * directly (e.g. from a custom loop or a test) without starting the built-in
+ * animation loop.
+ * @param viz - The visualizer handle.
+ */
+export declare function renderAudioVisualizerFrame(viz: AudioVisualizer): void;
+
 /**
  * A surface Babylon Lite can render into. Either a DOM canvas (main thread) or an
  * `OffscreenCanvas` (e.g. one transferred to a Web Worker via
@@ -6384,6 +6769,12 @@ export declare function resizeSurface(surface: SurfaceContext): void;
  *  Babylon viewport y is normalized from the bottom; WebGPU viewport/scissor y is from the top. */
 export declare function resolveCameraViewport(camera: Camera | null | undefined, targetWidth: number, targetHeight: number): PixelViewport;
 
+/** Resumes a paused sound. */
+export declare function resumeSound(sound: StaticSound, options?: StaticSoundPlayOptions): void;
+
+/** Resumes a paused streaming sound. */
+export declare function resumeStreamingSound(sound: StreamingSound, options?: StreamingSoundPlayOptions): void;
+
 /** Options for `createRibbonData`: a set of parallel paths joined into a strip. */
 export declare interface RibbonOptions {
     pathArray: Vec3[][];
@@ -6599,6 +6990,9 @@ export declare function setBoneScaling(skeleton: Skeleton, bone: Bone, x: number
  *  so the bone returns to its animated / rest scale. */
 export declare function setBoneVisible(skeleton: Skeleton, bone: Bone, visible: boolean): void;
 
+/** Sets a bus's output volume, optionally ramping. Works on a generic bus or the main bus. */
+export declare function setBusVolume(bus: PrimaryAudioBus, value: number, options?: RampOptions): void;
+
 /**
  * Configure orbit/zoom limits on an ArcRotateCamera. This is fully opt-in and
  * self-contained: cameras that never call it pay zero cost and bundle no clamping
@@ -6714,6 +7108,14 @@ export declare function setHierarchyInstanceMatrix(pool: HierarchyInstancePool,
  *  modules it pulls). Call before the first KHR_texture_basisu texture loads. */
 export declare function setKtx2DecoderUrl(url: string, wasmUrls?: Record<string, Record<string, string>>): void;
 
+/**
+ * Sets the master output volume, optionally ramping to the new value.
+ * @param engine - The audio engine.
+ * @param value - Target volume (1 = unchanged).
+ * @param options - Optional ramp shape/duration.
+ */
+export declare function setMasterVolume(engine: AudioEngine, value: number, options?: RampOptions): void;
+
 /** Raise (or lower) the maximum number of scene lights in the shared lights UBO.
  *  Must be called BEFORE scene pipelines are compiled — existing pipelines
  *  and UBOs bake the cap into their WGSL/layout. */
@@ -6950,6 +7352,51 @@ export declare function setShaderVector3(material: ShaderMaterial, name: string,
 /** Register scene-owned shadow caster inputs for a generator. */
 export declare function setShadowTaskCasterMeshes(shadowGenerator: ShadowGenerator, casterMeshes: readonly Mesh[]): void;
 
+/**
+ * Sets the source volume, optionally ramping.
+ * @param source - The sound source.
+ * @param value - Linear gain (`1` = unity).
+ * @param options - Optional ramp options.
+ */
+export declare function setSoundSourceVolume(source: AudioInputSource, value: number, options?: RampOptions): void;
+
+/** Sets the sound's output volume, optionally ramping. */
+export declare function setSoundVolume(sound: StaticSound, value: number, options?: RampOptions): void;
+
+/**
+ * Toggles a `requestAnimationFrame`-driven loop that calls
+ * {@link updateSpatialAudio} automatically.
+ * @param engine - The audio engine.
+ * @param enabled - Whether to run the auto-update loop.
+ * @param minUpdateMs - Minimum time between updates, in milliseconds. Defaults to `0`.
+ */
+export declare function setSpatialAutoUpdate(engine: AudioEngine, enabled: boolean, minUpdateMs?: number): void;
+
+/**
+ * Configures the spatial listener (the "ears"). Builds it on first use.
+ * @param engine - The audio engine.
+ * @param options - Listener options.
+ */
+export declare function setSpatialListener(engine: AudioEngine, options?: SpatialListenerOptions): void;
+
+/** Sets the listener world position, building the listener on first use. */
+export declare function setSpatialListenerPosition(engine: AudioEngine, position: Vec3): void;
+
+/**
+ * Sets the facing orientation of a spatial sound/bus.
+ * @param host - A `StaticSound` or `AudioBus`.
+ * @param orientation - Facing direction.
+ */
+export declare function setSpatialOrientation(host: AudioGraphHost, orientation: Vec3): void;
+
+/**
+ * Sets the world position of a spatial sound/bus, building the panner sub-node
+ * on first use.
+ * @param host - A `StaticSound` or `AudioBus`.
+ * @param position - World-space position.
+ */
+export declare function setSpatialPosition(host: AudioGraphHost, position: Vec3): void;
+
 /**
  * Sets the atlas frame of the sprite referenced by `handle`.
  * @param handle - Handle of the sprite to update.
@@ -6996,6 +7443,18 @@ export declare function setSprite2DUvOffset(layer: Sprite2DLayer, index: number,
  */
 export declare function setSpriteRendererTarget(sr: SpriteRenderer, target: Texture2D | null): void;
 
+/**
+ * Sets the stereo pan of a sound or bus, building the stereo sub-node on first
+ * use.
+ * @param host - A `StaticSound`, `StreamingSound`, or `AudioBus`.
+ * @param pan - Pan in the range `[-1, 1]` (`-1` = full left, `1` = full right).
+ * @param options - Optional ramp options for a smooth transition.
+ */
+export declare function setStereoPan(host: AudioGraphHost, pan: number, options?: RampOptions): void;
+
+/** Sets the sound's output volume, optionally ramping. */
+export declare function setStreamingSoundVolume(sound: StreamingSound, value: number, options?: RampOptions): void;
+
 /** Set `visible` on `node` and all descendants (via `node.children`). glTF
  *  KHR_node_visibility specifies that children inherit their parent's
  *  invisibility — we materialize this at set-time so the render hot-path
@@ -7045,6 +7504,14 @@ export declare function setThinInstances(mesh: Mesh, matrices: Float32Array | Fl
  */
 export declare function setUniformEffectUniforms(wrapper: UniformEffectWrapper, data: ArrayBuffer | ArrayBufferView): void;
 
+/**
+ * Enables or disables the unmute button. When disabled it is hidden; when
+ * enabled it is shown if the engine is not running.
+ * @param ui - The UI handle.
+ * @param enabled - Whether the button may be shown.
+ */
+export declare function setUnmuteUIEnabled(ui: UnmuteUI, enabled: boolean): void;
+
 /** Vertex attribute names a ShaderMaterial can bind. */
 export declare type ShaderAttributeName = "position" | "normal" | "uv" | "uv2" | "tangent" | "color";
 
@@ -7346,6 +7813,114 @@ declare interface SkeletonData {
     readonly weights1: Float32Array | null;
 }
 
+/** A decoded audio buffer ready to be played by one or more sounds. */
+export declare interface SoundBuffer {
    /** Duration in seconds. */
+    readonly duration: number;
+    /** Sample rate in Hz. */
+    readonly sampleRate: number;
+    /** Number of channels. */
+    readonly channelCount: number;
+    /** Length in samples. */
+    readonly length: number;
+}
+
+/** Options for {@link createSoundBufferAsync}. */
+export declare interface SoundBufferOptions {
+    /** Skip the browser codec check when selecting among multiple URLs. */
+    skipCodecCheck?: boolean;
+}
+
+/** Source accepted when creating a sound or sound buffer. */
+export declare type SoundSource = ArrayBuffer | AudioBuffer | SoundBuffer | string | string[];
+
+/** Options for {@link createSoundSourceAsync} and {@link createMicrophoneSoundSourceAsync}. */
+export declare interface SoundSourceOptions {
+    /** Optional name. */
+    name?: string;
+    /** Output bus. Defaults to the engine's main bus unless {@link outBusAutoDefault} is `false`. */
+    outBus?: PrimaryAudioBus;
+    /**
+     * Whether the output bus defaults to the engine's main bus when {@link outBus}
+     * is not set. Defaults to `true` for {@link createSoundSourceAsync} and `false`
+     * for {@link createMicrophoneSoundSourceAsync} (a mic is usually analyzed, not
+     * played back, to avoid feedback).
+     */
+    outBusAutoDefault?: boolean;
+    /** Initial volume. Defaults to `1`. */
+    volume?: number;
+}
+
+/** Playback state of a sound or sound instance. Values match Babylon.js exactly. */
+export declare const SoundState: {
+    readonly Stopping: 0;
+    readonly Stopped: 1;
+    readonly Starting: 2;
+    readonly Started: 3;
+    readonly FailedToStart: 4;
+    readonly Paused: 5;
+};
+
+export declare type SoundState = (typeof SoundState)[keyof typeof SoundState];
+
+/** Which components of a target's world transform drive the spatial node. */
+export declare type SpatialAttachmentType = "position" | "rotation" | "positionAndRotation";
+
+/** Spatial listener options. The listener orientation is derived from its rotation quaternion. */
+export declare interface SpatialListenerOptions {
+    /** Listener world position. Defaults to `(0, 0, 0)`. */
+    position?: Vec3;
+    /** Listener rotation. Drives the listener forward/up vectors. */
+    rotationQuaternion?: Quat;
+    /** Follow a world transform. */
+    attachedTo?: SpatialTarget;
+    /** Which transform components to follow. Defaults to `"positionAndRotation"`. */
+    attachmentType?: SpatialAttachmentType;
+}
+
+/** Spatial (3D) options for a sound or bus. All fields optional; defaults match Babylon.js. */
+export declare interface SpatialSoundOptions {
+    /** World position of the source. Defaults to `(0, 0, 0)`. */
+    position?: Vec3;
+    /** Facing direction of the source. Defaults to `(1, 0, 0)`. */
+    orientation?: Vec3;
+    /** Source rotation as a quaternion. When set, drives {@link orientation}. */
+    rotationQuaternion?: Quat;
+    /** Pan between left/right channels. Defaults to `true`. */
+    panningEnabled?: boolean;
+    /** Panning algorithm. Defaults to `"equalpower"`. */
+    panningModel?: PanningModelType;
+    /** Distance attenuation model. Defaults to `"linear"`. */
+    distanceModel?: DistanceModelType;
+    /** Reference distance for attenuation. Defaults to `1`. */
+    minDistance?: number;
+    /** Max distance (linear model). Defaults to `10000`. */
+    maxDistance?: number;
+    /** Attenuation roll-off factor. Defaults to `1`. */
+    rolloffFactor?: number;
+    /** Cone inner angle, in radians. Defaults to `2π`. */
+    coneInnerAngle?: number;
+    /** Cone outer angle, in radians. Defaults to `2π`. */
+    coneOuterAngle?: number;
+    /** Volume outside the cone outer angle. Defaults to `0`. */
+    coneOuterVolume?: number;
+    /** Follow a world transform's position and/or rotation. */
+    attachedTo?: SpatialTarget;
+    /** Which transform components to follow. Defaults to `"positionAndRotation"`. */
+    attachmentType?: SpatialAttachmentType;
+}
+
+/**
+ * Anything exposing a world transform — typically a Lite `Mesh` or camera.
+ * The spatial node reads `worldMatrix` each update; if `onDispose` is provided,
+ * the node auto-detaches when the target is disposed.
+ */
+export declare interface SpatialTarget {
+    /** Column-major world matrix of the target. */
+    readonly worldMatrix: Mat4;
+    /** Optional dispose signal — firing it auto-detaches the spatial node. */
+    readonly onDispose?: AudioSignal<unknown>;
+}
+
 /** Procedural UV sphere — matches Babylon MeshBuilder.CreateSphere defaults.
  *  Generates vertex positions, normals, and indices for a unit sphere.
  *  Left-handed winding (CCW front face) to match Babylon. */
@@ -7408,6 +7983,10 @@ export declare interface Sprite2DLayer {
    readonly atlas: SpriteAtlas;
     readonly depth: Sprite2DDepthMode;
     readonly blendMode: SpriteBlendMode;
     opacity: number;
+    /** Coverage gamma applied to anti-aliased edges; see `Sprite2DLayerOptions.coverageGamma`.
+     *  Default 1 (no-op). Read each frame into the layer UBO. Mutating it live changes the
+     *  thickness, but the per-fragment `pow` only runs on layers created with `coverageGamma !== 1`. */
+    coverageGamma: number;
     visible: boolean;
     order: number;
     view: Sprite2DView;
@@ -7433,6 +8012,20 @@ export declare interface Sprite2DLayerOptions {
     capacity?: number;
     blendMode?: SpriteBlendMode;
     opacity?: number;
+    /**
+     * Coverage gamma for anti-aliased edges (text rendering). When set to a value other than 1,
+     * the sampled texture alpha is raised to `1/coverageGamma` in the fragment shader, thickening
+     * anti-aliased edges to mimic the gamma-space blending of native text rasterizers
+     * (DirectWrite/CoreText "stem darkening"). Intended for glyph-atlas (bitmap text) layers drawn
+     * into an sRGB (linear-blended) surface, where correct linear AA otherwise makes text look
+     * lighter/thinner. Values \>1 thicken; 1 (default) is a no-op and ships the base fragment.
+     *
+     * The per-fragment `pow` is gated on this create-time opt-in (like `uvScroll`), so only gamma
+     * layers run it. The plumbing (one extra `Layer` UBO `vec4`, the gamma shader permutation, and
+     * this option field) is, however, in the always-loaded sprite path, so it adds a small fixed
+     * cost (~0.3 KB raw) to every sprite scene — reflected in the sprite-scene bundle ceilings.
+     */
+    coverageGamma?: number;
     visible?: boolean;
     order?: number;
     view?: Partial<Sprite2DView>;
@@ -7803,6 +8396,13 @@ export declare interface StandardMaterialProps extends Material {
  *  @throws If `requestAnimationFrame` is unavailable in the host environment. */
 export declare function startAnimationManager(manager: AnimationManager): void;
 
+/**
+ * Starts the `requestAnimationFrame` render loop. No-op if already running or if
+ * `requestAnimationFrame` is unavailable (e.g. a non-browser environment).
+ * @param viz - The visualizer handle.
+ */
+export declare function startAudioVisualizer(viz: AudioVisualizer): void;
+
 /**
  * Start the render loop. Resolves after the first frame has been rendered.
  * Scenes registered via `registerScene()` before this call are included in
@@ -7817,6 +8417,69 @@ export declare function startEngine(engine: EngineContext): Promise<void>;
  */
 export declare function startSpriteAnimationManager(manager: SpriteAnimationManager): void;
 
+/** A buffer-backed sound. Pure state — drive it with the sound functions. */
+export declare interface StaticSound {
+    /** Optional name. */
+    readonly name?: string;
+    /** The decoded buffer this sound plays. */
+    readonly buffer: SoundBuffer;
+    /** Current playback state. */
+    readonly state: SoundState;
+    /** Number of live instances. */
+    readonly instanceCount: number;
+    /** Fires when the sound finishes (all instances ended). */
+    readonly onEnded: AudioSignal<StaticSound>;
+
+/** Options for {@link createSoundAsync}. */
+export declare interface StaticSoundOptions extends SoundBufferOptions {
+    /** Play immediately once ready. Defaults to `false`. */
+    autoplay?: boolean;
+    /** Play duration in seconds (`0` = full buffer). Defaults to `0`. */
+    duration?: number;
+    /** Loop playback. Defaults to `false`. */
+    loop?: boolean;
+    /** Loop end point in seconds. Defaults to `0`. */
+    loopEnd?: number;
+    /** Loop start point in seconds. Defaults to `0`. */
+    loopStart?: number;
+    /** Maximum simultaneous instances. Defaults to `Infinity`. */
+    maxInstances?: number;
+    /** Output bus. Defaults to the engine's default main bus. */
+    outBus?: PrimaryAudioBus;
+    /** Detune in cents. Defaults to `0`. */
+    pitch?: number;
+    /** Playback rate multiplier. Defaults to `1`. */
+    playbackRate?: number;
+    /** Start offset in seconds. Defaults to `0`. */
+    startOffset?: number;
+    /** Initial volume. Defaults to `1`. */
+    volume?: number;
+}
+
+/** Per-play overrides for {@link playSound}. */
+export declare interface StaticSoundPlayOptions {
+    /** Play duration in seconds (`0` = full buffer). */
+    duration?: number;
+    /** Loop playback. */
+    loop?: boolean;
+    /** Loop end point in seconds. */
+    loopEnd?: number;
+    /** Loop start point in seconds. */
+    loopStart?: number;
+    /** Start offset in seconds. */
+    startOffset?: number;
+    /** Per-instance volume. */
+    volume?: number;
+    /** Delay before playback starts, in seconds. */
+    waitTime?: number;
+}
+
+/** Options for {@link stopSound}. */
+export declare interface StaticSoundStopOptions {
+    /** Delay before stopping, in seconds. */
+    waitTime?: number;
+}
+
 /** Optional stencil-test state baked into a material's main-pass pipeline. Shared by every concrete material kind
  *  (Standard, PBR, Shader) so none has to depend on another. Lets one material WRITE the stencil buffer where it
  *  draws (a mask) and another DISCARD fragments where the stencil was written — with NO dynamic stencil reference:
@@ -7840,15 +8503,30 @@ export declare interface StencilState {
     readonly writeMask?: number;
 }
 
+/** Options for {@link enableStereo}. */
+export declare interface StereoSoundOptions {
+    /** Stereo pan in the range `[-1, 1]` (`-1` = full left, `1` = full right). Defaults to `0`. */
+    pan?: number;
+}
+
 /** Stop playback and reset to frame 0. */
 export declare function stopAnimation(group: AnimationGroup): void;
 
 /** Stops the manager's autonomous requestAnimationFrame loop. No-op if not running. */
 export declare function stopAnimationManager(manager: AnimationManager): void;
 
+/**
+ * Stops the render loop if it is running.
+ * @param viz - The visualizer handle.
+ */
+export declare function stopAudioVisualizer(viz: AudioVisualizer): void;
+
 /** Stop the render loop. */
 export declare function stopEngine(engine: EngineContext): void;
 
+/** Stops the sound (and all its instances). */
+export declare function stopSound(sound: StaticSound, options?: StaticSoundStopOptions): void;
+
 /**
  * Pauses an animation without removing it; it can be resumed with `playSpriteFrameAnimation`.
  * @param animation - Animation to stop.
@@ -7861,6 +8539,53 @@ export declare function stopSpriteAnimation(animation: SpriteFrameAnimation): vo
  */
 export declare function stopSpriteAnimationManager(manager: SpriteAnimationManager): void;
 
+/** Stops the sound (and all its instances). */
+export declare function stopStreamingSound(sound: StreamingSound): void;
+
+/** A streaming, media-element-backed sound. Pure state — drive it with the streaming-sound functions. */
+export declare interface StreamingSound {
+    /** Optional name. */
+    readonly name?: string;
+    /** Current playback state. */
+    readonly state: SoundState;
+    /** Number of live instances. */
+    readonly instanceCount: number;
+    /** Number of instances that have finished preloading. */
+    readonly preloadCompletedCount: number;
+    /** Fires when the sound finishes (all instances ended). */
+    readonly onEnded: AudioSignal<StreamingSound>;
+
+/** Options for {@link createStreamingSoundAsync}. */
+export declare interface StreamingSoundOptions {
+    /** Play immediately once ready. Defaults to `false`. */
+    autoplay?: boolean;
+    /** Loop playback. Defaults to `false`. */
+    loop?: boolean;
+    /** Maximum simultaneous instances. Defaults to `Infinity`. */
+    maxInstances?: number;
+    /** Output bus. Defaults to the engine's default main bus. */
+    outBus?: PrimaryAudioBus;
+    /** Number of instances to preload. Defaults to `1`. */
+    preloadCount?: number;
+    /** Start offset in seconds. Defaults to `0`. */
+    startOffset?: number;
+    /** Initial volume. Defaults to `1`. */
+    volume?: number;
+}
+
+/** Per-play overrides for {@link playStreamingSound}. */
+export declare interface StreamingSoundPlayOptions {
+    /** Loop playback. */
+    loop?: boolean;
+    /** Start offset in seconds. */
+    startOffset?: number;
+    /** Per-instance volume. */
+    volume?: number;
+}
+
+/** A streaming sound source: a URL, a list of candidate URLs, or an existing media element. */
+export declare type StreamingSoundSource = string | string[] | HTMLMediaElement;
+
 /** Subsurface configuration. Nested sub-features — presence = enabled. */
 export declare interface SubSurfaceProps {
     /** Translucency: light passing through thin surfaces. */
@@ -8032,6 +8757,8 @@ export declare interface TextLayer {
    readonly data: TextData;
     scale: number;
     order: number;
     opacity: number;
+    /** Coverage gamma for anti-aliased edges (see `TextLayerOptions.coverageGamma`). Default 1. */
+    coverageGamma: number;
     visible: boolean;
 
 /** Initial placement and compositing options for a 2D text layer in a standalone text renderer. */
@@ -8049,6 +8776,13 @@ export declare interface TextLayerOptions {
     readonly order?: number;
     /** Alpha multiplier in [0, 1]. Default 1. */
     readonly opacity?: number;
+    /** Coverage gamma for anti-aliased edges. Raises per-pixel coverage to `1/coverageGamma`
+     *  before compositing, darkening/thickening anti-aliased edges to mimic the gamma-space
+     *  blending used by native text renderers (DirectWrite/CoreText "stem darkening"). Only
+     *  meaningful when rendering into an sRGB (linear-blended) surface, where correct linear
+     *  AA otherwise makes text look lighter/thinner than gamma-space rasterizers. Values \>1
+     *  thicken; 1 (default) is a no-op. Typical text values are ~1.8–2.2. */
+    readonly coverageGamma?: number;
     /** Default true. */
     readonly visible?: boolean;
 }
@@ -8326,6 +9060,22 @@ export declare interface UniformEffectWrapperOptions {
     uniformByteLength: number;
 }
 
+/**
+ * Unlocks (resumes) the audio engine. Browsers require a user gesture before a
+ * real-time context can produce sound; call this from a click/tap handler.
+ * @param engine - The audio engine.
+ */
+export declare function unlockAudioEngineAsync(engine: AudioEngine): Promise<void>;
+
+/** Unmute UI handle. Pure state — driven by the unmute-UI functions. */
+export declare interface UnmuteUI {
+
+/** Options for {@link createUnmuteUI}. */
+export declare interface UnmuteUIOptions {
+    /** Parent element for the button. Defaults to `document.body`. */
+    parentElement?: HTMLElement;
+}
+
 /** Unregister the effect renderer from its surface. No-op if not registered. */
 export declare function unregisterEffectRenderer(er: EffectRenderer): void;
 
@@ -8416,6 +9166,13 @@ export declare function updateNavCrowd(crowd: NavCrowd, dt: number): void;
 /** Run `tileCache.update()` until all pending obstacle requests are resolved. */
 export declare function updateNavMeshObstacles(plugin: NavigationPlugin): void;
 
+/**
+ * Pumps one spatial update for every attached node and the listener. Call this
+ * from your render loop, or enable {@link setSpatialAutoUpdate}.
+ * @param engine - The audio engine.
+ */
+export declare function updateSpatialAudio(engine: AudioEngine): void;
+
 /**
  * Updates the properties of the sprite referenced by `handle`.
  * @param handle - Handle of the sprite to update.