au.ForceSyncAudioDecodes

au.ForceSyncAudioDecodes

#Overview

name: au.ForceSyncAudioDecodes

The value of this variable can be defined or overridden in .ini config files. 2 .ini config files referencing this setting variable.

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

It is referenced in 7 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of au.ForceSyncAudioDecodes is to control whether audio decoding operations are performed synchronously or asynchronously in Unreal Engine’s audio system. This setting variable is primarily used in the audio rendering and processing subsystem.

The Unreal Engine subsystem that relies on this setting variable is the Audio Mixer module, as evidenced by the file locations in the Engine/Source/Runtime/AudioMixer directory.

The value of this variable is set through a console variable (cvar) system. It’s initialized to 0 and can be changed at runtime using the console command “au.ForceSyncAudioDecodes”.

This variable interacts closely with its associated variable ForceSyncAudioDecodesCvar. They share the same value, with ForceSyncAudioDecodesCvar being the actual integer storage and au.ForceSyncAudioDecodes being the console-accessible name.

Developers must be aware that setting this variable to 1 will force all audio decoding to occur synchronously, which can impact performance, especially on lower-end systems or when dealing with many audio sources simultaneously. It’s primarily intended for debugging or specific use cases where synchronous decoding is necessary.

Best practices when using this variable include:

  1. Leaving it at the default value (0) for most scenarios to allow asynchronous decoding.
  2. Only enabling it (setting to 1) when debugging audio issues or when synchronous decoding is absolutely required.
  3. Being cautious about enabling it in shipping builds, as it can negatively impact performance.

Regarding the associated variable ForceSyncAudioDecodesCvar: This is an integer variable that directly stores the value set by au.ForceSyncAudioDecodes. It’s used in the actual C++ code to check whether synchronous decoding should be forced. The variable is checked in various places within the audio decoding system to determine whether to use synchronous or asynchronous task execution.

Developers should note that this variable is used in conjunction with other conditions (like bForceSyncDecode in some function parameters) to determine the final behavior. In some cases, synchronous decoding might be forced even if ForceSyncAudioDecodesCvar is 0, based on these other conditions.

The best practice when working with ForceSyncAudioDecodesCvar is to not modify it directly in code, but rather to use the au.ForceSyncAudioDecodes console variable to change its value when needed.

#Setting Variables

#References In INI files

Location: <Workspace>/Projects/Lyra/Config/Android/AndroidEngine.ini:21, section: [ConsoleVariables]

Location: <Workspace>/Projects/Lyra/Config/IOS/IOSEngine.ini:16, section: [ConsoleVariables]

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/AudioMixer/Private/AudioMixerSourceDecode.cpp:14

Scope: file

Source code excerpt:

static int32 ForceSyncAudioDecodesCvar = 0;
FAutoConsoleVariableRef CVarForceSyncAudioDecodes(
	TEXT("au.ForceSyncAudioDecodes"),
	ForceSyncAudioDecodesCvar,
	TEXT("Disables using async tasks for processing sources.\n")
	TEXT("0: Not Disabled, 1: Disabled"),
	ECVF_Default);

static int32 ForceSynchronizedAudioTaskKickCvar = 0;

#Loc: <Workspace>/Engine/Source/Runtime/AudioMixer/Private/AudioMixerSourceDecode.h:74

Scope (from outer to inner):

file
namespace    Audio

Source code excerpt:


		// Force this decoding operation to occur synchronously,
		// regardless of the value of au.ForceSyncAudioDecodes. (used by time synth)
		bool bForceSyncDecode;

		FDecodeAudioTaskData()
			: AudioData(nullptr)
			, DecompressionState(nullptr)
			, BufferType(Audio::EBufferType::Invalid)

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/AudioMixer/Private/AudioMixerSourceDecode.cpp:12

Scope: file

Source code excerpt:

#include "DSP/FloatArrayMath.h"

static int32 ForceSyncAudioDecodesCvar = 0;
FAutoConsoleVariableRef CVarForceSyncAudioDecodes(
	TEXT("au.ForceSyncAudioDecodes"),
	ForceSyncAudioDecodesCvar,
	TEXT("Disables using async tasks for processing sources.\n")
	TEXT("0: Not Disabled, 1: Disabled"),
	ECVF_Default);

static int32 ForceSynchronizedAudioTaskKickCvar = 0;
FAutoConsoleVariableRef CVarForceSynchronizedAudioTaskKick(

#Loc: <Workspace>/Engine/Source/Runtime/AudioMixer/Private/AudioMixerSourceDecode.cpp:269

Scope (from outer to inner):

file
namespace    Audio
class        class FHeaderDecodeHandle : public FDecodeHandleBase
function     FHeaderDecodeHandle

Source code excerpt:

	{
		Task = new FAsyncTask<FAsyncDecodeWorker>(InJobData);
        if (ForceSyncAudioDecodesCvar)
        {
            Task->StartSynchronousTask();
            return;
        }
        
		Task->StartBackgroundTask();

#Loc: <Workspace>/Engine/Source/Runtime/AudioMixer/Private/AudioMixerSourceDecode.cpp:290

Scope (from outer to inner):

file
namespace    Audio
class        class FProceduralDecodeHandle : public FDecodeHandleBase
function     FProceduralDecodeHandle

Source code excerpt:

	{
		Task = new FAsyncTask<FAsyncDecodeWorker>(InJobData);
        if (ForceSyncAudioDecodesCvar || InJobData.bForceSyncDecode)
        {
            Task->StartSynchronousTask();
            return;
        }
        
		// We tried using the background priority thread pool

#Loc: <Workspace>/Engine/Source/Runtime/AudioMixer/Private/AudioMixerSourceDecode.cpp:334

Scope (from outer to inner):

file
namespace    Audio
class        class FSynchronizedProceduralDecodeHandle : public FDecodeHandleBase
function     FSynchronizedProceduralDecodeHandle

Source code excerpt:

		// failed to queue it up, so do a normal start...
		QueueId = 0;
		if (ForceSyncAudioDecodesCvar || InJobData.bForceSyncDecode)
		{
			Task->StartSynchronousTask();
			return;
		}
		Task->StartBackgroundTask();
	}

#Loc: <Workspace>/Engine/Source/Runtime/AudioMixer/Private/AudioMixerSourceDecode.cpp:483

Scope (from outer to inner):

file
namespace    Audio
class        class FDecodeHandle : public FDecodeHandleBase
function     FDecodeHandle

Source code excerpt:

	{
		Task = new FAsyncTask<FAsyncDecodeWorker>(InJobData);
        if (ForceSyncAudioDecodesCvar || InJobData.bForceSyncDecode)
        {
            Task->StartSynchronousTask();
            return;
        }
        
		const bool bUseBackground = ShouldUseBackgroundPoolFor_FAsyncRealtimeAudioTask();