用代码造一台三角钢琴：从尺寸一路算到声音 Building a Grand Piano in Code: From Dimensions to Sound

The most important step a piano takes is the one nobody ever sees.

Press a key and the hammer rises. About 1.7 mm short of the string, the jack that has been pushing it is stopped by a felted button; it can no longer rise, only turn, so it slides out from under the hammer’s knuckle. The hammer crosses that last 1.7 mm with nothing touching it, at whatever speed it already had. Push harder and you cannot catch it. This is let-off, and the whole of piano touch lives in those two millimetres.

“Nobody sees it” is not a figure of speech. From the front, the pinblock and 236 tuning pins are in the way. From directly above, the plate is. Along the row, the next hammer is a wall. From behind at a low angle, the bridge. The camera stations in this world were not placed by taste; they were found by raycasting — a sweep over azimuth and elevation asking which directions reach note 2’s jack and its crown with nothing in between. What survives is a narrow cone in over the sawn-down bass wall.

So the brief is one sentence: the lid is off and half the case is cut away; eighty-eight hammers in a shrinking line, and one of them lets go of its jack two millimetres short of the string.

The first of five stations. You are standing over the instrument looking down into it — which is the only posture from which this picture exists in real life.

The complete source is in Makone: about 3,200 lines of JavaScript, nine parts, no imported model and not one sample. What follows is the code that actually decides what this piano is.

Dimensions are solved, not typed

params.js is the foundation of this world, and its opening comment says what it is for: nothing here is a number that looked right on a screenshot. Four chains, and all four are algebra.

The black keys are not centred between the whites

An octave is 165 mm, so a white key pitch is 165/7 = 23.571 mm. That is the only free number in the front view.

What about the black keys? Most people assume they sit on the boundary between their two neighbouring naturals. They do not. The real constraint is something else entirely: the exposed “necks” of the white keys — the narrow part that runs back between the sharps — must be equal within a group. C-D-E is three naturals and two sharps; F-G-A-B is four and three. Solve each group:

/** Equal-neck solution for one group of white keys. `whites` naturals and `whites - 1` blacks
 *  share the group's width; every neck is the same, and so is every gap. Returns the neck. */
const neck = (whites) => (whites * WHITE_PITCH
  - (whites - 1) * KEYS.blackW - (2 * whites - 2) * KEYS.gap) / whites;

export const NECK_2 = neck(3);      // C D E   → 14.97 mm
export const NECK_3 = neck(4);      // F G A B → 13.90 mm

Once the necks are equal, the key tails in a group are evenly spaced and every sharp lands exactly midway between two of them. The asymmetry everyone recognises and nobody can name falls out — not one offset is typed by hand:

C −4.3   C♯ −2.15   D 0.0   D♯ +2.15   E +4.3
F −4.84  F♯ −3.23   G −1.61  G♯ 0.0   A +1.61  A♯ +3.23  B +4.84   (mm)

C♯ sits 2.15 mm left of the C/D boundary, F♯ 3.23 mm left of F/G, G♯ exactly on G/A. Space the blacks evenly instead and every player who looks at it says something is wrong, while almost none of them can say what.

Front-on is the cruel angle for this kind of model. If the sharp offsets are wrong, this single frame is where it shows.

There are only twelve distinct keys on a piano

A key’s head sits on the keyboard’s 23.571 mm pitch; its tail sits on the action’s 13.75 mm pitch. The two only agree once per octave, so every key steps sideways where the sharps begin — and the step is a constant for each pitch class: C always 4.3 mm, F always 4.84, D and G♯ not at all.

So a piano has exactly twelve distinct key shapes, each appearing seven or eight times. Which is precisely what an InstancedMesh wants: twelve geometries, 88 instances, plus two more instanced meshes for the capstan and the back check, because those are the same object on every key and only their x changes.

Every part is reviewed alone on its own sheet. The complete 88-note keyboard costs 748 triangles and six materials — the budget it saves goes where you can see it.

The lever chain: three ratios multiplied, two unknowns

Ten millimetres of key dip has to become 46 mm of hammer travel through three ratios that multiply: the key (capstan arm / touch arm), the wippen (jack arm / heel arm), and the hammer (crown radius / knuckle radius).

The third one is fixed by parts you can see: 125.08 / 16.5 = 7.58. The other two cannot be chosen independently, because the capstan has to stand under the wippen heel — one point, shared by two levers. So it is really two equations in two unknowns:

