Soundef

Appearance

Troubleshooting ​

Task-oriented fixes for common problems. Every symptom maps to a diagnostic code or a behavior described in the Spec. For the full code list, see Diagnostics.

A layer is silent ​

  • The layer was skipped. If the layer has probability below 1, its per-trigger roll may have failed - the resolved layer is marked skipped: true and does not play. Try a different seed, or raise probability. Forge shows skipped layers as dashed ghosts on the timeline.
  • The source resolved to zero files. A glob that matches nothing emits unresolved-source (warning) and, if a layer ends up with no sources, no-sources (error, blocks the plan). Check the basename glob against your sounds/ folder.
  • Gain is very low. A large negative gain (e.g. -20dB) is nearly inaudible. Confirm the value and unit.

A glob matches 0 files (unresolved-source) ​

  • Globs only work in the basename (last path segment): swords/body_*.wav is fine, swords/*/*.wav and **/*.wav are rejected as invalid-source.
  • The path is relative to the project sounds/ folder. swords/body_01.wav means MyProject/sounds/swords/body_01.wav (your project folder). See Sources.
  • At resolve time, pass your sounds/ listing so globs can expand; without it, patterns stay literal and warn unresolved-source. See Integration: Pipeline.

A path is rejected (path-outside-sounds / invalid-source) ​

Sources are hard sounds/-only and portable:

  • path-outside-sounds - you used a /absolute path or a leading /. Use a bare path like swords/body_01.wav.
  • invalid-source - you used .., **, a directory glob (*/), or a backslash \. None can escape the project root.

The sounds/ prefix alias is allowed and normalized: sounds/swords/body_01.wav is the same file as swords/body_01.wav.

A unit error blocks the plan ​

  • x-soundef-sameUnit - a randomRange has different units on each end, e.g. [-2dB, 5ms]. Both ends must share the unit.
  • unit-mismatch - the range unit does not match the field. gain wants dB, offset wants ms, pitch wants st.
  • invalid-unit - a scalar string is not a recognized form like -2dB, 17ms, -2st, 1.5s.

See Units for the full rules.

I get an implicit-unit warning ​

You used a bare number where a unit is canonical, e.g. gain: 1. It still plays (as 1dB), but the canonical form is gain: 1dB. This keeps old files working instead of failing. Add the unit to clear the warning.

Decode fails / unsupported-format ​

  • Any extension passes the schema, but Forge warns unsupported-format for files outside the supported set. First-class: wav, ogg, oga, opus, mp3, flac, aif, aiff; best-effort: m4a, aac, webm.
  • If a layer's file cannot be decoded, bake skips that layer with a warning. Convert the file to a supported format.

The bake clips (red dot) ​

  • A persistent red clip dot on the final waveform + a bake-clipped warning means the render peaked over 0dB. A hard limiter at -0.1dB prevents the file itself from clipping, but the mix is too hot.
  • Fix: lower a layer's gain and re-bake, or add an effects.limiter bus (see hammer_limited).
  • Normalize -1dB scales the baked buffer explicitly and clears the dot.

External edits are not loading (dirty banner) ​

There is no auto-save. When another program writes the .soundef on disk:

  • If your editor is clean, Forge reloads the file.
  • If your editor has unsaved changes, Forge shows a banner changed on disk - [Load] [Keep mine]. Preview keeps running from your editor until you choose. Select Load to use the disk file or Keep mine to keep your edits. See the FAQ.

The watcher is not firing at all ​

The watcher runs on sounds/* and soundefs/* with a 120ms debounce, and only when a valid project is open. Confirm you opened your project folder (any name) that has both sounds/ and soundefs/ siblings (lowercase).

version errors (unknown-version / missing-required) ​

  • version must be exactly 0. Any other value fails with unknown-version.
  • name, version, and layers are all required - a missing one is missing-required.

unknown-property ​

You used a key that is not allowed at the top level or inside a layer. The only place unknown keys are tolerated is inside effects, where they surface as forge-only warnings (ignored live, baked only), not errors.

See also ​

Soundef — declarative SFX behavior