Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 15 additions & 3 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,20 @@

## Unreleased

**A protective player, and loops.**

**274 sounds in 21 categories** (was 180 in 15), **a protective player, and loops.**

- New categories: **cards & casino** (card-flip, card-deal, card-place, card-shuffle, chip-stack, dice-roll, slot-spin,
slot-stop, jackpot), **vehicles** (engine-start, engine-rev, tire-screech, car-crash, car-horn, boost, race-light),
**horror** (jumpscare, dread-drone, whisper, horror-sting, chains-rattle, static-burst, music-box), **farm & crafting**
(axe-chop, tree-fall, pickaxe-mine, dig, plant-seed, watering-can, harvest, fishing-cast, fish-bite), **sci-fi & tech**
(computer-beep, scan, access-granted, access-denied, door-slide, robot-chatter, shutdown, glitch) and **puzzle** (swap,
match, combo-chain, line-clear, piece-lock, merge).
- 44 more in existing categories: melee (kick, stab, sword-clash, sword-draw, body-fall), destructibles (crate-break,
pot-break, metal-clang, rock-crumble, ignite), guns (machine-gun, shell-casing, flamethrower, grenade-launch), app UI
(drag-start, drop, success, maximize, minimize, question, message-send, trash, page-turn), RPG items (potion-drink, eat,
loot-rare, equip), weather and water (thunder-crack, ocean-wave, rain-burst, dive-splash), animals (zombie-groan, roar,
dog-bark, cat-meow), quiz (buzzer-wrong, ding-correct, timer-done), highscore, boss-intro, slide, fall-whistle,
step-carpet, step-mud.
- `play()` returns a voice: `stop(fade?)` fades out (10 ms by default, so no click), `rate(r)` glides the
playback rate, `node` is the `AudioBufferSourceNode`. Code that called `.stop()` on the old return value
keeps working. Still `undefined` when a sound is skipped.
Expand All @@ -16,7 +28,7 @@
- `muted(on?)`: mute everything and keep the volume. Not stored; the README has the `localStorage` one-liner.
- `stopAll()` fades in 10 ms instead of cutting.
- Gallery: loop sounds start on click and stop on the next click; hover and arrow keys don't start them.
- Player: 3.1 kB gzip (was 2.9), everything 15.7 kB. 184 sounds.
- Player: 3.1 kB gzip (was 2.9), everything 23.0 kB with all 274 sounds.

- CLI: `plinkfx mcp`, an MCP server on stdio with five tools: `list_sounds`, `show_sound`, `render_sound`,
`measure_sound` and `check_sound`. No dependencies, no network.
Expand Down
30 changes: 16 additions & 14 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,13 @@
<img alt="plinkfx: game sound effects as code" src="https://cdn.jsdelivr.net/gh/maximilianfeix/plinkfx@main/brand/banners/readme-light.svg" width="100%">
</picture>

**<!-- count -->184<!-- /count --> game sound effects, written as code.** Coins, jumps, hits, lasers, explosions,
**<!-- count -->274<!-- /count --> game sound effects, written as code.** Coins, jumps, hits, lasers, explosions,
UI clicks and the rest of what a game needs, each one a few readable numbers that a 3.1 kB player turns into sound.
CC0, no audio files, no account.

<a href="https://maximilianfeix.github.io/plinkfx/"><img src="https://cdn.jsdelivr.net/gh/maximilianfeix/plinkfx@main/docs/media/gallery.gif" alt="The plinkfx gallery: clicking tiles plays coin, jump, laser, explosion and more; each tile shows its waveform" width="100%"></a>

