@johnmorrisdotca/kyogijo-stadiums 0.60.1 → 0.61.0

package/CHANGELOG.md

@@ -7,6 +7,15 @@ All notable changes to this project are written here. The format follows
 
 ## [Unreleased]
 
+## [0.61.0] - 2026-11-03
+
+### Added
+
+- **Sound: the crowd of each kind of venue, at a level (KYOGIJO-STADIUMS-36)** ([sound](./docs/sound.md)): `@johnmorrisdotca/kyogijo-stadiums/sound` has `createKyogijoSound`, a surface's crowd made in the browser with Web Audio (the building's air, people talking, applause and the crowd's voice, and the pool's water), at five levels from quiet to a roar, heard in the room its venue makes (its roof and its seats: an arena rings, an open stadium does not), as large as the crowd in it and drier from above in 2D. An index of sound sets (`SOUND_BEDS`, `SOUND_SETS`, `SOUND_OF_SPORT`) gives every surface a bed for its kind of venue (arena, open stadium, ballpark, court hall, pool, dojo, ring, track) and the levels it offers (a kyudo hall only two); a surface with none has no sound. Off until turned on: nothing is fetched, made or decoded before, one audio context serves the page, and nothing plays or decodes while it is off, muted, hidden or out of sight. `soundRoom`, `soundMix` and `levelFor` are the rules, pure.
+- The demo: a Sound button, a volume slider and the crowd's levels as buttons, kept in the address (`sound=on`, `volume`, `level`), on the real arenas (venues.html), under the surface in Try it (the levels of each surface's venue, none with the crowd off) and over the arena at the top of the page. Its recordings (`demo/sounds/`) are CC0 or in the public domain, each listed with its source, author and licence in [sound credits](./docs/sound-credits.md), made by `pnpm sounds:fetch` and `pnpm sounds` (loudness matched, seamless loops, Opus with AAC); the most a sport loads is under 110 kB. They are not in the npm package.
+- **Sound: a game's cues from its replay (KYOGIJO-STADIUMS-36)** ([game cues](./docs/sound.md#game-cues)): `sound.follow(controller, { periods, scoreAt })` plays each sport's cues as the replay goes by them (hockey's goal horn and the crowd's swell, a whistle at a stoppage, the buzzer at a period's end, a ring's bell, a starting gun, an "ooh" at a near miss), none on a seek or while paused, and under `level: "auto"` the crowd follows the game (`excitementAt`: loud late in a close game, a roar after a goal). `cueKindOf` reads a timeline's own words (`touchdown`, `try`, `ippon`, `foul`...); `cuesOf` and `cuesOfChange` are the rules, pure. The demo's game section and every Play a game (the arena at the top of the page, Try it and the real arenas) have the sound, with Follow the game among the levels; `play-game.js` tells a page of the replay it puts on the view (`onReplay`).
+- **Sound: live events (KYOGIJO-STADIUMS-36)** ([live events](./docs/sound.md#live-events)): `sound.cue({ kind, team })` plays an event's cues as it happens, and `sound.game(moment)` gives the game's state to the level under `auto`; a goal lifts it to a roar for six seconds. The demo's live score has the sound, and pushes each goal and the game's end as they come.
+
 ## [0.60.1] - 2026-11-03
 
 ### Fixed

package/README.md

@@ -260,6 +260,7 @@ console.log(svg.startsWith("<svg"), svg.includes("USA 3, Canada 2"));
 - **Bring your own race feed**: a race plays from a feed you choose, read by your own browser from an address, pasted or from a file, and followed while it is live: kyogijo's open race timeline or OpenF1-style lap rows, with our made-up sample feed first. [The race feed](./docs/race-feed.md), [Where to find a feed](./docs/where-to-find-a-feed.md).
 - **Tournaments**: several surfaces on one floor, who judges where, boards laid over a surface. [Layouts](./docs/multi.md), [judging](./docs/judging.md), [boards](./docs/boards.md).
 - **Data on a surface**: points, heat maps, shot and pass charts, team shapes and a replay, flat or in 3D with the players standing on the ice, in 48 providers' coordinate frames. [Layers](./docs/layers.md), [frames](./docs/frames.md), [replay](./docs/replay.md), [an example game](./docs/example-games.md).
+- **Sound**: the crowd of each kind of venue at a level from quiet to a roar, heard in the room its venue makes, and its game's sounds (the goal horn, the whistle, the buzzer, the bell) from a replay or live events; made in the browser, off until turned on. [Sound](./docs/sound.md).
 - **Looks and flags**: eight named looks, a flag or crest on each half, trophies and crests from Dougu Sports, flags from Hata, light and dark. [Theming](./docs/theming.md), [the pageant](./docs/pageant.md).
 - **Four ways in**: a function that returns SVG text, a helper that draws into a container, a custom element, a frame for pages with no script; renderers for a canvas, d3, Observable Plot, GeoJSON and PNG. [Entry points](./docs/entry-points.md), [renderers](./docs/renderers.md).
 - **Accessible and small**: each drawing is an `img` with a title and a description, in English or Japanese; no dependencies, no network requests, nothing stored.
@@ -275,6 +276,7 @@ console.log(svg.startsWith("<svg"), svg.includes("USA 3, Canada 2"));
 | `./circuits` | Race tracks as OpenStreetMap maps them, in 2D and 3D, and a simulated race on them with its clock and timing board ([demo](https://johnmorrisdotca.github.io/kyogijo-stadiums/circuits.html?race=1)). |
 | `./multi`, `./judging`, `./layouts` | Several surfaces for one event ([demo](https://johnmorrisdotca.github.io/kyogijo-stadiums/halls.html)); who judges where; small multiples and backgrounds. |
 | `./layers`, `./charts`, `./frames`, `./zones`, `./pointer`, `./replay` | Data layers, charts, the providers' frames, zones by the rules, a click as a place, tracking data played on a surface. |
+| `./sound` | A surface's crowd and its game's sounds, made in the browser with Web Audio ([demo](https://johnmorrisdotca.github.io/kyogijo-stadiums/venues.html?sound=on)). |
 | `./athletics`, `./budo`, `./skating` | The athletics stadium, the budō (areas, dohyō, the dojo builder) and the skating rinks. |
 | `./scene`, `./canvas`, `./d3`, `./plot`, `./geojson`, `./png` | The drawing as data, on a canvas, in d3, as an Observable Plot mark, as GeoJSON, as a PNG. |
 | `./mount`, `./react`, `./element`, `./element/define` | Draw into a container; React props; the `<kyogijo-field>` element and its registration. |

package/catalogue.json

@@ -3,7 +3,7 @@
  "generatedAt": "2026-11-03",
  "package": {
   "name": "@johnmorrisdotca/kyogijo-stadiums",
-  "version": "0.60.1"
+  "version": "0.61.0"
  },
  "address": "https://johnmorrisdotca.github.io/kyogijo-stadiums/catalogue.json",
  "site": "https://johnmorrisdotca.github.io/kyogijo-stadiums/",

package/dist/catalogue.data.js

@@ -3,7 +3,7 @@ export const CATALOGUE_DATA = {
     "generatedAt": "2026-11-03",
     "package": {
         "name": "@johnmorrisdotca/kyogijo-stadiums",
-        "version": "0.60.1"
+        "version": "0.61.0"
     },
     "address": "https://johnmorrisdotca.github.io/kyogijo-stadiums/catalogue.json",
     "site": "https://johnmorrisdotca.github.io/kyogijo-stadiums/",

package/dist/sound-entry.d.ts

@@ -0,0 +1,8 @@
+export { SOUND_TAIL, createKyogijoSound } from "./sound.dom.ts";
+export type { KyogijoSound, SoundAudioContext, SoundFetch, SoundFileName, SoundFollow, SoundLevelChoice, SoundQuiet, SoundSettings, SoundState } from "./sound.dom.ts";
+export { LEVEL_MIX, cueKindOf, cuesOf, cuesOfChange, excitementAt, levelFor, soundLevelsOf, soundMix, soundRoom, soundSetOf, soundVoicesOf } from "./sound.mix.ts";
+export type { GameMoment, SoundContext, SoundCue, SoundMix, SoundPeriod, SoundRoom, SoundVenue } from "./sound.mix.ts";
+export { CUE_KINDS, SOUND_BEDS, SOUND_LEVELS, SOUND_OF_SPORT, SOUND_SETS } from "./sound.sets.ts";
+export type { CueKind, SoundBed, SoundBedId, SoundLayer, SoundLevel, SoundSet, SoundVoice } from "./sound.sets.ts";
+export { SOUND_WORDS } from "./sound.words.ts";
+export type { SoundWords } from "./sound.words.ts";

package/dist/sound-entry.js

@@ -0,0 +1,6 @@
+// The sound entry (`@johnmorrisdotca/kyogijo-stadiums/sound`): a surface's sound in a page, a crowd bed for its kind of venue at a level, heard in the room its venue makes, and the cues of
+// its sport (a goal horn, a whistle, a buzzer, a bell) from a replay it follows or from events pushed as they happen. Made in the browser with Web Audio; recordings are a page's own files.
+export { SOUND_TAIL, createKyogijoSound } from "./sound.dom.js";
+export { LEVEL_MIX, cueKindOf, cuesOf, cuesOfChange, excitementAt, levelFor, soundLevelsOf, soundMix, soundRoom, soundSetOf, soundVoicesOf } from "./sound.mix.js";
+export { CUE_KINDS, SOUND_BEDS, SOUND_LEVELS, SOUND_OF_SPORT, SOUND_SETS } from "./sound.sets.js";
+export { SOUND_WORDS } from "./sound.words.js";

package/dist/sound.dom.d.ts

@@ -0,0 +1,113 @@
+import type { GameMoment, SoundContext, SoundCue, SoundPeriod, SoundVenue } from "./sound.mix.ts";
+import type { SoundLayer, SoundLevel, SoundVoice } from "./sound.sets.ts";
+import type { ReplayController } from "./replay.control.ts";
+import type { ReplayEvent } from "./replay.types.ts";
+/** The recordings a page may give, by the layer or the voice they stand for; anything not given is made in the browser. */
+export type SoundFileName = SoundLayer | SoundVoice;
+/** What the engine needs of an audio context: a page's `AudioContext`, or a stand-in in a test. */
+export type SoundAudioContext = BaseAudioContext & {
+    resume(): Promise<void>;
+    suspend(): Promise<void>;
+};
+/** How the engine fetches a recording: `fetch` by default. */
+export type SoundFetch = (url: string) => Promise<{
+    ok: boolean;
+    arrayBuffer(): Promise<ArrayBuffer>;
+}>;
+/** A crowd level, or `auto`: the level follows the game a sound follows (`excitementAt`), and is `engaged` with no game. */
+export type SoundLevelChoice = SoundLevel | "auto";
+/** The settings of a surface's sound. */
+export interface SoundSettings {
+    /** The surface (`nhl`, `soccer`, ...). A surface with no sound set makes no sound and offers no levels (`state().has`). */
+    sport: string;
+    venue?: SoundVenue;
+    /** The share of the seats taken, 0 to 1: 0 is no crowd (a page's Crowd off). */
+    crowd?: number;
+    view?: "2d" | "3d";
+    /** The crowd's level: `engaged` by default. */
+    level?: SoundLevelChoice;
+    /** 0 to 1: 0.6 by default. 0 is muted, and nothing is heard or made. */
+    volume?: number;
+    /** Recordings by name, for the voices and layers a page has files for (the demo's: `demo/sounds/`). Fetched only when the sound is first turned on, and decoded only when it is heard. */
+    files?: Partial<Record<SoundFileName, string>>;
+    /** Makes the page's one audio context: `new AudioContext()` by default. A test gives a stand-in. */
+    audio?: () => SoundAudioContext;
+    fetch?: SoundFetch;
+    /** The element the surface is drawn in: the sound stops while it is out of sight. */
+    host?: Element;
+    /** The page, for whether it is hidden: `document` by default. */
+    doc?: Document;
+    /** Told of every cue as it plays: a page may show it. */
+    onCue?: (cue: SoundCue) => void;
+}
+/** Why a sound is not heard. */
+export type SoundQuiet = "no-sound" | "off" | "muted" | "hidden" | "out-of-sight" | "paused";
+/** What a sound is doing. */
+export interface SoundState {
+    /** The surface has a sound set: a page shows the sound's controls only when it has. */
+    has: boolean;
+    on: boolean;
+    /** Heard now: on, with volume, the page shown, the surface in sight and its game not paused. */
+    audible: boolean;
+    /** Why it is not heard, when it is not. */
+    quiet?: SoundQuiet;
+    sport: string;
+    volume: number;
+    level: SoundLevelChoice;
+    /** The level heard: the choice, the game's under `auto`, held to what the surface offers. */
+    heard: SoundLevel;
+    /** The levels the surface offers, quietest first. */
+    levels: readonly SoundLevel[];
+    /** The voices its cues use. */
+    voices: readonly SoundVoice[];
+    /** The recordings fetched (they are decoded when heard). */
+    fetched: readonly SoundFileName[];
+    /** Following a replay. */
+    following: boolean;
+}
+/** Following a replay: its periods and its score at a time, for the cues of the periods' ends and for the level under `auto`. */
+export interface SoundFollow {
+    periods?: readonly SoundPeriod[];
+    scoreAt?: (t: number) => {
+        home: number;
+        away: number;
+    };
+}
+/** A surface's sound in a page. */
+export interface KyogijoSound {
+    /** Turn it on: call it from a press, so that the browser lets the audio start. The first call makes the audio context and fetches the recordings. */
+    enable(): Promise<void>;
+    /** Turn it off: nothing is heard, made or decoded, and the audio context is suspended when no other sound of the page is heard. */
+    disable(): void;
+    setVolume(volume: number): void;
+    setLevel(level: SoundLevelChoice): void;
+    /** Change the context: another surface, venue, crowd or view. The levels and cues offered follow the surface. */
+    setContext(context: Partial<SoundContext>): void;
+    /** Follow a replay's controller: the cues of its events as they go by while it plays, quiet while it is paused, the level under `auto` from its game. Returns a function that stops it. */
+    follow(controller: ReplayController, game?: SoundFollow): () => void;
+    /** A live event, pushed as it happens: its cues play now. A goal lifts the level under `auto` for a few seconds. */
+    cue(event: Pick<ReplayEvent, "kind" | "team">): void;
+    /** The live game's state for the level under `auto`, or `undefined` for none. */
+    game(moment: GameMoment | undefined): void;
+    state(): SoundState;
+    /** Stop and take everything away. */
+    destroy(): void;
+}
+/** How long the sound is held on after a game's clock stopped on a cue (its end), in seconds. */
+export declare const SOUND_TAIL = 5;
+/**
+ * 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 declare function createKyogijoSound(settings: SoundSettings): KyogijoSound;