# V2 Visual Sound Indicators

This runbook covers `TODOS.phase-72.72.13.1.7`: directional HUD indicators for
off-screen sounds, including gunfire, footsteps, and environmental hazards.

## Runtime Surface

The visual sound indicator profile lives in V2UI:

- C++ header: `V2/ue/Source/V2UI/Public/V2VisualSoundIndicators.h`
- C++ source: `V2/ue/Source/V2UI/Private/V2VisualSoundIndicators.cpp`
- automation spec:
  `V2/ue/Source/V2Tests/Private/UI/VisualSoundIndicators.spec.cpp`
- contract:
  `V2/ue/Content/V2/UI/Accessibility/VisualSoundIndicators_V2_Contract.json`
- focused checker: `V2/ue/Tools/check-v2-visual-sound-indicators.py`

`FV2VisualSoundIndicators::BuildDefaultProfile` returns
`Accessibility.VisualSoundIndicators.V2` for the
`HUD.Accessibility.VisualSoundIndicators` surface.

## Cue Coverage

The profile maps each required off-screen sound class to a distinct shape and
icon token:

- Gunfire: `Chevron`, `UI.Icon.SoundIndicator.Gunfire`
- Footstep: `Footprint`, `UI.Icon.SoundIndicator.Footstep`
- EnvironmentalHazard: `WarningDiamond`,
  `UI.Icon.SoundIndicator.EnvironmentalHazard`

`FV2VisualSoundIndicators::BuildRenderItem` converts an off-screen sound event
into an `FV2VisualSoundIndicatorRenderItem` with a safe-area-clamped screen-edge
anchor, rotation, scale, opacity, shape, and priority. The render item remains
valid when audio is muted.

## Release Policy

The profile is valid only when it:

- displays directional indicators for off-screen sounds;
- covers gunfire, footsteps, and environmental hazards;
- clamps indicators to the HUD safe area;
- works when audio is muted;
- uses shape/icon coding in addition to color;
- combines with subtitles and closed captions.

## Verification

Run these checks after changing visual sound indicators:

```bash
python3 V2/ue/Tools/check-v2-visual-sound-indicators.py
python3 V2/ue/Tools/check-v2-ui-module.py
python3 V2/ue/Tools/check-v2-ci-workflow.py
python3 V2/tools/validate-v2-docs.py
python3 -m py_compile V2/ue/Tools/check-v2-visual-sound-indicators.py V2/ue/Tools/check-v2-ci-workflow.py
python3 -m json.tool V2/ue/Content/V2/UI/Accessibility/VisualSoundIndicators_V2_Contract.json
```

Automation test name: `V2.UI.Accessibility.VisualSoundIndicators.AssetContract`.

## Horde Gates

- `visual-sound-indicators-source`
- `visual-sound-indicators-cue-coverage`
- `visual-sound-indicators-directional-projection`
- `visual-sound-indicators-muted-audio`
- `visual-sound-indicators-automation`
- `visual-sound-indicators-ci-wired`