//   capstanArm + heelArm = balanceZ − wippenZ                     (they share the span)
//   (capstanArm/touchArm) × (jackArm/heelArm) × hammerRatio = ratio
export const CHAIN = (() => {
  const hammerRatio = reachOf(REF_NOTE) / HAMMER.knuckleR;
  const touchArm = KEYS.frontZ - KEYS.touchInset - KEYS.balanceZ;
  const span = KEYS.balanceZ - ACTION.wippenZ;
  const k = (HAMMER.ratio / hammerRatio) * touchArm;
  const heelArm = (span * ACTION.jackArm) / (ACTION.jackArm + k);
  const capstanArm = span - heelArm;
  const wippenRatio = ACTION.jackArm / heelArm;
  const keyRatio = capstanArm / touchArm;
  return {
    touchArm, span, heelArm, capstanArm, hammerRatio, wippenRatio, keyRatio,
    ratio: keyRatio * wippenRatio * hammerRatio,                 // = HAMMER.ratio, by construction
    capstanZ: KEYS.balanceZ - capstanArm,
    keyAngle: KEYS.dip / touchArm,                               // radians the key turns, ~3°
    /** jack lift per unit of key dip — the whole chain below the hammer */
    perDip: keyRatio * wippenRatio,
  };
})();

It comes out at: 193 mm from the touch point to the balance pin, a 116.67 mm capstan arm, a 53.33 mm heel arm, a wippen ratio of 1.20:1, a key ratio of 0.605:1, and 2.97° of rotation at the bottom of the dip. The capstan’s position is derived, not nudged until it lined up.

And then an assertion, in code rather than in a comment:

if (Math.abs(CHAIN.ratio - HAMMER.ratio) > 1e-9) throw new Error('params: the chain does not solve');

There is a lovely contradiction hiding here. The brief asks for a 5.5:1 action ratio and for 10 mm of dip to make 46 mm of blow — but 5.5 × 10 is 55, not 46. Those are not the same claim. What resolves it is let-off itself: the chain stops being rigid. After the jack escapes, the key still has a millimetre or two to travel, and that travel is felt by the finger and delivered to nobody. It is called after touch: 2.07 mm in the bass, 1.64 near middle C, 1.13 at the top. Below 0.8 mm params.js throws, because that means the key bottoms out before the hammer arrives and the note never sounds at all.

The escapement as arithmetic, not animation

Nothing in this world is keyframed. The whole stroke is a pure function of one number: how long ago this note’s finger started down.

First the part that does not depend on the clock:

const PRESS = 0.055;      // seconds for the finger to take the key to the bottom
const G = 78;             // rad/s²: gravity on a hammer whose crown is 125 mm out
const REBOUND = 0.52;     // how much of its speed the felt gives back

function ballistics(k) {
  const rate = (KEYS.dip * CHAIN.perDip) / PRESS;          // jack, metres per second
  const tLet = PRESS * (k.dipToLetoff / KEYS.dip);
  const w0 = rate / HAMMER.knuckleR;                       // hammer, radians per second
  const aLet = k.aStrike - LETOFF.gap / k.L;               // 1.7 mm short, in radians
  // free flight: w0·s − ½G·s² = the last gap. G barely matters over 2 mm, and it is still right.
  const gap = LETOFF.gap / k.L;
  const s = (w0 - Math.sqrt(Math.max(0, w0 * w0 - 2 * G * gap))) / G;
  return { rate, tLet, w0, aLet, tHit: tLet + s, wHit: w0 - G * s };
}

And then one function that accounts for the entire chain at any instant:

function stroke(n, tau, releaseAt) {
  const k = NOTES[n], b = BALL[n];
  // ── the finger ──
  let u;
  if (tau < PRESS) u = tau / PRESS;
  else if (tau < releaseAt) u = 1;
  else u = Math.max(0, 1 - (tau - releaseAt) / RELEASE);

  // ── the jack, and how far it has turned out from under the knuckle ──
  const dip = u * KEYS.dip;
  const escape = Math.max(0, dip - k.dipToLetoff) / TOE_ARM;

  // ── the hammer ──
  let a, phase;
  if (tau <= b.tLet) {                       // driven by the jack
    a = k.aRest + (dip * CHAIN.perDip) / HAMMER.knuckleR;
    phase = 'jack on knuckle';
  } else if (tau <= b.tHit) {                // the 1.7 mm nobody is touching
    const s = tau - b.tLet;
    a = b.aLet + b.w0 * s - 0.5 * G * s * s;
    phase = 'let-off — free flight';
  } else {                                   // struck, and falling back
    const s = tau - b.tHit;
    a = k.aStrike - REBOUND * b.wHit * s - 0.5 * G * s * s;
    // the back check is bolted to the key, so it only reaches while the key is down
    const floor = k.aRest + (u * KEYS.dip * (KEYS.balanceZ - k.tailZ) / CHAIN.touchArm) / b.tailR;
    phase = a <= floor ? 'checked' : 'rebound';
    a = Math.min(k.aStrike, Math.max(a, Math.min(floor, k.aStrike)));
  }
  ...
}

