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.