narraleaf-react 0.21.1 → 0.23.0

package/dist/game/player/lib/AudioManager.d.ts

@@ -1,34 +1,141 @@
-import { Sound as SoundElement, SoundType } from "../../nlcore/elements/sound";
+import { Sound as SoundElement, SoundBusId } from "../../nlcore/elements/sound";
 import { SoundToken } from "@narraleaf/sound";
 import { FadeOptions } from "../../nlcore/elements/type";
 import { Awaitable } from "../../../util/data";
 import { GameState } from "../gameState";
 import { LogicAction } from "../../nlcore/action/logicAction";
+import { AudioBusState } from "../../nlcore/game/audioBus";
 export type AudioDataRaw = {
     isPlaying: boolean;
     position: number;
 };
 export type AudioManagerDataRaw = {
     sounds: [string, AudioDataRaw][];
-    groups: [SoundType, number][];
+    /**
+     * Bus volumes, keyed by bus id.
+     *
+     * The name is historical - these used to be the three fixed "groups". A save written before
+     * buses existed carries exactly `bgm`/`sound`/`voice`, which are still buses, so it restores
+     * unchanged.
+     */
+    groups: [string, number][];
 };
 export declare class AudioManager {
     private gameState;
+    /**
+     * How much of the backend's channel budget to ask for.
+     *
+     * `@narraleaf/sound` defaults to 128 *including* the master, and throws outright when a
+     * `createChannel` would cross it. Three buses never came close; a game that gives every member
+     * of a large voiced cast its own bus can, and the failure mode is a hard throw at boot. This is
+     * a per-channel `GainNode` and nothing else, so a generous ceiling costs effectively nothing.
+     */
+    private static readonly MaxChannels;
+    /**
+     * Time constant of the bus-volume ramp, in seconds. ~20ms: long enough to turn a step into a
+     * slew nobody hears, short enough that a slider still feels attached to the sound.
+     */
+    private static readonly BusRampTimeConstant;
+    /**
+     * When to pin the exact target after the ramp. `setTargetAtTime` approaches asymptotically and
+     * never lands, so five time constants in (within 0.7% - inaudible) the value is written
+     * outright. Without this a long drag would accumulate a drift the mixer's own bookkeeping does
+     * not have.
+     */
+    private static readonly BusRampSettle;
     private state;
     private channels;
-    private channelVolumes;
+    private busTree;
+    private busSubscription;
+    private unknownBuses;
     private globalVolume;
     private sound;
     private ready;
     private isReady;
     private isInitializing;
     constructor(gameState: GameState);
+    /**
+     * The volume of every bus, and the tree they are wired into.
+     *
+     * It lives on `Game`, not here: a bus volume is a player setting that exists before the audio
+     * context unlocks and outlives any one player mount. This manager is the thing that makes it
+     * audible, not the thing that remembers it.
+     */
+    private get mixer();
     /**
      * Must be called ONCE on the client side to prepare audio subsystem.
      * Doing it here avoids "AudioContext is not defined" on the server.
      */
     initialize(): void;
+    /**
+     * Build the host's declared bus tree into real channels, once.
+     *
+     * Walked front to back the tree hands every bus out after its parent, so a child always has a
+     * live parent channel to be created from - that is what nests the gain nodes, and cascading
+     * gain then falls out of the audio graph rather than out of any arithmetic here.
+     *
+     * Done once, at boot, and never re-shaped: `Channel.remove()` stops every token in its subtree,
+     * so re-parenting a bus while the game runs would cut the music off. Volumes stay live.
+     */
+    private realizeBusTree;
+    /**
+     * Write a bus's volume onto its gain node, ramping rather than stepping.
+     *
+     * `Channel.setVolume` assigns `gain.value` bare with no `cancelScheduledValues`, so a slider
+     * drag arrives as a staircase of discontinuities - the zipper. The backend exposes no ramping
+     * setter, only `getGainNode()`, so the ramp is driven from here.
+     *
+     * **Who owns the value.** `Channel.volume` remains authoritative bookkeeping and the
+     * `AudioParam` is authoritative for what is heard, and this method is the only writer of
+     * either, so the two can only disagree for the ~20ms a ramp is in flight. `channel.setVolume`
+     * is still called first and deliberately: it is what clamps to 0..1, what keeps
+     * `channel.getVolume()` truthful, and what `Channel.mute()`/`unmute()` re-read when they
+     * rewrite the gain themselves. Its bare write is then superseded in the same synchronous turn -
+     * `cancelScheduledValues` drops the implicit `setValueAtTime` that the assignment inserted at
+     * `currentTime`, and the ramp is scheduled from the value the parameter actually had. Nothing
+     * else in the engine touches a bus gain node, so there is no other automation to fight.
+     *
+     * Falls back to the plain assignment whenever the graph is not reachable - a backend without
+     * `getGainNode`, or a parameter without `setTargetAtTime`. Stepping is the behaviour that
+     * shipped; degrading to it is strictly no worse.
+     */
+    private applyBusVolume;
+    /**
+     * The value a bus's gain parameter has right now, or `null` when the graph cannot be reached.
+     */
+    private static readGain;
+    /**
+     * The channel a clip plays through.
+     *
+     * A bus id nothing declared is not fatal. Refusing to play would turn one typo in one clip's
+     * `type` into silence or a thrown action mid-scene; routing it to the always-seeded sfx bus
+     * keeps the game audible and says so once, per id, in the log. This is also where a bus name
+     * that {@link import("../../nlcore/game/audioBus").acceptsAudioBus} let through at story-build time is
+     * finally caught.
+     */
+    private channelFor;
+    /**
+     * The volume a clip started with no explicit target should reach.
+     *
+     * Full volume was never a sensible default here: a `Sound` carries the volume it was configured
+     * with, so a caller that says nothing about volume is asking for *that*, not for 1. Reading
+     * `state` rather than the user config is deliberate - it is the same value {@link SoundElement.play}
+     * and {@link SoundElement.resume} put in their `FadeOptions`, so a clip replayed after
+     * {@link AudioManager.setVolume} comes back at the volume it was last set to instead of jumping
+     * back to whatever the author first wrote down.
+     */
+    private static defaultFade;
     play(sound: SoundElement, options?: FadeOptions): Awaitable<void>;
+    /**
+     * Start a clip and hand the token back once playback is under way.
+     *
+     * With no `duration` the target volume is written to the token *synchronously* before this
+     * returns, and nothing is left running: no gain automation is in flight when the caller gets the
+     * token. That is what makes an explicit `token.setVolume` or a fade the caller drives itself
+     * afterwards the last writer, which several hosts rely on. Defaulting `duration` to anything
+     * above 0 would break that - `token.fade` below is deliberately not awaited, so a non-zero
+     * default would leave a ramp running past the return and over whatever the caller did next.
+     */
     playSoundToken(sound: SoundElement, options?: FadeOptions): Promise<SoundToken>;
     stop(sound: SoundElement, duration?: number): Awaitable<void>;
     setVolume(sound: SoundElement, volume: number, duration?: number): Awaitable<void>;
@@ -42,13 +149,51 @@ export declare class AudioManager {
      */
     seek(sound: SoundElement, time: number): Awaitable<void>;
     /**
-     * The in/out points of a clip as the sound backend's play options.
+     * The in/out points of a clip.
      *
      * `endTime` is left off entirely when the author set none: passing `undefined` explicitly is the
      * same thing to the backend, but omitting it keeps `{...region}` spreads from writing a key that
      * reads as "there is a region here" to anything inspecting the object.
      */
     private static clipRegionOf;
+    /**
+     * The region as the sound backend's play options.
+     *
+     * A looping clip deliberately hands over **no** `endTime`. The backend turns `endTime` into a
+     * timer that stops the token after one pass, whether or not the clip loops, so passing it here
+     * is what kept the loop region from ever repeating. The region reaches a looping clip through
+     * {@link AudioManager.applyLoopRegion} instead; for a one-shot `endTime` *is* the out point and
+     * the backend's timer is exactly the right mechanism.
+     */
+    private static playRegionOf;
+    /**
+     * Write a looping clip's region onto the Web Audio node the backend is playing it through.
+     *
+     * **This is a shim against `@narraleaf/sound@0.1.0`'s internals, and the only place in this
+     * repo that reaches into them.** Two things in that version make the region unusable from the
+     * outside:
+     *
+     * - `SoundToken`'s constructor arms `setTimeout(stop, duration * 1000)` whenever a duration was
+     *   given, without consulting `loop` — so a looping clip with an out point hard-stops after its
+     *   first pass through the region.
+     * - `Sound.createToken` pins `loopStart` to the playback start offset, so "play the intro from
+     *   0s, then repeat 12s→90s forever" cannot be expressed at all.
+     *
+     * The fix belongs upstream and is small: honour `loop` before arming the duration timer, and
+     * accept an independent `loopStart` in `PlayOptions`. Until that ships, this manager withholds
+     * `endTime` from a looping clip's play options (which is what disarms the timer) and sets the
+     * loop region here.
+     *
+     * `SoundToken.sourceController` is TypeScript-`private` while `AudioSourceController.getSource`
+     * is public, so the node is reachable at runtime but not through the types — hence the cast and
+     * the shape check. If a later backend changes that shape this returns silently and the clip
+     * degrades to the behaviour it has today: the region plays once and the clip stops.
+     *
+     * Seeking survives this. `SoundToken.seek` rebuilds the buffer source and copies `loop`,
+     * `loopStart` and `loopEnd` off the old node onto the new one, so a jump inside a looping track
+     * keeps the region.
+     */
+    private static applyLoopRegion;
     private static clampToRegion;
     setRate(sound: SoundElement, rate: number): Awaitable<void>;
     getPosition(sound: SoundElement): number;
@@ -70,11 +215,67 @@ export declare class AudioManager {
      * as it did before.
      */
     preload(sound: SoundElement): Promise<void>;
+    /**
+     * Start a new game: stop everything and put the mixer back on the wire.
+     *
+     * The tree itself is **not** rebuilt - the channels are the same channels, because a bus is
+     * part of the game's declared shape, not part of its state. What is re-applied is every bus's
+     * current volume, read back off the mixer rather than off `SoundType`, which is what lets a
+     * host's own buses exist here at all.
+     *
+     * Note the seeded three are then immediately overwritten from the preferences, exactly as
+     * before; a bus the host declared keeps whatever volume the player left it at, because that is
+     * a setting and not something a new game should undo.
+     */
     reset(): void;
-    setGroupVolume(type: SoundType, volume: number): void;
+    /**
+     * Set **the player's** volume for a bus, 0..1, live. 1 means "leave the author's mix alone".
+     *
+     * Reaches sounds that are **already playing**: a bus is a gain node every clip beneath it is
+     * routed through, so nothing has to be found, stopped or restarted for the change to be heard.
+     * Setting a bus that has not been realized yet is fine - the value is kept and applied when the
+     * audio context unlocks.
+     *
+     * Equivalent to `game.audioBuses.setVolume(...)`, which is the surface a host should prefer:
+     * it exists before the player mounts.
+     */
+    setBusVolume(id: SoundBusId, volume: number): void;
+    /**
+     * The player's volume for a bus - what was last set, else 1. Not the author's declared mix
+     * (`game.audioBuses.getDeclaredVolume`) and not what is on the gain node
+     * (`getEffectiveVolume`).
+     */
+    getBusVolume(id: SoundBusId): number;
+    /**
+     * Every bus with its parent and both of its volumes, parents first. `volume` is the half a
+     * host persists.
+     */
+    getBuses(): AudioBusState[];
+    /**
+     * @deprecated Use {@link AudioManager.setBusVolume}. Kept because the three sound types are
+     * still bus ids and hosts call this with them.
+     */
+    setGroupVolume(type: SoundBusId, volume: number): void;
+    /**
+     * @deprecated Use {@link AudioManager.getBusVolume}.
+     */
+    getGroupVolume(type: SoundBusId): number;
     setGlobalVolume(volume: number): void;
     getGlobalVolume(): number;
-    getGroupVolume(type: SoundType): number;
     destroy(): void;
+    /**
+     * The three volume preferences are aliases onto the three seeded buses, and this is the alias.
+     *
+     * They stay the way a player's music/sfx/voice sliders are driven - widening the preference key
+     * union to cover arbitrary bus ids is not possible without reshaping `GamePreference`, and is
+     * not needed: a host bus is driven through {@link AudioManager.setBusVolume} instead.
+     *
+     * They write the **player's** half only. This used to write the bus's whole gain, and because
+     * these preferences default to 1 it meant that a host declaring `{id: "sound", volume: 0.6}`
+     * had its mix silently overwritten with 1 the moment the audio subsystem started - the author
+     * set SFX to 60% and every player heard 100%. Custom buses were unaffected because nothing
+     * aliases them, so the three buses every existing project uses were the only ones that ignored
+     * the declaration. Now `soundVolume: 1` means "do not attenuate further" and 0.6 survives.
+     */
     private setupGroupVolume;
 }