@yali-engine/audio 0.0.0-stage → 0.4.0

package/dist/plugin.d.ts

@@ -0,0 +1,174 @@
+import { type AssetLoader, type Component, type World, type YaliPlugin } from '@yali-engine/core';
+import { type AudioClips, AudioMixer, type ClipId } from './audio.ts';
+/** `audio.Source`'s fields (ADR-0096). */
+export declare const SOURCE_FIELDS: {
+    readonly clip: "u32";
+    readonly volume: "f32";
+    readonly pitch: "f32";
+    readonly loop: "u8";
+    /** 1: playing (set it to start); the plugin sets 0 when a clip that does not loop ends. */
+    readonly play: "u8";
+    readonly spatial: "u8";
+    readonly distanceModel: "u8";
+    readonly refDistance: "f32";
+    readonly maxDistance: "f32";
+    readonly rolloff: "f32";
+    readonly coneInner: "f32";
+    readonly coneOuter: "f32";
+    readonly coneOuterGain: "f32";
+};
+/** `audio.ReverbZone`'s fields (ADR-0116). */
+export declare const REVERB_ZONE_FIELDS: {
+    /** 0: a sphere of radius `x`; 1: a box of half extents `x`, `y`, `z` (turned with the entity). */
+    readonly shape: "u8";
+    readonly x: "f32";
+    readonly y: "f32";
+    readonly z: "f32";
+    /** How far inside the edge it reaches full strength, m. */
+    readonly fade: "f32";
+    /** Seconds to fall 60 dB. */
+    readonly decay: "f32";
+    /** Its level at full strength (linear). */
+    readonly wet: "f32";
+};
+/** The `audio.Source`, `audio.Listener` and `audio.ReverbZone` components (the plugin registers them). */
+export interface AudioComponents {
+    readonly Source: Component;
+    /** On the entity the scene is heard from (its `GlobalTransform`; forward −Z); none: the camera. */
+    readonly Listener: Component;
+    /** A space with its own reverb (ADR-0116), heard while the listener is inside it. */
+    readonly ReverbZone: Component;
+}
+/** Registers the audio components on `world` (the same ids every call). */
+export declare function registerAudioComponents(world: World): AudioComponents;
+/** What `reverbZone` takes. */
+export interface ReverbZoneOptions {
+    /** A sphere of this radius (m), or a box of these half extents (m). */
+    readonly sphere?: number;
+    readonly box?: readonly [number, number, number];
+    /** Seconds the reverb takes to fall 60 dB (default 1.5: a hall; 0.4 a small room, 4 a cathedral). */
+    readonly decay?: number;
+    /** Its level once inside (default 0.4). */
+    readonly wet?: number;
+    /** Metres inside the edge at which it reaches full strength (default 2). */
+    readonly fade?: number;
+}
+/**
+ * `audio.ReverbZone` values (ADR-0116): put on an entity with a transform; while the listener is
+ * inside, every spatial sound also plays through this reverb, faded in over `fade` metres. Zones may
+ * overlap (each is heard at its own weight).
+ *
+ * @example
+ * world.insert(hall, audio.ReverbZone, reverbZone({ box: [12, 6, 20], decay: 2.2, wet: 0.5 }));
+ */
+export declare function reverbZone(o: ReverbZoneOptions): Record<string, number>;
+/**
+ * An asset-server loader for clips (ADR-0116): `assets.load<ClipId>('sounds/step.ogg')` decodes into
+ * `clips`, and a hot reload of the file swaps the sound under the same id. `audioPlugin` registers
+ * it with the app's asset server itself when there is one.
+ */
+export declare function audioClipLoader(clips: AudioClips): AssetLoader<ClipId>;
+/** What `audioSource` takes; every field optional. */
+export interface SourceOptions {
+    readonly volume?: number;
+    readonly pitch?: number;
+    readonly loop?: boolean;
+    /** Start playing on insert (default true). */
+    readonly play?: boolean;
+    /** Placed in 3D (default true); false: heard as it is (music, UI). */
+    readonly spatial?: boolean;
+    readonly distanceModel?: 'linear' | 'inverse' | 'exponential';
+    /** Full volume up to this distance (default 1 m). */
+    readonly refDistance?: number;
+    /** Where `linear` falls to its end (default 100 m). */
+    readonly maxDistance?: number;
+    readonly rolloff?: number;
+    /** A directional source: inner and outer cone angles in degrees, the gain outside (default: none). */
+    readonly cone?: {
+        readonly inner: number;
+        readonly outer: number;
+        readonly outerGain: number;
+    };
+}
+/**
+ * `audio.Source` values (ADR-0096) for clip `clip`: put on an entity with a transform; it plays
+ * from there. Set `play` to 0 to stop it, 1 to start it again.
+ *
+ * @example
+ * world.insert(engine, audio.Source, audioSource(hum, { loop: true, refDistance: 3 }));
+ */
+export declare function audioSource(clip: number, o?: SourceOptions): Record<string, number>;
+/** `@yali-engine/audio` options. */
+export interface AudioPluginOptions {
+    /** The context to play through (default a new AudioContext; tests pass an OfflineAudioContext). */
+    readonly context?: BaseAudioContext;
+    /** Master volume (default 1). */
+    readonly volume?: number;
+    /** Resume a suspended AudioContext on the first pointer or key press (default true; browsers start it suspended). */
+    readonly resumeOnGesture?: boolean;
+    /** Register the clip loader with the app's asset server (default true when there is one; ADR-0116). */
+    readonly assets?: boolean;
+    /** Makes a streamed clip's element (tests; default `new Audio(url)`). */
+    readonly element?: (url: string) => HTMLMediaElement;
+    /**
+     * Doppler (ADR-0127, default on): a moving source or listener plays faster or slower, from their
+     * velocities (each entity's move between frames, smoothed; a jump faster than `maxSpeed` is a
+     * teleport, not a speed). `scale` 0 turns it off, 1 is physical; `speedOfSound` in m/s.
+     */
+    readonly doppler?: boolean | {
+        readonly scale?: number;
+        readonly speedOfSound?: number;
+        readonly maxSpeed?: number;
+    };
+    /**
+     * Occlusion (ADR-0127, default on when the app has physics): a ray from the listener to each
+     * playing spatial source through `physics.raycasts`; blocked, the source is muffled and quieter
+     * (`AudioMixer.occlusionHz`, `.occlusionGain`), gliding in and out. The ray starts and stops
+     * `margin` m short (the listener's and the source's own colliders); `mask` picks the colliders that
+     * block sound. `query` replaces physics: rays [origin, dir, distance], one blocked flag each.
+     *
+     * ADR-0130: with physics, how much is in the way counts. A second ray from the source back finds the
+     * last wall's far side, and the solid span between the two hits occludes `1 − exp(−span / thickness)`
+     * (`thickness` 0.25 m: a 5 cm partition muffles a little, a 30 cm wall nearly fully). Diffraction: a
+     * source occluded now also casts four detours through points `radius` m around it (across the line
+     * to the listener); each detour clear both ways lets `diffraction / 4` of the sound around the wall.
+     * `diffraction: 0` turns it off. With `query` (blocked or clear only), occlusion stays all or nothing.
+     */
+    readonly occlusion?: boolean | {
+        readonly mask?: number;
+        readonly margin?: number;
+        readonly thickness?: number;
+        readonly diffraction?: number;
+        readonly radius?: number;
+        readonly query?: (rays: readonly (readonly [readonly [number, number, number], readonly [number, number, number], number])[]) => readonly boolean[];
+    };
+    /**
+     * Early reflections (ADR-0130, default on when the app has physics): six rays a frame from the
+     * listener (±x, ±y, ±z, up to `distance` m) find the nearest walls, and each puts a delayed echo of
+     * every spatial sound in the mix (2d / c later, `gain` / (1 + 2d) as loud, panned to its side), so a
+     * corridor sounds different from a hall. `mask` picks the colliders that reflect.
+     */
+    readonly reflections?: boolean | {
+        readonly distance?: number;
+        readonly gain?: number;
+        readonly mask?: number;
+    };
+}
+/** The `audio` resource. */
+export interface AudioContextResource extends AudioComponents {
+    readonly context: BaseAudioContext;
+    readonly clips: AudioClips;
+    readonly mixer: AudioMixer;
+}
+/**
+ * Spatial audio (ADR-0096): every entity with `audio.Source` and a `GlobalTransform` plays its
+ * clip from where it is, heard from the `audio.Listener` entity or, without one, the render
+ * camera. Runs in Extract, after transforms propagate. Provides `audio`; tools `audio.voices`
+ * and `audio.volume`.
+ *
+ * @example
+ * App.create({ core, plugins: [renderPlugin({ canvas }), audioPlugin(), transformsPlugin(), game] });
+ * const audio = app.resource<AudioContextResource>('audio');
+ * world.insert(e, audio.Source, audioSource(await audio.clips.load('hum.ogg'), { loop: true }));
+ */
+export declare function audioPlugin(options?: AudioPluginOptions): YaliPlugin;