au.WaitForSoundWaveToLoad

au.WaitForSoundWaveToLoad

#Overview

name: au.WaitForSoundWaveToLoad

This variable is created as a Console Variable (cvar).

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of au.WaitForSoundWaveToLoad is to control whether the audio system should wait for a USoundWave to be fully loaded before attempting to play it back.

This setting variable is primarily used by the Unreal Engine’s audio system, specifically within the Engine module. It’s referenced in the AudioDevice.cpp file, which is a core component of the audio playback system.

The value of this variable is set using a console variable (CVar) system. It’s initialized to 1 by default, meaning it will wait for sound waves to load before playing.

The au.WaitForSoundWaveToLoad variable interacts directly with the WaitForSoundWaveToLoadCvar variable. They share the same value, with WaitForSoundWaveToLoadCvar being the actual integer variable used in the code logic.

Developers must be aware that when this variable is set to 1 (default), the audio system will refuse to play any sound unless the corresponding USoundWave has been fully loaded. This can prevent audio glitches or missing sounds, but may introduce slight delays in audio playback.

Best practices when using this variable include:

  1. Keep it enabled (set to 1) for most scenarios to ensure smooth audio playback.
  2. Consider disabling it (set to 0) only if you’re certain that all your audio assets will be loaded in time, or if you’re willing to risk some sounds not playing immediately.
  3. Be mindful of potential performance impacts, especially when loading many sounds simultaneously.

Regarding the associated variable WaitForSoundWaveToLoadCvar:

The purpose of WaitForSoundWaveToLoadCvar is to serve as the actual integer storage for the au.WaitForSoundWaveToLoad setting.

This variable is used directly in the audio system’s logic, specifically in the FAudioDevice::StartSources function. It determines whether the system should skip starting a sound source if the corresponding WaveData is still loading or in the process of being precached.

The value of WaitForSoundWaveToLoadCvar is set through the au.WaitForSoundWaveToLoad console variable.

It interacts closely with the PrecacheState of sound waves and the RF_NeedLoad flag to determine if a sound should be played or not.

Developers should be aware that modifying WaitForSoundWaveToLoadCvar directly is not recommended. Instead, they should use the au.WaitForSoundWaveToLoad console variable to change its value.

Best practices for WaitForSoundWaveToLoadCvar include:

  1. Avoid modifying it directly in code; use the console variable system instead.
  2. When debugging audio issues, check its value to understand if sound loading is affecting playback.
  3. Consider its impact on audio playback timing when optimizing game performance.

#References in C++ code

#Callsites

This variable is referenced in the following C++ source code:

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/AudioDevice.cpp:104

Scope: file

Source code excerpt:

static int32 WaitForSoundWaveToLoadCvar = 1;
FAutoConsoleVariableRef CVarWaitForSoundWaveToLoad(
	TEXT("au.WaitForSoundWaveToLoad"),
	WaitForSoundWaveToLoadCvar,
	TEXT("When set to 1, we will refuse to play any sound unless the USoundWave has been loaded.\n")
	TEXT("0: Attempt to play back, 1: Wait for load."),
	ECVF_Default);

static int32 BakedAnalysisEnabledCVar = 1;

#Associated Variable and Callsites

This variable is associated with another variable named WaitForSoundWaveToLoadCvar. They share the same value. See the following C++ source code.

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/AudioDevice.cpp:102

Scope: file

Source code excerpt:

	ECVF_Default);

static int32 WaitForSoundWaveToLoadCvar = 1;
FAutoConsoleVariableRef CVarWaitForSoundWaveToLoad(
	TEXT("au.WaitForSoundWaveToLoad"),
	WaitForSoundWaveToLoadCvar,
	TEXT("When set to 1, we will refuse to play any sound unless the USoundWave has been loaded.\n")
	TEXT("0: Attempt to play back, 1: Wait for load."),
	ECVF_Default);

static int32 BakedAnalysisEnabledCVar = 1;
FAutoConsoleVariableRef CVarBakedAnalysisEnabledCVar(

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/AudioDevice.cpp:4402

Scope (from outer to inner):

file
function     void FAudioDevice::StartSources

Source code excerpt:

		ESoundWavePrecacheState PrecacheState = WaveData->GetPrecacheState();
		const bool bIsSoundWaveStillLoading = WaveData->HasAnyFlags(RF_NeedLoad);
		if (PrecacheState == ESoundWavePrecacheState::InProgress || (WaitForSoundWaveToLoadCvar && bIsSoundWaveStillLoading))
		{
			continue;
		}

		// Editor uses bIsUISound for sounds played in the browser.
		if (!WaveInstance->ShouldStopDueToMaxConcurrency() && (bGameTicking || WaveInstance->bIsUISound))