AudioNumBuffersToEnqueue

AudioNumBuffersToEnqueue

#Overview

name: AudioNumBuffersToEnqueue

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

It is referenced in 7 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of AudioNumBuffersToEnqueue is to control the number of audio buffers that are kept in the queue for audio playback. This setting is part of the audio system in Unreal Engine 5 and affects audio latency and performance.

This setting variable is used across multiple platform-specific modules in Unreal Engine, including:

  1. MacTargetPlatform
  2. WindowsTargetPlatform
  3. AndroidRuntimeSettings
  4. IOSRuntimeSettings

The value of this variable is typically set in the platform-specific settings classes (e.g., UMacTargetSettings, UWindowsTargetSettings, UAndroidRuntimeSettings, UIOSRuntimeSettings). It can be configured through the project settings in the Unreal Editor.

This variable interacts with other audio-related settings, such as AudioCallbackBufferFrameSize and AudioSampleRate, to determine the overall audio performance and latency.

Developers should be aware of the following when using this variable:

  1. Increasing the number of buffers can help compensate for variable compute availability in audio callbacks on some platforms, but it also increases latency.
  2. The minimum value is platform-dependent (1 for most platforms, 2 for Android).
  3. The actual effect may vary depending on the target platform and device capabilities.

Best practices when using this variable include:

  1. Start with the default value for the target platform and adjust if necessary.
  2. Balance between latency and stability - use more buffers if experiencing audio dropouts, fewer for lower latency.
  3. Test thoroughly on target devices to ensure optimal audio performance.
  4. Consider the requirements of your specific game or application when adjusting this value.
  5. Coordinate with other audio settings to achieve the best overall audio experience.

#Setting Variables

#References In INI files

Location: <Workspace>/Projects/Lyra/Config/DefaultEngine.ini:304, section: [/Script/WindowsTargetPlatform.WindowsTargetSettings]

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Developer/Mac/MacTargetPlatform/Classes/MacTargetSettings.h:137

Scope (from outer to inner):

file
class        class UMacTargetSettings : public UObject

Source code excerpt:

	/** The number of buffers to keep enqueued. More buffers increases latency, but can compensate for variable compute availability in audio callbacks on some platforms. */
	UPROPERTY(config, EditAnywhere, Category = "Audio", meta = (ClampMin = "1", UIMin = "1", DisplayName = "Number of Buffers To Enqueue"))
	int32 AudioNumBuffersToEnqueue;

	/** The max number of channels (voices) to limit for this platform. The max channels used will be the minimum of this value and the global audio quality settings. A value of 0 will not apply a platform channel count max. */
	UPROPERTY(config, EditAnywhere, Category = "Audio", meta = (ClampMin = "0", UIMin = "0", DisplayName = "Max Channels"))
	int32 AudioMaxChannels;

	/** The number of workers to use to compute source audio. Will only use up to the max number of sources. Will evenly divide sources to each source worker. */

#Loc: <Workspace>/Engine/Source/Developer/Windows/WindowsTargetPlatform/Classes/WindowsTargetSettings.h:74

Scope (from outer to inner):

file
class        class UWindowsTargetSettings : public UObject

Source code excerpt:

	/** The number of buffers to keep enqueued. More buffers increases latency, but can compensate for variable compute availability in audio callbacks on some platforms. */
	UPROPERTY(config, EditAnywhere, Category = "Audio", meta = (ClampMin = "1", UIMin = "1", DisplayName = "Number of Buffers To Enqueue"))
	int32 AudioNumBuffersToEnqueue;

	/** The max number of channels (voices) to limit for this platform. The max channels used will be the minimum of this value and the global audio quality settings. A value of 0 will not apply a platform channel count max. */
	UPROPERTY(config, EditAnywhere, Category = "Audio", meta = (ClampMin = "0", UIMin = "0", DisplayName = "Max Channels"))
	int32 AudioMaxChannels;

	/** The number of workers to use to compute source audio. Will only use up to the max number of sources. Will evenly divide sources to each source worker. */

#Loc: <Workspace>/Engine/Source/Developer/Windows/WindowsTargetPlatform/Private/WindowsTargetPlatformClasses.cpp:18

