Two palms give you four numbers, and one of them is best left alone. Their mean height is the pitch. The distance between them is the volume. The angle of the line joining them sat unused for months and is now the vibrato: see-saw your hands and the note begins to sing. The fourth is where the pair sits horizontally, and it stays free on purpose, so that nobody is pinned to one spot in front of the camera. Their apparent size is a fifth thing and not a position at all; it moves a lowpass and a reverb send, so leaning back makes the room bigger. The angle is independent of the distance, so the vibrato leaves the volume alone, and the string drawn between the hands is already a picture of it.
It began as a phone toy — tilt left and right for volume, forward and back for pitch. The camera came later and turned out to be the better instrument. The phone mode is still there.
No video leaves your machine. The hand tracking is MediaPipe's Hand Landmarker compiled to WASM, running on your own GPU. The tracker and its model are fetched once from a CDN, about 8 MB, and after that you can unplug the network and it still plays.
Most of the work was not the sound. It was the hand that disappears. MediaPipe finds a palm by its plane, so it loses one when you turn your wrist edge-on, or when the room is dark and the webcam falls to fifteen frames a second and a moving hand becomes a smear. At first I held the note for a second after a hand vanished. People said it lagged. I cut it to half a second. People said the sound kept dropping out. Both were right. Now the hold depends on where the hand was last seen: near the edge of the frame a person has genuinely taken their hand away, so 400 ms; deep in frame nobody teleports and the detector merely blinked, so a full second, and no one hears the gap.
The other stubborn thing was the bass. A phone speaker produces nothing below roughly 150 Hz, and raising the gain there does nothing at all — I tried ten decibels and heard silence. So the bottom octave is split off, saturated gently to breed harmonics, and its fundamental is then filtered away. The ear reconstructs a pitch it never heard.
That trick then caused a bug I misread for a week. A tester said the pitch moved in steps in the phone mode, worst in the bass, and guessed it was a frame rate problem. It was not. The phone reports its tilt angle quantised to something close to a whole degree, and I had packed six octaves into eighty degrees of tilt — so one tick of the sensor was most of a semitone. It was audible in the bass specifically because of the exciter: at 70 Hz the ear resolves pitch poorly, but the exciter re-voices the note through harmonics at two and three hundred hertz, which is exactly where the ear resolves cents best. So the fix was not the sound and not the frame rate. It was a narrower range, a wider sweep, and reading the sensor at frame rate instead of once per event.
One HTML file, no build step, MIT: https://github.com/gurov/theremin