music-video-gen/metabolism/README.md

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 — 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.

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.