Struct SoundDoc 

pub struct SoundDoc {
    pub name: String,
    pub duration: f32,
    pub sample_rate: u32,
    pub seed: u64,
    pub version: Option<u32>,
    pub engine: Option<u32>,
    pub stereo: Stereo,
    pub normalize: Option<Normalize>,
    pub playback: Playback,
    pub root: Node,
}

A complete sound: metadata plus a single root node.

Fields

name: String

Human-readable label for the sound (e.g. "laser_zap").

duration: f32

Length of the rendered sound in seconds.

sample_rate: u32

Output sample rate in Hz.

seed: u64

Seed for any stochastic node (noise). Same seed ⇒ identical audio.

version: Option<u32>

DSL schema version. Omitted ⇒ 1, the semantics documents were authored under before versioning mattered; the authoring tools stamp new documents with the current SCHEMA_VERSION. Documents from a newer tono are rejected by validate instead of silently misrendered.

engine: Option<u32>

DSP-kernel revision (see ENGINE_VERSION). Omitted ⇒ 0, the original kernels — so every existing document renders byte-for-byte as before. The authoring tools stamp new documents with the current ENGINE_VERSION; raising a document’s engine opts it into newer, higher-quality kernels (anti-aliased drive, …) and DOES change its output. A document from a newer tono (engine > ENGINE_VERSION) is rejected by validate rather than silently misrendered.

stereo: Stereo

Optional stereo treatment applied to the final mono render. Defaults to mono (game SFX are usually authored mono and spatialised by the engine; use stereo for BGM, ambience, and UI stingers).

normalize: Option<Normalize>

Optional output-stage loudness normalization + true-peak limiting. When set with target_lufs, the final render is gain-matched to that integrated loudness, then brick-wall limited so the inter-sample (true) peak never exceeds ceiling_dbtp. Leave unset for the default behaviour (a transparent −0.1 dBFS sample-peak safety limit only). Use it to ship a level-matched set: pick one target (e.g. −16 LUFS for SFX) for the pack.

playback: Playback

Playback intent. oneshot (default) renders the sound as-is. loop extracts the loop region and equal-power crossfades its tail into its head so the rendered file repeats seamlessly — the right mode for ambience beds, engine drones, and BGM. The exported WAV carries a smpl loop chunk so engines (Godot / Unity / FMOD) loop at the sample-accurate points without manual setup.

root: Node

The signal graph. Usually a mix, mul, or chain.

Implementations

impl SoundDoc

pub fn validate(&self) -> Result<(), ValidateError>

Validate ranges and structure beyond what serde already enforces. The error’s message is human-readable and names the offending field.

impl SoundDoc

pub fn new(name: impl Into<String>, root: Node) -> Self

A new document around root, stamped with the current SCHEMA_VERSION and ENGINE_VERSION (this is the authoring constructor — new sounds get the current kernels) and every other field at its serde default: 0.3 s, 44 100 Hz, seed 0, mono, one-shot.

impl SoundDoc

pub fn effective_version(&self) -> u32

The schema version this document’s render semantics follow (omitted ⇒ 1).

pub fn effective_engine(&self) -> u32

The DSP-kernel revision this document renders under (omitted ⇒ 0, the original kernels). Gates byte-changing kernel upgrades so old documents stay bit-exact; see ENGINE_VERSION.

pub fn sf2_paths(&self) -> Vec<&str>

Every SoundFont path the document references (each seq with wave: "sampler" and a non-empty sf2). validate is filesystem-free — the core is pure compute — so a loader (the CLI, the Python bindings, a game’s asset pipeline) calls this after validation to check the files exist and fail loud at load time.

pub fn ensure_track_ids(&mut self) -> bool

Backfill missing track ids deterministically (layer_<position>, suffixed on collision with explicit ids). Runs at the build chokepoint so every persisted mixer document carries addressable layers; the rule is positional, so replaying a journal mints identical ids. Returns true if anything changed.

Trait Implementations

impl Clone for SoundDoc

fn clone(&self) -> SoundDoc

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SoundDoc

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for SoundDoc

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl From<SoundDoc> for Patch

fn from(doc: SoundDoc) -> Self

Converts to this type from the input type.

impl JsonSchema for SoundDoc

fn schema_name() -> Cow<'static, str>

The name of the generated JSON Schema.

fn schema_id() -> Cow<'static, str>

Returns a string that uniquely identifies the schema produced by this type.

fn json_schema(generator: &mut SchemaGenerator) -> Schema

Generates a JSON Schema for this type.

fn inline_schema() -> bool

Whether JSON Schemas generated for this type should be included directly in parent schemas, rather than being re-used where possible using the $ref keyword.

impl Serialize for SoundDoc

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.