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:** Currently PLACEHOLDER (Sprint 7). Redo scheduled next audio sprint (#453). Design brief below captures target register.

## Assets

| ID | Filename | Status | Bus | Method | Duration | Prompt/Notes | Sprint |
|----|----------|--------|-----|--------|----------|-------------|--------|
| UI-001 | `cursor_hover.ogg` | draft | UI Sounds | SAO | 50-100ms | Subtle tick/ping on entity hover (D-056). Insert-tech: clean, precise, synthetic. Almost subliminal — notice if missing, not if present. Needs trim to target duration (#453). | S7 #440 |
| UI-002 | `implant_open.ogg` | draft | UI Sounds | SAO | 150-250ms | Rising tone when insert UI opens (radial menu, inventory, stance). Neural lattice powering up. Frequency sweep, harmonic shimmer. Needs trim (#453). | S7 #440 |
| UI-003 | `fog_recognition.ogg` | draft | UI Sounds | SAO | 300-400ms | Warm organic chime at onset of cognitive delay (D-060). Character recognizing a person. Unresolved tone. Needs trim (#453). | S7 #440 |
| UI-004 | `weapon_aim.ogg` | draft | UI Sounds | SAO | 100-150ms | Harder click/lock for weapon aim state. Mechanical, deliberate. SKETCH ONLY — no weapons in Sprint 7. Needs trim (#453). | S7 #440 |
| UI-005 | `sfx_monologue_chime.ogg` | draft | UI Sounds | SAO | 500-1000ms | PLACEHOLDER. Soft crystalline tone, neural lattice surfacing a thought. Quiet, non-intrusive. Redo in next audio sprint (#453). See design brief below. | S7 #440 |
| UI-006 | `sfx_monologue_chime_urgent.ogg` | draft | UI Sounds | SAO | 500-1000ms | PLACEHOLDER. Sharper variant for contradiction/anomaly. Brighter, more insistent. Redo in next audio sprint (#453). See design brief below. | S7 #440 |
| UI-007 | `sfx_weapon_aim_lock.ogg` | draft | UI Sounds | SAO | 300-500ms | Sharp targeting lock-on confirmation for weapon aim. Clinical/dangerous, harder than general entity lock. Descending digital sweep with metallic precision click. | S8 #440 |
| UI-008 | `sfx_stance_change.ogg` | draft | UI Sounds | SAO | 200-400ms | Soft mechanical mode-switch click for stance toggle (Walk/Sprint/Careful/Crouch). Subtle digital detent, nearly subliminal. Fires frequently — fatigue-safe. | S8 #440 |

## 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 (PLACEHOLDER)

**Target emotional register for Sprint 8 redo:**

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."

**Placeholder spec (Sprint 7):**
- Normal: pure sine 1.2kHz, 600ms, gentle attack, natural decay. Conservative volume.
- Urgent: sine 1.2kHz + harmonic 2.4kHz, 400ms, sharper attack, 15% louder.
- Deliberately undersized — obviously temporary. Ugly placeholders get replaced.

**Evaluation gate:** First internal playtest after Sprint 7: "Does the normal chime feel like a thought arriving? Does the urgent chime create a physiological response?" If no → trigger chime redesign.