Glossary

Short definitions for the terms used across Soundef docs. Deep detail lives in the Spec.

Soundef: the declarative format (.soundef) and the project. A .soundef file describes the behavior of a game sound when triggered, not a fixed audio file.

Forge: the desktop app that edits, previews, bakes, and shares .soundef files. See Getting Started.

.soundef file: a YAML 1.2 document (JSON is valid too) with name, version: 0, and layers. See Spec.

Layer: one lane of a sound, under layers.<name>. Each layer picks and places one file per trigger. Layer order is the timeline display order. See Layers.

Source: a file path in a layer's sources list, relative to the project sounds/ folder (bare, sounds/-only, no ../ or /absolute). Basename globs (*, ?) are allowed. See Sources.

Selection: how a layer chooses among its sources per trigger: random (uniform) or sequence (round-robin). avoidRepeat prevents recent repeats in random mode. See Selection.

Probability: the chance a layer plays at all (0..1), rolled per trigger, per layer. A failed roll marks the layer skipped.

offset: time from the event trigger to a layer's start, in milliseconds. Distinct from a DSP delay line. See the FAQ.

gain: a layer's level in decibels. 0dB = unity; negative = quieter. Converted to linear as 10^(dB/20) at playback.

pitch: a layer's pitch shift in semitones. 12st = one octave. Converted to a rate as 2^(st/12); source duration scales with it.

Value forms: offset/gain/pitch accept a scalar with unit ("-2dB"), a bare number (implicit unit, warns), or a randomRange: [min, max] lerped per trigger. See Value forms.

randomRange: { randomRange: [min, max] }. A uniform pick between two bounds (same unit both ends) chosen per trigger with the layer's RNG.

seed: a string | number that drives all randomness. Same definition + same seed → same result. See Determinism.

Determinism: definition + seed → the same PlaybackPlan, always, on every platform. Enables reproducible variation.

Isolated RNG: each layer uses its own random stream seeded seed + "#" + layerName, so changing one layer never shifts another's rolls. Effects use #reverb/#delay/#limiter streams. See Integration.

PlaybackPlan: the resolved plan for a seed: a JSON object with name, seed, layers (concrete source + offset ms + gain dB + pitch st), and optional effects. See Integration: The PlaybackPlan.

ResolvedLayer: one entry in a plan's layers: source, offset (ms), gain (dB), pitch (st), and optional skipped.

skipped / ghost: a layer whose probability roll failed. Kept in the plan (skipped: true) so the timeline can draw it as a dashed ghost; playback and bake ignore it.

Effects: an optional, Forge-only effects block (reverb, delay, limiter). Baked render includes it; a live runtime may skip it. Users may implement it. See Effects.

forge-only: a warning for effects.* keys: ignored live, baked only. Unknown keys inside effects are allowed and surface as this warning, not an error.

Bake: render a .soundef + seed to a plain wav in baked/. A baked file needs no runtime: useful for A/B against live, or shipping without a Soundef runtime. See Bake.

Pack: a .zip (Export Pack / Import Pack) bundling soundefs/*, sounds/**, an optional preview, and a manifest.json (version: 0) for sharing a project.

Diagnostic: a { severity, message, code, range } note from parse/resolve. error blocks the plan; warning still plays. See Diagnostics.

Runtime: an engine-side implementation that plays a PlaybackPlan (Godot/Unity/Unreal/Bevy/web). Optional: Forge can bake to wav instead. See Integration.

Glossary ​

See also ​

Glossary

See also