The timescales of a real instrument all land: the key reaches the bottom in 55 ms, the jack escapes at 42.1 ms, free flight lasts 1.63 ms, and the crown arrives at the string doing 1.04 m/s. The film warps time not for prettiness but out of necessity — at any single rate the subject is either a blur or a still.

That line in the corner is not a subtitle. It is read off the geometry: the crown’s distance to the string plane, 0.60 mm on this frame.

After the strike the hammer rebounds at about half speed and falls onto the back check. Note the floor line above: the back check is bolted to the key, so it can only catch the hammer while the key is still down. Let go and it rises with the key, and the hammer drops back to its rest rail. That is not a description; it is that one line.

The next moment of the same machine: rebound, 3.28 mm from the string. The height at which the check catches it is read off this note’s own hammer tail, and no two of the eighty-eight are the same.

One straight rail, eighty-eight different parts

The hammer flange rail is straight — it is a rail. But the rest angles are graduated: A0’s shank hangs 21.8° below horizontal, C8’s only 13.1°. So the knuckle sits about 2 mm lower in the bass than in the treble.

How does a real piano absorb that? With eighty-eight jacks of slightly different length, and eighty-eight let-off buttons screwed to slightly different depths. Same here, and it falls out rather than being placed: the jacks run 25.53 mm in the bass to 27.71 mm at the top; the underside of the buttons walks from 86.04 to 86.69 mm.

The head itself is drawn once, normalised — one unit from the shank line to the crown, one unit wide — and scaled per note:

// the head: normalised, so its scale is its size, and it sits on the end of the shank.
// The z scale carries the head's DEPTH: the profile is drawn 0.30 units deep, so dividing
// by that turns a metre measurement straight into a scale factor.
head.makeScale(k.hammerW, k.rise, k.hammerD / 0.30).setPosition(0, 0, -k.shank);
local.multiplyMatrices(m, head);
mould.setMatrixAt(n, local);
under.setMatrixAt(n, local);
felt.setMatrixAt(n, local);

There is a trap here worth writing down. A real bass hammer head measures 19.5 mm — put that in the width and sixty of the eighty-eight interpenetrate their neighbours and the whole row renders as a solid white band. The reason is simple: the action’s note pitch is 13.75 mm, and nothing in the row can ever be wider than its own slot. The 19.5 mm is the head’s depth along the string, which is where a bass hammer’s mass actually goes. Two different sizes with one name.

So params.js ends with a check that hammers and dampers share:

/** Anything that stands in the row of 88 has one slot, and it is SEMI wide. Two things at
 *  13.75mm centres cannot both be wider than that and still be two things. */
const inItsSlot = (what, w) => {
  if (w > SEMI - 0.0008)
    throw new Error(`params: ${what} is ${Math.round(w * 1000)}mm across on a `
      + `${Math.round(SEMI * 1000)}mm pitch — it is inside its neighbour`);
};

The dampers were 17.5 mm across on a 13.3 mm pitch — all sixty-eight of them inside their neighbours — which is what this check found the day it was written.

The shot the brief asks for. The line of heads tapers, so the ridge narrows as it recedes — a row of eighty-eight identical hammers would only read as a factory rack.

Strings do not double per octave

C8 speaks 50 mm. Every octave down multiplies by 1.88, not 2 — a true doubling would need a 12 m bass string, and nobody has that case.

The ideal length is then soft-clipped against a 1.92 m cap with a p-norm, which is exactly what a real scale does in a piano that is not long enough: A0 comes out at 1882 mm and everything above middle C is untouched.

const softMin = (a, b, p) => (a ** -p + b ** -p) ** (-1 / p);

const ideal = STRINGS.c8 * STRINGS.perOctave ** ((108 - midi) / 12);
const len = softMin(ideal, STRINGS.cap, STRINGS.capP);      // cap = 1.920, p = 3
const frac = 1 / lerp(STRINGS.strikeBass, STRINGS.strikeTreble, t);

