[codex] v3.31 add optional proximity sonification

[Anthonyiswhy]

Summary

Follow-on PR stacked on #17. This adds an optional non-speech proximity tone layer inspired by the IJHCS sonification guidance study.

This should be tested only after #17 behaves acceptably in the hallway.

What changed

• Added optional ProximityTonePlayer for local stereo pulses.
• Kept speech as the action/safety channel; tones are only ambient nearby-hazard cues.
• Added exponential distance-to-pulse-rate mapping:
  • close hazards pulse faster
  • far hazards are quieter by policy / not pulsed in balanced mode
• Added stereo panning:
  • left hazard: stronger left channel
  • right hazard: stronger right channel
  • ahead: centered pulse
• Tones skip playback while speech is active so they do not compete with safety speech.
• Added audio mode config:
  • BLINDNAV_AUDIO_MODE=quiet|balanced|training
  • BLINDNAV_PROXIMITY_TONES=1
  • BLINDNAV_TONE_VOLUME=0.0..1.0
• Added tools/run_tts_clips_tones.sh for later field testing.
• Added hardware-free regression tests for tone mapping, panning, busy-audio suppression, and pulse playback.

Why

The study suggests a useful split: use short verbal instructions for requested actions, and non-speech sonification for quantities like distance/remaining correction. For BlindNav, that maps well to:

• speech: urgent/warning commands such as Stop, person left, obstacle ahead
• tones: lightweight proximity cue for nearby hazards without adding more spoken information

Validation

• python3 -m pytest tests/test_blindnav_v326.py::TestProximityTonePlayer -q
  • 5 passed
• python3 -m pytest tests/test_blindnav.py tests/test_blindnav_v326.py -q
  • first run hit a known timing-sensitive playback-start assertion, rerun of that exact test passed
  • final full rerun: 211 passed in 12.74s

Field test order

1. Test [codex] v3.30 reduce audio overload in hallway alerts #17 first with plain clip mode:

cd ~/blind_navigation_aid
source ~/blindnav-venv/bin/activate
export BLINDNAV_LOG_UPLOAD=1
export BLINDNAV_VOICE_INPUT=0
./tools/run_tts_clips.sh

2. If [codex] v3.30 reduce audio overload in hallway alerts #17 is acceptable, test this PR:

cd ~/blind_navigation_aid
source ~/blindnav-venv/bin/activate
export BLINDNAV_LOG_UPLOAD=1
export BLINDNAV_VOICE_INPUT=0
./tools/run_tts_clips_tones.sh

Listen for whether the pulses improve nearby side/ahead awareness without masking hallway sounds or making speech harder to catch.

[Anthonyiswhy]

Synced the side-pass alert priority fix from PR #17 into this stacked tone PR in 94bf9e0. Tests on this branch: python3 -m pytest tests/test_blindnav.py tests/test_blindnav_v326.py -q (213 passed).

[Anthonyiswhy]

Field-log follow-up from the 2026-05-21/2026-05-22 school runs, ignoring the classroom entry/exit edges: updated PR #18 in f7db8ce so proximity tones can still play for close/side hazards while speech is busy, and tone mode now defers non-person obstacle speech beyond the closest range to avoid stacking long obstacle clips. Person voice alerts remain protected. Tests: python3 -m pytest tests/test_blindnav.py tests/test_blindnav_v326.py -q (215 passed).

[Anthonyiswhy]

Voice command fix: logs from 2026-05-29 showed STT sometimes returned the old prompt text itself: "BlindNav voice commands: describe, nearest, people, status, repeat, cancel." The parser saw cancel and spoke "Voice command canceled." Updated in c107cbd to detect prompt echoes as no command heard, make cancel stricter, and remove the cancel word/list-style prompt from the STT prompt. Tests: python3 -m pytest tests/test_blindnav.py tests/test_blindnav_v326.py -q (219 passed).

[Anthonyiswhy]

Detection-to-alert fix from the 2026-05-29 hallway run: the middle segment showed many confirmed detections were being logged but suppressed as static_stationary_suppression because IMU/user_moving stayed still for most of the hallway. Updated in 27a202d so nearby confirmed detections still speak awareness even when IMU says still: people within 2.2m and obstacles within 1.4m. Also stopped proximity tones from replacing urgent obstacle voice. No COCO classes were removed or ignored. Tests: python3 -m pytest tests/test_blindnav.py tests/test_blindnav_v326.py -q (221 passed).