**[▶ Hear all <!-- count -->184<!-- /count --> in your browser](https://maximilianfeix.github.io/plinkfx/)** (one click per sound, tweak any of them and share the link) · [play the 30-second demo game](https://maximilianfeix.github.io/plinkfx/game.html) · [watch the 30 s video with sound](https://github.com/maximilianfeix/plinkfx/blob/main/docs/media/hero-16x9.mp4)
**[▶ Hear all <!-- count -->274<!-- /count --> in your browser](https://maximilianfeix.github.io/plinkfx/)** (one click per sound, tweak any of them and share the link) · [play the 30-second demo game](https://maximilianfeix.github.io/plinkfx/game.html) · [watch the 30 s video with sound](https://github.com/maximilianfeix/plinkfx/blob/main/docs/media/hero-16x9.mp4)

```bash
npm i plinkfx
Expand All @@ -27,7 +27,7 @@ sound like a loop.
<details>
<summary>More ways to play: options, game setup, tree-shaking, your own sound</summary>

**By name** (every sound included, 15.7 kB gzipped):
**By name** (every sound included, 23.0 kB gzipped):

```js
import { play, volume, muted } from "plinkfx";
Expand All @@ -37,6 +37,7 @@ play("coin", { volume: 0.5, rate: 1.2 }); // quieter, a bit higher
play("step-wood", { variant: 2 }); // a specific take (0-3)
play("step-wood", { pan: -0.6 }); // to the left
play("coin", { delay: 0.1 }); // 100 ms later
play("combo-chain", { rate: 2 ** (n / 12) }); // n-th combo step, a semitone higher each
volume(0.8); // master volume, 0..1
muted(true); // mute everything, muted() reads it
```
Expand Down Expand Up @@ -144,18 +145,19 @@ const useSfx = (name) => useCallback((opts) => play(name, opts), [name]);
<!-- catalog -->
| Category | Sounds | Examples |
|---|---:|---|
| UI | 23 | `click` `click-soft` `toggle-on` `confirm` `error` `notify` `swipe` `plink` |
| Pickups | 15 | `coin` `coin-double` `coin-bag` `gem` `key` `heart` `ka-ching` |
| Jump & land | 10 | `jump` `jump-double` `jump-cartoon` `land` `land-heavy` `spring` |
| Hits | 15 | `hit` `hit-heavy` `punch` `hurt` `enemy-die` `sword-hit` `block` `crit` |
| UI | 32 | `click` `click-soft` `toggle-on` `confirm` `error` `notify` `swipe` `plink` |
| Pickups | 19 | `coin` `coin-double` `coin-bag` `gem` `key` `heart` `ka-ching` |
| Jump & land | 12 | `jump` `jump-double` `jump-cartoon` `land` `land-heavy` `spring` |
| Hits | 20 | `hit` `hit-heavy` `punch` `hurt` `enemy-die` `sword-hit` `block` `crit` |
| Explosions | 10 | `explosion` `explosion-big` `explosion-retro` `firework` `implosion` |
| Power-ups | 12 | `powerup` `level-up` `extra-life` `shield-on` `heal` `charge-up` |
| Shots & lasers | 17 | `laser` `blaster` `zap` `pew` `gunshot` `ricochet` `bow-twang` `reload` |
| Footsteps | 10 | `step-grass` `step-stone` `step-wood` `step-metal` `step-snow` `step-water` |
| Shots & lasers | 21 | `laser` `blaster` `zap` `pew` `gunshot` `ricochet` `bow-twang` `reload` |
| Footsteps | 12 | `step-grass` `step-stone` `step-wood` `step-metal` `step-snow` `step-water` |
| Magic | 13 | `sparkle` `spell-cast` `fireball` `ice` `teleport` `harp` `lightning` |
| Alerts | 10 | `alarm` `warning` `low-health` `heartbeat` `countdown` `radar-ping` |
| Jingles | 9 | `victory` `checkpoint` `level-complete` `game-over` `secret-found` `achievement` |
| Alerts | 13 | `alarm` `warning` `low-health` `heartbeat` `countdown` `radar-ping` |
| Jingles | 11 | `victory` `checkpoint` `level-complete` `game-over` `secret-found` `achievement` |
| Doors & mechanics | 10 | `door-open` `door-heavy` `lock-open` `chest-open` `lever` `ratchet` |
play("combo-chain", { rate: 2 ** (n / 12) }); // n-th combo step, a semitone higher each
| World | 13 | `whoosh` `swing` `splash` `water-drop` `wind` `glass-break` `engine-idle` (loop) `force-field` (loop) |
| Creatures | 9 | `bat-flap` `slime-blob` `growl-small` `ghost-moan` `bee-buzz` `voice-babble` |
| Nature | 8 | `thunder-far` `rain-drop` `bird-chirp` `frog-croak` `stone-drop` `rain-loop` (loop) `wind-loop` (loop) |
Expand Down Expand Up @@ -187,7 +189,7 @@ Each sound in the gallery also has a "download .wav" button. Ready-made players

### One audio sprite (Phaser, Howler)

For the web, one file with every sound means one request instead of 184:
For the web, one file with every sound means one request instead of 274:

```bash
npx plinkfx export public/sfx --sprite --format both # all sounds, 0.1 s of silence between them
Expand Down Expand Up @@ -313,9 +315,9 @@ sfxr (DrPetter, 2007) started this genre, and these are the tools most people re
| | **plinkfx** | [ZzFX](https://github.com/KilledByAPixel/ZzFX) | [jsfxr](https://github.com/chr15m/jsfxr) | [Kenney audio packs](https://kenney.nl/assets/category:Audio) |
|---|---|---|---|---|
| What it is | named sound library as code | tiny synth + designer | sfxr port: generator + library | WAV/OGG asset packs |
| Size (gzip) | 3.1 kB player, 15.7 kB with all sounds | ~1.3 kB | ~6.3 kB | no code, files |
| Size (gzip) | 3.1 kB player, 23.0 kB with all sounds | ~1.3 kB | ~6.3 kB | no code, files |
| Licence | CC0 sounds, MIT code | MIT | Unlicense | CC0 |
| Named sounds | <!-- count -->184<!-- /count --> | 4 examples, random generators | random generators per category | many, generic file names |
| Named sounds | <!-- count -->274<!-- /count --> | 4 examples, random generators | random generators per category | many, generic file names |
| Matched loudness | yes, measured in tests | no | no | not stated |
| Same input, same samples | yes, seeded and hash-tested | only with randomness set to 0 | per saved parameter set | fixed files |
| Variations | 4 seeded takes per sound | edit or randomise | mutate | separate files |
Expand Down
30 changes: 18 additions & 12 deletions README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@

# plinkfx

**<!-- count -->184<!-- /count --> 个游戏音效,全部用代码写成。** 金币、跳跃、打击、激光、爆炸、UI 点击……每个音效只是几个看得懂的参数,由 3.1 kB 的播放器在浏览器里实时合成。音效 CC0,可商用,无需署名;没有音频文件,无需注册。
**<!-- count -->274<!-- /count --> 个游戏音效,全部用代码写成。** 金币、跳跃、打击、激光、爆炸、UI 点击……每个音效只是几个看得懂的参数,由 3.1 kB 的播放器在浏览器里实时合成。音效 CC0,可商用,无需署名;没有音频文件,无需注册。

<a href="https://maximilianfeix.github.io/plinkfx/"><img src="https://cdn.jsdelivr.net/gh/maximilianfeix/plinkfx@main/docs/media/gallery.gif" alt="plinkfx 在线音效库:点击方块即可试听 coin、jump、laser、explosion 等音效,每个方块显示波形" width="100%"></a>

Expand Down Expand Up @@ -48,21 +48,27 @@ muted(true); // 全部静音;不会自动保存,需要时自己存
<!-- catalog -->
| 分类 | 数量 | 示例 |
|---|---:|---|
| UI | 23 | `click` `toggle-on` `confirm` `error` `notify` `plink` |
| 拾取 | 15 | `coin` `coin-double` `gem` `key` `heart` `ka-ching` |
| 跳跃与落地 | 10 | `jump` `jump-double` `land` `land-heavy` `spring` |
| 打击 | 15 | `hit` `hit-heavy` `punch` `hurt` `enemy-die` `sword-hit` |
| UI | 32 | `click` `toggle-on` `confirm` `error` `notify` `plink` |
| 拾取 | 19 | `coin` `coin-double` `gem` `key` `heart` `ka-ching` |
| 跳跃与落地 | 12 | `jump` `jump-double` `land` `land-heavy` `spring` |
| 打击 | 20 | `hit` `hit-heavy` `punch` `hurt` `enemy-die` `sword-hit` |
| 爆炸 | 10 | `explosion` `explosion-big` `explosion-retro` `firework` |
| 强化 | 12 | `powerup` `level-up` `extra-life` `shield-on` `heal` |
| 射击与激光 | 17 | `laser` `blaster` `zap` `pew` `gunshot` `reload` |
| 脚步 | 10 | `step-grass` `step-stone` `step-wood` `step-snow` |
| 射击与激光 | 21 | `laser` `blaster` `zap` `pew` `gunshot` `reload` |
| 脚步 | 12 | `step-grass` `step-stone` `step-wood` `step-snow` |
| 魔法 | 13 | `sparkle` `fireball` `ice` `teleport` `lightning` |
| 提示 | 10 | `alarm` `warning` `low-health` `countdown` |
| 短旋律 | 9 | `victory` `level-complete` `game-over` `achievement` |
| 提示 | 13 | `alarm` `warning` `low-health` `countdown` |
| 短旋律 | 11 | `victory` `level-complete` `game-over` `achievement` |
| 门与机关 | 10 | `door-open` `door-heavy` `chest-open` `lever` |
| 环境 | 13 | `whoosh` `splash` `water-drop` `wind` `glass-break` `engine-idle`(循环) |
| 生物 | 9 | `bat-flap` `slime-blob` `growl-small` `ghost-moan` `voice-babble` |
| 自然 | 8 | `thunder-far` `rain-drop` `bird-chirp` `stone-drop` `rain-loop`(循环) |
| 环境 | 18 | `whoosh` `splash` `water-drop` `wind` `glass-break` `engine-idle`(循环) |
| 生物 | 13 | `bat-flap` `slime-blob` `growl-small` `ghost-moan` `voice-babble` |
| 自然 | 12 | `thunder-far` `rain-drop` `bird-chirp` `stone-drop` `rain-loop`(循环) |
| 卡牌与赌场 | 9 | `card-flip` `card-shuffle` `chip-stack` `dice-roll` `jackpot` |
| 载具 | 7 | `engine-start` `engine-rev` `tire-screech` `car-crash` `boost` |
| 恐怖 | 7 | `jumpscare` `dread-drone` `whisper` `horror-sting` `music-box` |
| 农场与制作 | 9 | `axe-chop` `tree-fall` `pickaxe-mine` `dig` `watering-can` |
| 科幻与科技 | 8 | `computer-beep` `scan` `access-granted` `door-slide` `glitch` |
| 益智 | 6 | `swap` `match` `combo-chain` `line-clear` `merge` |
<!-- /catalog -->

## 导出给游戏引擎
Expand Down
18 changes: 18 additions & 0 deletions gallery/style.css
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,14 @@
--c-jingle: #2f8f8a;
--c-mechanic: #6f6f6f;
--c-world: #3b7ea1;
--c-creature: #8a6d3b;
--c-nature: #5f8a3a;
--c-card: #a83a4f;
--c-vehicle: #56677a;
--c-horror: #5c2d3d;
--c-farm: #9c8a2e;
--c-scifi: #2b93a8;
--c-puzzle: #b95fa6;
color-scheme: light;
}
@media (prefers-color-scheme: dark) {
Expand All @@ -50,6 +58,8 @@
--c-footstep: #a8987a;
--c-magic: #8a7ee0;
--c-mechanic: #8f8f8f;
--c-vehicle: #7a8b9e;
--c-horror: #8e4a5e;
color-scheme: dark;
}
}
Expand Down Expand Up @@ -444,6 +454,14 @@ i {
[data-cat="jingle"] { --sw: var(--c-jingle); }
[data-cat="mechanic"] { --sw: var(--c-mechanic); }
[data-cat="world"] { --sw: var(--c-world); }
[data-cat="creature"] { --sw: var(--c-creature); }
[data-cat="nature"] { --sw: var(--c-nature); }
[data-cat="card"] { --sw: var(--c-card); }
[data-cat="vehicle"] { --sw: var(--c-vehicle); }
[data-cat="horror"] { --sw: var(--c-horror); }
[data-cat="farm"] { --sw: var(--c-farm); }
[data-cat="scifi"] { --sw: var(--c-scifi); }
[data-cat="puzzle"] { --sw: var(--c-puzzle); }

/* ---------- grid ---------- */
.layout {
Expand Down
19 changes: 19 additions & 0 deletions library/alert.ts
Original file line number Diff line number Diff line change
Expand Up @@ -59,4 +59,23 @@ export default def("alert", {
{ wave: "sine", freq: 1175, fm: [2, 0.7, 0.2], arp: [0, 5, 7], arpRate: 0.11, a: 0.003, h: 0.3, d: 0.3, gain: 0.35 },
],
}],
"buzzer-wrong": ["Quiz-show wrong-answer buzzer", {
vary: 0.05,
layers: [
{ wave: "saw", freq: 110, a: 0.005, h: 0.45, d: 0.08, shape: 1, lp: 2000, drive: 1.5 },
{ wave: "square", freq: 111.5, a: 0.005, h: 0.45, d: 0.08, shape: 1, lp: 1200, gain: 0.6 },
],
}],
"ding-correct": ["Quiz-show correct-answer ding-ding", {
vary: 0.05,
verb: [0.3, 0.18],
layers: [0, 0.16].map((at) => ({ wave: "sine" as const, freq: 1760, fm: [3.5, 1.4, 0.1], at, a: 0.002, d: 0.5, shape: -4 })),
}],
"timer-done": ["Kitchen timer done: rapid bell trill", {
vary: 0.05,
layers: [
...Array.from({ length: 10 }, (_, i) => ({ wave: "metal" as const, freq: 2600, bp: 3500, q: 2, at: i * 0.05, a: 0.001, d: 0.045, shape: -4, gain: 0.6 })),
{ wave: "sine" as const, freq: 3500, a: 0.002, h: 0.45, d: 0.1, gain: 0.15 },
],
}],
});
90 changes: 90 additions & 0 deletions library/card.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,90 @@
import { def } from "./def.ts";

