# CYMATICS LAB: design dossier

**Status (2026-10-11):** M0–M6 are built. The plan is settled; the physics core and the
render core are proven by tests; the toy cell is playable at `toy.html`; flute, clarinet and
cello are **measured from recordings** ([Measured voices](voices.md)), each note playing its
recording's attack, pitch wander and vibrato
([articulation](03-sound-design.md#41-articulation-how-a-note-moves)). **Chapters I–III are
playable** at `play.html`: 18 plates, each proven by the oracle and judged exactly from the
physics, with the Atlas, the Sweep, hints, a field guide (`guide.html`) and an Album. Reviews
wait on the owner: the look (`lab.html`), the feel and the voices (`toy.html`), and the
playtest of Chapters I–III. M7 (Chapters IV–VI and the Lab) comes next
([roadmap](11-roadmap.md#milestones)).

**The idea.** A small round cell of water in the dark, lit by colored lamps at different
angles. Sound enters through needles on the rim: flutes, pipes, a clarinet, a cello, singing
bowls. The water answers by drawing mandalas of reflected light. Each puzzle shows a plate, a
photograph of a pattern, and the player finds the sound that makes the water draw it. Two
flutes slightly out of tune make the mandala breathe with the beat you hear. Two loud notes
can raise a third pattern that neither plays: the Tartini tone, made visible.

## Read in this order

| Page | Owns | Read it for |
|---|---|---|
| [01 Vision](01-vision.md) | Pitch, pillars, the reference look, fit with the wing | What we're making and why |
| [02 Acoustics](02-acoustics.md) | Beats, roughness, combination (Tartini) tones, tempering | **The answer to "what is it called?"** and the hearing science |
| [03 Sound design](03-sound-design.md) | The eight Consort voices, engine choice, spectra pipeline | **Choosing the right sounds** |
| [04 Water physics](04-water-physics.md) | Dispersion, eigenmodes, damping, modal engine, ring selection, Tartini and Faraday in water | The maths of the cell |
| [05 Optics](05-optics.md) | Reflection imaging, colored lamps at angles, exposure, strobes, caustics | How water becomes a picture |
| [06 GPU pipeline](06-gpu-pipeline.md) | Pass graph, formats, **the matrix shortcuts**, tiers | How it runs fast |
| [07 Audio engine](07-audio-engine.md) | The Consort worklet, shared clock, master chain | How sound stays locked to the picture |
| [08 Puzzle design](08-puzzle-design.md) | Verbs, win predicates, 7 chapters, the Lab, the oracle | What the player does |
| [09 UX & accessibility](09-ux-accessibility.md) | Layout, Tonnetz, Atlas, Sweep, input, photosensitivity, CVD, hearing | How it feels and who can play |
| [10 Architecture](10-architecture.md) | Modules, layering, level format, standards, testing, deployment | How it's built and kept honest |
| [11 Roadmap](11-roadmap.md) | Milestones M0–M8, risks, **decisions D1–D8** | What happens next |
| [Measured voices](voices.md) | Generated: what was measured from the recordings, and how well it fits | Checking a voice |
| [References](references.md) | Every source, with what was verified | Checking any claim |

## Five things to know

1. **The name for the two-flutes effect.** You hear **beats** (|f₁ − f₂| pulses per second)
   from wave interference. They blur into **roughness** at about a quarter of a critical band.
   Loud, pure pairs also make the ear produce a **difference tone** f₂ − f₁, the **Tartini
   tone**, plus a cubic one at 2f₁ − f₂. → [Acoustics § 1](02-acoustics.md#1-the-owners-question-answered)
2. **The look is reflection, not caustics.** CymaScope pictures are ring lights reflected
   off tilted water. Each lamp at angle θ lights the slopes equal to tan(θ/2), so colored
   lamps at different angles paint different contour families. Per pixel the renderer does
   **one lookup** in a lamp map, or a **closed form** for ring lamps.
   → [Optics § 1–2](05-optics.md#1-reflection-imaging-the-slope-picks-the-lamp)
3. **The patterns are the cell's own modes.** Bessel functions in a 24 mm, 5 mm-deep cell
   (the CymaScope's own size). Each mode is driven as a damped oscillator with an *exact*
   exponential integrator. Symmetric needle rings select angular orders l ≡ q (mod N), which is
   what makes mandalas clean. → [Physics § 5–6](04-water-physics.md#5-driving-the-cell-the-modal-engine)
4. **The GPU shortcut: the time is in the phasors, not the textures.** Fields are
   synthesised only when the physics changes. Every frame, each pixel rotates its complex
   slopes by per-sample phasors, `vec4 × mat4` for 4 clusters × 4 samples, and samples the
   lamp map with lamps packed in RGBA lanes. → [GPU § 3](06-gpu-pipeline.md#3-the-matrix-shortcuts)
5. **One score, two renderers.** A custom AudioWorklet synthesizes exactly the partials the
   water receives, phase-locked through a shared clock, so the beat you hear is the breath
   you see. → [Sound design § 1](03-sound-design.md#1-requirements-a-voice-must-meet),
   [Audio § 4](07-audio-engine.md#4-the-shared-clock)

## The numbers behind the pages

`plan/tools/` holds the Node scripts behind every computed value: dispersion tables, Bessel
zeros, Q, the resonance ladder, ring spacings, Faraday thresholds, the ring-lamp closed form
checked against brute force, and memory budgets. Run them with `node plan/tools/<name>.cjs`.
They take seconds and run single-threaded.