Errors and Edge Cases

Exact messages from sfx.py 0.1.8. Most are one JSON line with "ok": false and exit 1.

Surprises

finish corrects a wrong extension

A .wav output name with an OGG destination writes .ogg. Read out in the answer, not the name you passed:

$ python sfx.py finish bed_loop.wav out2.wav --dest web --keep-ends
{"ok": true, "out": "out2.ogg", "dest": "web", "peak_ceiling_db": -3.0, "sr": 44100, "format": "ogg", "note": "a file-level peak reference, not a delivery spec; balance the whole project by ear"}
$ head -c 4 out2.ogg; echo; ls out2*
OggS
out2.ogg
out2.ogg.sfx.json

A wrong parameter type names the parameter

explosion's distance is a number. A word fails with the parameter's name:

$ python sfx.py synth explosion --param distance=far --out x.wav
{"ok": false, "error": "explosion: a --param has the wrong name or type, given ['distance']; see references/routes.md"}
$ echo $?
1
$ python sfx.py synth explosion --param distance=2 --out boom.wav
{"ok": true, "files": ["boom.wav"]}
$ echo $?
0

Flags and BLOCKED exit 0

See Commands. A script that gates on the exit code passes a blocked project.

edit --op gain with no value still succeeds

$ python sfx.py edit creak.wav e_x.wav --op gain
{"ok": true, "out": "e_x.wav", "route": "gain", "flags": []}
$ echo $?
0

ffmpeg's own error can come through

When --ir names a missing file, the message is ffmpeg's text inside error, not a check of the path by sfx.py.

Command line

Argparse errors go to exit 2 with usage:

$ python sfx.py
usage: sfx.py [-h] [--version]
              {doctor,init,add,validate,status,plan,synth,gen,library,register,check,tone,pop,set,timing,degrade,edit,layer,vary,sequence,loop,record-sheet,place,finish,name,sheet,review,doc,ship,budget} ...
sfx.py: error: the following arguments are required: cmd
$ echo $?
2

Sound lists

$ python sfx.py init sounds.json --project demo --use game --commercial yes
{"ok": false, "error": "sounds.json exists; pass --force to replace it"}
$ echo $?
1
$ python sfx.py add sounds.json step --event "again" --kind one-shot --length 0.4
{"ok": false, "error": "step is already in the list"}
$ echo $?
1
$ python sfx.py ship missing.json
{"ok": false, "error": "no sound list at missing.json; run: sfx.py init missing.json"}
$ echo $?
1

Recipes

$ python sfx.py synth nosuch --out x.wav
{"ok": false, "error": "unknown recipe nosuch; have beep, click, creak, explosion, fire, footstep, modal, retro, shaker, switch, whoosh, wind"}
$ echo $?
1
$ python sfx.py synth modal --param material=cheese --out x.wav
{"ok": false, "error": "material must be one of glass, metal, plastic, stone, wood"}
$ echo $?
1
$ python sfx.py synth retro --param kind=zap --out x.wav
{"ok": false, "error": "retro kind must be coin, laser, jump, hit, explode, powerup or blip"}
$ echo $?
1

Files and sets

$ python sfx.py check missing.wav
{"ok": false, "error": "file not found: missing.wav"}
$ echo $?
1
$ python sfx.py check
{"ok": false, "error": "nothing to check"}
$ echo $?
1
$ python sfx.py set wood.wav
{"ok": false, "error": "a set needs at least two files"}
$ echo $?
1

Finish and rights

$ python sfx.py finish wood.wav f.wav --dest podcast
{"ok": false, "error": "unknown destination podcast; have film, game-ambience, game-foley, game-sfx, library, roblox, unity, web"}
$ echo $?
1
$ python sfx.py library nd.wav --licence cc-by-nc --title "No author"
{"ok": false, "error": "this licence needs credit: pass --author"}
$ echo $?
1

Names

name --check tests only the shape. crate fails it and the UCS-shaped name is not listed:

$ python sfx.py name --check crate.wav "WOODImpt_Crate Drop_ME_GAME.wav"
{"ok": false, "not_ucs_shape": ["crate"], "note": "this checks the shape; the CatID list is at universalcategorysystem.com"}
$ echo $?
1

Not tested

• gen against a live ComfyUI, and any hosted API.
• Non-WAV input.
• Any transcript on Linux or macOS. The tests run there in CI.