Skip to content

Player: voice handle, cooldown, voice cap, seamless loops, mute - #26

Merged
maximilianfeix merged 2 commits into
mainfrom
player-guard-loops
Nov 15, 2026
Merged

maximilianfeix merged 2 commits into
mainfrom
player-guard-loops

Conversation

@maximilianfeix

@maximilianfeix maximilianfeix commented Nov 15, 2026 •

Copy link
Copy Markdown
Owner

A protective player and runtime loops: the two things the UI-sound libraries with traction have (cooldown, voice cap) and no game SFX library has (loops you start and stop at runtime).

API

const v = play("coin");                      // a voice, or undefined when skipped
v?.stop(0.2);                                // fade out (default 10 ms, no click)
v?.rate(1.5);                                // glide the playback rate
v?.node;                                     // the AudioBufferSourceNode

play("coin", { cooldown: 0.03 });            // default: same sound within 30 ms is skipped
play("explosion", { voices: 2 });            // default 4 copies at once, oldest stopped with a fade
const engine = play("engine-idle");          // loop sounds loop until stop()
play("coin", { loop: true });                // any sound can loop
muted(true); muted();                        // mute, keeps the volume; not stored
  • Backwards compatible: code that called .stop() on the old return value still works.
  • Cooldown compares start times, so play(s, { delay: i * 0.1 }) sequences still play. Loops are exempt.
  • SSR: unchanged; everything is a no-op without AudioContext.
  • muted() is not persisted (the README has the localStorage one-liner).

Loops

loop: true on a Sound makes the renderer cut the last 0.5 s and crossfade 0.25 s of it into the start, so the last sample runs into the first. Four new sounds: rain-loop, wind-loop (nature), engine-idle, force-field (world), 3.0 s each. The names don't collide with the one-shot sounds that are being added in parallel.

Checked in sounds.test.ts for every take at 44.1 and 48 kHz: the step at the wrap is below the sound's own 99.9th-percentile sample step (measured: 0.01-0.65 of it), and the 50 ms RMS across the wrap stays within 3 dB of the median. Tonal loops use vary: 0 and whole-number frequencies, so the crossfade stays in phase.

Size

The player is now 3.12 kB gzip in CI and 3.08 kB locally (was 2.92 / 2.9 kB; CI's gzip comes out about 30 bytes bigger). I got some of that back by packing the WAV header as 32-bit words, building the filters in a loop and merging the caches, but it still doesn't fit in 3 kB. The size-limit is now 3.15 kB for the player and for player + one sound (3.08 kB in CI), and 16 kB for everything (15.69 kB in CI). The docs say 3.1 kB and 15.7 kB. Every size mention is updated: READMEs, package.json, gallery lede + e2e regex, skill, brand text. The sound count is now 184.

plinkfx check (after merging #25)

audit() takes a loop flag, and the CLI and MCP check pass sound.loop. Loops skip the edge, tail and silence checks (a loop is meant to start and end at full level). Instead a new loop-click check fails a loop when the wrap jumps more than the sound's 99.9th-percentile step. plinkfx check --all: 184 checked, 0 failed. The new check is documented in reference.md.

Tests

  • tests/play.test.ts (new, fake AudioContext): handle, stop fade, rate, delay, cooldown, voices, loops, stopAll, mute.
  • cli.test.ts: loop-click passes a whole-cycle tone and fails one cut mid-cycle; check rain-loop engine-idle exits 0.
  • e2e: a loop tile starts on click and stops on the next click.
  • npm run check and npx playwright test pass locally.

Gallery: loop sounds toggle on click; hover, arrow keys and the tour don't start them.

play() now returns a voice { stop(fade?), rate(r), node } instead of the bare
source node (stop() keeps working). Per-sound guards: cooldown (default 30 ms,
compared by start time so delay-spread plays still happen) and voices (default
4, oldest stopped with a fade). loop option; loop: true on a Sound renders a
seamless loop (tail crossfaded into the head) and play() loops it by default.
muted(on?) keeps the volume for unmute; not stored (README one-liner).

Four loop sounds: rain-loop, wind-loop (nature), engine-idle, force-field
(world). sounds.test checks every take at 44.1/48 kHz for a click-free wrap and
an even level; play.test covers the player with a fake AudioContext.

Gallery: loop sounds toggle on click. Player 3.08 kB gzip (limit 3.1 kB,
was 2.9); sizes and counts updated in READMEs, skill, gallery, brand.
# Conflicts:
#	CHANGELOG.md
#	skills/plinkfx/SKILL.md
@maximilianfeix
maximilianfeix merged commit 97117f9 into main Nov 15, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant