1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
//! 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`) · [`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 only); the heavy deps are optional,
//! behind features (both on by default): `analysis` pulls in rustfft + image for
//! [`analysis`]/[`review`], and `sampler` pulls in rustysynth for the SoundFont
//! sampler instrument. So the same core compiles to a native binary, a WASM
//! playground, 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).
//!
//! [cookbook]: https://github.com/marmikshah/tono/blob/master/docs/cookbook.md
//! [architecture guide]: https://marmikshah.github.io/tono/architecture.html
/// 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 nineteen modules.