au.ForceSynchronizedAudioTaskKick

au.ForceSynchronizedAudioTaskKick

#Overview

name: au.ForceSynchronizedAudioTaskKick

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

• type: Var
• help: Force all Audio Tasks created in one \

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of au.ForceSynchronizedAudioTaskKick is to control the synchronization of audio tasks within the Unreal Engine’s audio mixer system. It forces all audio tasks created in one “audio render frame” to be queued until they can all be executed simultaneously at the end of the frame.

This setting variable is primarily used by the audio mixer subsystem within Unreal Engine 5. It’s part of the audio rendering and processing pipeline, specifically in the context of task management for audio decoding and processing.

The value of this variable is set through the Unreal Engine’s console variable system. It’s defined as an FAutoConsoleVariableRef, which allows it to be modified at runtime through console commands or configuration files.

The associated variable ForceSynchronizedAudioTaskKickCvar directly interacts with au.ForceSynchronizedAudioTaskKick. They share the same value, with ForceSynchronizedAudioTaskKickCvar being the actual integer variable used in the code, while au.ForceSynchronizedAudioTaskKick is the console-accessible name.

Developers must be aware that enabling this variable (setting it to 1) will change the behavior of audio task execution. Instead of tasks being executed as soon as they’re created, they will be queued and executed together at the end of the audio render frame. This can affect audio processing timing and potentially impact performance or audio quality.

Best practices when using this variable include:

1. Use it for debugging or profiling audio performance issues.
2. Be cautious when enabling it in production builds, as it may impact audio performance or quality.
3. Test thoroughly with both enabled and disabled states to understand its impact on your specific audio implementation.

Regarding the associated variable ForceSynchronizedAudioTaskKickCvar:

• Its purpose is to provide a C++ accessible version of the au.ForceSynchronizedAudioTaskKick setting.
• It’s used directly in the audio mixer’s source decoding logic to determine whether to create synchronized or asynchronous audio tasks.
• Its value is set by the console variable system when au.ForceSynchronizedAudioTaskKick is modified.
• It interacts closely with the SoundGenerator’s GetSynchronizedRenderQueueId() method to determine the task queue behavior.
• Developers should be aware that this variable directly affects the audio task creation logic in the CreateAudioTask function.
• Best practices include using this variable consistently with au.ForceSynchronizedAudioTaskKick and considering its impact on audio task scheduling when modifying audio-related code.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

static int32 ForceSynchronizedAudioTaskKickCvar = 0;
FAutoConsoleVariableRef CVarForceSynchronizedAudioTaskKick(
	TEXT("au.ForceSynchronizedAudioTaskKick"),
	ForceSynchronizedAudioTaskKickCvar,
	TEXT("Force all Audio Tasks created in one \"audio render frame\" to be queued until they can all be \"kicked\" at once at the end of the frame.\n")
	TEXT("0: Don't Force, 1: Force"),
	ECVF_Default);

namespace Audio

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	ECVF_Default);

static int32 ForceSynchronizedAudioTaskKickCvar = 0;
FAutoConsoleVariableRef CVarForceSynchronizedAudioTaskKick(
	TEXT("au.ForceSynchronizedAudioTaskKick"),
	ForceSynchronizedAudioTaskKickCvar,
	TEXT("Force all Audio Tasks created in one \"audio render frame\" to be queued until they can all be \"kicked\" at once at the end of the frame.\n")
	TEXT("0: Don't Force, 1: Force"),
	ECVF_Default);

namespace Audio
{

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

Scope (from outer to inner):

file
namespace    Audio
function     IAudioTask* CreateAudioTask

Source code excerpt:

IAudioTask* CreateAudioTask(Audio::FDeviceId InDeviceId, const FProceduralAudioTaskData& InJobData)
{
	if (ForceSynchronizedAudioTaskKickCvar || (InJobData.SoundGenerator && InJobData.SoundGenerator->GetSynchronizedRenderQueueId()))
	{
		AudioTaskQueueId QueueId = InJobData.SoundGenerator->GetSynchronizedRenderQueueId();
		if (!QueueId)
		{
			// Only use the audio device ID as the task queue id if both 
			// ForceSynchronizedAudioTaskKickCvar is true AND the caller has
			// not specified a specific task queue id in their SoundGenerator.
			QueueId = (AudioTaskQueueId)InDeviceId;
		}
		return new FSynchronizedProceduralDecodeHandle(InJobData, QueueId);
	}