dancer
A realtime, procedural dancing agent: it listens to music it has never heard, maintains a
hierarchical belief about the metre with calibrated precision, and drives a body that moves before
the beat, commits to long moves only when it is sure, and hedges when it is not.
The research roadmap is docs/BLUE_SKY_PLAN.md; per-layer designs are in
docs/plans/. This branch is executing the engineering-only tier, whose build order is
docs/plans/T1_IMPLEMENTATION.md.
Layout
packages/core/ @dancer/core: pure TypeScript, no DOM, runs in Node and the browser
src/time sample clocks and frame-rate constants
src/rng seeded RNG; nothing in the system calls Math.random
src/types the contracts every layer speaks
src/sim Score -> ground truth, activations and audio (the test oracle)
src/metrics every metric in the gate, as pure functions over traces
src/replay recorder, replayer, canonical hashing
src/ears DSP features and the BEAST adapter
src/pulse templates, bar-pointer filter, PIPPET phase filter
src/form bars, phrases, sections, drop forecasting, repeat memory
src/feel energy, syncopation, groove, urge to move
src/choreo motif library and planner
src/body phase-time motion, retiming, layered limbs
bench/ the frozen gate: cases, thresholds.json, NOTES.md
apps/web/ Vite + React + three.js live app
research/ optional Python: oracles, ONNX provenance
stimuli/ generated test audio (not committed)
Commands
npm run monitor # the live pulse monitor at http://localhost:5173
npm run gate # typecheck + tests + bench. Run before every commit.
npm test # unit tests only
npm run bench # the gate cases and their thresholds
npm run stimuli # render the stimulus set to stimuli/*.wav
npm run fixtures # cache real-ONNX activations for the S12 stimuli
npm run replay -- recording.json
Hearing it
npm run monitor opens a page that runs Ears and Pulse on live audio - microphone, tab audio, or a
file - and schedules a click on the predicted beat, ahead of real time. If the belief is right
the click fuses with the music; if it is wrong you know instantly, which no number on a panel tells
you as quickly.
Three synthetic tracks with exact ground truth are built in. Start with those: you know what the
answer is, so you can tell a problem with the system from a problem with the track.
What to look for:
- lock in two to four beats, and the click sitting inside the kick rather than beside it
- talking over the music or waving a hand at the microphone should not move the belief at all
- a real tempo change should take four or five beats to absorb, the way a person does
- through a breakdown the mode should read
coasting and the click should keep going
Rules that are not negotiable
- The gate is frozen. Thresholds live in
packages/core/bench/thresholds.json. Nothing here may
lower one, widen a tolerance or skip a case. If a threshold looks wrong, the argument goes in
packages/core/bench/NOTES.md and the case stays red until a human changes it.
- Determinism is a feature. All randomness goes through an injected seeded RNG. Two runs with
the same inputs and seed produce byte-identical output.
- Evidence is counted once. Overlapping-window model outputs are never fed to a filter as
independent observations. This is what the old tracker got wrong.
- The future is never read from the file. In player mode the page knows the upcoming audio; the
live path must not touch it. It is an evaluation oracle only.
- Estimates come with precision. No layer emits a bare number: every predicted time carries a
standard deviation, every label a distribution.
