@driftengine/audio 3.61.0

package/dist/graph.d.ts

@@ -0,0 +1,406 @@
+import { AmbientLoop } from './ambientLoop.ts';
+import { KickDetector } from './rhythm/kickDetector.ts';
+import type { FetchLike } from './registry.ts';
+import { SoundRegistry } from './registry.ts';
+import { MixConsole } from './mix/console.ts';
+import { type DefaultLayout } from './mix/defaultLayout.ts';
+/**
+ * The audio graph: layered stems into a master filter, with parallel sends.
+ *
+ *   stems[] → stemGain[] → musicGain ─┬→ lift(highpass→duck) → dry ─┬→ bus → lowpass → dest
+ *                                     └→ slam(shelf→drive→clip) ──┘
+ *   one-shots → level ─────→ effectsGain ───────────────────┘   │
+ *                                                              │
+ *                              lift ─────────────────────────┬──┼→ convolver ────→ dest
+ *                                                            ├──┼→ longConvolver → dest
+ *                                                            └──┼→ feedbackDelay → dest
+ *
+ * Music and effects have their own gain stage because players expect to turn them
+ * down independently — muting the score while keeping the game audible is the single
+ * most-used audio setting there is.
+ *
+ * **The sends are fed from the music alone.** They hung off the shared bus first, which
+ * put reverb and delay on every sound the game made when only the score should carry
+ * them. A footstep with a
+ * six-second tail on it is not atmosphere, it is a bug, and the effects that carry
+ * the world's own sound need to stay dry and immediate to be legible. The master
+ * filter still applies to everything, which is deliberate: going under water muffles
+ * the world, not only the score.
+ *
+ * Game code expresses musical intent — "louder, faster, brighter" — and never
+ * builds nodes. That boundary is what stops mixing decisions from ending up
+ * spread across gameplay code where nobody can find them.
+ *
+ * Everything here degrades to silence rather than to a crash. A browser that
+ * blocks audio, an unsupported node type, a context that never resumes: all of
+ * them leave a playable game, because sound is not what the game is for.
+ */
+export interface AudioGraphOptions {
+    /** How many simultaneous music layers to allocate. */
+    stemCount: number;
+    /**
+     * Build on this context instead of creating a live one.
+     *
+     * For rendering a mix rather than hearing it: hand in an `OfflineAudioContext` and
+     * every node below is built on it, so `startRendering` produces the same mix the
+     * speakers would have made. Additive — omitting it is exactly the previous
+     * behaviour.
+     */
+    readonly context?: BaseAudioContext;
+    /**
+     * Where the music and effects stages start. Unity for both when omitted.
+     *
+     * The reason this exists rather than a `setMusicVolume` call after construction: a
+     * graph built to *reproduce* a mix has to be at that mix's levels from its own zero,
+     * and every parameter move here is a `setTargetAtTime` — which approaches its target
+     * over `RAMP` and so would open a rendered clip with a third of a second of glide
+     * down from unity to whatever the player actually chose. A level that does not change
+     * for the whole render is not a move; it is where the parameter starts.
+     *
+     * It also cannot be scheduled on the wrong clock, which the other shape can: offline
+     * there is no "now", so a level set imperatively lands wherever the render happens to
+     * have got to. See `at`.
+     */
+    readonly levels?: MixLevels;
+    /**
+     * Fetch every registered sound goes through, instead of the global `fetch`.
+     *
+     * A game may need to gate its own asset requests — a signed URL, a token header —
+     * without the engine knowing why. Additive — omitting it is exactly the previous
+     * behaviour, and `SoundRegistry` already degrades any fetch failure to its `synth`
+     * fallback, so a caller's custom fetch can fail as loudly or as quietly as it likes
+     * without a new error path opening up here.
+     */
+    readonly fetchImpl?: FetchLike;
+    /**
+     * Told why this browser gave no audio at all, when `create` returns null.
+     *
+     * Null is deliberately coarse — it means "there is nothing to wake", and a caller
+     * reporting it learns only that somebody, somewhere, heard nothing. A game with
+     * telemetry needs the other half: a missing constructor and a context that threw
+     * are different bugs with different fixes, and the field that said neither was
+     * `soundtrack_init_null`. Never called when a graph is returned; a suspended
+     * context is not unavailable.
+     */
+    readonly onUnavailable?: (reason: string) => void;
+    /**
+     * Where randomness comes from, for the noise the reverb impulses are made of.
+     *
+     * Defaults to `Math.random`, which is what a game wants: a hall built from a fresh sequence every
+     * session is a hall, and one built from a fixed one is a hall with a repeating texture in its
+     * tail. Supplied only where a render has to be reproducible sample for sample — a check script
+     * comparing two mixes cannot do that while every convolver is different.
+     *
+     * Additive: omitting it is exactly the previous behaviour.
+     */
+    readonly random?: () => number;
+}
+/**
+ * The two levels a player is given control of: the score, and everything else.
+ *
+ * Named as a pair because they travel as one — a second graph reproducing this mix
+ * needs both or neither, and the failure of carrying one is silent.
+ */
+export interface MixLevels {
+    readonly music: number;
+    readonly effects: number;
+}
+export declare class AudioGraph {
+    readonly context: BaseAudioContext;
+    readonly registry: SoundRegistry;
+    /**
+     * The mix, as a tree of buses rather than as nodes held here.
+     *
+     * Everything below that used to be a field — the music and effects stages, the master filter, the
+     * lift, the slam, the three sends and their returns — is a bus or an insert now, and
+     * `defaultLayout` is where the shape they make is written down. What is left in this class is the
+     * transport: what is playing, from where, at what rate.
+     */
+    private readonly mix;
+    private readonly layoutNodes;
+    /**
+     * The recording tap, created once.
+     *
+     * Cached because it used to be built per call and never taken down — the mix accumulated one
+     * `MediaStreamAudioDestinationNode` per export, each still pulling audio for the rest of the
+     * session. Ten exports while testing is ten of them, on the thread least able to absorb it and
+     * the one whose overrun is heard as a click.
+     */
+    private tap;
+    /**
+     * The player's own two levels, held here because a second graph built to render this mix has to
+     * be built at them.
+     *
+     * Mirrored rather than read back off the buses for the reason the buses themselves mirror: a
+     * level is *ramped*, and mid-ramp a parameter is somewhere between where it was and where it is
+     * going. A fade asking "back to the player's level" or a render asking "at what level" would both
+     * get whatever instant they happened to ask on.
+     *
+     * Which is also why `fadeMusic` does not write here. A fade is part of an edit, not a setting; it
+     * has to return to the setting when it is over.
+     */
+    private readonly mixLevels;
+    /**
+     * A gain per live source, so a stem can be faded out without touching the stem's own level —
+     * which the *replacement* source is already connected to.
+     */
+    private readonly sourceLevels;
+    /** Where scheduled work lands: an explicit instant, or null for "now". See `at`. */
+    private atSec;
+    private readonly stemGains;
+    private readonly stemBuffers;
+    private readonly stemSources;
+    private started;
+    /**
+     * Transport position, integrated rather than derived from elapsed wall time.
+     *
+     * The playback rate moves with the character, so three seconds of context time at
+     * rate 1.1 is 3.3 seconds of tape — and a caller that puts the track's beat zero
+     * on a start line needs to know where the tape actually is.
+     */
+    private positionSec;
+    private positionAt;
+    private rate;
+    private paused;
+    private constructor();
+    /** The mix this graph plays into, for a caller that wants a bus of its own. */
+    get console(): MixConsole;
+    /**
+     * Build a graph, or return null only if the browser has no audio to give.
+     *
+     * **Null means "this browser will not do audio at all", never "not yet".** The
+     * distinction is the whole of a bug that silenced audio on mobile devices, both
+     * Android and iOS: this used to `await context.resume()`
+     * inside the try, so a browser that *rejects* that call — which is what a
+     * rejection means when autoplay is blocked — threw a perfectly good graph into
+     * the `catch` and reported no audio. The caller latches its load so it happens
+     * once, so that null was permanent: silence for the session, with a `wake()`
+     * that had nothing left to wake.
+     *
+     * A suspended context is not a failure. Its clock does not advance, so nothing
+     * scheduled on it is missed, and `wake()` exists to start it on the first
+     * gesture. The resume is still *attempted* here, because when this is called
+     * from a gesture — or on a site the browser already trusts — it starts
+     * immediately and there is no reason to wait for a tap that already happened.
+     * It is just no longer awaited, and no longer fatal.
+     *
+     * Desktop cannot show you this. Chrome grants autoplay to a site its user keeps
+     * visiting, so on the machine this game is built on the context comes up
+     * already running. It only breaks on a device that has not earned that trust,
+     * which is every phone arriving from a share link.
+     */
+    static create(options: AudioGraphOptions): Promise<AudioGraph | null>;
+    /**
+     * Whether the context is actually producing sound.
+     *
+     * A context built without a user gesture is `suspended`: nodes run, sources are
+     * scheduled, and nothing is heard. A caller that has something to say about that — an
+     * intro film with a score, say — needs to be able to ask.
+     */
+    get audible(): boolean;
+    /**
+     * Ask the browser to start the context, if it will.
+     *
+     * Safe to call from anywhere and safe to call repeatedly: outside a gesture the promise
+     * simply rejects, which is not an error state — it is the policy working. Anything
+     * already scheduled begins when it succeeds, because a suspended context's clock does
+     * not advance, so nothing is missed in the meantime.
+     */
+    wake(): void;
+    loadStem(index: number, buffer: AudioBuffer): void;
+    /** Whether the stems are running. */
+    get playing(): boolean;
+    /**
+     * Start every stem at one scheduled instant.
+     *
+     * Layers must be sample-locked: started independently they drift apart by
+     * however long each `start()` call happened to take, and a bassline a few
+     * milliseconds off its drums is heard as flamming rather than as one track.
+     */
+    start(): void;
+    /** Whether the transport is stopped mid-track, as opposed to not yet started. */
+    get held(): boolean;
+    /**
+     * Stop the stems where they are.
+     *
+     * The tape stops — this is a *pause*, not a duck, and the distinction is what
+     * several rounds of feedback kept correcting toward: the pause itself was right, it
+     * only ever needed a longer tail of effects to keep the music in the background.
+     * So the source stops
+     * and the sends carry what was already in flight. Reverb and delay live downstream
+     * of the stems, so cutting the source is exactly what leaves a decaying tail
+     * behind, and `setLongReverbSend` is how far that tail reaches.
+     *
+     * Idempotent: the caller is a per-frame mix that knows a *state*, not an event.
+     */
+    hold(): void;
+    /**
+     * Start the stems again from where `hold` left them.
+     *
+     * From where it left them, rather than from where the tape *would* have been: a
+     * pause that catches up is a jump cut, and on a long glide it is audible as the
+     * track skipping. The cost is that airborne time puts the score behind the route's
+     * bar grid — a real trade, taken deliberately, because the hold is felt on every
+     * jump and the grid is felt once at the start line.
+     */
+    release(): void;
+    /**
+     * Stop the stems and start them again from the top.
+     *
+     * A `BufferSource` cannot be rewound — the spec makes it one-shot — so starting
+     * over means discarding the sources and creating new ones. That is cheap: a
+     * source node is a handle onto a buffer that is already decoded and already
+     * resident, and nothing about the graph downstream of it is rebuilt.
+     *
+     * Exists because a caller needs the track's beat zero to coincide with something
+     * in its own world. Left running instead, a loop's downbeats land somewhere
+     * different on every attempt.
+     *
+     * **Returns how long until beat zero is actually heard**, in seconds, because
+     * `launch` schedules a little ahead of now and a caller lining a picture up
+     * against the music needs that number rather than an assumption. Zero when
+     * nothing started.
+     */
+    restart(): number;
+    /**
+     * Seconds until the scheduled start of whatever is playing, or 0 if it is
+     * already sounding.
+     *
+     * Reads the instant `launch` scheduled, which is the only authority on when the
+     * stems begin: everything else about the transport is a consequence of it.
+     */
+    get startsInSec(): number;
+    /**
+     * Create one source per stem, all at the same scheduled instant and the same
+     * offset into the buffer.
+     *
+     * Layers must be sample-locked: started independently they drift apart by however
+     * long each `start()` call happened to take, and a bassline a few milliseconds off
+     * its drums is heard as flamming rather than as one track.
+     */
+    private launch;
+    /**
+     * Stop every stem, quietly. See `FADE_OUT` for why the fade is not optional.
+     *
+     * The sources are dropped from `stemSources` immediately but stay connected until
+     * their fade has run: disconnecting a node mid-fade is the same discontinuity this
+     * exists to remove.
+     */
+    private stopSources;
+    /**
+     * Let go of a faded-out source once it can no longer be heard.
+     *
+     * A timer rather than `onended`, because an offline render has no wall clock to fire
+     * one on and the nodes it leaves behind are discarded with the context anyway. Live,
+     * a handful of nodes for a fifth of a second is cheaper than a listener per source.
+     */
+    private release_;
+    /**
+     * Schedule everything that follows at `seconds` on this context's timeline, or at
+     * "now" when null.
+     *
+     * An offline render sets it once per frame and gets a mix whose every move lands
+     * where the picture is, exactly, with no clock involved. Live callers never touch it.
+     */
+    at(seconds: number | null): void;
+    /**
+     * The instant scheduled work lands on.
+     *
+     * One reader, so "now" exists in one place — and so an offline render can move it.
+     */
+    private scheduleAt;
+    /**
+     * How far ahead the stems are launched, seconds.
+     *
+     * Live it is a lead, so the layers start sample-locked however long the calls take.
+     * Offline there is nothing to be late for: work scheduled at an exact instant is
+     * already sample-locked, and a lead would only push beat zero off the clip's zero.
+     */
+    private startLead;
+    /** The context as a live one, or null when this graph is rendering offline. */
+    private live;
+    /** Carry the transport position up to now at the rate it has been running at. */
+    private advance;
+    setStemGain(index: number, gain: number): void;
+    /**
+     * The layout this graph plays into: its buses, its inserts and its returns.
+     *
+     * **This is where the mix went in 3.0.0.** Every setter this class used to carry — the two
+     * volumes, the lift, the slam, the master filter, the three sends and the delay — is a method on
+     * a bus or an insert now, and `PORTING.md` maps them one for one. They were removed rather than
+     * left forwarding, because a shim that works forever is a second answer to every question the
+     * console already answers, and the two would drift the first time one of them grew a clamp.
+     */
+    get layout(): DefaultLayout;
+    /**
+     * The two levels a player chose, read from the buses that hold them.
+     *
+     * Derived rather than mirrored, which it was until 3.0.0. A mirror is a second place the answer
+     * is decided, and the reason the old one existed — that a level is ramped, so mid-ramp the
+     * *parameter* is between two values — is answered by the bus itself keeping its own fader
+     * setting. A duck does not move it, which is the distinction `fadeMusic` needed a paragraph for.
+     */
+    get levels(): MixLevels;
+    setPlaybackRate(rate: number): void;
+    /**
+     * Start a looping environmental bed, silent until the caller gives it a
+     * level. Routed through the effects stage, so the effects slider governs the
+     * world's own sound and the music slider governs only the score.
+     *
+     * Returns null for a missing buffer, so a caller can create loops
+     * unconditionally and let an unresolved slot simply be silent.
+     */
+    createLoop(buffer: AudioBuffer | undefined): AmbientLoop | null;
+    /**
+     * A live kick detector listening to the music.
+     *
+     * Tapped off the music stage rather than the master bus, so it hears the
+     * track and not the game's own sound effects — a splash landing on the beat
+     * would otherwise read as a kick and flash the world.
+     *
+     * The taps are pure observers: nothing is connected onward from them, so
+     * inserting a detector cannot change what anyone hears.
+     */
+    createKickDetector(): KickDetector | null;
+    /**
+     * A stream of everything the player is hearing, for a clip recording.
+     *
+     * Tapped off the mix rather than replacing the destination, so recording cannot
+     * silence the game — a clip that captures perfectly while the player hears
+     * nothing is a bug they would report as "the export broke the sound".
+     *
+     * **Off `out`, which is the whole mix, and not off `master`, which is the dry
+     * path.** The send returns rejoin downstream of the master filter, so a tap on
+     * `master` hears the track and the speed filter and nothing wet at all. See
+     * `out`.
+     *
+     * **The alignment of this against the video is not ours to fix, and that was
+     * measured rather than assumed.** A probe that flashed one frame white while
+     * scheduling a click at the same instant, decoded back out of the file, found the
+     * audio leading the picture by a mean of 51 ms in one run and 85 ms in the next, with
+     * `outputLatency` reporting 0.048 then 0.024. Feeding the tap through a delay does
+     * move it — a forced 200 ms landed at +132 ms, near one for one — but there is no
+     * constant to use: correcting by an unstable reading made a run worse, from -51 to
+     * -85. `MediaRecorder` aligns its tracks by when data reached it, and nothing here can
+     * see that. The offline path exists because it never asks this question.
+     *
+     * The same tap every time. Building one per recording left the last one
+     * connected and running.
+     */
+    captureStream(): MediaStream | null;
+    /**
+     * Fire a one-shot. Routed so it sits under the same master filter and sends.
+     *
+     * `pan` places it across the stereo field (-1 to 1); pass the result of
+     * `stereoPan`. Omitted, the sound is centred, which is right for anything
+     * that happens *to* the player rather than somewhere near them.
+     */
+    play(buffer: AudioBuffer | undefined, gain?: number, pan?: number): void;
+    dispose(): void;
+    /**
+     * Every parameter move is ramped. Assigning `.value` directly steps the
+     * signal, and a step in a gain or a filter cutoff is an audible click — which
+     * at sixty updates a second becomes a buzz rather than a mix.
+     */
+    private ramp;
+}