Generated from

rules/*.md

by

src/build.mjs

. Do not edit by hand.

pipeline-detect-input

• "open", "appear", "in", "show", "expand", "confirm" -> ascending pitch.
• "close", "dismiss", "out", "hide", "collapse", "cancel" -> descending pitch.

1. Source-shape adjectives (

   warm

   ,

   bright

   ,

   glassy

   ,

   metallic

   ,

   lofi

   ,

   retro

   ,

   organic

   ) - mutate

   source.type

   ,

   source.fm

   , or add

   filter

   .
2. Envelope adjectives (

   punchy

   ,

   airy

   ) - mutate

   envelope.attack

   /

   envelope.decay

   .
3. Effect adjectives (

   reverby

   ,

   delayed

   ,

   crushed

   ) - append to

   effects

   .

• warm

  +

  bright

  -> the later token wins.

• lofi

  +

  glassy

  -> apply both, but cap

  effects

  at 2 entries.

• punchy

  +

  airy

  -> they're orthogonal (envelope vs source); both apply.

.web-kits/<patch>.ts

import type { SoundDefinition } from "@web-kits/audio";

export const myClick: SoundDefinition = {
  source: { type: "sine", frequency: 1300, fm: { ratio: 0.5, depth: 60 } },
  envelope: { decay: 0.012, release: 0.004 },
  gain: 0.18,
};

"click" -> base from

event-click

; "warm" -> kept default sine, no extra filter needed at 1.3 kHz.

• Skip the first 1-2 ms if the onset is a click transient; it pollutes the FFT.
• For very short sounds (< 20 ms) use fewer slices and a smaller window.
• Use a Hanning window before FFT (already applied in

  analyze_slice

  ) to reduce spectral leakage.

• sustain < 0.01

  -> drop the field; the sound is percussive.

• attack < 0.001

  -> set

  attack: 0

  .

• release < 0.005

  -> clamp to

  0.005

  to avoid clicks at the end.

• toggle-on

  : low note first, then high (ascending = enabling).

• toggle-off

  : high note first, then low (descending = disabling).

copy

sync

toggleOn

toggleOff

copy

sync

• Replace

  source

  with

  { type: "noise", color: "white" }

  .
• Replace

  filter

  with bandpass envelope reaching a high peak (4-6 kHz).
• Lengthen

  envelope.attack

  to 0.02-0.04 s so the result fades in rather than snapping.
• Lower

  gain

  to 0.08-0.12.

• Remove any

  filter

  of type

  lowpass

  , or raise its cutoff above 6 kHz.
• If the base used

  triangle

  , upgrade to

  sine

  with

  fm: { ratio: 2.5, depth: 50 }

  for sparkle.
• Slight

  gain

  bump (+0.02) is fine but stay under the budget.

• source.type: "sine"

  .

• source.fm: { ratio: 3.5, depth: 200-300 }

  .
• Append

  effects: [{ type: "reverb", decay: 0.7, damping: 0.5, mix: 0.15 }]

  .
• Extend

  envelope.decay

  to at least 0.3 s so the bell can ring.

ding

sparkle

star

• Add

  filter: { type: "lowpass", frequency: 1500 }

  .
• Append

  effects: [{ type: "bitcrusher", bits: 6-8, mix: 0.7-1 }]

  .
• Optionally drop

  gain

  by 0.02 because bitcrushing adds perceived loudness.

mood-retro

• source.type: "sine"

  (or

  square

  for a harsher result).

• source.fm: { ratio: 2.76, depth: 300-400 }

  - 2.76 is the inharmonic ratio used by

  badge

  in

  .web-kits/core.ts

  and reads as bell-metal.
• Short release; metallic shouldn't sustain.

mood-warm

badge

• source.type: "triangle"

  .
• Add

  source.detune: 5-10

  for very slight pitch wobble.
• Bump

  envelope.attack

  from 0 to 0.003-0.008 s so the onset isn't a hard click.
• Append a small reverb (

  mix: 0.05-0.1

  ).

mood-warm

mood-metallic

mood-lofi

• envelope.attack: 0

  .

• envelope.decay: <= 0.06

  .

• envelope.sustain: 0

  .

• envelope.release: <= 0.015

  .

• gain

  bump of +0.05 is fine because the energy lives in a shorter window.

• source.type: "square"

  (or

  "sawtooth"

  ).
• Add

  filter: { type: "lowpass", frequency: 3000 }

  to soften aliasing.
• Append

  effects: [{ type: "bitcrusher", bits: 8, sampleRateReduction: 2-4, mix: 1 }]

  .

• Add

  filter: { type: "lowpass", frequency: 2500 }

  (or 2-3 kHz).
• Optionally add

  effects: [{ type: "reverb", decay: 0.4, mix: 0.1 }]

  .
• If the base used

  sawtooth

  or

  square

  , downgrade to

  triangle

  so the source itself is rounder.

delay

1. High-frequency transient (3-5 kHz) with sub-10 ms decay - the "stick".
2. Lower-frequency body (80-300 Hz) with longer decay - the "drum".

type

sine

filter

effects

filter: {
  type: "bandpass",
  frequency: <resting Hz>,
  resonance: 1-3,
  envelope: { attack: 0.01-0.04, peak: <target Hz>, decay: 0.08-0.2 },
}

• Peak above resting -> upward swoosh.
• Peak below resting -> downward swoosh.
• Higher

  resonance

  (>2) makes it whistle-like; lower (<1.5) is broader.

noise

• bits

  : 4-8. Lower = more crunchy. Below 4 turns into noise.

• sampleRateReduction

  : 1 (off) to 8 (heavy aliasing). Combine with

  bits: 8

  for that 8-bit console sound.

• mix

  : usually 1. Mixing bitcrush with the dry signal sounds muddy.

square

sawtooth

effect-reverb-tail

source.fm: { ratio, depth }

• ratio

  : 2.5-3.5 for harmonic-bell, 2.76 for the "badge" inharmonic clang.

• depth

  : 150-400. Higher depth = more strident.

• envelope.decay

  : at least 0.3 s so the bell can ring.

ratio: 3.5

depth: 250

decay: 0.7, mix: 0.15

ratio: 0.5

depth: 200

mood-glassy

mood-metallic

filter: { type: "lowpass", frequency: 2500, resonance: 0.7 }

• frequency

  : 1500-3000 Hz for "warm". Below 1000 starts muffling the sound.

• resonance

  : omit or set 0.7-1.5. Above 2 the cutoff itself starts to whistle.

filter: {
  type: "lowpass",
  frequency: 2500,
  envelope: { attack: 0, peak: 6000, decay: 0.08 },
}

• decay

  : 0.3-0.6 s.

• damping

  : 0.4-0.6 (kills high frequencies in the tail; without this the reverb sounds metallic).

• mix

  : 0.08-0.15. Anything above 0.2 starts to feel like a music production effect.

effects

effects

MultiLayerSound

estimated = (envelope.attack ?? 0)
          + envelope.decay
          + (envelope.release ?? 0)
          + max(0, longestEffectTail)  // reverb decay, delay time * 4

• Click / tap / tick / hover / focus: <= 0.1 s.
• Toggle / copy / sync: <= 0.2 s.
• Modal / drawer / dropdown open/close: <= 0.3 s.
• Success / complete / notification: <= 0.8 s.
• Whoosh / page transition: <= 0.5 s.

validate

• envelope.decay > 0

  (always). Set to 0.005 minimum.
• If

  envelope.sustain > 0

  ,

  envelope.release

  must be present and

  > 0

  .

• envelope.attack

  : 0 for percussive, 0.003-0.05 for sustained tones, up to 0.1 for ambient sounds.

• envelope.decay + envelope.release

  : <= 2 s for any UI sound. Above that, you're writing music, not interface feedback.

• envelope.sustain

  : 0 for transients, 0.03-0.15 for "rings out" tones, 0.3-0.7 only for held loops.

validate

decay <= 0

sustain > 0

release

• source.frequency

  (or both

  start

  /

  end

  of a sweep): 20 Hz <= f <= 20000 Hz.

• filter.frequency

  : 20 Hz <= f <= 20000 Hz.

• filter.envelope.peak

  : same range as

  filter.frequency

  .

• Tonal sources: 80 Hz <= f <= 8000 Hz.
• High transient layers (clicks, sticks): up to 5 kHz.
• Sub layers (body, drum): 60-200 Hz.

validate

• gain

  between 0.04 and 0.3 for typical UI events.
• Background ticks/scroll-snaps: 0.04-0.10.
• Mid-importance (click, tap, hover): 0.12-0.20.
• High-importance (success, notification): 0.16-0.25.