The strike point walks from 1/8 of the length in the bass to 1/17 at the top. The hammer line is straight, because it is a rail. Multiply those two facts together and the agraffe line and the bridge can only be curves — they are consequences, not drawings. That 1.2 m of sweeping long bridge is a curve nobody placed.

const dir = { x: Math.sin(cross), z: -Math.cos(cross) };
const agraffe = { x: ax - dir.x * frac * len,       z: strikeZ - dir.z * frac * len };
const bridge  = { x: ax + dir.x * (1 - frac) * len, z: strikeZ + dir.z * (1 - frac) * len };

236 strings: one each for the lowest eight notes, two for the next twelve, three for the rest. The bottom twenty-six are copper-wound, run to a bass bridge of their own standing 20 mm taller, and lean 8° across the tenor strings on the way. Un-cross them and this is a square piano; cross them and it can only be a grand.

The bass bridge stands 20 mm above the long one, and those 20 mm are the entire reason the crossing works.

Sound, from the same numbers as the geometry

This piano makes noise, and none of it is sampled. Two reasons: a recording would be an external asset, and it would be a different piano from the one on screen.

sound.js is additive synthesis driven straight from params.js. Of the three things that make it sound like a piano rather than an organ, two are geometry this world already had lying around.

One: inharmonicity. A real string is stiff, so its partials are not integer multiples of the fundamental:

f_k = k · f₀ · √(1 + B·k²)

B rises toward the treble, where the wire is short, thick and stiff:

/** Longer strings ring longer, and every partial dies faster than the one below it. */
const decayOf = (n) => 14.5 * Math.exp(-n / 34) + 0.55;
/** Stiffness. Real B runs from about 3e-5 in the bass to 5e-3 at the top. */
const inharmOf = (n) => 3.2e-5 * Math.exp(n / 17.5);

Put numbers through it: B is 3.2e-5 at A0 and 4.6e-3 at C8. Near middle C the 8th partial is already 20 cents sharp; at the top of the keyboard the 5th partial is 95 cents sharp — very nearly a semitone. That single line is why a piano has to be tuned stretched and an organ never does. The decay times come along for the ride: A0 rings for 15 seconds, C8 for 1.7.

Two: the strike point. A string cannot be given a mode it was struck at the node of, so every partial carries a comb factor of |sin(kπ·frac)|. Struck at 1/8, the 8th partial is missing; at the top it is struck at 1/17. That frac is not a synth parameter — it is NOTES[n].frac, the very number the agraffe line and the bridge curve came out of. The timbre walks across the compass because of where a rail happens to be.

// harder playing does not only mean louder: it means more partials survive the hammer
const partials = Math.max(4, Math.round((16 - n / 8) * (0.55 + 0.55 * v)));
for (let p = 1; p <= partials; p++) {
  const f = p * f0 * Math.sqrt(1 + B * p * p);
  if (f > 15000) break;
  // the string cannot be given a mode it was struck at the node of
  const comb = Math.abs(Math.sin(p * Math.PI * k.frac));
  const amp = (comb / p ** 1.08) * v * (0.35 + 0.65 * v) ** (p / 4);
  if (amp < 0.0009) continue;
  const o = ctx.createOscillator();
  o.type = 'sine';
  o.frequency.value = f;
  const g = ctx.createGain();
  g.gain.setValueAtTime(0.0001, t);
  g.gain.linearRampToValueAtTime(amp, t + 0.003);
  g.gain.exponentialRampToValueAtTime(0.00006, t + decay / (1 + 0.42 * (p - 1)));
  o.connect(g).connect(gain);
  o.start(t);
  o.stop(t + decay + 0.4);
}

Three: the damper. Release a key and felt drops onto the string, so the note stops in about a tenth of a second — unless the pedal is down, or unless the note is above number 68, because the top twenty have no damper at all. That is audible, and it is the same fact the damper part is built from.

function release(n) {
  const v = live.get(n);
  if (!v) return;
  // no damper above note 68, and none of them are down while the pedal is
  if (v.damped && !pedalDown) stop(n, true);
}

On top of the strings there is one sound that is not a string: felt hitting wire. A short filtered burst of noise, brighter the harder you play.

