Getting Started

Install

In Claude Code (these two lines are from the README and were not run for this wiki):

claude plugin marketplace add m4bwav/sfxwright
claude plugin install sfxwright@sfxwright

Other agents can read skills/sfxwright/SKILL.md and run the script directly. To use the script alone, clone the repository and work in its scripts folder:

git clone https://github.com/m4bwav/sfxwright.git
cd sfxwright/skills/sfxwright/scripts

What needs what

Part	Needs	Without it
sfx.py	Python 3.9 or later, nothing else
synth, check, set, timing, vary, sequence, loop, pitch and other edits of WAV files	nothing more
edit --op stretch, edit --op convolve, OGG output	ffmpeg	error, exit 1
gen	a reachable ComfyUI with an audio model	error, exit 1; --workflow-out still writes the workflow
A musicwright install	optional	loop and check --loop use the script's own seam score

CI runs the tests on Ubuntu, macOS and Windows, on Python 3.9 and 3.14 (Ubuntu on 3.14 only). The transcripts here ran on Windows with Python 3.14 only.

See what you have

doctor prints what it found and which routes that allows. It exits 0 even when nothing is reachable:

$ python sfx.py --version
0.1.8
$ python sfx.py doctor
{"ok": true, "version": "0.1.8", "python": "3.14.6", "ffmpeg": true, "musicwright_mw": true, "comfyui": [], "routes": ["synth (procedural, always)", "gen --workflow-out (hand over a workflow; no reachable audio model)"], "elevenlabs_key": false, "note": "paid APIs and installs need the user's yes"}
$ echo $?
0

With ffmpeg off the PATH, the same command reports it, and only the steps that need it stop:

$ python sfx.py doctor
{"ok": true, "version": "0.1.8", "python": "3.14.6", "ffmpeg": false, "musicwright_mw": true, "comfyui": [], "routes": ["synth (procedural, always)", "gen --workflow-out (hand over a workflow; no reachable audio model)"], "elevenlabs_key": false, "note": "paid APIs and installs need the user's yes"}
$ echo $?
0
$ python sfx.py edit m.wav st.wav --op stretch --value 1.5
{"ok": false, "error": "ffmpeg not found; this step needs it (use WAV input, or install ffmpeg)"}
$ echo $?
1
$ python sfx.py edit m.wav p.wav --op pitch --value -5
{"ok": true, "out": "p.wav", "route": "varispeed", "flags": ["NOISE_FLOOR"]}
$ echo $?
0

Environment variables

Name	Does
SFX_COMFY_URLS	comma list of ComfyUI addresses for doctor and gen
SFX_MW	where mw.py is, when musicwright is not found by itself
ELEVENLABS_API_KEY	doctor reports whether it is set

The first project

$ python sfx.py init sounds.json --project demo --use game --commercial yes
{"ok": true, "list": "sounds.json"}
$ echo $?
0
$ python sfx.py add sounds.json step --event "player walks" --kind one-shot --length 0.4 --variations 6 --route synth:footstep --category foley/steps
{"ok": true, "id": "step", "count": 1}
$ echo $?
0
$ python sfx.py status sounds.json
step                   one-shot  planned    0/6  synth:footstep
$ echo $?
0

The wind row comes from a second add, shown on Sound list format. Next: Workflows.