Skip to content

t1k:designer:audio:sfx-synth

FieldValue
Moduleaudio
Version1.9.0
Efforthigh
Tools—

Keywords: audio, audio variants, clipping, coin sound, cue, cue inventory, dbfs, dc offset, dsp, explosion sound, fail sting, fanfare, hit sound, impact sound, level up sound, loudness, lufs, pickup sound, placeholder sound, procedural audio, render audio, sfx, shield sound, sound design, sound effect, sound replacement, synth, synthesis, telegraph sound, true peak, ui tap sound, variant floor, wav, whoosh

/t1k:designer:audio:sfx-synth

Author a game’s sound effects as synthesis recipes — small Python functions that render a WAV from first principles — instead of sourcing files. The recipe is the deliverable: it is reviewable, diffable, reproducible, and re-renderable at any length, band, or variant count.

  • A game has placeholder or missing sounds and needs real ones (see rules/placeholder-first-handoff.md)
  • A cue inventory has to become shipped audio: the list exists, the files do not
  • A cue’s loudness must be set to its band, or its variant count decided
  • An existing cue renders too loud, too quiet, clipped, dull, or machine-guns when chained
  • A team is about to buy or search for a sound that a 40-line recipe would produce exactly

Not this skill when: the ask is a music bed or sustained ambience (this kit renders one-shots — though pad/reverb in recipes.py extend to short loops), or the game already has a licensed library whose cue fits.

YouThe kit
Write the recipe: what layers, what envelope, what timbreRender, seed, normalize, measure, write WAV
Decide the band and variant count (from the matrix)Enforce both, and refuse a manifest that violates them
Listen and acceptReport every measurement as facts

Nothing in the kit knows a cue name, a target, or a variant count. All of it arrives in a per-game manifest — that is what keeps the kit reusable across every studio game.

  1. Get the cue inventory — the game’s list of cues with an action class each. If the game has none, derive it from the feedback matrix’s action classes; do not invent cue names.
  2. Build the manifest — one row per cue. Copy examples/cues.json as the template. Per cue: cue, recipe, fireRate (the four labels, verbatim), perLevel, variants, actionClass, note (why it exists and how it must read).
  3. Set the band and the variant count — from t1k:designer:base:feel-juice → references/feedback-matrix.md. Both tables are cited there and duplicated nowhere. manifest.py rejects a manifest that declares a band its target misses or a variant count under the V1 floor, so a wrong decision fails at validation rather than in the mix. A cue that ships under the V1 floor by design sets feedbackWaiver: "<reason>" on its row (the mandate’s feedback-waiver:).
  4. Pick or write the recipe — start from scripts/recipes.py (17 generic cues across 9 families). Change the recipe only when no existing one reads right; a new recipe belongs in the kit, not in a game folder. Design reasoning per family: references/recipe-cookbook.md.
  5. Render — python3 scripts/render.py --manifest <path> --out <dir>. Read the PASS/FAIL line per file. A FAIL names the check that failed.
  6. Measure what is on disk — python3 scripts/verify.py --manifest <path> --dir <dir>.
  7. Verify the kit itself if you touched dsp.py, manifest.py, or recipes.py: python3 scripts/selftest.py.
  8. STOP at the listen gate — see below. Nothing ships before a human has heard it.

Full reasoning, the EBU R128 measurement failure, and the true-peak cap: references/loudness-convention.md.

The one fact that gates every render:

A cue’s loudness is its active-sample RMS in dBFS, measured over the samples above −60 dB relative to the peak, with the true peak capped at −1 dBFS.

Band targets are the matrix’s table, read verbatim. The matrix labels the column LUFS; EBU R128 integrated LUFS is unusable for a one-shot, because its relative gate empties below roughly 400 ms and reports I: -70.0 LUFS for a perfectly healthy 250 ms hit. The band numbers are the operative target; active RMS dBFS is the measurement that reaches them. Do not try to satisfy an integrated-LUFS target on a short cue, and do not “fix” a −70 reading — it means the cue is too short to measure, not that it is silent.

ScriptDoes
scripts/dsp.pyThe DSP kit: oscillators, envelopes, filters, saturation, reverb, and the measurement helpers
scripts/recipes.py17 generic cue recipes; resolve() maps a manifest reference to a callable
scripts/manifest.pyCue manifest loading + the band and V1 validation; JSON or CSV
scripts/render.pyRender a manifest to 44.1 kHz / 16-bit / mono WAV, seeded per cue + variant
scripts/verify.pyRe-measure the WAVs on disk; --ffmpeg cross-checks with ffmpeg astats
scripts/selftest.pyPins the kit’s invariants; run after any change to the DSP or validation

A manifest cue names its recipe, so a game never edits kit code to pick one:

{ "cue": "SFX_CoinCollected", "recipe": "pickup_coin", "fireRate": "0.3 to 2/sec",
"perLevel": 30, "variants": 3, "actionClass": "valid-action",
"note": "reward family's brightest member; variants climb so a coin trail reads as a rising figure" }

Run these, read the output, then claim the result. A render is not verified by the render.

Terminal window
python3 scripts/render.py --manifest cues.json --out out/ # per-file PASS/FAIL
python3 scripts/verify.py --manifest cues.json --dir out/ --ffmpeg # what is on disk, cross-checked
python3 scripts/selftest.py # after any DSP/validation change

What each check catches — full table in references/verification.md:

  • band — active RMS outside its band: inaudible in the mix, or it stomps everything else
  • peak — true peak above −1 dBFS: inter-sample clipping on a real decoder even when the file looks fine
  • dc — a non-zero mean: eats headroom, and clicks on loop
  • clip — a sample at the digital ceiling: normalize must saturate toward the cap, never into it
  • centroid — brightness read beside its neighbours; a cue that is right alone can be wrong in a set

HARD. Rendering and measurement are necessary and not sufficient. A cue can pass every check and still be the wrong sound. Before any batch render of a game’s cue inventory:

  1. Render a small sample — 2–3 cues spanning different families.
  2. Have a human listen to those files and say whether they read correctly.
  3. Only then render the rest.

Per rules/preview-first-batch.md. The measurements are facts about loudness and cleanliness; only a listener can tell you whether a “punch” reads as a punch. Never declare a cue inventory done on measurements alone, and never bulk-render before the sample has been heard.

  • V1 keys on PLAY COUNT, not fire rate. They are independent axes: a quiet once-per-level sting needs one variant, a fast loud tile pop needs three. Conflating them over-variants one cue and machine-guns another. manifest.py implements the predicate correctly — do not “fix” it to use the band label.
  • DC and the peak cap interact. Gain to hit the RMS target can push the peak over its cap; the soft-clip that pulls it back introduces DC; removing that DC moves both again. They must converge together, which is why dsp.normalize owns all three. Enforcing them in sequence leaves only the last one met — see selftest.py’s first test.
  • Variants may differ in length. A different decay or tail trim is legitimate; a comparison across variants must use a common prefix, not assume equal arrays.
  • render.py’s PASS and verify.py’s PASS are different claims — in-memory before quantization vs. on disk after it. A cue can pass the first and fail the second. Both must run.
  • Engine integration is the engine kit’s business. How an ECS or job-system audio layer raises the feedback event that plays these files belongs to the engine kit, not here; this skill produces and verifies the files.