/** The knock of felt on wire: a short filtered burst, brighter the harder you play. */
function thump(t, k, vel) {
  const src = ctx.createBufferSource();
  src.buffer = noiseBuf;
  const bp = ctx.createBiquadFilter();
  bp.type = 'bandpass';
  bp.frequency.value = 380 + k.n * 46 + vel * 900;
  bp.Q.value = 0.9;
  const g = ctx.createGain();
  g.gain.setValueAtTime(0.9 * vel * vel, t);
  g.gain.exponentialRampToValueAtTime(0.0001, t + 0.055 + 0.05 * (1 - k.n / 88));
  src.connect(bp).connect(g).connect(out);
  src.start(t);
  src.stop(t + 0.3);
}

One compressor serves the whole instrument — ten notes at once must not clip, and a real piano does its own version of this through the bridge and the board — with twenty-two voices of polyphony.

And one detail that is engineering rather than music: the AudioContext is not created until somebody actually plays. Browsers will not start one without a gesture anyway, but headless Chromium is worse — it builds an audio thread for a device that is not there, and it takes 2.6 seconds to do it, long enough that the test harness’s own locators time out and report a world whose controls could not be driven. Nothing in a capture run can hear anything, so nothing in a capture run should pay for it:

if (globalThis.location && new URLSearchParams(location.search).get('capture') === '1') return false;

Letting it play itself

tunes.js holds four pieces: a summer-ish original, plus the openings of Bach’s Prelude in C, Beethoven’s Für Elise and Pachelbel’s Canon in D (all public domain). Each runs about thirty seconds.

They are written in note numbers, not pitch names — 0 is A0 and 39 is middle C, the same index everything else in this world is addressed by. Each piece has two tracks, for a musical reason and a visual one: the left hand holds the harmony and the pedal while the right carries the line, and the bass hammers are the big ones at the far end of the row while the melody is small and quick in the middle. You can see the difference.

Each entry is [beat, notes, lengthInBeats, velocity]:

const C = [C3, [E3, G3], G3];       // one entry per bar: [bass on 1, chord on 2 and 4, bass on 3]
const chords = [C, Am, F, G, C, Am, F, C, F, G, Em, Am, F, C];
chords.forEach((ch, b) => {
  const t = b * 4;
  const last = b === chords.length - 1;
  lh.push([t, [ch[0]], last ? 3.6 : 0.9, 0.80]);
  lh.push([t + 1, ch[1], last ? 3.0 : 0.7, 0.46]);
  if (last) return;
  // bar 7 and bar 13 change harmony half way through — the push home
  const half = (b === 6 || b === 12) ? G : ch;
  lh.push([t + 2, [half[2]], 0.9, 0.66]);
  lh.push([t + 3, half[1], 0.7, 0.44]);
});

The compiler turns that into a flat, time-ordered list of press / release / pedal events — the same events a pair of hands would produce, so nothing downstream can tell a piece playing itself from a person playing it:

function compile(piece) {
  const spb = 60 / piece.bpm;
  const per = piece.beatsPerBar ?? 4;
  const ev = [];
  for (const [beat, notes, len, vel] of [...piece.lh, ...piece.rh]) {
    for (const n of notes) {
      ev.push({ t: beat * spb, press: n, vel });
      ev.push({ t: (beat + len) * spb, release: n });
    }
  }
  if (piece.pedal === 'bar') {
    for (let b = 0; b < piece.bars; b++) {
      // up on the bar line and down again just after it — one harmony's worth of ring,
      // which is a foot doing exactly what a foot does
      ev.push({ t: Math.max(0, b * per * spb - 0.04), pedal: false });
      ev.push({ t: b * per * spb + 0.05, pedal: true });
    }
  }
  // The piece is over when its last string has been let go of, not when its last bar line
  // goes by: a held final chord runs past the bar.
  const lastOff = ev.reduce((m, e) => (e.release !== undefined ? Math.max(m, e.t) : m), 0);
  ev.push({ t: lastOff + 0.25, pedal: false });
  ev.push({ t: lastOff + 1.3, end: true });
  return ev.sort((a, b) => a.t - b.t || (a.release !== undefined ? -1 : 1));
}

That last comment has a real bug behind it. Counting bars instead of releases left five seconds of silence on the end of one of these, because its final chord is held past the bar line.

The repertoire is not a matter of taste either. The summer piece is the hardest thing this object can be asked to do — sixteen hammers a bar with the pedal changing under all of them. Für Elise is the one piece here with no pedal at all, so every damper you can see drops back onto its own strings the instant the key comes up, sixty-eight of them. The Canon puts one note a bar in the far bass, so the biggest hammers in the instrument move on their own, slowly, while the small ones hurry above them. And the Bach has no melody whatsoever — one broken chord turning over and over, which is what makes the hammers come up in a running ripple instead of one at a time.

