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. One vocabulary: faster ticks = approaching, the bullseye sound = centered right now. Timing is split, not sound identity:

• Outside the center zone: tick.wav (60 ms) repeats faster as you near level — axis-agnostic "warmer/colder", rate is the message. No settle gate. Rate is exponential in the error, clamped 1.5/s (≥~5°) → 8/s (≤~0.4°), hard-capped. Constant loudness (acceleration is the signal). Scheduling is anchored to the last tick off a monotonic clock, due-time recomputed each frame from the current interval → immediate reaction to changing tilt, no drift, no catch-up burst, ≤1 tick per update.
• Inside the center zone: the ticks give way to the looping level.wav immediately — no dwell, no velocity gate — even on a fast pass, because a momentary alignment is real, locating information (that little zone needs the most help). It stops the instant you leave. Alignment uses spatial hysteresis (enter ≤0.2°, rearm only after leaving ≥0.35°) — not a time debounce, which would hide a legitimate quick re-crossing — and is measured from the same hypot(stable pitch, stable roll) that drives the bubble, so the sound can't lag the visual. level.wav's stream id is retained and stopped before every restart / on exit.
• The stronger "held level" confirmation — persistent lime, the "Flat within 0.35°" label, and the haptic — is decided separately by the velocity-aware LockDetector (≤0.2° + ≤0.3°/s → 175 ms confirm). The locating sound never waits on it; a fast fly-through gets the bullseye cue but not the "you nailed it" confirmation.

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)

• Cue character decides tolerance more than raw rate. As discrete report cues, ~180 ms spacing felt alarm-like and ~600 ms felt calm — but as a continuous proximity tick an 8/s (125 ms) near rate reads as pleasant acceleration, not an alarm (it's a Geiger/parking sensor, and the ear expects it to quicken as you close in). Judge by feel on the phone.
• Volume is a poor information channel (phone volume + room noise make loudness unreliable) — let rate/pitch carry the message and keep loudness constant.
• 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.