au.MetaSound.WavePlayer.MaxDecodeSizeInFrames

au.MetaSound.WavePlayer.MaxDecodeSizeInFrames

#Overview

name: au.MetaSound.WavePlayer.MaxDecodeSizeInFrames

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

• type: Var
• help: Max size in frames used for decoding audio in the MetaSound wave player node.\nDefault: 1024

It is referenced in 8 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of au.MetaSound.WavePlayer.MaxDecodeSizeInFrames is to control the maximum size (in frames) used for decoding audio in the MetaSound wave player node. This setting variable is primarily used in the audio rendering and decoding system of Unreal Engine 5.

The Unreal Engine subsystems that rely on this setting variable are primarily the MetaSound plugin and the audio rendering system. Based on the callsites, it’s used in the MetaSound Engine module and the HarmonixDsp plugin.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of 1024 frames and can be modified at runtime using the console command system.

This variable interacts closely with its associated variable MaxDecodeSizeInFrames, which is used in various parts of the audio system, including the StreamingAudioRendererV2 and SoundWaveProxyReader classes.

Developers must be aware that:

1. This variable affects the performance and memory usage of audio decoding.
2. The actual value used may be rounded up to the nearest power of two for efficiency.
3. It has a minimum value enforced by the system (DefaultMinDecodeSizeInFrames).

Best practices when using this variable include:

1. Only modify it if you understand the implications on audio performance and quality.
2. Consider the target platform’s capabilities when adjusting this value.
3. Profile the audio system performance before and after changes to ensure improvements.

Regarding the associated variable MaxDecodeSizeInFrames:

• It serves the same purpose as au.MetaSound.WavePlayer.MaxDecodeSizeInFrames but is used more broadly in the engine.
• It’s used in various audio-related classes like StreamingAudioRendererV2 and SoundWaveProxyReader.
• The value is typically set to 1024 frames by default but can be modified.
• It’s crucial for determining buffer sizes for audio decoding and streaming.
• Developers should be cautious when modifying this value, as it can affect audio performance and memory usage across multiple systems.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Plugins/Runtime/Metasound/Source/MetasoundEngine/Private/MetasoundWavePlayerNode.cpp:312

Scope (from outer to inner):

file
namespace    Metasound

Source code excerpt:

	static int32 MaxDecodeSizeInFrames = 1024;
	FAutoConsoleVariableRef CVarMetaSoundWavePlayerMaxDecodeSizeInFrames(
		TEXT("au.MetaSound.WavePlayer.MaxDecodeSizeInFrames"),
		MaxDecodeSizeInFrames,
		TEXT("Max size in frames used for decoding audio in the MetaSound wave player node.\n")
		TEXT("Default: 1024"),
		ECVF_Default);

	// Block size for deinterleaving audio. 

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Plugins/Runtime/Harmonix/Source/HarmonixDsp/Private/HarmonixDsp/AudioData/StreamingAudioRendererV2.cpp:498

Scope (from outer to inner):

file
function     TUniquePtr<FSoundWaveProxyReader> FStreamingAudioRendererV2::CreateProxyReader

Source code excerpt:

{
	FSoundWaveProxyReader::FSettings WaveReaderSettings;
	WaveReaderSettings.MaxDecodeSizeInFrames = MaxDecodeSizeInFrames;
	WaveReaderSettings.StartTimeInSeconds = 0.0f;
	WaveReaderSettings.bMaintainAudioSync = true;
	return FSoundWaveProxyReader::Create(WaveProxy, WaveReaderSettings);	
}

bool FStreamingAudioRendererV2::HasLoopSection() const

#Loc: <Workspace>/Engine/Plugins/Runtime/Harmonix/Source/HarmonixDsp/Private/HarmonixDsp/AudioData/StreamingAudioRendererV2.h:87

Scope (from outer to inner):

file
class        class FStreamingAudioRendererV2 : public IAudioDataRenderer

