@zkmake/sound-scape 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zubin Khavarian
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,218 @@
+# @zkmake/sound-scape
+
+Soundscapes for web games: a looping **bed** (wind, room tone, traffic) with **emitters** above
+it, short samples that fire on random timers (birds, cups, a distant siren). A game without one
+goes silent between sound effects. This is the layer that fills that silence, and it stays out of
+the way of your music and effects.
+
+```sh
+bun add @zkmake/sound-scape   # or npm i / pnpm add
+```
+
+Live demo: [zkmake.github.io/sound-kit](https://zkmake.github.io/sound-kit/). Background:
+[Soundscapes for Web Games, part 1](https://zubin.dev/blog/web-game-soundscapes-1-concepts/) and
+[part 2](https://zubin.dev/blog/web-game-soundscapes-2-howler/).
+
+- **Never the same sample twice in a row.** Each emitter draws from a pool of 3–6 samples. Of
+  everything here, this does the most to stop a soundscape sounding like a tape loop.
+- **Tight random ranges.** Every fire gets its own volume, rate and pan. The defaults are
+  `[0.7, 1]`, `[0.95, 1.05]` and `[-0.4, 0.4]`; past about ±5% rate, a sample turns chipmunk.
+- **A voice cap.** A fire past `maxConcurrent` is dropped, not queued, so a cluster of fires never
+  muddies the mix or clips the master.
+- **Ducking that reaches every voice.** `bus.duck()` dips the bed and every emitter, including
+  ones already playing, by −12 dB over 120 ms, and brings them back over 450 ms. It lowers gain
+  instead of pausing, so loops keep their place.
+- **Fades everywhere.** Beds fade in and out. A voice is stopped when its fade lands, so no silent
+  voices are left alive.
+- **Swaps and tab changes.** `SoundscapePlayer` crossfades between scenes. It ignores a def with the
+  same content, and fades out while the tab is hidden.
+- **Safe teardown.** `dispose()` is safe to call twice and under React StrictMode. A timer queued
+  before a teardown does nothing, so no ghost bird sings in the next level.
+- **Two backends, one engine.** `./howler` sits on Howler; `./web-audio` has no dependencies. The
+  engine talks to either through four functions, so you can write your own.
+
+## Entry points
+
+| Import                          | What                                                     | Needs        |
+| ------------------------------- | -------------------------------------------------------- | ------------ |
+| `@zkmake/sound-scape`           | `Soundscape`, `SoundscapePlayer`, types. No DOM, no deps | nothing      |
+| `@zkmake/sound-scape/web-audio` | `createWebAudioBus`: the adapter on the Web Audio API    | nothing      |
+| `@zkmake/sound-scape/howler`    | `createHowlerBus`: the adapter on Howler                 | `howler` 2.2 |
+| `@zkmake/sound-scape/react`     | `useSoundscape`, `<SoundscapeRunner>`                    | `react` 18+  |
+
+Every entry imports under SSR. Nothing touches `window` or creates an `AudioContext` until it
+plays.
+
+## Vanilla
+
+```ts
+import { SoundscapePlayer, type SoundscapeDef } from "@zkmake/sound-scape";
+import { createWebAudioBus } from "@zkmake/sound-scape/web-audio";
+
+// name → sources, in order of preference: the first one the browser plays wins.
+const bus = createWebAudioBus({
+  room: ["audio/room.ogg", "audio/room.m4a"],
+  "cup-1": ["audio/cup-1.ogg", "audio/cup-1.m4a"],
+  "cup-2": ["audio/cup-2.ogg", "audio/cup-2.m4a"],
+  "cup-3": ["audio/cup-3.ogg", "audio/cup-3.m4a"],
+});
+
+const CAFE: SoundscapeDef = {
+  bed: { sample: "room", volume: 0.5 },
+  emitters: [{ name: "cups", samples: ["cup-1", "cup-2", "cup-3"], intervalMs: [1500, 5000] }],
+  maxConcurrent: 4,
+};
+
+await bus.load({ onProgress: (settled, total) => bar(settled / total) });
+
+const player = new SoundscapePlayer(bus, { crossfadeMs: 1500 });
+
+player.play(CAFE); // from a click or key press: browsers start audio suspended
+player.play(STREET); // crossfades
+player.play(null); // fades out
+
+const release = bus.duck(); // a voice line starts
+release(); // …and ends
+```
+
+For full control, use `Soundscape` directly: `new Soundscape(def, bus)`, then `start()`,
+`stop()` and `dispose()`. Both expose `fire(name)`, `suppressEmitters(on)` and `setBedGain(gain)`
+(the player through `player.current`).
+
+## React and React Three Fiber
+
+```tsx
+import { useSoundscape } from "@zkmake/sound-scape/react";
+
+function Ambience({ scene, paused }: { scene: SceneId; paused: boolean }) {
+  useSoundscape(bus, SCENES[scene], { active: !paused, crossfadeMs: 1500 });
+
+  return null;
+}
+```
+
+- **Placement:** keep the hook outside `<Canvas>`. Audio is a side effect of the scene, not part
+  of the render loop.
+- **Inline defs:** a def is compared by content, so an inline object literal doesn't restart the
+  bed on every render.
+- **Unmounting** fades the soundscape out.
+- **The bus:** make it once, at module scope or in a ref. A new bus starts a new player.
+- **The return value** is the player, for `player.current?.fire("cups")`.
+- **JSX alternative:** `<SoundscapeRunner bus={bus} def={def} active={!paused} />` does the same.
+
+## Definitions
+
+`SoundscapeDef` is plain data, and it is all you tune: you can adjust a scene's feel without
+touching engine code.
+
+| Field                   | Default        | Meaning                                                          |
+| ----------------------- | -------------- | ---------------------------------------------------------------- |
+| `bed.sample`            |                | The looping layer. Non-positional; set `bed` to `null` for none. |
+| `bed.volume`            |                | Before the bus level and duck.                                   |
+| `bed.fadeInMs`          | 500            | A bed that starts at full volume is heard as a seam.             |
+| `bed.fadeOutMs`         | 700            |                                                                  |
+| `emitters[].samples`    |                | The pool. 3–6 is plenty.                                         |
+| `emitters[].intervalMs` |                | `[min, max]` wait between fires. The first fire comes sooner.    |
+| `emitters[].volume`     | `[0.7, 1]`     |                                                                  |
+| `emitters[].rate`       | `[0.95, 1.05]` | Playback rate, which also shifts pitch.                          |
+| `emitters[].pan`        | `[-0.4, 0.4]`  | Stereo, −1..1.                                                   |
+| `emitters[].name`       | its index      | For `fire(name)` and `onEmitter`.                                |
+| `maxConcurrent`         | 4              | Emitter voices at once, across the soundscape.                   |
+
+Options for `Soundscape` and `SoundscapePlayer`:
+
+- `random`: pass `seededRandom(n)` to make a soundscape play the same way each time.
+- `timers`: inject these to drive time in tests.
+- `onEmitter({ emitter, sample, phase })`: for captions, debug panels or tests.
+- Player only:
+  - `crossfadeMs`: default 1000.
+  - `whenHidden`: `"stop"` (the default) or `"play"`.
+
+Calls:
+
+- `suppressEmitters(true)` fades out the emitters that are playing and holds back new fires while
+  dialog is on screen, because one-shots compete with screen readers even when ducked. The timers
+  keep running, and `suppressEmitters(false)` lets fires through again.
+- `fire(name)` fires one emitter now, still within the cap, for debug buttons.
+
+## The adapters
+
+Both return a `SoundscapeAdapter`. It has the engine's four functions plus `load`, `duck`,
+`ducked`, `setLevel`, `setMuted`, `stopAll`, `voices` and `dispose`. Use one bus as your ambience
+bus, shared by every soundscape, so its duck and level carry across a scene swap.
+
+| Option          | Web Audio             | Howler    | Meaning                                                                                     |
+| --------------- | --------------------- | --------- | ------------------------------------------------------------------------------------------- |
+| `level`         | 1 (above 1 allowed)   | 1 (max 1) | Bus level, for a settings slider. `setLevel(v, fadeMs)` moves it live.                      |
+| `muted`         | false                 | false     | Mutes in place: beds keep their phase, and emitters don't fire.                             |
+| `duck`          | −12 dB, 120 / 450 ms  | same      | Defaults for `duck()`. Ducks count, and the deepest held one wins.                          |
+| `context`       | made on first use     |           | Share your game's `AudioContext`. One the adapter made is closed on `dispose`.              |
+| `destination`   | `context.destination` |           | Route the bus into your own mixer node.                                                     |
+| `autoUnlock`    | true                  |           | Resumes the context on the first pointer or key press, and again after an iOS interruption. |
+| `html5`         |                       | false     | Streams through `<audio>`, with no per-voice pan or rate.                                   |
+| `loadTimeoutMs` |                       | 10000     | A sample still loading after this long counts as settled.                                   |
+
+Behaviour when a sample is missing or still loading:
+
+- `load()` never rejects. A sample that fails logs one warning and stays silent; its fires are
+  skipped.
+- A bed may start before its sample loads, and fades in when it arrives.
+- An emitter whose sample isn't loaded yet is skipped, because a late bird is worse than none.
+
+### Writing your own
+
+The engine only ever calls these four functions:
+
+```ts
+type SoundscapeBus<Id> = {
+  playBed(sample, { volume, fadeInMs }): Id | null;
+  playEmitter(sample, { volume, rate, pan, onEnd }): Id | null;
+  stop(id, fadeOutMs): void; // forget the id synchronously, then fade and stop
+  setVolume(id, volume, fadeMs): void;
+};
+```
+
+The contract:
+
+- `stop` must forget the id at once, so a fade in flight survives a dispose that follows.
+- `onEnd` is called once, when a voice ends by itself. It needn't be called for a voice the engine
+  stopped.
+- Return `null` when a voice can't play. The engine skips that fire and counts nothing.
+
+## Formats and iOS
+
+Give each sample two sources: `[ogg, m4a]`. Opus in Ogg is small and decodes in Chrome, Firefox
+and recent Safari. AAC in M4A is the fallback that every Safari version decodes. The Web Audio
+adapter skips any source that `canPlayType` rejects, and tries the next source if decoding fails.
+Howler does the same with its `src` list.
+
+For beds, prefer Ogg. AAC encoders add a few milliseconds of padding at the start, which can
+leave a gap at a loop seam. If a bed has to be AAC, listen to it on an iPhone.
+
+On iOS, audio starts on a gesture: call `play` from a tap, or rely on `autoUnlock`. After a phone
+call or Siri, Safari reports the context as `"interrupted"`, and the next tap resumes it. Targets:
+iOS 17 and later, and current desktop browsers.
+
+## Shipping it
+
+- **Settings:** connect your sliders to `setLevel` and your mute switch to `setMuted`. Both apply
+  live to voices already playing.
+- **Narration:** duck while a voice line plays, and call `suppressEmitters(true)` while dialog is
+  on screen.
+- **Size:** the core is about 3.5 kB gzipped. The Web Audio adapter adds 2.7 kB and the Howler
+  adapter 1.7 kB (Howler itself is about 7 kB more).
+
+## Origin
+
+The engine is extracted from four copies of the same idea:
+
+- keyboard-express
+- platform-typing
+- finlit-careers
+- virtual-room-three
+
+Their tests came with it.
+
+## License
+
+MIT

package/dist/adapter-D8cYn0vs.d.ts

@@ -0,0 +1,43 @@
+import { a as SoundscapeBus } from "./types-BML2s2Se.js";
+//#region src/core/adapter.d.ts
+/** The source of a sample: a URL, or URLs in order of preference (`[opus, m4a]`). The first one the browser plays wins. */
+type SampleSource = string | readonly string[];
+type DuckOptions = {
+  /** How far the bus dips, in dB. Default −12. */
+  db?: number;
+  /** Default 120. */
+  attackMs?: number;
+  /** Default 450. */
+  releaseMs?: number;
+};
+type LoadOptions = {
+  /** Called as each sample settles, loaded or not, so a loading bar never stalls on a bad file. */
+  onProgress?: (settled: number, total: number) => void;
+};
+/**
+ * What both shipped adapters give the game on top of the engine's four functions: loading,
+ * ducking, a level, mute and teardown. The bus is the ambience bus; share one between soundscapes
+ * and its duck and level carry across a swap.
+ */
+type SoundscapeAdapter<Id = unknown> = SoundscapeBus<Id> & {
+  /** Fetch and decode every sample. Never rejects: a sample that fails logs once and stays silent. */
+  load(opts?: LoadOptions): Promise<void>;
+  /**
+   * Dip every voice on the bus, ones already playing included, and return the release. Ducks
+   * count: the bus comes back up when the last one is released.
+   */
+  duck(opts?: DuckOptions): () => void;
+  readonly ducked: boolean;
+  /** The bus level, 0..1 (the Web Audio adapter allows more), for a settings slider. */
+  setLevel(level: number, fadeMs?: number): void;
+  /** Mute in place: beds keep their phase and come back without a click; emitters don't fire while muted. */
+  setMuted(muted: boolean): void;
+  /** Stop every voice on the bus. */
+  stopAll(fadeOutMs?: number): void;
+  /** Voices playing now: beds and emitters. */
+  readonly voices: number;
+  dispose(): void;
+};
+//#endregion
+export { SoundscapeAdapter as i, LoadOptions as n, SampleSource as r, DuckOptions as t };
+//# sourceMappingURL=adapter-D8cYn0vs.d.ts.map

package/dist/adapter-DHuOy8V8.js

@@ -0,0 +1,58 @@
+//#region src/core/adapter.ts
+const DEFAULT_DUCK = {
+	db: -12,
+	attackMs: 120,
+	releaseMs: 450
+};
+const dbToGain = (db) => 10 ** (db / 20);
+const sources = (source) => typeof source === "string" ? [source] : source;
+/**
+* Ref-counted ducking: `duck()` returns a release that works once. The deepest duck held wins;
+* releasing it eases back to the next deepest, or to full. `apply(gain, ms)` moves the adapter's
+* duck multiplier.
+*/
+const createDucker = (defaults, apply) => {
+	const held = /* @__PURE__ */ new Map();
+	let current = 1;
+	const update = (fadeMs) => {
+		const target = Math.min(1, ...held.values());
+		if (target !== current) {
+			current = target;
+			apply(target, fadeMs);
+		}
+	};
+	return {
+		duck(opts = {}) {
+			const db = opts.db ?? defaults?.db ?? DEFAULT_DUCK.db;
+			const attackMs = opts.attackMs ?? defaults?.attackMs ?? DEFAULT_DUCK.attackMs;
+			const releaseMs = opts.releaseMs ?? defaults?.releaseMs ?? DEFAULT_DUCK.releaseMs;
+			const token = Symbol("duck");
+			held.set(token, dbToGain(db));
+			update(attackMs);
+			return () => {
+				if (held.delete(token)) update(releaseMs);
+			};
+		},
+		get ducked() {
+			return held.size > 0;
+		},
+		clear() {
+			held.clear();
+			current = 1;
+		}
+	};
+};
+/** Warn once per sample: a missing file shouldn't flood the console every fire. */
+const createWarnOnce = (label) => {
+	const warned = /* @__PURE__ */ new Set();
+	return (sample, message) => {
+		if (!warned.has(sample)) {
+			warned.add(sample);
+			console.warn(`[${label}] ${sample}: ${message}`);
+		}
+	};
+};
+//#endregion
+export { createWarnOnce as n, sources as r, createDucker as t };
+
+//# sourceMappingURL=adapter-DHuOy8V8.js.map

package/dist/adapter-DHuOy8V8.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-DHuOy8V8.js","names":[],"sources":["../src/core/adapter.ts"],"sourcesContent":["import { type SoundscapeBus } from \"./types.ts\";\n\n/** The source of a sample: a URL, or URLs in order of preference (`[opus, m4a]`). The first one the browser plays wins. */\ntype SampleSource = string | readonly string[];\n\ntype DuckOptions = {\n  /** How far the bus dips, in dB. Default −12. */\n  db?: number;\n  /** Default 120. */\n  attackMs?: number;\n  /** Default 450. */\n  releaseMs?: number;\n};\n\ntype LoadOptions = {\n  /** Called as each sample settles, loaded or not, so a loading bar never stalls on a bad file. */\n  onProgress?: (settled: number, total: number) => void;\n};\n\n/**\n * What both shipped adapters give the game on top of the engine's four functions: loading,\n * ducking, a level, mute and teardown. The bus is the ambience bus; share one between soundscapes\n * and its duck and level carry across a swap.\n */\ntype SoundscapeAdapter<Id = unknown> = SoundscapeBus<Id> & {\n  /** Fetch and decode every sample. Never rejects: a sample that fails logs once and stays silent. */\n  load(opts?: LoadOptions): Promise<void>;\n  /**\n   * Dip every voice on the bus, ones already playing included, and return the release. Ducks\n   * count: the bus comes back up when the last one is released.\n   */\n  duck(opts?: DuckOptions): () => void;\n  readonly ducked: boolean;\n  /** The bus level, 0..1 (the Web Audio adapter allows more), for a settings slider. */\n  setLevel(level: number, fadeMs?: number): void;\n  /** Mute in place: beds keep their phase and come back without a click; emitters don't fire while muted. */\n  setMuted(muted: boolean): void;\n  /** Stop every voice on the bus. */\n  stopAll(fadeOutMs?: number): void;\n  /** Voices playing now: beds and emitters. */\n  readonly voices: number;\n  dispose(): void;\n};\n\nconst DEFAULT_DUCK = { db: -12, attackMs: 120, releaseMs: 450 } as const;\n\nconst dbToGain = (db: number) => 10 ** (db / 20);\n\nconst sources = (source: SampleSource): readonly string[] =>\n  typeof source === \"string\" ? [source] : source;\n\n/**\n * Ref-counted ducking: `duck()` returns a release that works once. The deepest duck held wins;\n * releasing it eases back to the next deepest, or to full. `apply(gain, ms)` moves the adapter's\n * duck multiplier.\n */\nconst createDucker = (\n  defaults: DuckOptions | undefined,\n  apply: (gain: number, fadeMs: number) => void,\n) => {\n  const held = new Map<symbol, number>();\n  let current = 1;\n\n  const update = (fadeMs: number) => {\n    const target = Math.min(1, ...held.values());\n\n    if (target !== current) {\n      current = target;\n      apply(target, fadeMs);\n    }\n  };\n\n  return {\n    duck(opts: DuckOptions = {}) {\n      const db = opts.db ?? defaults?.db ?? DEFAULT_DUCK.db;\n      const attackMs = opts.attackMs ?? defaults?.attackMs ?? DEFAULT_DUCK.attackMs;\n      const releaseMs = opts.releaseMs ?? defaults?.releaseMs ?? DEFAULT_DUCK.releaseMs;\n      const token = Symbol(\"duck\");\n\n      held.set(token, dbToGain(db));\n      update(attackMs);\n\n      return () => {\n        if (held.delete(token)) {\n          update(releaseMs);\n        }\n      };\n    },\n    get ducked() {\n      return held.size > 0;\n    },\n    clear() {\n      held.clear();\n      current = 1;\n    },\n  };\n};\n\n/** Warn once per sample: a missing file shouldn't flood the console every fire. */\nconst createWarnOnce = (label: string) => {\n  const warned = new Set<string>();\n\n  return (sample: string, message: string) => {\n    if (!warned.has(sample)) {\n      warned.add(sample);\n      // oxlint-disable-next-line no-console\n      console.warn(`[${label}] ${sample}: ${message}`);\n    }\n  };\n};\n\nexport { createDucker, createWarnOnce, dbToGain, DEFAULT_DUCK, sources };\nexport type { DuckOptions, LoadOptions, SampleSource, SoundscapeAdapter };\n"],"mappings":";AA4CA,MAAM,eAAe;CAAE,IAAI;CAAK,UAAU;CAAK,WAAW;AAAI;AAE9D,MAAM,YAAY,OAAe,OAAO,KAAK;AAE7C,MAAM,WAAW,WACf,OAAO,WAAW,WAAW,CAAC,MAAM,IAAI;;;;;;AAO1C,MAAM,gBACJ,UACA,UACG;CACH,MAAM,uBAAO,IAAI,IAAoB;CACrC,IAAI,UAAU;CAEd,MAAM,UAAU,WAAmB;EACjC,MAAM,SAAS,KAAK,IAAI,GAAG,GAAG,KAAK,OAAO,CAAC;EAE3C,IAAI,WAAW,SAAS;GACtB,UAAU;GACV,MAAM,QAAQ,MAAM;EACtB;CACF;CAEA,OAAO;EACL,KAAK,OAAoB,CAAC,GAAG;GAC3B,MAAM,KAAK,KAAK,MAAM,UAAU,MAAM,aAAa;GACnD,MAAM,WAAW,KAAK,YAAY,UAAU,YAAY,aAAa;GACrE,MAAM,YAAY,KAAK,aAAa,UAAU,aAAa,aAAa;GACxE,MAAM,QAAQ,OAAO,MAAM;GAE3B,KAAK,IAAI,OAAO,SAAS,EAAE,CAAC;GAC5B,OAAO,QAAQ;GAEf,aAAa;IACX,IAAI,KAAK,OAAO,KAAK,GACnB,OAAO,SAAS;GAEpB;EACF;EACA,IAAI,SAAS;GACX,OAAO,KAAK,OAAO;EACrB;EACA,QAAQ;GACN,KAAK,MAAM;GACX,UAAU;EACZ;CACF;AACF;;AAGA,MAAM,kBAAkB,UAAkB;CACxC,MAAM,yBAAS,IAAI,IAAY;CAE/B,QAAQ,QAAgB,YAAoB;EAC1C,IAAI,CAAC,OAAO,IAAI,MAAM,GAAG;GACvB,OAAO,IAAI,MAAM;GAEjB,QAAQ,KAAK,IAAI,MAAM,IAAI,OAAO,IAAI,SAAS;EACjD;CACF;AACF"}

package/dist/howler.d.ts

@@ -0,0 +1,17 @@
+import { i as SoundscapeAdapter, n as LoadOptions, r as SampleSource, t as DuckOptions } from "./adapter-D8cYn0vs.js";
+//#region src/howler/index.d.ts
+type HowlerBusOptions = {
+  /** Bus level, 0..1. Default 1. */
+  level?: number;
+  muted?: boolean;
+  /** Defaults for `duck()`. */
+  duck?: DuckOptions;
+  /** Stream through `<audio>` instead of decoding. No pan or rate per voice then. Default false. */
+  html5?: boolean;
+  /** A sample still loading after this long counts as settled for `load`. Default 10000. */
+  loadTimeoutMs?: number;
+};
+declare const createHowlerBus: <Sample extends string>(samples: Record<Sample, SampleSource>, opts?: HowlerBusOptions) => SoundscapeAdapter<number>;
+//#endregion
+export { type DuckOptions, type HowlerBusOptions, type LoadOptions, type SampleSource, type SoundscapeAdapter, createHowlerBus };
+//# sourceMappingURL=howler.d.ts.map

package/dist/howler.js

@@ -0,0 +1,167 @@
+import { n as createWarnOnce, r as sources, t as createDucker } from "./adapter-DHuOy8V8.js";
+import { Howl } from "howler";
+//#region src/howler/index.ts
+/**
+* @zkmake/sound-scape/howler: a `SoundscapeAdapter` over Howler 2 (peer dependency). One Howl per
+* sample, made once and replayed; every voice keeps its own base volume so a duck or a level change
+* reaches beds and emitters already playing. Howler clamps volume to 0..1, so loud beds stay at 1.
+*/
+const createHowlerBus = (samples, opts = {}) => {
+	const howls = /* @__PURE__ */ new Map();
+	const voices = /* @__PURE__ */ new Map();
+	let nextId = 1;
+	const warn = createWarnOnce("sound-scape/howler");
+	let level = opts.level ?? 1;
+	let muted = opts.muted ?? false;
+	let duckGain = 1;
+	const howlFor = (sample) => {
+		const known = howls.get(sample);
+		if (known) return known;
+		const source = samples[sample];
+		if (source === void 0) {
+			warn(sample, "not in the sample map; the fire is skipped");
+			return null;
+		}
+		const howl = new Howl({
+			src: [...sources(source)],
+			html5: opts.html5 ?? false
+		});
+		howl.once("loaderror", (_id, error) => {
+			warn(sample, `failed to load (${String(error)}); it stays silent`);
+		});
+		howls.set(sample, howl);
+		return howl;
+	};
+	const effective = (base) => Math.min(1, Math.max(0, base * level * duckGain));
+	const fadeTo = ({ howl, sound, base }, fadeMs) => {
+		const target = effective(base);
+		if (fadeMs <= 0) howl.volume(target, sound);
+		else howl.fade(howl.volume(sound), target, fadeMs, sound);
+	};
+	const rescale = (fadeMs) => {
+		for (const voice of voices.values()) fadeTo(voice, fadeMs);
+	};
+	const ducker = createDucker(opts.duck, (gain, fadeMs) => {
+		duckGain = gain;
+		rescale(fadeMs);
+	});
+	const stop = (id, fadeOutMs) => {
+		const voice = voices.get(id);
+		if (!voice) return;
+		voices.delete(id);
+		const { howl, sound } = voice;
+		howl.off("end", void 0, sound);
+		if (fadeOutMs <= 0) {
+			howl.stop(sound);
+			return;
+		}
+		howl.once("fade", () => howl.stop(sound), sound);
+		howl.fade(howl.volume(sound), 0, fadeOutMs, sound);
+	};
+	return {
+		playBed(sample, { volume, fadeInMs }) {
+			const howl = howlFor(sample);
+			if (!howl) return null;
+			const sound = howl.play();
+			const id = nextId++;
+			const voice = {
+				howl,
+				sound,
+				base: volume
+			};
+			howl.loop(true, sound);
+			howl.mute(muted, sound);
+			howl.volume(0, sound);
+			voices.set(id, voice);
+			fadeTo(voice, fadeInMs);
+			return id;
+		},
+		playEmitter(sample, { volume, rate, pan, onEnd }) {
+			if (muted) return null;
+			const howl = howlFor(sample);
+			if (!howl || howl.state() === "unloaded") return null;
+			const sound = howl.play();
+			const id = nextId++;
+			const voice = {
+				howl,
+				sound,
+				base: volume
+			};
+			howl.loop(false, sound);
+			howl.volume(effective(volume), sound);
+			howl.rate(rate, sound);
+			if (!opts.html5) howl.stereo(pan, sound);
+			voices.set(id, voice);
+			howl.once("end", () => {
+				if (voices.get(id) === voice) {
+					voices.delete(id);
+					onEnd();
+				}
+			}, sound);
+			return id;
+		},
+		stop,
+		setVolume(id, volume, fadeMs) {
+			const voice = voices.get(id);
+			if (voice) {
+				voice.base = volume;
+				fadeTo(voice, fadeMs);
+			}
+		},
+		load(loadOpts = {}) {
+			const names = Object.keys(samples);
+			let settled = 0;
+			return Promise.all(names.map((name) => new Promise((resolve) => {
+				const howl = howlFor(name);
+				let done = false;
+				const finish = () => {
+					if (!done) {
+						done = true;
+						settled += 1;
+						loadOpts.onProgress?.(settled, names.length);
+						resolve();
+					}
+				};
+				if (!howl || howl.state() === "loaded") {
+					finish();
+					return;
+				}
+				howl.once("load", finish);
+				howl.once("loaderror", finish);
+				globalThis.setTimeout(finish, opts.loadTimeoutMs ?? 1e4);
+			}))).then(() => void 0);
+		},
+		duck: ducker.duck,
+		get ducked() {
+			return ducker.ducked;
+		},
+		setLevel(next, fadeMs = 0) {
+			level = next;
+			rescale(fadeMs);
+		},
+		setMuted(next) {
+			muted = next;
+			for (const { howl, sound } of voices.values()) howl.mute(muted, sound);
+		},
+		stopAll(fadeOutMs = 0) {
+			for (const id of Array.from(voices.keys())) stop(id, fadeOutMs);
+		},
+		get voices() {
+			return voices.size;
+		},
+		dispose() {
+			for (const { howl, sound } of voices.values()) {
+				howl.off("end", void 0, sound);
+				howl.stop(sound);
+			}
+			voices.clear();
+			ducker.clear();
+			for (const howl of howls.values()) howl.unload();
+			howls.clear();
+		}
+	};
+};
+//#endregion
+export { createHowlerBus };
+
+//# sourceMappingURL=howler.js.map

package/dist/howler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"howler.js","names":[],"sources":["../src/howler/index.ts"],"sourcesContent":["/**\n * @zkmake/sound-scape/howler: a `SoundscapeAdapter` over Howler 2 (peer dependency). One Howl per\n * sample, made once and replayed; every voice keeps its own base volume so a duck or a level change\n * reaches beds and emitters already playing. Howler clamps volume to 0..1, so loud beds stay at 1.\n */\nimport { Howl } from \"howler\";\n\nimport {\n  createDucker,\n  createWarnOnce,\n  type DuckOptions,\n  type LoadOptions,\n  type SampleSource,\n  sources,\n  type SoundscapeAdapter,\n} from \"../core/adapter.ts\";\n\ntype HowlerBusOptions = {\n  /** Bus level, 0..1. Default 1. */\n  level?: number;\n  muted?: boolean;\n  /** Defaults for `duck()`. */\n  duck?: DuckOptions;\n  /** Stream through `<audio>` instead of decoding. No pan or rate per voice then. Default false. */\n  html5?: boolean;\n  /** A sample still loading after this long counts as settled for `load`. Default 10000. */\n  loadTimeoutMs?: number;\n};\n\n/** A voice: its Howl and Howler's id for it. The bus hands out its own ids, unique across Howls. */\ntype Voice = { howl: Howl; sound: number; base: number };\n\nconst createHowlerBus = <Sample extends string>(\n  samples: Record<Sample, SampleSource>,\n  opts: HowlerBusOptions = {},\n): SoundscapeAdapter<number> => {\n  const howls = new Map<string, Howl>();\n  const voices = new Map<number, Voice>();\n  let nextId = 1;\n  const warn = createWarnOnce(\"sound-scape/howler\");\n  let level = opts.level ?? 1;\n  let muted = opts.muted ?? false;\n  let duckGain = 1;\n\n  const howlFor = (sample: string) => {\n    const known = howls.get(sample);\n\n    if (known) {\n      return known;\n    }\n\n    const source = (samples as Record<string, SampleSource | undefined>)[sample];\n\n    if (source === undefined) {\n      warn(sample, \"not in the sample map; the fire is skipped\");\n\n      return null;\n    }\n\n    const howl = new Howl({ src: [...sources(source)], html5: opts.html5 ?? false });\n\n    howl.once(\"loaderror\", (_id, error) => {\n      warn(sample, `failed to load (${String(error)}); it stays silent`);\n    });\n    howls.set(sample, howl);\n\n    return howl;\n  };\n\n  const effective = (base: number) => Math.min(1, Math.max(0, base * level * duckGain));\n\n  const fadeTo = ({ howl, sound, base }: Voice, fadeMs: number) => {\n    const target = effective(base);\n\n    if (fadeMs <= 0) {\n      howl.volume(target, sound);\n    } else {\n      howl.fade(howl.volume(sound) as number, target, fadeMs, sound);\n    }\n  };\n\n  const rescale = (fadeMs: number) => {\n    for (const voice of voices.values()) {\n      fadeTo(voice, fadeMs);\n    }\n  };\n\n  const ducker = createDucker(opts.duck, (gain, fadeMs) => {\n    duckGain = gain;\n    rescale(fadeMs);\n  });\n\n  const stop = (id: number, fadeOutMs: number) => {\n    const voice = voices.get(id);\n\n    if (!voice) {\n      return;\n    }\n\n    // Forget it now: a dispose straight after must not cut this fade short.\n    voices.delete(id);\n\n    const { howl, sound } = voice;\n\n    howl.off(\"end\", undefined, sound);\n\n    if (fadeOutMs <= 0) {\n      howl.stop(sound);\n\n      return;\n    }\n\n    // Stop when the fade lands, or Howler keeps a silent voice alive.\n    howl.once(\"fade\", () => howl.stop(sound), sound);\n    howl.fade(howl.volume(sound) as number, 0, fadeOutMs, sound);\n  };\n\n  return {\n    playBed(sample, { volume, fadeInMs }) {\n      const howl = howlFor(sample);\n\n      if (!howl) {\n        return null;\n      }\n\n      const sound = howl.play();\n      const id = nextId++;\n      const voice: Voice = { howl, sound, base: volume };\n\n      howl.loop(true, sound);\n      howl.mute(muted, sound);\n      howl.volume(0, sound);\n      voices.set(id, voice);\n      fadeTo(voice, fadeInMs);\n\n      return id;\n    },\n\n    playEmitter(sample, { volume, rate, pan, onEnd }) {\n      if (muted) {\n        return null;\n      }\n\n      const howl = howlFor(sample);\n\n      if (!howl || howl.state() === \"unloaded\") {\n        return null;\n      }\n\n      const sound = howl.play();\n      const id = nextId++;\n      const voice: Voice = { howl, sound, base: volume };\n\n      howl.loop(false, sound);\n      howl.volume(effective(volume), sound);\n      howl.rate(rate, sound);\n\n      if (!opts.html5) {\n        howl.stereo(pan, sound);\n      }\n\n      voices.set(id, voice);\n      howl.once(\n        \"end\",\n        () => {\n          if (voices.get(id) === voice) {\n            voices.delete(id);\n            onEnd();\n          }\n        },\n        sound,\n      );\n\n      return id;\n    },\n\n    stop,\n\n    setVolume(id, volume, fadeMs) {\n      const voice = voices.get(id);\n\n      if (voice) {\n        voice.base = volume;\n        fadeTo(voice, fadeMs);\n      }\n    },\n\n    load(loadOpts: LoadOptions = {}) {\n      const names = Object.keys(samples);\n      let settled = 0;\n\n      return Promise.all(\n        names.map(\n          (name) =>\n            new Promise<void>((resolve) => {\n              const howl = howlFor(name);\n              let done = false;\n              const finish = () => {\n                if (!done) {\n                  done = true;\n                  settled += 1;\n                  loadOpts.onProgress?.(settled, names.length);\n                  resolve();\n                }\n              };\n\n              if (!howl || howl.state() === \"loaded\") {\n                finish();\n\n                return;\n              }\n\n              howl.once(\"load\", finish);\n              howl.once(\"loaderror\", finish);\n              globalThis.setTimeout(finish, opts.loadTimeoutMs ?? 10_000);\n            }),\n        ),\n      ).then(() => undefined);\n    },\n\n    duck: ducker.duck,\n\n    get ducked() {\n      return ducker.ducked;\n    },\n\n    setLevel(next, fadeMs = 0) {\n      level = next;\n      rescale(fadeMs);\n    },\n\n    setMuted(next) {\n      muted = next;\n\n      for (const { howl, sound } of voices.values()) {\n        howl.mute(muted, sound);\n      }\n    },\n\n    stopAll(fadeOutMs = 0) {\n      for (const id of Array.from(voices.keys())) {\n        stop(id, fadeOutMs);\n      }\n    },\n\n    get voices() {\n      return voices.size;\n    },\n\n    dispose() {\n      for (const { howl, sound } of voices.values()) {\n        howl.off(\"end\", undefined, sound);\n        howl.stop(sound);\n      }\n\n      voices.clear();\n      ducker.clear();\n\n      for (const howl of howls.values()) {\n        howl.unload();\n      }\n\n      howls.clear();\n    },\n  };\n};\n\nexport { createHowlerBus };\nexport type { HowlerBusOptions };\nexport type { DuckOptions, LoadOptions, SampleSource, SoundscapeAdapter } from \"../core/adapter.ts\";\n"],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+import { a as SoundscapeBus, c as Timers, i as Range, n as EmitterDef, o as SoundscapeDef, r as EmitterPhase, s as SoundscapeOptions, t as BedDef } from "./types-BML2s2Se.js";
+import { n as SoundscapePlayerOptions, r as Soundscape, t as SoundscapePlayer } from "./player-CepoDB_J.js";
+//#region src/core/random.d.ts
+/**
+ * One of `pool` at random, never `last` when there is a choice. With one sample it repeats; with
+ * two it alternates; with three or more the ear stops hearing a pattern.
+ */
+declare const pickNotLast: <T>(pool: readonly T[], last: T | null, random: () => number) => T | undefined;
+/**
+ * A small seeded generator (mulberry32) in `Math.random`'s shape: the same seed plays the same
+ * soundscape, for tests and for demos you want to reproduce.
+ */
+declare const seededRandom: (seed: number) => () => number;
+//#endregion
+export { type BedDef, type EmitterDef, type EmitterPhase, type Range, Soundscape, type SoundscapeBus, type SoundscapeDef, type SoundscapeOptions, SoundscapePlayer, type SoundscapePlayerOptions, type Timers, pickNotLast, seededRandom };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,2 @@
+import { i as seededRandom, n as Soundscape, r as pickNotLast, t as SoundscapePlayer } from "./player-BlQ9UyoK.js";
+export { Soundscape, SoundscapePlayer, pickNotLast, seededRandom };