on_the_level/AUDIO_DESIGN_LOG.md

Audio Assist — design log

Hands-free audio to level something without watching the screen. Setting cycles OFF / TONES / VOICE from the Level header. Plays on USAGE_MEDIA (so the volume slider controls it) and never takes audio focus.

Source of truth for the current design is [SOUND_DESIGN_HANDOFF.md], from Jay's dedicated sound-design sessions. This log records the journey — especially rejected approaches — so they don't get rediscovered. Where the two ever disagree, the handoff wins.

Chosen direction (current)

Two modes / two mechanisms, one sound identity (all derived from a 500 Hz blip):

SURFACE (2-D) — TONES = continuous proximity ticking. A tick (tick.wav, 60 ms) repeats faster as you near level — axis-agnostic "warmer/colder", the RATE is the whole message (a bubble level asks nothing of you). No settle gate — it ticks at every point in the adjustment. Rate is exponential in the stable tilt error, clamped 1.5/s (≥~5°) → 8/s (≤~0.4°), hard-capped at 8/s. Constant loudness (acceleration is the signal, not volume). On lock (reusing LockDetector.isLocked — dwell + hysteresis, no second audio threshold): ticking stops, level.wav plays once, silence while it holds; unlock resumes ticking. Scheduling is deadline-based off a monotonic clock — advances a next-tick deadline (no drift, no catch-up bursts, ≤1 tick per sensor update); re-entry (enable TONES / return FACE_UP / unlock) ticks immediately. level.wav's 1.39 s stream is retained and stopped on unlock/disable so a fresh tick can't overlap its tail.

EDGE (1-D, future) — the "sonar staircase." Direction + magnitude as a 4-blip pitch contour (rising = raise it, falling = lower it, steepness = how far; level sounds flat), one report per move→settle. Five pre-rendered assets staged in sonar-staircase-v3/; wired when Edge mode is built.

VOICE — deliberately separate, a SETTLED-CHANGE announcer (not a timer). Speaks one correction, then stays silent while moving; when it settles again it speaks only if the dominant direction changed, it crossed coarse→fine, or it reached lock ("that's level"). A settle still needing the same coarse nudge gets silence. No periodic repeat, no bed under it.

Implementation: pure SurfaceTickPolicy (monotonic deadline scheduler, exponential rate, unit-tested) + VoiceGuidancePolicy; the SoundPool layer stays dumb (play a tick / play & stop level). Sounds are Jay's SoundQ-derived blips (tick.wav, level.wav) downsampled to mono 44.1 kHz in res/raw.

Rejected approaches (and why)

1. Two fixed proximity bands + lock ping (original). Worked but coarse; the near/close jump was audible ("a lower ding when close").
2. Continuous cadence — beep interval shrinks smoothly toward center (parking-sensor). → "gets a bit much." Monotonous over a long adjustment.
3. Rising-pitch discrete beeps. Better, but still same-note-ish and busy.
4. Continuous glide tone — one warm tone, pitch low→treble by closeness, resolving into the aura. → "the constant sound works but it's too much; not clicking." A continuous tone gives the ear no silence to rest on, so it fatigues; it also bypassed the tested scheduler.
5. Radar doublet on a per-band cadence — two sonar pings ~110 ms apart, repeating on a 1.3/0.9/0.6 s cadence while off-level. The literal two-ping "pew-pew" read as UI/radar beeps, not sonar, and the continued cadence was still a clock. Kept the bands/pitch, dropped the cadence in favor of one packet per settle.
6. Continuous forcefield aura bed (looping CC0 ambience while locked). Seamless on a PC media player but clicked at the loop point through Android SoundPool. Pulled; a gapless bed needs AudioTrack/ExoPlayer.
7. Settle-gated two-ding "status packet" (banded pitch + gap, one packet per move→settle, fuller arrival ding at lock). Built, unit-tested, on-device tested. Coherent, but on the bench the settle-then-report model felt sparse/laggy for the fiddly 2-D surface adjustment — you want live "warmer/colder" while you're actually moving it, not a report after you stop. Superseded by continuous ticking for Surface. (The settle-then-report shape lives on for VOICE and for future EDGE, where a discrete per-settle report fits the 1-D task.)

Guiding principles (learned)

• Leave air between cues; silence is restful. (600 ms near cadence is responsive without being alarm territory; ~180 ms was alarm territory.)
• Pitch carries distance more reliably than volume (phone volume + room noise make loudness a poor information channel).
• Keep the SoundPool layer dumb; put decisions in tested pure logic.
• The centered sound needs source loudness/spectrum presence, not just a bigger volume number.
• No reverb/comb tails on phone speakers — they smear and lengthen fatigue.
• Reuse the real lock state for the centered handoff; never invent a second audio threshold.