{"id":51608516,"url":"https://github.com/marmikshah/tono","last_synced_at":"2026-07-12T04:02:18.114Z","repository":{"id":363085024,"uuid":"1261897888","full_name":"marmikshah/tono","owner":"marmikshah","description":"A deterministic synthesis-graph audio engine in Rust — author sounds and songs as data, render byte-identical audio, edit them live. Library + CLI + a native pattern-station studio. Fully synthetic: instruments, drum kits, effects, and built-in analysis — no samples.","archived":false,"fork":false,"pushed_at":"2026-07-10T07:52:10.000Z","size":18446,"stargazers_count":2,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-07-10T09:11:11.998Z","etag":null,"topics":["audio","audio-engine","chiptune","daw","dsp","gamedev","music","procedural-audio","rust","sound-design","sound-synthesis","step-sequencer","synthesis"],"latest_commit_sha":null,"homepage":"https://marmikshah.github.io/tono/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/marmikshah.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-07T09:55:17.000Z","updated_at":"2026-07-10T07:50:36.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/marmikshah/tono","commit_stats":null,"previous_names":["marmikshah/sonarium","marmikshah/tono"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/marmikshah/tono","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marmikshah%2Ftono","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marmikshah%2Ftono/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marmikshah%2Ftono/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marmikshah%2Ftono/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marmikshah","download_url":"https://codeload.github.com/marmikshah/tono/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marmikshah%2Ftono/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35381310,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-12T02:00:06.386Z","response_time":87,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["audio","audio-engine","chiptune","daw","dsp","gamedev","music","procedural-audio","rust","sound-design","sound-synthesis","step-sequencer","synthesis"],"created_at":"2026-07-12T04:02:17.429Z","updated_at":"2026-07-12T04:02:18.108Z","avatar_url":"https://github.com/marmikshah.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/logo.png\" width=\"112\" alt=\"tono — a pluck waveform on a dark tile\"\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/logo-wordmark.png\" width=\"384\" alt=\"tono\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\u003cstrong\u003eGame audio as a pure function — procedural, deterministic, zero-asset.\u003cbr\u003eAuthor a synthesis graph; get byte-identical audio from Rust, Python, a CLI, or a live keyboard.\u003c/strong\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/marmikshah/tono/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/marmikshah/tono/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://crates.io/crates/tono-core\"\u003e\u003cimg src=\"https://img.shields.io/crates/v/tono-core\" alt=\"crates.io\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/license-MIT-8c6ee6\" alt=\"license\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/river-flows-spectrogram.png\" width=\"640\" alt=\"spectrogram of River Flows in You, 800 notes on the sampled piano\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\u003cem\u003eEverything you can hear below was rendered by this engine — no samples, no WAVs shipped.\u003c/em\u003e\u003c/p\u003e\n\n## Hear it\n\nRecognizable classics rebuilt from scratch — the ▶ links play right on GitHub:\n\n| Sound | Play | The trick |\n|---|---|---|\n| retro-coin | [▶](docs/examples/audio/retro-coin.mp4) | B5 grace note into a held E6 — the interval *is* the sound |\n| jump-8bit | [▶](docs/examples/audio/jump-8bit.mp4) | exponential square sweep, gone at sustain 0 |\n| waka | [▶](docs/examples/audio/waka.mp4) | per-note pitch slides alternating up/down — the chomp drawn into the notes |\n| nokia-tune | [▶](docs/examples/audio/nokia-tune.mp4) | 13 notes of Gran Vals on the Karplus-Strong pluck |\n| deep-note | [▶](docs/examples/audio/deep-note.mp4) | supersaw tracks gliding from a scattered cluster onto a five-octave D chord |\n| river-flows-in-you | [▶](docs/examples/audio/river-flows-in-you.mp4) | a complete piano piece — 800 notes on the sampled grand |\n| band-demo | [▶](docs/examples/audio/band-demo.mp4) | four instruments, one groove, mixed on the stereo bus |\n\nMore in [docs/examples/audio/](docs/examples/audio/) — game-ready BGM loops and\nambient beds, all deterministic renders.\n\n## What it is\n\nA sound in tono is a **symbolic graph** (oscillators → envelopes → filters →\neffects → mix); rendering it is a **pure function of `(graph, seed, sample_rate)`\n→ byte-identical audio**. The same document sounds identical offline, streamed\nin real time, or played as an instrument — so audio becomes something you can\n**test, diff, cache, and ship without asset files**.\n\n- **Instruments \u0026 songs** — a polyphonic sequencer, an 11-preset factory bank, a\n  GM drum kit, catalog voices (piano, bass, guitar, strings…), and a fluent\n  `Song` API that compiles to a plain document.\n- **Game runtime** — an embeddable `Engine`/`Mixer` with **live DSP buses**\n  (reverb/EQ/compressor inserts + sends), **voice management** (polyphony caps,\n  priority stealing), and **interactive music** (beat-quantized section switches,\n  intensity layers, stingers on the downbeat).\n- **Zero-asset SFX** — a `Patch` renders infinite per-instance variations from\n  named parameters (`hardness`, `size`, …). Impact sounds that scale with\n  collision force, no sample library.\n- **An ear for critique** — LUFS/peak/spectral stats plus spectrogram + waveform\n  images per render, so \"does it sound right?\" becomes numbers and pictures.\n- **SoundFont sampler** — point the `sampler` voice at any free GM bank for real\n  recorded instruments, still deterministic.\n\n## Quick start\n\n```sh\ncargo install tono       # the `tono render` CLI\ncargo add tono-core      # …or the engine as a library (games, tools)\n```\n\nRender a document and look at what came back:\n\n```sh\ntono render docs/examples/blip.json -o out/\n#   out/blip.wav          the audio            (--format wav|flac|ogg)\n#   out/blip.png          the spectrogram      ← look at this\n#   out/blip_wave.png     the waveform         ← and this\n#   out/blip.stats.json   peak / RMS / LUFS / spectral / transient analysis\n```\n\nThat loop — emit a doc, render, read the images + stats, refine — is all a\nhuman *or an agent* needs to author sound by inspection.\n\n\u003e Sampled instruments need a free General MIDI SoundFont once (FluidR3 GM,\n\u003e GeneralUser GS): `wave: \"sampler\", sf2: \"/path/to/gm.sf2\", sf2_preset: 0`.\n\n## One engine, five faces\n\nEvery face renders the same `SoundDoc` byte-identically — pick the surface that\nfits your workflow. New to the codebase? Start with the\n[architecture \u0026 getting-started guide](https://marmikshah.github.io/tono/architecture.html).\n\n| Face | What it is | Entry point |\n|---|---|---|\n| CLI | render → audio + spectrogram + stats | `tono render f.json -o out/` |\n| Rust library | the engine embedded in a game or tool | `cargo add tono-core` |\n| Python bindings | live engine + deterministic numpy renders | `make python` |\n| Pattern station | Tauri app: FL-style step grid, live audio, undo | `make desktop` |\n| Playground | hear Rust snippets through the speakers | `make play EXAMPLE=band` |\n\n## Use it from Rust\n\n```rust\nuse tono_core::dsl::SoundDoc;\nuse tono_core::render;\n\nlet doc: SoundDoc = serde_json::from_str(r#\"{\n    \"name\": \"blip\", \"duration\": 0.3, \"engine\": 4,\n    \"root\": { \"type\": \"mul\", \"inputs\": [\n        { \"type\": \"sine\", \"freq\": 880 },\n        { \"type\": \"env\", \"a\": 0.002, \"d\": 0.08, \"s\": 0.0, \"r\": 0.05 } ] }\n}\"#)?;\n\nlet samples: Vec\u003cf32\u003e = render::render(\u0026doc); // byte-identical every run\n```\n\n### Game audio, in a few lines each\n\n```rust\nuse tono_core::runtime::{Engine, Mixer, Priority};\n\n// Voice management: a budget + priorities, and a bullet-hell scene stays clean.\nlet mut engine = Engine::new(48_000);\nengine.set_max_voices(32);\nengine.play_looping_prioritized(music, Priority::CRITICAL); // never stolen\nengine.play_prioritized(explosion, Priority::HIGH);\nengine.play(footstep);                                      // stolen first\n\n// Live DSP buses: inserts and sends, reusing the streaming effect kernels.\nlet mut mixer = Mixer::new_at(48_000);\nlet sfx = mixer.bus(\"sfx\");\nlet reverb = mixer.fx_bus(\"reverb\", vec![reverb_node])?;\nmixer.set_send(sfx, reverb, 0.9);\n```\n\n```rust\nuse tono_core::adaptive::{AdaptiveMusic, Quantize};\n\n// Interactive music: react on the beat, like a film score.\nlet mut music = AdaptiveMusic::new(48_000);\nmusic.set_tempo(120.0, 4);\nmusic.add_section(\"explore\", \u0026explore_doc);\nlet battle = music.add_section(\"battle\", \u0026battle_doc);\nmusic.transition_to(battle, Quantize::Bar);  // swaps on the next bar\nmusic.set_intensity(0.9);                    // stems swell with the action\nmusic.stinger_at(\u0026boss_hit, Quantize::Bar);  // lands on the downbeat\n```\n\n## Use it from Python\n\nThe same engine as a Python extension (`crates/tono-py`) — live procedural\naudio for Pygame / Ren'Py / Arcade, or deterministic numpy renders for anything:\n\n```python\nimport tono\n\nengine = tono.Engine(48000)            # owns the output stream + render thread\nengine.drumkit().note_on(36, 1.0)      # kick — the audio thread never touches Python\nengine.instrument(\"warm_lead\").note_on(\"C4\", 0.9)\n\nimpact = engine.load_patch(open(\"impact.patch.json\").read())\nimpact.trigger(hardness=0.8, size=0.3) # zero baked WAVs\n\n# …or pull deterministic numpy arrays (testable in CI):\nbuf = tono.Patch(open(\"impact.patch.json\").read()).render(hardness=0.7)\n```\n\nBuild it with `make python` (maturin; abi3 wheels for 3.9+ build in CI).\n\n## Determinism\n\nThe real-time streaming path is byte-identical to an offline bounce (verified\nby a fuzzer in CI), and byte-changing kernel upgrades are gated behind a\ndocument `engine` revision, so old sounds never change. A golden corpus pins\nrepresentative renders in CI. Render the same document twice, get the same bytes\n— which is what makes audio testable, diffable, and cacheable.\n\n## Learn more\n\n- [Architecture \u0026 getting started](https://marmikshah.github.io/tono/architecture.html) —\n  the smallest unit (a node) and the ladder up to a full game soundtrack.\n- [docs/cookbook.md](docs/cookbook.md) — the `SoundDoc` DSL, node vocabulary,\n  instrument table, worked recipes (validated in CI).\n- [docs/runtime.md](docs/runtime.md) — embedding the engine + parametric patches.\n- [docs/ROADMAP.md](docs/ROADMAP.md) — where 2.0 is headed.\n- `make help` — every target; `make verify` mirrors CI.\n\n## A personal note\n\nEvery line of code in tono was written by AI. I didn't write a single line\nmyself — my part was direction: deciding what to build, and holding the\nproject to the same practices and standards I use in the projects where I do\nstill write the code.\n\nIf tono helps you in any way — as a game-audio tool, a reference, or just a\nkick-start on your own project — that makes me genuinely happy. The tokens are\nalready spent; the least they can do is be useful to you too.\n\n\u003e **⚠️ Notice — versions below 2.0.0**\n\u003e\n\u003e I intend to follow SemVer, but be realistic about what this project is:\n\u003e AI-generated code. Diffs are large, and every release below 2.0.0 may\n\u003e contain breaking changes despite my best intentions.\n\u003e\n\u003e Once the tool has proven itself, I will cut a 2.0.0 release — that is the\n\u003e point where I start reviewing the code in detail and contributing to it\n\u003e directly. 2.0.0 will be tagged by me, by hand — it is the one release an AI\n\u003e agent is not allowed to cut. Until then, assume that anything below 2.0.0\n\u003e has not been fully reviewed by me and may contain bugs or security issues I\n\u003e haven't caught.\n\u003e\n\u003e Use at your own risk.\n\n## License\n\n[MIT](LICENSE) — permissive, no warranty.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarmikshah%2Ftono","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarmikshah%2Ftono","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarmikshah%2Ftono/lists"}