// Cards, chips, dice and slots. Paper is band-passed noise; chips and dice are short `modal` knocks.
const WOOD = [1, 2.32, 4.25, 6.63];

export default def("card", {
"card-flip": ["Flip a card face up: quick papery snap", {
vary: 1,
varyF: 3,
varyG: 1.5,
layers: [
{ wave: "noise", bp: 2600, bpTo: 4200, q: 1.2, a: 0.012, d: 0.035, shape: -4, gain: 0.7 },
{ wave: "noise", bp: 3800, q: 2.5, at: 0.045, a: 0.002, d: 0.012, shape: -6, gain: 0.6 },
{ wave: "pink", bp: 900, q: 1.5, at: 0.046, a: 0.001, d: 0.03, shape: -5, gain: 0.4 },
],
}],
"card-deal": ["Deal a card across the table: swish and slap", {
vary: 1,
varyF: 3,
varyG: 1.5,
layers: [
{ wave: "noise", bp: 1800, bpTo: 4500, q: 1.4, a: 0.05, d: 0.03, shape: 1 },
{ wave: "noise", bp: 3000, q: 1.5, at: 0.08, a: 0.002, d: 0.02, shape: -6, gain: 0.7 },
{ wave: "pink", lp: 1200, at: 0.08, a: 0.001, d: 0.04, shape: -5, gain: 0.5 },
],
}],
"card-place": ["Lay a card down on felt", {
vary: 0.8,
varyF: 2,
varyG: 1,
layers: [
{ wave: "pink", bp: 1400, q: 1, a: 0.002, d: 0.09, shape: -5 },
{ wave: "noise", bp: 3500, q: 2, a: 0.001, d: 0.008, shape: -6, gain: 0.25 },
{ wave: "pink", lp: 600, a: 0.002, d: 0.12, shape: -4, gain: 0.5 },
],
}],
"card-shuffle": ["Riffle shuffle: a fast burst of card ticks", {
vary: 0.5,
varyF: 2,
layers: [
...Array.from({ length: 16 }, (_, i) => ({ wave: "noise" as const, bp: 2800 + (i % 3) * 500, q: 2, at: i * 0.022 + (i % 2) * 0.004, a: 0.001, d: 0.012, shape: -5, gain: 0.5 + Math.sin(i / 5) * 0.4 })),
{ wave: "pink" as const, bp: 2000, q: 0.8, a: 0.05, h: 0.2, d: 0.12, gain: 0.25 },
],
}],
"chip-stack": ["Poker chips clack onto a stack", {
vary: 0.6,
varyF: 2,
varyG: 1.5,
layers: [0, 0.035, 0.06].flatMap((at, i) => [
{ wave: "modal" as const, freq: 1900 + i * 120, modes: [1, 1.59, 2.14, 2.65], at, a: 0.001, d: 0.06, shape: -6, gain: 1 - i * 0.2 },
{ wave: "noise" as const, bp: 4500, q: 2, at, a: 0.001, d: 0.006, shape: -6, gain: 0.5 },
]),
}],
"dice-roll": ["Dice tumble across a table and settle", {
vary: 0.8,
varyF: 2,
varyG: 2,
layers: [0, 0.07, 0.13, 0.2, 0.25, 0.31, 0.36, 0.4].flatMap((at, i) => [
{ wave: "modal" as const, freq: 900 + (i % 3) * 180, modes: WOOD, at, a: 0.001, d: 0.05, shape: -6, gain: 1 - i * 0.1 },
{ wave: "noise" as const, bp: 3000, q: 2, at, a: 0.001, d: 0.006, shape: -6, gain: 0.4 - i * 0.04 },
]),
}],
"slot-spin": ["Slot reels spinning: fast ratchet ticks", {
vary: 0.4,
varyF: 1.5,
layers: [
...Array.from({ length: 18 }, (_, i) => ({ wave: "square" as const, duty: 0.25, freq: 1400, at: i * 0.04, a: 0.001, d: 0.02, shape: 3, lp: 4000, gain: 0.5 })),
{ wave: "noise" as const, bp: 2500, q: 1, a: 0.05, h: 0.6, d: 0.1, gain: 0.08 },
],
}],
"slot-stop": ["A reel locks into place: clunk and ding", {
vary: 0.2,
verb: [0.25, 0.12],
layers: [
{ wave: "noise", bp: 1200, q: 1.5, a: 0.001, d: 0.02, shape: -5, drive: 1 },
{ wave: "sine", freq: 150, to: 90, a: 0.001, d: 0.08, shape: -5, gain: 0.7 },
{ wave: "sine", freq: 1568, fm: [3.5, 1.4, 0.1], at: 0.04, a: 0.002, d: 0.4, shape: -4, gain: 0.4 },
],
}],
jackpot: ["Jackpot: bell flurry over a rising arpeggio", {
vary: 0.05,
verb: [0.4, 0.2],
echo: [0.08, 0.3, 0.2],
layers: [
{ wave: "square", duty: 0.25, freq: 784, arp: [0, 4, 7, 12, 16, 19, 24, 19, 24], arpRate: 0.07, a: 0.002, h: 0.55, d: 0.4, shape: 2, lp: 5000, gain: 0.5 },
...[0.1, 0.25, 0.4, 0.55, 0.7, 0.85].map((at, i) => ({ wave: "sine" as const, freq: 2093 + (i % 2) * 544, fm: [3.5, 1.6, 0.1] as [number, number, number], at, a: 0.002, d: 0.35, shape: -4, gain: 0.3 })),
{ wave: "metal", freq: 5000, hp: 7000, a: 0.01, h: 0.8, d: 0.4, gain: 0.06 },
],
}],
});
Loading
Loading