settled-reach/docs/assets/audio/ui.md

# UI — Audio Assets

Interface sounds triggered by player interaction, insert systems, and cognitive events. Non-positional (AudioStreamPlayer). Routes to UI Sounds bus.

## Generation Approach

- **All UI sounds:** Generated via Stable Audio Open with sonic family prefix prompts, then trimmed/normalized/converted via `audio-post pipeline`.
- **Monologue chimes:** Replaced in Sprint 10 (#327) with manual synthesis. Insert-tech aesthetic: pure sine harmonics, mathematical envelope, no SAO. Previous S9 SAO versions were acknowledged placeholders per D-038 amendment.

## Assets

| ID | Filename | Status | Bus | Method | Duration | Prompt/Notes | Sprint |
|----|----------|--------|-----|--------|----------|-------------|--------|
| UI-001 | `cursor_hover.ogg` | done | UI Sounds | SAO | 77ms | Subtle tick/ping on entity hover (D-056). Insert-tech: clean, precise, synthetic. Trimmed + normalized to 44.1kHz in S9 #453. | S7 #440, S9 #453 |
| UI-002 | `implant_open.ogg` | done | UI Sounds | SAO | 217ms | Rising tone when insert UI opens (radial menu, inventory, stance). Neural lattice powering up. Trimmed + normalized in S9 #453. | S7 #440, S9 #453 |
| UI-003 | `fog_recognition.ogg` | done | UI Sounds | SAO | 400ms | Warm organic chime at onset of cognitive delay (D-060). Re-generated in S9 — original was silent. Organic prefix + Chimes template. | S7 #440, S9 #453 |
| UI-004 | `weapon_aim.ogg` | done | UI Sounds | SAO | 127ms | Harder click/lock for weapon aim state. Mechanical, deliberate. Trimmed + normalized in S9 #453. | S7 #440, S9 #453 |
| UI-005 | `sfx_monologue_chime.ogg` | done | UI Sounds | manual synthesis | 800ms | Production-quality manual synthesis in S10. Insert-tech: 1200Hz fundamental + harmonics (2400Hz -12dB, 3600Hz -24dB, 6000Hz -30dB). 15ms attack, 0.2 sustain ratio, exp decay. Peak -15dB. No SAO — pure mathematical precision. | S7 #440, S9 #453, S10 #327 |
| UI-006 | `sfx_monologue_chime_urgent.ogg` | done | UI Sounds | manual synthesis | 800ms | Production-quality manual synthesis in S10. Insert-tech: 1220Hz fundamental (detuned +20Hz for tension) + stronger harmonics (2440Hz -6dB, 3660Hz -18dB, 5087Hz -24dB, inharmonic 5087Hz -28dB). 8ms attack, 0.3 sustain ratio. Peak -6.3dB. | S7 #440, S9 #453, S10 #327 |
| UI-007 | `sfx_weapon_aim_lock.ogg` | done | UI Sounds | SAO | 505ms | Sharp targeting lock-on confirmation for weapon aim. Downsampled to 44.1kHz + normalized in S9 #453. | S8 #440, S9 #453 |
| UI-008 | `sfx_stance_change.ogg` | done | UI Sounds | SAO | 349ms | Soft mechanical mode-switch click for stance toggle. Downsampled to 44.1kHz + normalized in S9 #453. | S8 #440, S9 #453 |

## Mix Specs (not audio files)

These are AudioBus parameter changes, documented in `docs/audio/dialogue-ambient-dip.md`:

| Spec | Trigger | Effect | Sprint |
|------|---------|--------|--------|
| Dialogue dip | Dialogue box opens | Ambient -6 to -8dB, 300ms ease-in, 500ms ease-out | S7 #440 |
| Confrontation dip | Confrontation dialogue | Ambient -10 to -12dB + LP (800Hz), World SFX -4 to -6dB, 500ms ease-in, 1000ms ease-out | S7 #440 |

## Detailed Entries

### UI-001: cursor_hover
- **Sonic family:** insert-tech
- **Frequency range:** 3-4kHz primary
- **Design principle:** "Like breathing — present, functional, invisible." Player shouldn't describe it if asked, but would notice absence. Fatigue test critical — plays 300+ times per session.
- **Generation:** Pure synthesis. Sine tone at 3.2kHz, exponential decay over 40-50ms. No SAO — precision and purity are the point.
- **Debouncing:** AudioManager enforces 100ms cooldown between plays (rapid mouse movement).
- **Integration:** CursorRenderer.cursor_state_changed signal → AudioManager.play_ui("cursor_hover")
- **Cross-reference:** D-056 (cursor states)

### UI-003: fog_recognition
- **Sonic family:** organic
- **Frequency range:** 300Hz-1.5kHz
- **Design principle:** "The sound you hear internally when something clicks into place." Not a chime — more like a soft exhalation of tone. Sits BETWEEN insert sounds and ambient — not UI, not world, cognition.
- **Timing (Q-014 resolved):** Fires at ONSET of cognitive delay. Sequence: hear something in fog → chime plays → 0.6s delay → monologue during delay → blob transitions to D-033 color. Chime is "your character is processing," color transition is "recognition complete."
- **Integration:** Cognitive delay onset event → AudioManager.play_ui("fog_recognition")
- **Cross-reference:** D-060 (cognitive delay), D-018 (three-range sound, medium range)

### UI-007: sfx_weapon_aim_lock
- **Sonic family:** insert-tech
- **Frequency range:** 1-3kHz primary
- **Design principle:** "Crosshair snapping to bone." Clinical confirmation that the weapon system has acquired a target. Harder and more aggressive than cursor_entity_lock — this is the weapon variant. Still UI feedback, not a combat sound. Should not startle.
- **Generation:** SAO 5s generation, trimmed to best 0.5s transient. Insert-tech prefix + UI template. CFG 8, 100 steps.
- **Integration:** cursor_state_machine.gd weapon_aim_lock signal → AudioManager.play_ui("sfx_weapon_aim_lock")
- **Cross-reference:** D-056 (cursor states), weapon_aim.ogg (aim enter, different from lock)

### UI-008: sfx_stance_change
- **Sonic family:** insert-tech
- **Frequency range:** 1-2kHz primary
- **Design principle:** "A precision dial clicking one notch." Subtle neural insert feedback on stance toggle. Player may toggle stances many times while positioning — must be short, pleasant, fatigue-safe. No long tails, no reverb. Nearly subliminal.
- **Generation:** SAO 5s generation, trimmed to best 0.35s transient. Insert-tech prefix + UI template. CFG 8, 100 steps.
- **Debouncing:** AudioManager should enforce 150ms cooldown (rapid stance toggling).
- **Integration:** stance_indicator.gd stance_changed signal → AudioManager.play_ui("sfx_stance_change")
- **Cross-reference:** D-048 (neural insert feedback aesthetic), D-053 (movement stances)

### UI-005 / UI-006: Monologue Chime Design Brief

**Target emotional register (achieved Sprint 9 #453):**

The monologue chimes are the two poles of augmented cognition made audible:

| Variant | Meaning | Feel | Target |
|---------|---------|------|--------|
| Normal | "My lattice surfaced this" | A thought arriving — not a notification. Like your own attention shifting. | Player never consciously notices it. Pavlovian: text appeared, brain registered, moved on. |
| Urgent | "My lattice flagged a contradiction" | Productive discomfort. "Wait, what did I miss?" | Micro-spike of alertness. Not alarm. The delta from normal must be SMALL but unmistakable. |

**Relationship to fog recognition chime:**
- Fog recognition = organic (biological cognition, warm, 300-800Hz)
- Monologue normal = insert-tech (crystalline, clean, higher register, ~1.2kHz)
- Monologue urgent = insert-tech (sharper, brighter, adds second harmonic ~2.4kHz)
- Same cognitive family, different branches. Cousins, not twins.

**Quality bar:** If the urgent chime feels like a quest marker ping, it has failed. If it feels like Ubisoft, it has failed. The delta between normal and urgent = "someone thinking quietly" vs "someone's eyes going slightly wide."

**Sprint 9 generation spec:**
- Normal: SAO 5s generation (insert-tech prefix + chimes template), CFG 7, 100 steps. Trimmed to 0.8s (attack + initial decay). LUFS normalized to -16.
- Urgent: SAO 5s generation (insert-tech prefix + chimes template, sharper/brighter descriptors), CFG 8, 100 steps. Trimmed to 0.8s. Stronger attack (-6.3dB peak vs -15.3dB normal), more sustained energy.
- Both at 44.1kHz stereo, Vorbis q6 encoding.

**Evaluation gate:** First internal playtest: "Does the normal chime feel like a thought arriving? Does the urgent chime create a physiological response?" If no → iterate with manual synthesis.