Home

sfxwright is a skill for AI coding agents, plus a standard-library Python script (sfx.py), for planning, making, editing, checking and documenting sound effects. It keeps each file's source and licence beside it. It is not a sound library, a model or an audio editor, and it cannot hear.

Version 0.1.0. It is a Claude Code plugin on GitHub, with no package on any registry.

Read this first

• Nobody has heard these routes yet. No generation route or synth recipe has been judged in a listening test. Rankings in the route table are reading and inference.
• A flag means listen. It is not a verdict, and a clean result does not mean a sound is good.
• set does not catch pitch-shifted copies. Six vary copies of one footstep pass it clean. See Checks and flags.
• Thresholds are being calibrated. Treat every limit as provisional.
• ship keeps a record. It is not legal advice.

The smallest example

Six footsteps, a set check, a walk and a timing check, with no model and no download:

$ python sfx.py synth footstep --param surface=gravel --takes 6 --out takes --name step
{"ok": true, "files": ["takes\\step_01.wav", "takes\\step_02.wav", "takes\\step_03.wav", "takes\\step_04.wav", "takes\\step_05.wav", "takes\\step_06.wav"]}
$ python sfx.py set takes/step_*.wav
{"ok": true, "files": 6, "flags": [], "near_duplicates": [], "outliers": [], "peak_spread_db": 0.0, "rms_spread_db": 1.78, "corr_max": 0.316, "corr_median": 0.163, "attack_dist_median": 0.26, "note": "heuristic; a blind listen decides whether a set machine-guns"}
$ echo $?
0
$ python sfx.py sequence takes/step_*.wav --out walk.wav --count 12
{"ok": true, "out": "walk.wav", "events": [0.0, 0.577, 1.143, 1.682, 2.206, 2.779, 3.324, 3.839, 4.363, 4.946, 5.533, 6.078], "seconds": 7.05}
$ python sfx.py timing walk.wav
{"ok": true, "onsets": 11, "mean_gap_s": 0.55, "gap_cv": 0.045, "neighbour_corr_median": 0.162, "flags": []}
$ echo $?
0

Every transcript in this wiki is real output from sfx.py 0.1.0, run on Windows with Python 3.14 and no reachable ComfyUI. Windows prints \\ in JSON paths; Linux and macOS print /. Those two systems run the test suite in CI, but these transcripts were not run on them.

Pages

• Getting started: install, what needs ffmpeg or ComfyUI, the first run.
• Commands: every command and flag, with exit codes.
• Sound list format: sounds.json and the sidecars, the contract with other plugins.
• Checks and flags: what each flag reads, and what the checks miss.
• Routes and synth recipes: where sounds come from, recipe parameters, how far to trust each.
• Rights and shipping: licences, what edits refuse, BLOCKED, CHECK and CLEAR.
• Workflows: a variation set, a loop, a film cue, a shipping pass.
• Errors and edge cases: exact messages and surprises.
• FAQ: short answers.
• Versions and upgrading: what has been released.
• Development: tests, size budget, the release rule.

Elsewhere: README, changelog, issues.