@threenative/core 0.1.0 → 0.3.0

package/dist/audio-Dp2mXpD3.d.ts

@@ -0,0 +1,94 @@
+import { AudioListener, Object3D, Audio, Vector3, PositionalAudio } from 'three';
+
+interface IAudioBusOptions {
+    readonly camera: Object3D;
+    readonly gestureTarget?: EventTarget;
+    readonly listener?: AudioListener;
+    readonly source?: () => EventTarget | undefined;
+    /**
+     * Ceiling on simultaneously sounding one-shots. Past it the oldest voice is stopped and its
+     * slot reused: a firefight generates far more cues than a listener can resolve, and the newest
+     * event is always the one they need to hear. Looping voices from `music` are exempt.
+     * Defaults to 48.
+     */
+    readonly maxVoices?: number;
+}
+interface IAudioPlayOptions {
+    readonly fade?: number;
+    readonly loop?: boolean;
+    readonly volume?: number;
+    /**
+     * Metres from the source where positional attenuation begins; `playAt` only. Three's panner
+     * default of 1 m makes a shot 20 m away all but inaudible — raise this to keep mid-distance
+     * sounds loud. Must be finite and positive.
+     */
+    readonly refDistance?: number;
+    /**
+     * How fast volume falls off past `refDistance`; `playAt` only. 0 keeps the sound at full
+     * volume at any distance. Must be finite and non-negative.
+     */
+    readonly rolloffFactor?: number;
+    /**
+     * Pitch offset in cents; ±100 is a semitone. Applied before the first sample rather than
+     * through three's `setDetune`, which ramps over ~30 ms and turns a percussive attack into an
+     * audible sweep. A few dozen cents of per-shot spread is what stops a repeated sample
+     * comb-filtering with its own copies into a metallic buzz.
+     */
+    readonly detune?: number;
+    /**
+     * Seconds of the buffer to pass before an exponential cut-off. A 1.4 s gunshot fired ten times
+     * a second stacks fourteen overlapping tails into mush; truncating all but the last keeps the
+     * transient and drops the wash. Must be finite and positive.
+     */
+    readonly cutoffSeconds?: number;
+    /**
+     * Low-pass corner in Hz. Air and geometry eat the top of a sound as it crosses a space, and a
+     * sample played flat at every range is the loudest tell that a game's audio is not in a place.
+     * Must be finite and positive.
+     */
+    readonly lowpassHz?: number;
+}
+interface IAudioRuntimeSnapshot {
+    readonly queued: number;
+    readonly voices: number;
+    /** Retired voices held for reuse. Bounded by peak concurrency, never by session length. */
+    readonly pooled: number;
+}
+declare class AudioBus {
+    #private;
+    readonly listener: AudioListener;
+    constructor(options: IAudioBusOptions);
+    get queued(): number;
+    get voices(): number;
+    /**
+     * Retired voices held for reuse. This is the number that used to climb without limit: it is
+     * now bounded by how many cues have ever sounded at once, so a gate can pin it.
+     */
+    get pooled(): number;
+    setCamera(camera: Object3D): void;
+    reparent(camera: Object3D): void;
+    unlock(): Promise<void>;
+    /**
+     * A cue with no place: the listener's own weapon, UI, narration.
+     *
+     * The returned voice is valid for as long as it is sounding. Once it ends the bus reclaims it
+     * and may hand the same object to a later cue, so a caller holding the reference past that
+     * point is addressing somebody else's sound. Read `isPlaying` before touching a voice you kept.
+     */
+    play(buffer: AudioBuffer, options?: IAudioPlayOptions): Audio;
+    /**
+     * A cue somewhere in the world, at a fixed point or riding a moving object.
+     *
+     * A `Vector3` source is read in the coordinate space of the camera's parent, which is the
+     * scene in the ordinary case. Pass an `Object3D` to weld the cue to something that moves.
+     *
+     * The same reclaim rule as `play` applies to the returned voice.
+     */
+    playAt(buffer: AudioBuffer, source: Object3D | Vector3, options?: IAudioPlayOptions): PositionalAudio;
+    music(buffer: AudioBuffer, options?: IAudioPlayOptions): Audio;
+    stop(): void;
+    dispose(): void;
+}
+declare function audioRuntimeSnapshot(): IAudioRuntimeSnapshot;
+
+export { AudioBus as A, type IAudioBusOptions as I, audioRuntimeSnapshot as a, type IAudioPlayOptions as b };