ue-audio-system

What this skill does

# UE Audio System

You are an expert in Unreal Engine's audio systems, covering UAudioComponent, sound asset types,
spatial attenuation, concurrency management, submix routing, MetaSounds, and runtime audio analysis.

## Context Check

Before implementing audio, read `.agents/ue-project-context.md` for:

- **Audio plugins** enabled (Resonance Audio, Steam Audio, Wwise, FMOD, MetaSound plugin version)
- **Target platforms** — mobile has strict voice limits; consoles differ from PC
- **Dedicated server** flag — audio must be skipped server-side or it will crash/log errors
- **VR flag** — VR projects require binaural spatialization settings

## Information Gathering

Ask about:

1. One-shot SFX, looping ambient, music, UI feedback, or dialogue?
2. Spatialized (follows actor) or global 2D?
3. Concurrency concern (gunshots, footsteps, explosions)?
4. Runtime control needed (fade, pause, parameter changes)?
5. MetaSound procedural or pre-authored SoundCue/SoundWave?

---

## Sound Asset Hierarchy

```
USoundBase                    // abstract base (SoundBase.h)
  ├── USoundWave              // raw PCM/compressed audio asset
  ├── USoundCue               // node-graph: random, modulator, mixer, attenuator nodes
  └── UMetaSoundSource        // procedural audio graph (MetaSound plugin)
```

**USoundWave** — Import .wav/.ogg/.flac. Set `SoundClassObject` and `AttenuationSettings` on asset.

**USoundCue** — Node graph combining multiple waves. Key nodes:
`USoundNodeRandom`, `USoundNodeModulator`, `USoundNodeMixer`, `USoundNodeAttenuation`,
`USoundNodeLooping`, `USoundNodeDelay`, `USoundNodeDistanceCrossFade`.

**UMetaSoundSource** — Procedural audio graph. Declare typed inputs (float, bool, int32, trigger).
Set parameters at runtime via `UAudioComponent::SetFloatParameter`, `SetBoolParameter`, `SetIntParameter`.

### Streaming Long Audio

For music and ambient tracks exceeding ~30 seconds, set `USoundWave::LoadingBehavior`:
`ESoundWaveLoadingBehavior::ForceInline` for short SFX, `RetainOnLoad` for music loaded at level start.
Long files should use `LoadOnDemand` to avoid loading the full waveform into memory.
In the editor: SoundWave asset → Details → Loading → Loading Behavior.

---

## Playing Sounds from C++

### Fire-and-Forget

```cpp
#include "Kismet/GameplayStatics.h"

// 2D — not spatialized (UI, music)
UGameplayStatics::PlaySound2D(
    this, ImpactSound, 1.0f /*Vol*/, 1.0f /*Pitch*/, 0.0f /*StartTime*/,
    ConcurrencySettings, OwningActor
);

// 3D — spatialized, requires AttenuationSettings on the sound asset
UGameplayStatics::PlaySoundAtLocation(
    this, GunShotSound, GetActorLocation(), FRotator::ZeroRotator,
    1.0f, 1.0f, 0.0f,
    AttenuationOverride,    // USoundAttenuation* (nullptr = use asset default)
    ConcurrencyOverride,    // USoundConcurrency* (nullptr = use asset default)
    this                    // OwningActor for per-owner concurrency
);
```

### Spawn with Handle

```cpp
// Returns UAudioComponent* — auto-destroyed when sound finishes if bAutoDestroy=true
UAudioComponent* Comp = UGameplayStatics::SpawnSoundAtLocation(
    this, ExplosionSound, Location, FRotator::ZeroRotator,
    1.0f, 1.0f, 0.0f, AttenuationSettings, nullptr, /*bAutoDestroy=*/true
);

// Attach to a moving component (vehicle engine)
UAudioComponent* EngineAudio = UGameplayStatics::SpawnSoundAttached(
    EngineLoopSound, GetMesh(), NAME_None,
    FVector::ZeroVector, FRotator::ZeroRotator,
    EAttachLocation::SnapToTargetIncludingScale,
    /*bStopWhenAttachedToDestroyed=*/true,
    1.0f, 1.0f, 0.0f, AttenuationSettings, nullptr,
    /*bAutoDestroy=*/false   // keep alive for looping
);
```

### UAudioComponent as Permanent Actor Component

```cpp
// In constructor:
AudioComponent = CreateDefaultSubobject<UAudioComponent>(TEXT("AudioComponent"));
AudioComponent->SetupAttachment(RootComponent);
AudioComponent->bAutoActivate = false;
AudioComponent->bStopWhenOwnerDestroyed = true;
```

### Playback Control