Scope (from outer to inner):

file
function     UWindowsTargetSettings::UWindowsTargetSettings

Source code excerpt:

	AudioSampleRate = 48000;
	AudioCallbackBufferFrameSize = 1024;
	AudioNumBuffersToEnqueue = 1;
	AudioNumSourceWorkers = 4;
}

static bool FilterShaderPlatform_D3D12(const FString& InShaderPlatform)
{
	return InShaderPlatform == TEXT("PCD3D_SM6") || InShaderPlatform == TEXT("PCD3D_SM5") || InShaderPlatform == TEXT("PCD3D_ES31");

#Loc: <Workspace>/Engine/Source/Runtime/Android/AndroidRuntimeSettings/Classes/AndroidRuntimeSettings.h:572

Scope (from outer to inner):

file
class        class UAndroidRuntimeSettings : public UObject

Source code excerpt:

	/** The number of buffers to keep enqueued. More buffers increases latency, but can compensate for variable compute availability in audio callbacks on some platforms. */
	UPROPERTY(config, EditAnywhere, Category = "Audio", meta = (ClampMin = "2", UIMin = "2", DisplayName = "Number of Buffers To Enqueue"))
	int32 AudioNumBuffersToEnqueue;

	/** The max number of channels (voices) to limit for this platform. The max channels used will be the minimum of this value and the global audio quality settings. A value of 0 will not apply a platform channel count max. */
	UPROPERTY(config, EditAnywhere, Category = "Audio", meta = (ClampMin = "0", UIMin = "0", DisplayName = "Max Channels"))
	int32 AudioMaxChannels;

	/** The number of workers to use to compute source audio. Will only use up to the max number of sources. Will evenly divide sources to each source worker. */

#Loc: <Workspace>/Engine/Source/Runtime/Android/AndroidRuntimeSettings/Private/AndroidRuntimeSettings.cpp:31

Scope (from outer to inner):

file
function     UAndroidRuntimeSettings::UAndroidRuntimeSettings

Source code excerpt:

	, AudioSampleRate(44100)
	, AudioCallbackBufferFrameSize(1024)
	, AudioNumBuffersToEnqueue(4)
	, CacheSizeKB(65536)
	, MaxSampleRate(48000)
	, HighSampleRate(32000)
    , MedSampleRate(24000)
    , LowSampleRate(12000)
	, MinSampleRate(8000)

#Loc: <Workspace>/Engine/Source/Runtime/AudioMixerCore/Private/AudioMixer.cpp:937

Scope (from outer to inner):

file
function     FAudioPlatformSettings FAudioPlatformSettings::GetPlatformSettings

Source code excerpt:

	}

	if (GConfig->GetString(PlatformSettingsConfigFile, TEXT("AudioNumBuffersToEnqueue"), TempString, GEngineIni))
	{
		Settings.NumBuffers = FMath::Max(FCString::Atoi(*TempString), 1);
	}

	if (GConfig->GetString(PlatformSettingsConfigFile, TEXT("AudioMaxChannels"), TempString, GEngineIni))
	{

#Loc: <Workspace>/Engine/Source/Runtime/IOS/IOSRuntimeSettings/Classes/IOSRuntimeSettings.h:515

Scope (from outer to inner):

file
class        class UIOSRuntimeSettings : public UObject

Source code excerpt:

	/** The number of buffers to keep enqueued. More buffers increases latency, but can compensate for variable compute availability in audio callbacks on some platforms. */
	UPROPERTY(config, EditAnywhere, Category = "Audio", meta = (ClampMin = "1", UIMin = "1", DisplayName = "Number of Buffers To Enqueue"))
	int32 AudioNumBuffersToEnqueue;

	/** The max number of channels (voices) to limit for this platform. The max channels used will be the minimum of this value and the global audio quality settings. A value of 0 will not apply a platform channel count max. */
	UPROPERTY(config, EditAnywhere, Category = "Audio", meta = (ClampMin = "0", UIMin = "0", DisplayName = "Max Channels"))
	int32 AudioMaxChannels;

	/** The number of workers to use to compute source audio. Will only use up to the max number of sources. Will evenly divide sources to each source worker. */