@johnmorrisdotca/kyogijo-stadiums 0.60.0 → 0.61.0

package/dist/sound.dom.js

@@ -0,0 +1,508 @@
+// The sound of a surface in a page: a crowd bed at a level, the room it is heard in, and the cues of a game, from a replay it follows or from events a page pushes as they happen. Off until a
+// page turns it on (a browser lets audio start only after a press anyway): nothing is fetched, made or decoded before that. One audio context serves every sound of a page, and it is
+// suspended whenever none of them is heard: turned off, at no volume, the page hidden, the surface out of sight or its game paused. A bed's loops play only while it is heard.
+import { cueKindOf, cuesOf, cuesOfChange, excitementAt, levelFor, soundLevelsOf, soundMix, soundSetOf, soundVoicesOf } from "./sound.mix.js";
+import { SOUND_BEDS } from "./sound.sets.js";
+import { bufferOf, impulseSamples, layerBuffer, layerFilter, makeVoice, LAYER_SECONDS, noiseSamples } from "./sound.synth.js";
+const hubs = new Map();
+const DEFAULT_AUDIO = () => new AudioContext();
+/** The page's audio context for a maker, made the first time a sound is turned on. */
+function hubOf(audio) {
+    let hub = hubs.get(audio);
+    if (hub === undefined) {
+        hub = { users: new Set() };
+        hubs.set(audio, hub);
+    }
+    return hub;
+}
+/** Run the context while any sound of the page is heard, and suspend it when none is. */
+function settle(hub) {
+    const context = hub.context;
+    if (context === undefined)
+        return;
+    const wanted = [...hub.users].some((user) => user.audible());
+    if (wanted && context.state !== "running")
+        void context.resume().catch(() => undefined);
+    else if (!wanted && context.state === "running")
+        void context.suspend().catch(() => undefined);
+}
+const clamp = (value, least, greatest) => Math.min(greatest, Math.max(least, value));
+const isNum = (value) => typeof value === "number" && Number.isFinite(value);
+/** How fast a level glides to another, in seconds (a time constant). */
+const GLIDE = 0.6;
+/** The same voice twice within this many seconds plays once. */
+const SAME_VOICE = 0.2;
+/** How long the sound is held on after a game's clock stopped on a cue (its end), in seconds. */
+export const SOUND_TAIL = 5;
+const TAIL = SOUND_TAIL;
+/** How long a goal lifts the level under `auto`, in seconds. */
+const GOAL_LIFT = 6;
+/**
+ * The sound of a surface: its crowd bed at a level and the cues of its game. Nothing happens until `enable()`, which a page calls from a press.
+ * @example
+ * ```ts no-run
+ * import { createKyogijoSound } from "@johnmorrisdotca/kyogijo-stadiums/sound";
+ * import { mountKyogijoTurn } from "@johnmorrisdotca/kyogijo-stadiums/turn";
+ *
+ * const host = document.querySelector<HTMLElement>("#rink")!;
+ * const sound = createKyogijoSound({ sport: "nhl", venue: { roof: "fixed", seats: 18000 }, view: "3d", level: "auto", host });
+ * document.querySelector("#sound")!.addEventListener("click", () => sound.enable());
+ * const view = mountKyogijoTurn(host, { sport: "nhl" });
+ * const replay = view.replay({ frames: [{ t: 0, objects: [] }, { t: 60, objects: [] }], events: [{ t: 30, kind: "goal", team: "home" }] });
+ * sound.follow(replay, { periods: [{ start: 0, end: 60 }] });
+ * ```
+ */
+export function createKyogijoSound(settings) {
+    const audio = settings.audio ?? DEFAULT_AUDIO;
+    const get = settings.fetch ?? ((url) => fetch(url));
+    const doc = settings.doc ?? (typeof document === "undefined" ? undefined : document);
+    const files = { ...settings.files };
+    const context = { sport: settings.sport, venue: settings.venue, crowd: settings.crowd, view: settings.view };
+    let level = settings.level ?? "engaged";
+    let volume = isNum(settings.volume) ? clamp(settings.volume, 0, 1) : 0.6;
+    let on = false;
+    let inSight = true;
+    let paused = false;
+    let following;
+    let followMoment;
+    let liveMoment;
+    /** The context's time until which a live goal holds the level up. */
+    let liftUntil = -1;
+    let graph;
+    let destroyed = false;
+    /** The level the bed was last glided to, and whether a setting changed since: the bed is glided only then, not on every frame of a game. */
+    let glidedTo;
+    let dirty = false;
+    /** The timer that ends the hold after a game's clock stopped on a cue. */
+    let tailing;
+    const hub = hubOf(audio);
+    const fetched = new Map();
+    const decoded = new Map();
+    const lastPlayed = new Map();
+    const made = { layers: new Map() };
+    const user = { audible: () => audible() };
+    hub.users.add(user);
+    const hidden = () => doc?.visibilityState === "hidden";
+    const has = () => soundSetOf(context.sport) !== undefined;
+    function quiet() {
+        if (!has())
+            return "no-sound";
+        if (!on)
+            return "off";
+        if (volume === 0)
+            return "muted";
+        if (hidden())
+            return "hidden";
+        if (!inSight)
+            return "out-of-sight";
+        if (paused)
+            return "paused";
+        return undefined;
+    }
+    function audible() {
+        if (destroyed)
+            return false;
+        const why = quiet();
+        return why === undefined || (why === "paused" && tailing !== undefined);
+    }
+    /** Hold the sound on for `TAIL` seconds after the clock stopped on a cue, then let it go quiet: one timer, once. */
+    function tail() {
+        if (tailing !== undefined)
+            clearTimeout(tailing);
+        tailing = setTimeout(() => {
+            tailing = undefined;
+            refresh();
+        }, TAIL * 1000);
+    }
+    function heard() {
+        if (level !== "auto")
+            return levelFor(context.sport, level);
+        const ctx = hub.context;
+        if (ctx !== undefined && ctx.currentTime < liftUntil)
+            return levelFor(context.sport, "roar");
+        const moment = followMoment ?? liveMoment;
+        return levelFor(context.sport, moment === undefined ? "engaged" : excitementAt(moment));
+    }
+    const mixNow = () => soundMix(context, heard());
+    /** The names a surface needs: its bed's layers and its cues' voices that a page has files for. */
+    const wanted = () => {
+        const found = soundSetOf(context.sport);
+        if (found === undefined)
+            return [];
+        return [...SOUND_BEDS[found.bed].layers, ...soundVoicesOf(context.sport)].filter((name) => typeof files[name] === "string");
+    };
+    /** Fetch what the surface needs and has not been fetched: only after the sound was first turned on. */
+    function fetchWanted() {
+        return Promise.all(wanted()
+            .filter((name) => !fetched.has(name) && !decoded.has(name))
+            .map((name) => get(files[name]).then((answer) => (answer.ok ? answer.arrayBuffer().then((bytes) => void fetched.set(name, bytes)) : void decoded.set(name, "failed")), () => void decoded.set(name, "failed")))).then(() => undefined);
+    }
+    /** Decode the fetched recordings, only while heard; when they are ready the bed is laid again with them. */
+    function decodeFetched() {
+        const ctx = hub.context;
+        if (ctx === undefined || !audible())
+            return;
+        for (const [name, bytes] of fetched) {
+            if (decoded.has(name))
+                continue;
+            const job = ctx.decodeAudioData(bytes.slice(0)).then((buffer) => {
+                decoded.set(name, buffer);
+                fetched.delete(name);
+                if (graph !== undefined && SOUND_BEDS[soundSetOf(context.sport)?.bed ?? "arena"].layers.includes(name))
+                    relayBed();
+            }, () => {
+                decoded.set(name, "failed");
+                fetched.delete(name);
+            });
+            decoded.set(name, job);
+        }
+    }
+    const recording = (name) => {
+        const found = decoded.get(name);
+        return found !== undefined && typeof found === "object" && "getChannelData" in found ? found : undefined;
+    };
+    const buffers = (ctx) => ({
+        noise: () => (made.noise ?? (made.noise = bufferOf(ctx, [noiseSamples(Math.round(LAYER_SECONDS * ctx.sampleRate), 71, "pink")]))),
+        applause: () => (made.applause ?? (made.applause = layerBuffer(ctx, "applause"))),
+    });
+    const madeLayer = (ctx, layer) => {
+        let buffer = made.layers.get(layer);
+        if (buffer === undefined) {
+            buffer = layer === "applause" ? buffers(ctx).applause() : layerBuffer(ctx, layer);
+            made.layers.set(layer, buffer);
+        }
+        return buffer;
+    };
+    /** A looping source of a layer, through its filter when it is made. */
+    function loop(ctx, layer, into) {
+        const source = ctx.createBufferSource();
+        const recorded = recording(layer);
+        source.buffer = recorded ?? madeLayer(ctx, layer);
+        source.loop = true;
+        if (recorded === undefined) {
+            const filter = layerFilter(ctx, layer);
+            source.connect(filter);
+            filter.connect(into);
+        }
+        else
+            source.connect(into);
+        source.start();
+        return source;
+    }
+    function impulse(ctx, decay) {
+        return bufferOf(ctx, impulseSamples(decay, ctx.sampleRate, 97));
+    }
+    /** Lay the bed of the surface into the graph: a loop for each of its layers, and the roar's swell. */
+    function layBed(ctx, g, mix) {
+        for (const layer of mix.bed.layers) {
+            const gain = ctx.createGain();
+            gain.gain.value = mix.layers[layer] * mix.gain;
+            gain.connect(g.mix);
+            g.layers.set(layer, { gain, source: loop(ctx, layer, gain) });
+        }
+        if (mix.bed.layers.includes("roar")) {
+            const gain = ctx.createGain();
+            gain.gain.value = 0;
+            gain.connect(g.mix);
+            g.swell = { gain, source: loop(ctx, "roar", gain) };
+        }
+    }
+    function clearBed(g) {
+        for (const { source, gain } of [...g.layers.values(), ...(g.swell === undefined ? [] : [g.swell])]) {
+            source.stop();
+            source.disconnect();
+            gain.disconnect();
+        }
+        g.layers.clear();
+        g.swell = undefined;
+    }
+    function relayBed() {
+        const ctx = hub.context;
+        const mix = mixNow();
+        if (ctx === undefined || graph === undefined)
+            return;
+        clearBed(graph);
+        if (mix !== undefined)
+            layBed(ctx, graph, mix);
+    }
+    /** Make the graph and start the bed: when the sound becomes heard. */
+    function build(ctx) {
+        const mix = mixNow();
+        if (mix === undefined)
+            return;
+        const master = ctx.createGain();
+        master.gain.value = volume;
+        master.connect(ctx.destination);
+        const mixBus = ctx.createGain();
+        const dry = ctx.createGain();
+        const wet = ctx.createGain();
+        const convolver = ctx.createConvolver();
+        convolver.buffer = impulse(ctx, mix.decay);
+        dry.gain.value = 1 - mix.wet;
+        wet.gain.value = mix.wet;
+        mixBus.connect(dry);
+        mixBus.connect(convolver);
+        convolver.connect(wet);
+        dry.connect(master);
+        wet.connect(master);
+        const cues = ctx.createGain();
+        cues.gain.value = 0.9;
+        cues.connect(mixBus);
+        graph = { master, mix: mixBus, dry, wet, convolver, decay: mix.decay, layers: new Map(), swell: undefined, cues };
+        glidedTo = mix.level;
+        dirty = false;
+        layBed(ctx, graph, mix);
+    }
+    /** Stop the bed and take the graph away: when the sound stops being heard. */
+    function tearDown() {
+        if (graph === undefined)
+            return;
+        clearBed(graph);
+        for (const node of [graph.cues, graph.mix, graph.dry, graph.wet, graph.convolver, graph.master])
+            node.disconnect();
+        graph = undefined;
+    }
+    /** Glide the bed to the mix of now: the level, the room, the volume. */
+    function glide() {
+        const ctx = hub.context;
+        if (ctx === undefined || graph === undefined)
+            return;
+        const mix = mixNow();
+        if (mix === undefined)
+            return;
+        dirty = false;
+        glidedTo = mix.level;
+        const now = ctx.currentTime;
+        graph.master.gain.setTargetAtTime(volume, now, 0.05);
+        graph.dry.gain.setTargetAtTime(1 - mix.wet, now, GLIDE);
+        graph.wet.gain.setTargetAtTime(mix.wet, now, GLIDE);
+        for (const [layer, { gain }] of graph.layers)
+            gain.gain.setTargetAtTime(mix.layers[layer] * mix.gain, now, GLIDE);
+        if (Math.abs(mix.decay - graph.decay) > graph.decay * 0.1) {
+            graph.convolver.buffer = impulse(ctx, mix.decay);
+            graph.decay = mix.decay;
+        }
+    }
+    /** Bring the graph to whether the sound is heard: made when it starts being heard, taken away when it stops, and the context run or suspended. */
+    function refresh() {
+        const ctx = hub.context;
+        if (ctx !== undefined) {
+            if (audible()) {
+                if (graph === undefined)
+                    build(ctx);
+                else if (dirty || heard() !== glidedTo)
+                    glide();
+                decodeFetched();
+            }
+            else
+                tearDown();
+        }
+        settle(hub);
+    }
+    /**
+     * A recording as a cue: whole, or for the end of a game two short whistles and a long one, or for applause (a loop) three seconds that rise and fall away, so that a loop's cut is
+     * never heard.
+     */
+    function playRecording(ctx, out, buffer, voice, now) {
+        const one = (at, length) => {
+            const source = ctx.createBufferSource();
+            source.buffer = buffer;
+            const gain = ctx.createGain();
+            source.connect(gain);
+            gain.connect(out);
+            const until = at + (length ?? buffer.duration);
+            gain.gain.setValueAtTime(0, at);
+            gain.gain.linearRampToValueAtTime(1, at + (voice === "applause" ? 0.3 : 0.005));
+            gain.gain.setValueAtTime(1, Math.max(at + 0.01, until - (voice === "applause" ? 1.2 : 0.05)));
+            gain.gain.linearRampToValueAtTime(0, until);
+            source.start(at, 0, length ?? buffer.duration);
+            source.stop(until);
+        };
+        if (voice === "whistle-end") {
+            one(now, 0.25);
+            one(now + 0.4, 0.25);
+            one(now + 0.8);
+        }
+        else if (voice === "applause")
+            one(now, Math.min(buffer.duration, 3.5));
+        else
+            one(now);
+    }
+    function play(cue) {
+        const ctx = hub.context;
+        if (ctx === undefined || graph === undefined || !audible())
+            return;
+        const now = ctx.currentTime;
+        const last = lastPlayed.get(cue.voice);
+        if (last !== undefined && now - last < SAME_VOICE)
+            return;
+        lastPlayed.set(cue.voice, now);
+        settings.onCue?.(cue);
+        if (cue.voice === "swell") {
+            const swell = graph.swell;
+            const mix = mixNow();
+            if (swell === undefined || mix === undefined || mix.crowd === 0)
+                return;
+            const g = swell.gain.gain;
+            g.cancelScheduledValues(now);
+            g.setValueAtTime(g.value, now);
+            g.linearRampToValueAtTime(mix.crowd * mix.gain, now + 0.5);
+            g.setValueAtTime(mix.crowd * mix.gain, now + 2.5);
+            g.setTargetAtTime(0, now + 2.5, 1.5);
+            return;
+        }
+        const recorded = recording(cue.voice === "whistle-end" ? "whistle" : cue.voice);
+        if (recorded !== undefined)
+            playRecording(ctx, graph.cues, recorded, cue.voice, now);
+        else
+            makeVoice(ctx, cue.voice, graph.cues, buffers(ctx), now);
+    }
+    const onVisibility = () => refresh();
+    doc?.addEventListener("visibilitychange", onVisibility);
+    let observer;
+    if (settings.host !== undefined && typeof IntersectionObserver !== "undefined") {
+        observer = new IntersectionObserver((entries) => {
+            const last = entries[entries.length - 1];
+            if (last === undefined)
+                return;
+            inSight = last.isIntersecting;
+            refresh();
+        });
+        observer.observe(settings.host);
+    }
+    const sound = {
+        async enable() {
+            if (destroyed)
+                return;
+            on = true;
+            hub.context ?? (hub.context = audio());
+            refresh();
+            await fetchWanted();
+            refresh();
+        },
+        disable() {
+            on = false;
+            refresh();
+        },
+        setVolume(next) {
+            volume = isNum(next) ? clamp(next, 0, 1) : volume;
+            dirty = true;
+            refresh();
+        },
+        setLevel(next) {
+            level = next;
+            dirty = true;
+            refresh();
+        },
+        setContext(next) {
+            const before = soundSetOf(context.sport)?.bed;
+            Object.assign(context, next);
+            dirty = true;
+            if (soundSetOf(context.sport)?.bed !== before) {
+                tearDown();
+                if (on)
+                    void fetchWanted().then(refresh);
+            }
+            refresh();
+        },
+        follow(controller, game = {}) {
+            following?.stop();
+            const periods = game.periods ?? [];
+            let lastT = controller.state().t;
+            let goalAt;
+            const momentOf = (t, start, end) => ({ t, start, end, periods, score: game.scoreAt?.(t), sinceGoal: goalAt === undefined ? undefined : t - goalAt });
+            const take = (s) => {
+                paused = !s.playing;
+                if (s.playing && tailing !== undefined) {
+                    clearTimeout(tailing);
+                    tailing = undefined;
+                }
+                followMoment = momentOf(s.t, s.start, s.end);
+            };
+            take(controller.state());
+            const stop = controller.subscribe((change) => {
+                const cues = cuesOfChange(change, lastT, context.sport, periods);
+                if (change.state.t < lastT || change.reason === "seek")
+                    goalAt = undefined;
+                for (const event of change.crossed) {
+                    const kind = cueKindOf(event);
+                    if (change.reason === "tick" && (kind === "goal" || kind === "point"))
+                        goalAt = event.t;
+                }
+                lastT = change.state.t;
+                // The cues of the last move are heard out, though the clock stopped with it (the horn at the end of the game): the sound goes quiet a few seconds later.
+                if (cues.length > 0 && !change.state.playing)
+                    tail();
+                take(change.state);
+                refresh();
+                for (const cue of cues)
+                    play(cue);
+            });
+            const handle = {
+                stop() {
+                    stop();
+                    if (following === handle) {
+                        following = undefined;
+                        followMoment = undefined;
+                        paused = false;
+                        refresh();
+                    }
+                },
+            };
+            following = handle;
+            refresh();
+            return () => handle.stop();
+        },
+        cue(event) {
+            const voices = cuesOf(event, context.sport);
+            const ctx = hub.context;
+            const kind = cueKindOf(event);
+            if (ctx !== undefined && (kind === "goal" || kind === "point") && voices.length > 0)
+                liftUntil = ctx.currentTime + GOAL_LIFT;
+            dirty = true;
+            refresh();
+            if (kind === undefined)
+                return;
+            const t = ctx?.currentTime ?? 0;
+            for (const voice of voices)
+                play(event.team === undefined ? { voice, kind, t } : { voice, kind, t, team: event.team });
+        },
+        game(moment) {
+            liveMoment = moment;
+            refresh();
+        },
+        state() {
+            const why = quiet();
+            return {
+                has: has(),
+                on,
+                audible: audible(),
+                ...(why === undefined ? {} : { quiet: why }),
+                sport: context.sport,
+                volume,
+                level,
+                heard: heard(),
+                levels: soundLevelsOf(context.sport),
+                voices: soundVoicesOf(context.sport),
+                fetched: [...new Set([...fetched.keys(), ...[...decoded].filter(([, v]) => v !== "failed").map(([k]) => k)])],
+                following: following !== undefined,
+            };
+        },
+        destroy() {
+            if (destroyed)
+                return;
+            following?.stop();
+            destroyed = true;
+            on = false;
+            if (tailing !== undefined)
+                clearTimeout(tailing);
+            tailing = undefined;
+            tearDown();
+            doc?.removeEventListener("visibilitychange", onVisibility);
+            observer?.disconnect();
+            hub.users.delete(user);
+            settle(hub);
+        },
+    };
+    return sound;
+}

