Crate tono_core 

Tono core — the pure, headless audio engine.

This crate is the deterministic heart of tono with no I/O and no transport. Rendering is a pure function of (graph, seed, sample_rate) → byte-identical audio, so a sound is data you can test, diff, and cache:

use tono_core::dsl::SoundDoc;
use tono_core::render;

let doc: SoundDoc = serde_json::from_str(r#"{
    "name": "blip", "duration": 0.3, "engine": 4,
    "root": { "type": "mul", "inputs": [
        { "type": "sine", "freq": 880 },
        { "type": "env", "a": 0.002, "d": 0.08, "s": 0.0, "r": 0.05 } ] }
}"#).unwrap();

let a = render::render(&doc);
let b = render::render(&doc);
assert_eq!(a, b); // byte-identical every run

The map

Authoring: dsl (the SoundDoc graph + validation) · patch (templates with named parameters) · edit (path-addressed edits) · vary (deterministic variations).

Rendering: render (the offline bounce) · streaming (real-time, byte-identical to the bounce) · dsp (RNG, loudness, limiting) · player (buffer playback).

Playing live: runtime (the runtime::AudioSource seam, Engine, Mixer, the wait-free split) · instrument (polyphonic playable voices) · drumkit · adaptive (intensity stems, quantized transitions, stingers).

Composing: song (tracks/patterns/arrangement, compiles to a plain SoundDoc) · music (pitches, intervals, scales, keys, chords) · catalog + presets (ready-made voices).

Feedback: analysis (stats + spectrogram/waveform images) · review (grade a sound against its archetype).

Features and the shell

The lean build is pure compute (serde + rustfft for the convolve node’s FFT convolution); the heavy deps are optional, behind features (both on by default): analysis pulls in image for analysis/review PNGs, and sampler pulls in rustysynth for the SoundFont sampler instrument. So the same core compiles to a native binary or a lean in-engine runtime. The tono render CLI, audio-file encoders, and MIDI export live in the tono shell crate that depends on this one.

Longer-form guides: the cookbook (the node vocabulary + recipes) and the architecture guide (how the pieces compose, bottom-up).

Modules

adaptive

adaptive — reactive music for games.

analysis

Audio analysis: level/spectral stats, a spectrogram PNG, and a waveform PNG.

catalog

catalog — a library of ready-to-play instruments.

diag

Structured diagnostics for song compilation (ADR 0003).

drumkit

drumkit — a playable drum kit.

dsl

The Tono synthesis-graph DSL.

dsp

Small shared DSP core: the deterministic PRNG, dB conversions, and the output peak limit. One copy of each — these protect the project’s determinism contract (same graph + seed ⇒ identical bytes), so they must never fork per module.

edit

Surgical, path-addressed edits to a sound graph.

ids

Stable identifier newtypes for the compiled program (ADR 0003).

instrument

instrument — a playable, pitched, polyphonic instrument built from a patch.

music

music — harmony: pitches, intervals, scales, keys, chords, and voicings.

patch

Parametric patches — the in-engine runtime.

player

Real-time audition: a Player that serves a document’s audio in blocks to an audio callback (a native cpal stream, or a browser AudioWorklet).

prelude

The workhorse names in one import: use tono_core::prelude::*; covers the primary flow (author a doc or a song::Song, render it, analyze it, play it) without hunting across the crate’s twenty-two modules.

presets

presets — a factory bank of ready-to-play instruments.

program

program — the immutable result of compiling a Song (ADR 0003).

render

Deterministic graph → samples renderer.

review

Deterministic sound review: grade a rendered sound against archetype targets plus a universal ship checklist, emitting actionable findings.

runtime

runtime — the embeddable real-time control surface over the deterministic engine.

song

song — compose a full piece by adding instruments and arranging parts.

streaming

streaming — a stateful, block-by-block renderer for the causal subset of the graph.

units

Typed units and exact musical time for the composition/compile layer (ADR 0002).

vary

Variation tools: derive new takes from an existing sound.