Source code excerpt:

	// but also large enough that we're decoding multiple times per block
	static constexpr int32 DeinterleaveBlockSizeInFrames = 256;
	static constexpr uint32 MaxDecodeSizeInFrames = 1024;

	int32 CalculateNumFramesNeeded(const FLerpData* LerpData, int32 NumPoints);
};

#Loc: <Workspace>/Engine/Plugins/Runtime/Metasound/Source/MetasoundEngine/Private/MetasoundWavePlayerNode.cpp:310

Scope (from outer to inner):

file
namespace    Metasound

Source code excerpt:

	// Maximum decode size in frames. 
	static int32 MaxDecodeSizeInFrames = 1024;
	FAutoConsoleVariableRef CVarMetaSoundWavePlayerMaxDecodeSizeInFrames(
		TEXT("au.MetaSound.WavePlayer.MaxDecodeSizeInFrames"),
		MaxDecodeSizeInFrames,
		TEXT("Max size in frames used for decoding audio in the MetaSound wave player node.\n")
		TEXT("Default: 1024"),
		ECVF_Default);

	// Block size for deinterleaving audio. 
	static int32 DeinterleaveBlockSizeInFrames = 512;

#Loc: <Workspace>/Engine/Plugins/Runtime/Metasound/Source/MetasoundEngine/Private/MetasoundWavePlayerNode.cpp:719

Scope (from outer to inner):

file
namespace    Metasound
class        class FWavePlayerOperator : public TExecutableOperator<FWavePlayerOperator>
function     bool StartPlaying

Source code excerpt:

				// Create the wave proxy reader.
				FSoundWaveProxyReader::FSettings WaveReaderSettings;
				WaveReaderSettings.MaxDecodeSizeInFrames = FMath::IsPowerOfTwo(MaxDecodeSizeInFrames) ? 
					MaxDecodeSizeInFrames : FMath::RoundUpToPowerOfTwo(MaxDecodeSizeInFrames);

				WaveReaderSettings.StartTimeInSeconds = StartTime->GetSeconds();
				WaveReaderSettings.LoopStartTimeInSeconds = LoopStartTime->GetSeconds();
				WaveReaderSettings.LoopDurationInSeconds = LoopDuration->GetSeconds(); 
				WaveReaderSettings.bIsLooping = *bLoop;

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Classes/Sound/SoundWaveProxyReader.h:47

Scope (from outer to inner):

file
class        class FSoundWaveProxyReader

Source code excerpt:

	struct FSettings
	{
		uint32 MaxDecodeSizeInFrames = 1024;
		float StartTimeInSeconds = 0.f;
		bool bIsLooping = false;
		float LoopStartTimeInSeconds = 0.f;
		float LoopDurationInSeconds = 0.f;
		bool bMaintainAudioSync = false;
	};

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/SoundWaveProxyReader.cpp:68

Scope (from outer to inner):

file
function     FSoundWaveProxyReader::FSoundWaveProxyReader

Source code excerpt:

	// Determine max size of decode buffer
	Settings.MaxDecodeSizeInFrames = FMath::Max(DefaultMinDecodeSizeInFrames, Settings.MaxDecodeSizeInFrames);

	// Prepare to read audio
	bIsDecoderValid = InitializeDecoder(Settings.StartTimeInSeconds);
}

/** Create a wave proxy reader.

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/SoundWaveProxyReader.cpp:404

Scope (from outer to inner):

file
function     bool FSoundWaveProxyReader::InitializeDecoder

Source code excerpt:

	// initialized decode buffers
	const uint32 DecodeSize = ConformDecodeSize(Settings.MaxDecodeSizeInFrames);
	NumFramesPerDecode = FMath::Max(DecodeSize, NumFramesPerDecode);
	ResidualBuffer.SetNum(NumFramesPerDecode * NumChannels);
	SampleConversionBuffer.SetNumUninitialized(NumFramesPerDecode * NumChannels);
	DecoderOutput.Reserve(/* MinCapacity = */ NumFramesPerDecode * NumChannels * 2, /* bRetainExistingSamples = */ false);
	NumDecodeSamplesToDiscard = 0;