package/dist/sound.mix.d.ts

@@ -0,0 +1,158 @@
+import type { ReplayChange, ReplayEvent } from "./replay.types.ts";
+import type { CueKind, SoundBed, SoundLayer, SoundLevel, SoundSet, SoundVoice } from "./sound.sets.ts";
+/** The venue a surface is in, as far as the sound cares: its roof and its seats. Both are optional; without them the bed's own are used. */
+export interface SoundVenue {
+    /**
+     * The kind of roof, as the venues and the stadiums give it: `open` and `canopy` leave the crowd under the sky; `cable` and `panels` (a retractable roof) mostly close it in; `fixed`, `dome`,
+     * `saddle` and `barrel` close it in. An unknown word is taken as the bed's own.
+     */
+    roof?: string;
+    /** The seats. */
+    seats?: number;
+}
+/** Where and how a surface is heard. */
+export interface SoundContext {
+    /** The surface: a sport of the package (`nhl`, `soccer`, `judo`, ...). */
+    sport: string;
+    venue?: SoundVenue;
+    /** The share of the seats that are taken, 0 to 1 (1 by default): 0 is an empty building, as when a page's Crowd is off. */
+    crowd?: number;
+    /** The view: `3d` is in the building, `2d` the drawing from above, heard as a broadcast is, the crowd further off and the room drier. */
+    view?: "2d" | "3d";
+}
+/** The room a surface is heard in. */
+export interface SoundRoom {
+    bed: SoundBed;
+    /** How closed in it is, 0 (open sky) to 1 (a roof all over). */
+    enclosure: number;
+    /** How long the room rings, in seconds. */
+    decay: number;
+    /** How much of the sound is the room's echo, 0 to 1. */
+    wet: number;
+    /** The people in it. */
+    people: number;
+    /** How loud the crowd is for the people in it, 0 (nobody) to a little over 1 (more than the bed was made for). */
+    crowd: number;
+    /** All of it, for the view: 1 in 3D, less from above. */
+    gain: number;
+}
+/** A mix: each layer's gain, and the room. */
+export interface SoundMix extends SoundRoom {
+    level: SoundLevel;
+    layers: Readonly<Record<SoundLayer, number>>;
+}
+/** The set of a surface's sport, or `undefined` when it has none (a surface with no sound shows no sound controls). */
+export declare function soundSetOf(sport: string): SoundSet | undefined;
+/** The crowd levels a surface offers, quietest first: none for a surface with no sound. */
+export declare function soundLevelsOf(sport: string): readonly SoundLevel[];
+/** The voices a surface's cues use, each once, in the order of `CUE_KINDS`: what a page loads when it has files for them. */
+export declare function soundVoicesOf(sport: string): readonly SoundVoice[];
+/**
+ * The room of a surface in its context: how closed in the venue is (its roof, else its bed's), how long it rings (longer closed in and larger), how much echo, and how loud the crowd is for the
+ * people in it (the seats times the share taken, on a scale that grows as a crowd's sound does, slower than its number). `undefined` for a surface with no sound.
+ * @example
+ * ```ts
+ * import { soundRoom } from "@johnmorrisdotca/kyogijo-stadiums/sound";
+ * const arena = soundRoom({ sport: "nhl", venue: { roof: "fixed", seats: 18000 } })!;
+ * const field = soundRoom({ sport: "soccer", venue: { roof: "open", seats: 50000 } })!;
+ * console.log(arena.bed.id, arena.decay > field.decay, arena.wet > field.wet);
+ * console.log(soundRoom({ sport: "nhl", crowd: 0 })!.crowd);
+ * // arena true true
+ * // 0
+ * ```
+ */
+export declare function soundRoom(context: SoundContext): SoundRoom | undefined;
+/** Each layer's gain at each level, before the crowd's size: the room and the water stay, the voices come up. */
+export declare const LEVEL_MIX: Readonly<Record<SoundLevel, Readonly<Record<SoundLayer, number>>>>;
+/** The nearest level a surface offers to the one asked for: a dojo asked to roar is loud. */
+export declare function levelFor(sport: string, level: SoundLevel): SoundLevel;
+/**
+ * The mix of a surface in its context at a crowd level: each of its bed's layers' gain (the crowd's voices scaled by the people in the room; a layer the bed does not have is 0) and the room.
+ * `undefined` for a surface with no sound.
+ * @example
+ * ```ts
+ * import { soundMix } from "@johnmorrisdotca/kyogijo-stadiums/sound";
+ * const quiet = soundMix({ sport: "nhl" }, "quiet")!;
+ * const roar = soundMix({ sport: "nhl" }, "roar")!;
+ * console.log(quiet.layers.roar, roar.layers.roar > roar.layers.murmur, soundMix({ sport: "kyudo" }, "roar")!.level);
+ * // 0 true murmur
+ * ```
+ */
+export declare function soundMix(context: SoundContext, level: SoundLevel): SoundMix | undefined;
+/** A period of a game on the timeline's clock, as the example games give them. */
+export interface SoundPeriod {
+    number?: number;
+    start: number;
+    end: number;
+}
+/** A game at a moment: what moves the crowd. */
+export interface GameMoment {
+    /** The time on the timeline's clock. */
+    t: number;
+    /** The game's periods; without them the whole timeline is one. */
+    periods?: readonly SoundPeriod[];
+    /** The timeline's first and last moments. */
+    start: number;
+    end: number;
+    /** The score now. */
+    score?: {
+        home: number;
+        away: number;
+    };
+    /** Seconds since the last goal, when there was one. */
+    sinceGoal?: number;
+}
+/**
+ * How excited the crowd is at a moment of a game: a murmur before the start, between periods and after the end; engaged while it plays; loud late in a close game; a roar for a few seconds
+ * after a goal; and back to a murmur when one side is far ahead late on.
+ * @example
+ * ```ts
+ * import { excitementAt } from "@johnmorrisdotca/kyogijo-stadiums/sound";
+ * const periods = [{ start: 0, end: 100 }, { start: 120, end: 220 }];
+ * console.log(excitementAt({ t: 50, start: 0, end: 220, periods, score: { home: 0, away: 0 } }));
+ * console.log(excitementAt({ t: 110, start: 0, end: 220, periods }));
+ * console.log(excitementAt({ t: 200, start: 0, end: 220, periods, score: { home: 2, away: 1 } }));
+ * console.log(excitementAt({ t: 60, start: 0, end: 220, periods, sinceGoal: 2 }));
+ * // engaged
+ * // murmur
+ * // loud
+ * // roar
+ * ```
+ */
+export declare function excitementAt(moment: GameMoment): SoundLevel;
+/** The kind of moment a timeline's event is, or `undefined` for one with no cue (a pass). */
+export declare function cueKindOf(event: Pick<ReplayEvent, "kind">): CueKind | undefined;
+/**
+ * The voices an event calls on a surface: its kind's cue in the sport's set, or none.
+ * @example
+ * ```ts
+ * import { cuesOf } from "@johnmorrisdotca/kyogijo-stadiums/sound";
+ * console.log(cuesOf({ kind: "goal" }, "nhl").join(), cuesOf({ kind: "goal" }, "soccer").join(), cuesOf({ kind: "whistle" }, "nba").join());
+ * console.log(cuesOf({ kind: "pass" }, "nhl").length, cuesOf({ kind: "goal" }, "a-surface-with-no-sound").length);
+ * // horn,swell swell whistle
+ * // 0 0
+ * ```
+ */
+export declare function cuesOf(event: Pick<ReplayEvent, "kind">, sport: string): readonly SoundVoice[];
+/** A cue to play: its voice, the event that called it, and the time on the timeline's clock it belongs to. */
+export interface SoundCue {
+    voice: SoundVoice;
+    kind: CueKind;
+    t: number;
+    team?: "home" | "away";
+}
+/**
+ * The cues of a move of a replay: the events it went by and the periods it began or ended, each with its voices. Only a move made by the clock playing (`tick`) or by a step forward calls
+ * cues; a seek, a jump back, a pause or a change of speed calls none, as scrubbing announces nothing. The end of the last period is the game's end.
+ * @example
+ * ```ts
+ * import { cuesOfChange } from "@johnmorrisdotca/kyogijo-stadiums/sound";
+ * const state = { t: 10, start: 0, end: 60, playing: true, ended: false, speed: 1, loop: false, motion: "smooth" as const, follow: "off" as const, followHeld: false };
+ * const change = { state, reason: "tick" as const, crossed: [{ t: 9.5, kind: "goal", team: "home" as const }] };
+ * console.log(cuesOfChange(change, 9, "nhl").map((c) => c.voice).join());
+ * console.log(cuesOfChange({ ...change, reason: "seek" as const }, 9, "nhl").length);
+ * // horn,swell
+ * // 0
+ * ```
+ */
+export declare function cuesOfChange(change: ReplayChange, from: number, sport: string, periods?: readonly SoundPeriod[]): SoundCue[];