From 16f4b4a80512d142f6c0ae3a4b8fc104386bed48 Mon Sep 17 00:00:00 2001 From: Dejvino Date: Sat, 24 Oct 2026 08:27:56 +0200 Subject: [PATCH] Metabolism: add README MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Project pitch, invariants, quick-start commands, layout, reference songs, status, and how to read the coupling × residual report. --- metabolism/README.md | 115 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 115 insertions(+) create mode 100644 metabolism/README.md diff --git a/metabolism/README.md b/metabolism/README.md new file mode 100644 index 0000000..3ba72c2 --- /dev/null +++ b/metabolism/README.md @@ -0,0 +1,115 @@ +# metabolism + +Songs as **substrate**. A music video generator whose outcome is grown, not +mixed: the track is not a parameter set the renderer modulates — it is the +world an agent ecology grows on. Same song + same seed ⇒ the same world, +bit for bit, frame for frame, preview identical to export. + +``` + song (PCM) ──► analyse ──► score · field · graph · laws ──► species ──► world ──► camera ──► frames +``` + +The full concept and rationale live in **[DESIGN.md](DESIGN.md)** — read it +before touching the code. + +--- + +## The idea in one paragraph + +Most visualisers *modulate* one fixed stage: the song turns knobs, and every +track ends up presenting the same toy in different clothes. Here the song +places the **food** (events land where the track's harmonies point), the **laws** +(each section changes the rules at its boundary), and the **species** (the +seed picks a rule set — built from tempo, noise, brightness and band +correlations — not a parameter vector). Two songs differ like two habitats +differ, not like two skins. `drone` grows a slow tonal weaver with heavy, +lasting ground markings; `runner` grows a fast noisy swarm with jittered +motion and thin ephemeral trails; `dusk` grows a crystalline, slow, +over-clustered world where the sparks reject the builders. + +## Invariants + +Everything is load-bearing to keep these true: + +- **Persistence** — agents and their trails last seconds to tens of seconds. +- **Causality** — every visible event has an audible cause (hits are rings on + the ground) and a visible one. +- **Consequence** — the field is eaten, the trails accumulate; state at `t` is + made of state at `t−1`, never re-rolled. +- **Determinism** — no `Math.random`, no wall clock; tools and browser share + the same `Run`, so preview provably equals export. + +--- + +## Quick start + +Requires Node 20+ (for `node --test`) and your usual package manager. + +```bash +npm install + +# tests: analysis, determinism, world invariants, metrics sanity +npm test + +# filmstrips: 12 frames per song, tiled +# (needs the flow-state test bank WAVs at ../flow-state/test/songs) +npm run strip # drone, runner, dusk +npm run strip -- --songs drone --cols 6 --rows 2 --out out +npm run strip -- --songs drone,runner,dusk --combined 1 # comparison sheet + +# report: coupling × residual fitness + fingerprint divergence across songs/seeds +npm run report # prints a table, writes out/report.md + report.json +npm run report -- --songs drone,runner,dusk --seeds 999,12345,777777 +``` + +Outputs land in `out/` (gitignored). `npm run dev` serves a Vite root once a +browser demo exists. + +## Layout + +``` +DESIGN.md concept, invariants, build order +src/ + audio/ WAV decode, radix-2 FFT, feature table, sectioning, onset score + song/ events (onsets → geometry), species (genome), palette, song assembly + sim/ wells (harmony→food) and world.js (the typed-array ecology) + render/ software framebuffer, trail composer, PNG encoder + camera.js event-reactive cutting, shot-size rhythm, drift-and-push + film.js Run: the single wire-up of sim → camera → framebuffer + metrics.js coupling, residual, fitness, fingerprint, divergence + rng.js seeded PRNGs (the only randomness in the repo) +tools/ + load.js WAV → analysis → song (node-only) + strip.js filmstrip renderer + report.js system-level evaluation → markdown table +test/ node:test suites +``` + +## References + +`tools/*` load the synthetic reference tracks from +`../flow-state/test/songs` (`drone`, `runner`, `dusk`) — three 120 s test +signals chosen to cover the axes the species reads: dark/tonal/beatless, +bright/noisy/fast, darkest/all-tonal/mid-tempo. Drop any WAV there and point +`--songs` at it; the species will derive from whatever the track actually says. + +## Status + +Currently a proof: the simulation is alive, the three songs are measurably +distinct (fingerprint divergence between songs ≫ divergence between seeds), +and the tools verify it. It is **not yet a film** — nothing is muxed to +audio/video, the renderer is a 480 p proof, and the demo page isn't built. +Next milestones: a browser demo, event-reactive cutting tuned to a full real +track, and video export. See DESIGN.md's *Build order & status*. + +## Auditing what it grew + +The report's **coupling × residual** fitness is the honest score: coupling is +how much the ecology answers the track; residual is the internal dynamics the +track does not explain. A pure visualiser scores ~0 (no residual); a random +walk scores ~0 (no coupling). The fingerprint (occupancy, clustering, trail +fill, class mix) tells you whether two songs grew *different* worlds without +anyone having to opine about it. + + \ No newline at end of file