One clock, two ways in

This world is a film and it is an instrument, and they are not two pieces of code. Both of them write to the same map:

const voices = new Map();          // note → { tau, releaseAt, vel }

The film converts screen time into the mechanism’s own time and writes the map. Your fingers write the map. The mechanism downstream cannot tell which — which is why turning a scrubbable film into a playable instrument cost the nine parts no change at all.

It is also why seekTo(t) and play() cannot disagree: both are the same pure function given a different value of one clock. The single trap is documented in place, and it is worth copying out:

// NOT `clock % DURATION` on the read: that maps the end of the timeline onto its start,
// and then seekTo(0) and seekTo(1) are the same frame — which verify calls a timeline
// you cannot see, correctly.
const u = Math.min(1, Math.max(0, clock / DURATION));

The automation side follows the same rule. pilot.js may only touch observe(), getState() and act(), and may not import main.js. The reasoning is blunt: an autopilot living inside main.js shares its bugs and proves nothing. It exercises the published interface, so if act({press: n}) and the hammer that moves are ever off by a note, or a key never comes back up, this is what finds it.

An instrument cannot be won, so it defines success for itself:

// It played a real number of notes, and when the performance ended NOTHING was left hanging —
// no key still down, no hammer off its rest rail, no damper still up. A stuck key is the one
// failure a keyboard can have that a screenshot will never show you.
export const succeeds = (s) => s.struck >= 20 && s.sounding.length === 0 && s.atRest === true;

Numbers, and a few things worth keeping

The whole instrument comes to 143,328 triangles and 159 draw calls. Several of the optimisations were measured rather than guessed.

Handing the generated environment map to scene.environment gives every fragment in the object an image-based lighting lookup — but felt and spruce do not reflect a room. Only the brass, the steel and a painted cast-iron plate do. In the software renderer the harness measures with, that one line was half the frame: 490 ms with it, 243 ms without. So the environment map goes onto the metals by hand, and everything else is lit by three lights, which is also the more honest description of what a piece of hammer felt does with light.

A 1024 shadow map over a 3 m frustum is 2.9 mm a texel, and this object has to resolve a 10 mm key dip across 1.3 × 2.2 m. The keyboard came out in triangular patches of acne, which read as “the bass end is hidden” and was entirely this. A frustum cut to what the object actually occupies, at 2048, is 0.9 mm a texel.

And coplanar faces bit three times, the same mistake wearing three faces: the white key’s wood top and its ivory both at 62.0 mm; the sharp’s cap sharing a plane with its own stick; the hammer’s under felt drawn at exactly the same size as its outer felt. The depth test has no answer for two surfaces in one plane, so it picks per pixel and per frame — a flickering keyboard, a speckled hammer head. The fixes are all crude: sink the lower layer 0.4 mm, or shrink it 4%. Nothing about them is subtle; finding them is the work.

A few things I would carry into the next one.

If a dimension can be solved, do not type it. The capstan’s position, the length of each jack, the height of each let-off button, the bridge curve — in this piano they are all solutions to equations. The payoff is practical: change one parameter and everything downstream moves with it, instead of leaving some part standing at an old coordinate.

When parts stand in a row, work out how wide each one is allowed to be first. The action’s note pitch is 13.75 mm and nothing can be wider. Written as an assertion that is worth far more than written as a comment — it is how the dampers were caught: 17.5 mm heads on a 13.3 mm pitch, all sixty-eight inside their neighbours, and on screen it was just an undifferentiated white smear.

If the motion can be computed, do not keyframe it. The whole stroke here is one function whose only input is how long ago the key went down. So a frame you scrub to and a frame you play cannot disagree — they are the same function. And it buys more than consistency: to see what happens 42 ms in, you feed in 42 ms.

Sound and geometry can share one set of parameters. Which partials exist is decided by the strike point, and the strike point is the same frac in the model and in the synthesiser. Read it the other way round: if your synth parameters and your model dimensions disagree, they are describing two different instruments. There is another post on synthesising music from scratch — that one renders to a WAV offline, this one computes in the browser as you play.

Do not let the test import the module under test. pilot.js calls only act(), observe() and getState(), which is the same path a person takes with a mouse and a keyboard. Import main.js and reach into its functions, and whatever is wrong in there is wrong in the test too.