```cpp
AudioComponent->SetSound(EngineLoopSound);
AudioComponent->Play(/*StartTime=*/0.0f);
AudioComponent->Stop();
AudioComponent->SetPaused(true);
AudioComponent->FadeIn(0.5f, 1.0f, 0.0f, EAudioFaderCurve::Linear);
AudioComponent->FadeOut(1.0f, 0.0f, EAudioFaderCurve::Linear);
AudioComponent->SetVolumeMultiplier(0.5f);
AudioComponent->SetPitchMultiplier(1.2f);

// Query play state (EAudioComponentPlayState: Playing, Stopped, Paused, FadingIn, FadingOut)
EAudioComponentPlayState State = AudioComponent->GetPlayState();
```

### Delegates (AudioComponent.h)

```cpp
// Declared in AudioComponent.h:
// DECLARE_DYNAMIC_MULTICAST_DELEGATE(FOnAudioFinished)
// DECLARE_DYNAMIC_MULTICAST_DELEGATE_TwoParams(FOnAudioPlaybackPercent, const USoundWave*, PlayingSoundWave, const float, PlaybackPercent)
// DECLARE_DYNAMIC_MULTICAST_DELEGATE_OneParam(FOnAudioPlayStateChanged, EAudioComponentPlayState, PlayState)

AudioComponent->OnAudioFinished.AddDynamic(this, &AMyActor::OnSoundFinished);
AudioComponent->OnAudioPlaybackPercent.AddDynamic(this, &AMyActor::OnPlaybackPercent);
AudioComponent->OnAudioPlayStateChanged.AddDynamic(this, &AMyActor::OnPlayStateChanged);

// Native (non-UObject) binding — no GC overhead:
// DECLARE_MULTICAST_DELEGATE_OneParam(FOnAudioFinishedNative, UAudioComponent*)
// DECLARE_MULTICAST_DELEGATE_ThreeParams(FOnAudioPlaybackPercentNative, const UAudioComponent*, const USoundWave*, const float)
AudioComponent->OnAudioFinishedNative.AddUObject(this, &AMyActor::OnSoundFinishedNative);
AudioComponent->OnAudioPlaybackPercentNative.AddUObject(this, &AMyActor::OnPlaybackPercentNative);
```

---

## Sound Attenuation (SoundAttenuation.h)

Defined in `USoundAttenuation` assets (wrapping `FSoundAttenuationSettings`).
Assign via `USoundBase::AttenuationSettings` or pass as override to play functions.

**Attenuation shapes** (`EAttenuationShape`): `Sphere` (default, omnidirectional), `Capsule` (elongated sources), `Box` (room-shaped), `Cone` (directional like spotlights).

**Distance model** (`EAttenuationDistanceModel`): `Linear`, `Logarithmic` (realistic), `NaturalSound` (perception-matched, recommended), `Inverse`, `LogReverse`, `Custom` (curve-driven).

```cpp
// Key FSoundAttenuationSettings fields:
uint8 bAttenuate : 1;          // enable distance-based volume falloff
uint8 bSpatialize : 1;         // enable 3D spatialization
// SpatializationAlgorithm: SPATIALIZATION_Default (panning), SPATIALIZATION_HRTF (binaural plugin)

uint8 bAttenuateWithLPF : 1;   // air absorption (distance-based lowpass)
float LPFRadiusMin;            // LPF starts at this distance (cm)
float LPFRadiusMax;            // LPF fully applied at this distance
float LPFFrequencyAtMin;       // Hz at min distance (e.g. 20000.f = bypass)
float LPFFrequencyAtMax;       // Hz at max distance (e.g. 800.f = muffled)

uint8 bEnableListenerFocus : 1;
float FocusAzimuth;            // in-focus cone half-angle (degrees)
float NonFocusAzimuth;         // non-focus cone half-angle (degrees)
float FocusDistanceScale;      // < 1.0 makes focused sound seem closer
float NonFocusVolumeAttenuation;

uint8 bEnableOcclusion : 1;
TEnumAsByte<ECollisionChannel> OcclusionTraceChannel; // e.g. ECC_Visibility
float OcclusionLowPassFilterFrequency;  // Hz when fully occluded
float OcclusionVolumeAttenuation;       // 0..1 volume scale when occluded
float OcclusionInterpolationTime;       // seconds to interpolate

uint8 bEnableReverbSend : 1;
EReverbSendMethod ReverbSendMethod;     // Linear, CustomCurve, Manual
float ReverbWetLevelMin;
float ReverbWetLevelMax;
float ReverbDistanceMin;
float ReverbDistanceMax;

uint8 bEnablePriorityAttenuation : 1;  // reduce priority of distant sounds
float PriorityAttenuationMin;
float PriorityAttenuationMax;

// Override attenuation inline on a UAudioComponent:
AudioComponent->bOverrideAttenuation = true;
AudioComponent->AttenuationOverrides.bAttenuate = true;
AudioComponent->AttenuationOverrides.bSpatialize = true;
AudioComponent->AttenuationOverrides.FalloffDista