Sound List Format

sounds.json is schema 1 and is the contract with other plugins: they read the file and never import each other. It changes only with a schema bump.

What init and add write

$ python sfx.py add sounds.json wind --event "cave bed" --kind loop --length 6 --route gen:sa3-medium
{"ok": true, "id": "wind", "count": 2}
$ cat sounds.json
{
 "schema": 1,
 "project": "demo",
 "use": "game",
 "commercial": true,
 "frame_rate": null,
 "style": "",
 "created": "2026-11-07",
 "sounds": [
  {
   "id": "step",
   "event": "player walks",
   "kind": "one-shot",
   "category": "foley/steps",
   "brief": "",
   "layers": [],
   "variations": 6,
   "length_s": 0.4,
   "loudness": "",
   "format": "wav",
   "route": "synth:footstep",
   "status": "planned",
   "takes": []
  },
  {
   "id": "wind",
   "event": "cave bed",
   "kind": "loop",
   "category": "",
   "brief": "",
   "layers": [],
   "variations": 1,
   "length_s": 6.0,
   "loudness": "",
   "format": "wav",
   "route": "gen:sa3-medium",
   "status": "planned",
   "takes": []
  }
 ]
}

Fields

Required per sound: id, event, kind, variations, length_s, format, route, status.

• kind: one-shot, loop, ambience, sequence, stinger, ui.
• status: planned, rendered, picked, finished, rejected. register moves a planned sound to rendered.
• Optional: category, brief, layers, loudness, at_s, sync_point_s, sync_class, role, trigger, priority, max_instances, spatial, randomize, load.

A take holds file, sha256, picked, heard, processing and source. heard starts empty: nothing fills it but a person's verdict.

Sidecars

Every made file gets <file>.sfx.json. Edits carry the parent's source forward and add a step. This is a pitch edit of a synth creak:

$ cat e_pitch.wav.sfx.json
cat: e_pitch.wav.sfx.json: No such file or directory

A file mixed from several sources, such as a sequence, holds a list in source.

Do not copy or rename a sound by hand. The sidecar stays behind, and the copy registers as unknown licence, which blocks a commercial project. Write to the final name with edit, finish or synth --out.

register stores the hash, and ship blocks if the file later changes. See Rights and shipping.