warp-mathAn integral, made visible, made audible.

The math behind tempo maps and warp markers, taught in code.

Start with the integral →

Source on GitHub

01 · The integral

Three closed-form regimes plus one numerical regime, derived in the code comments.

02 · Visualising the warp

Tempo curve + warp map with a draggable pin. The shaded area IS the integral.

03 · Real audio

Parse beat_this output, build the tempo model, play it back with plain Web Audio.

04 · Meter is not tempo

A second layer on the same axis — integer division, not calculus.

05 · When the data is messy

Detecting dropped beats, doubled beats, and broken monotonicity in real tracker output.

06 · Fixing a beat map by hand

Where ch.02 (pin) and ch.04 (meter) finally meet. Move, delete, and insert beats against a live meter validator.

The one idea

Tempo is a rate. "120 BPM" means beats arrive at 120 per minute — 2 per second. If musical position is $β$ (beats) and audio position is $t$ (seconds), tempo is the derivative of one with respect to the other:

\frac{d β}{d t} = \frac{BPM}{60} (beats per second)

We almost always want the other direction — given a beat, what second is it? — so we flip the fraction and integrate. Integrating a rate recovers the total:

t (β) = \int_{0}^{β} \frac{60}{BPM (b)} d b

That integral is the whole subject. A warp map is this function from beats to seconds; a warp marker is a single $(β, t)$ point that pins the two together. Everything else — snapping, playback, stretching, drift — falls out of evaluating or inverting this integral for different shapes of $BPM (b)$ .

Four shapes of BPM(b)

Shape of tempo	The integral becomes	The warp map looks like
Constant $BPM = K$	$t = (60 / K) \cdot β$ (constant rule)	a straight line
Piecewise-constant (what beat_this gives)	a running sum of rectangles	piecewise-linear, kinking at each marker
Linear ramp (accelerando)	$t = (60 / s) \cdot \ln (BPM (β) / b_{0})$ (closed form)	a curve — a logarithm
Curved (ease in/out, $BPM = b_{0} + Δ \cdot (β / L)^{k}$ )	no closed form — integrate numerically	a curve with no simple equation

The last row is the payoff. For general $k$ the antiderivative of $60 / (b_{0} + Δ (b / L)^{k})$ has no elementary form — so you stop solving by hand and evaluate the integral numerically with the trapezoidal rule. $k = 1$ recovers the linear ramp exactly; $k > 1$ eases in; $k < 1$ eases out.

The same integral underlies all four; only the difficulty changes. The chapters work through them in order.

The round trip

A live BPM readout is the derivative of the warp map coming back around:

BPM (β) = 60 \cdot \frac{d β}{d t} = \frac{60}{d t / d β}

Each map's bpmAt(β) is that derivative, evaluated analytically where a formula exists. The test suite confirms the round trip numerically across all four regimes.