Workflows

Each workflow ran as shown. None of the results has been listened to, so each ends with a listen you still owe.

A variation set from several takes

Separate takes differ more than pitch-shifted copies of one take. See what set misses.

$ 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"}

Then listen to them level-matched with review --match.

A loop

$ python sfx.py loop bed.wav bed_loop.wav --crossfade 1.5
{"ok": true, "out": "bed_loop.wav", "seconds": 6.5, "seam": 0.16, "seam_via": "mw.py", "seam_spectral": 0.93, "flags": [], "note": "use WAV or OGG: MP3 padding breaks loops"}
$ echo $?
0
$ python sfx.py check bed_loop.wav --loop
bed_loop.wav  6.500s sound 6.501s peak -3.1 rms -16.3 attack 2141ms tail 4.36s floor -19 click 3.6 seam 0.2  ok
0 of 1 flagged; a flag means listen, not reject
$ echo $?
0
$ python sfx.py finish bed_loop.wav out.ogg --dest game-ambience --keep-ends
{"ok": true, "out": "out.ogg", "dest": "game-ambience", "peak_ceiling_db": -14.0, "sr": 48000, "format": "ogg", "note": "a file-level peak reference, not a delivery spec; balance the whole project by ear", "warning": "upsampled from 44100 Hz; that adds no quality"}
$ echo $?
0

--keep-ends skips the trim and fades that would break the loop. The seam score does not replace a listen: a planted seam passed it.

A film cue placed by its sync point

place needs each file at its sample rate, so finish first. A sound at 44.1 kHz stops it with hit.wav is 44100 Hz; finish to 48000 first.

$ python sfx.py finish hit.wav hit48.wav --dest film
{"ok": true, "out": "hit48.wav", "dest": "film", "peak_ceiling_db": -1.0, "sr": 48000, "format": "wav", "note": "a file-level peak reference, not a delivery spec; balance the whole project by ear", "warning": "upsampled from 44100 Hz; that adds no quality"}
$ echo $?
0
$ python sfx.py init film2.json --project p --use film --commercial no --frame-rate 24
{"ok": true, "list": "film2.json"}
$ python sfx.py add film2.json door --event slam --kind one-shot --length 0.1 --at 2.5 --sync-point 0.0
{"ok": true, "id": "door", "count": 1}
$ python sfx.py register film2.json door hit48.wav
{"ok": true, "id": "door", "added": ["hit48.wav"], "warning": "no known licence: hit48.wav"}
$ python sfx.py place film2.json --out timeline.wav
{"ok": true, "fps": 24.0, "placed": [{"id": "door", "start_s": 2.5, "anchor": "sync_point_s", "peak_vs_anchor_frames": 0.0, "over_limit": false, "gain_db": 0.0}], "out": "timeline.wav", "note": "the peak is a measured stand-in for sync; check with picture"}
$ echo $?
0

The cue sheet, as Markdown or CSV:

$ python sfx.py doc film.json --kind cue
| Cue | Time | Frame | Sound | Role | Sync | Kind | Length s | File | Status |
|---|---|---|---|---|---|---|---|---|---|
| door | 2.500 | 60 | slam |  |  | one-shot | 0.1 | hit.wav | rendered |
$ echo $?
0
$ python sfx.py doc film.json --kind cue --format csv
Cue,Time,Frame,Sound,Role,Sync,Kind,Length s,File,Status
door,2.500,60,slam,,,one-shot,0.1,hit.wav,rendered
$ echo $?
0

A game event sheet and a size estimate

doc --kind impl starts pitch and volume at conventions, labelled as start points. budget is an estimate.

$ python sfx.py budget film.json
{"ok": true, "categories": {"one-shot": {"files": 1, "disk_kb": 51, "pcm_kb": 34, "adpcm_kb_est": 9}}, "savings": [], "note": "estimates: ADPCM is about 3.5:1 of 16-bit PCM; compare with a real engine import before quoting"}
$ echo $?
0

Before anything ships

1. check every batch, set every variation set, timing every sequence.
2. Listen. Record what was heard in the take's heard field and mark the pick picked: true.
3. finish, then doc --kind credits, then ship. Read answer, because the exit code stays 0.