on_the_level/SOUND_DESIGN_HANDOFF.md

On The Level — Audio Feedback Handoff

Handoff from the sound-design session (2026-07-16) to the app implementation. The design is final and approved by Jay; assets are ready to ship.

Two modes, two mechanisms, one sound identity — every sound derives from the same 500 Hz blip:

• Edge mode (1-D): sonar staircase, one discrete report per settle event.
• Surface mode (2-D): continuous proximity ticking — tick rate rises as you approach the bullseye; the moment you're on center, the ticks give way to the looping level.wav bullseye sound. One vocabulary: faster ticks = closer, bullseye sound = centered right now.

The staircase does NOT ship in surface mode. All earlier discussion of 2-D dominant-axis mapping is dead — surface is axis-agnostic warmer/colder by design, because leveling a surface shouldn't require decoding anything a bubble level wouldn't ask of you.

Surface mode: proximity ticking

Assets: tick.wav (in AudioGenerator's outputs/surface-proximity/) — the same 500 Hz blip shortened to 60 ms with a soft release. The app plays this single asset and schedules repetitions; rate is computed, not baked into loops. Arrival = the shared level.wav (already in this repo under sonar-staircase-v3/).

Rules — these are the difference between this and the old rejected "annoying mode":

1. Map total error → tick rate exponentially, ~1.5 ticks/s (far) to ~8 ticks/s (near). Hard cap at 8/s; beyond ~10/s it fuses into a buzz.
2. Loudness stays constant as rate rises. The acceleration is the signal; volume ramping is what turns it into a panic siren.
3. On entering the center zone: stop ticking and immediately start the looping level.wav — no dwell, no velocity gate, even on a fast pass. A momentary alignment is real locating information; that little zone needs the most help. level.wav loops while you rest on center and stops the instant you leave (ticks resume).
4. Spatial hysteresis on the zone (enter ≤0.2°, rearm only after leaving ≥0.35°) — not a time debounce, which would hide a legitimate quick re-crossing. Alignment is measured from the same hypot(pitch, roll) that drives the bubble, so the sound can't lag the visual.
5. Ticking runs continuously outside the zone, no settle gate — the realtime rate IS the feedback. (The settle-then-sound rule applies to edge mode.)
6. The stronger "held level" confirmation — persistent lime, the on-screen label, and the haptic — is decided separately by the velocity-aware lock (≤0.2° and moving slowly for ~175 ms). The locating sound never waits on it: a fast fly-through gets the bullseye cue but not the "you nailed it."

Rejected candidates kept for reference in AudioGenerator: the sustained "energy field" loops (bullseye-field-*.wav) and the alternate ticks (outputs/tick-candidates/). Do not ship them.

Edge mode: the "sonar staircase"

Leveling feedback is a short train of four sonar blips whose pitch contour is the message:

Reading	Sound	Pitch steps (semitones per blip)
Level	flat train — all four blips at the same pitch	0, 0, 0, 0
Slightly low (raise it a little)	gentle rising staircase	0, +1, +2, +3
Very low (raise it a lot)	steep rising staircase	0, +3, +6, +9
Slightly high	gentle falling staircase	0, −1, −2, −3
Very high	steep falling staircase	0, −3, −6, −9

Why this works:

• Direction = contour direction (rising = go higher; falling = go lower). Never invert this mapping.
• Magnitude = contour steepness. Humans are poor at absolute pitch but excellent at relative pitch, so a staircase is decodable without a reference.
• Level literally sounds "flat." The metaphor is self-explaining, and the flat train doubles as the reward/confirmation state.
• Constant rhythm at every zone. All five sounds share the same 175 ms blip cadence — a far-off reading is exactly as fast as a near one. Direction is audible by blip 2 (~200 ms), full reading by ~525 ms; the rest is decay.

When to play it (edge mode)

Staircase feedback fires only after movement followed by settling (same trigger as the app's voice feedback). One staircase per settle event.

The assets

outputs/sonar-staircase-v3/ (copy into the app bundle):

File	Duration
level.wav	1.39 s
slightly-low.wav	1.36 s
very-low.wav	1.32 s
slightly-high.wav	1.42 s
very-high.wav	1.50 s

All are 96 kHz stereo PCM-16 WAV, peak-normalized to 0.85. Downsampling to 44.1/48 kHz for the bundle is fine. The 500 Hz fundamental sits comfortably in phone-speaker range, including the −9 st variant (~297 Hz).

Anatomy of the sound (for regeneration or runtime synthesis)

• Blip: a single pure 500 Hz sine blip (100% tonal purity), ~165 ms including its natural decay, extracted from Jay's licensed SoundQ file (~/Downloads/SoundQ Audio/UIBeep_Beep Sonar_PSE_BW-BD3HL_OmEo5.wav, segment 515–680 ms). 4 ms attack fade, 30 ms release fade.
• Train: 4 blips, onsets every 175 ms, pitched per the table above. Pitch shifts are plain resampling (varispeed — pitch and length change together). On Android, SoundPool.setRate() reproduces this exactly, and its 0.5–2.0 range covers the full ±12 semitones used here.
• Tail: NOT reverb. The decay is rhythmic: the final blip repeats 4 more times at the same 175 ms cadence, each repeat −8 dB, holding the last blip's pitch (the tail "holds up the answer"). Jay specifically rejected a smooth reverb tail — the pulse must survive into silence. This matches the source file's own decay behavior (measured: repeats every ~180 ms, ~6 dB/repeat).

Generator script: build_staircase.py in this folder (AudioGenerator). Every parameter above is a named constant at the top. Run with .venv/bin/python build_staircase.py; outputs to outputs/sonar-staircase-v3/.

Implementation notes

1. Hysteresis on tier boundaries (important). With discrete tiers, a reading sitting at the slightly/very threshold will flip-flop between sounds on consecutive settles and feel indecisive. Require ~15% past a boundary before switching tiers. Same for the level/slightly boundary.
2. Three tiers is deliberate — don't add a fourth. Absolute-judgment limits make >3 discrete steepness levels hard to tell apart in the field. If finer feedback is ever wanted, synthesize the blips at runtime instead (enveloped sine oscillators via AudioTrack or Oboe) and make steepness continuous — proportional to the error angle. Continuous mapping sidesteps the categorization limit entirely; users only compare successive readings ("shallower than last time = converging").
3. Interruption: if a new settle event lands while a staircase is still playing its tail, cut it and play the new reading — the tail is decoration, the fresh reading is information.
4. Haptic pairing (optional): a light haptic tap synced to the level.wav blips makes the "arrived" state feel physical; the tool is usually pressed against a surface, so it lands well.

Licensing

The blip derives from Jay's SoundQ "Lifetime License" pack — perpetual royalty-free use, which for SFX marketplaces normally covers embedding in apps; standalone redistribution of the sounds is what's prohibited. If any doubt ever arises: the blip is a mathematically pure 500 Hz sine with simple envelopes, so a from-scratch synthesized replacement (zero licensing) is trivial and indistinguishable — the design carries the value, not the sample.