Three timescales now stack: per-frame reactivity, per-section seeded LFO
drift, and whole-song scene changes with lookahead. Layer instances are
cached per section and reused across crossfades — rebuilding them per frame
would recompile shaders every transition.
Crossfades run forward from a boundary: the outgoing scene holds while the
incoming one fades in over it.
Three real bugs, each found by a check that had to be rewritten first:
1. A pop exactly at every transition. buildSlope is discontinuous by
construction (~1 before a boundary, 0 after), and the outgoing layer is
still on screen when it flips — collapsing its lookahead ramp in one
frame. It now holds the slope it had entering the boundary.
2. FeatureTrack.at() returns a REUSED row object, and _boundarySlope()
called at() again mid-render, rewriting the features the layer was about
to read. Symptom: a frame correct on every repeat and wrong the first
time — invisible to fresh-vs-fresh comparison, and wrong in every export,
since export renders each frame exactly once. Now indexes the typed array
directly, with the aliasing hazard documented on at(), and a new check
covers the whole bug class.
3. Warm-up converged to 1%, leaving a visible 0.015 difference at heavy
feedback settings. Now targets 0.1%.
Two checks were themselves wrong and were rebuilt: a raw delta threshold
and an outlier-vs-local-median test both flag beat flashes as pops, and a
control window taken from a different scene reads an ordinary busy scene as
a 9x spike. The working formulation A/Bs each boundary against the interior
of the two scenes adjacent to it.
PLAN.md §6 corrected: boundary seeks are NOT exact for free. Layer state is
re-seeded there but the feedback buffer is global and carries across.
Clearing it at boundaries would buy exactness for a visible flash at every
transition; warm-up is the better trade and applies everywhere.
Gate 9/9.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Design document for a new generator that produces full-length, non-story
music videos from a track alone, with no sourced footage.
Core decisions:
- Deterministic engine: audio is analyzed up front into a frame-indexed
feature table, so realtime preview and offline export render from the
same code path and produce the same frames.
- Whole-song analysis enables lookahead, so builds can anticipate drops.
- Scenes declare their parameters in a schema, which drives uniform
binding, generated UI, seeded per-track variation and arc automation.
- Hybrid compositor: fragment-shader and three.js layers in one stack.
- Preview is a first-class surface with section jumping, live param
editing and segment test-renders.
- Forked from party-stage by copy, then fully detached.
Includes per-phase gates and the validation tooling they depend on.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
