au.MetaSound.WavePlayer.DeinterleaveBlockSizeInFrames

au.MetaSound.WavePlayer.DeinterleaveBlockSizeInFrames

#Overview

name: au.MetaSound.WavePlayer.DeinterleaveBlockSizeInFrames

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

It is referenced in 6 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of au.MetaSound.WavePlayer.DeinterleaveBlockSizeInFrames is to control the block size in frames used for deinterleaving audio in the MetaSound wave player node. This setting variable is primarily used in the audio rendering and processing system of Unreal Engine 5.

Based on the callsites provided, this setting variable is utilized by the Metasound plugin, which is part of Unreal Engine’s audio system. It’s specifically used in the MetasoundWavePlayerNode.cpp file, indicating its relevance to the wave player functionality within the Metasound system.

The value of this variable is set using an FAutoConsoleVariableRef, which means it can be adjusted at runtime through console commands. The default value is set to 512 frames.

This variable interacts closely with its associated variable DeinterleaveBlockSizeInFrames, which is used in various parts of the audio rendering system, including the StreamingAudioRendererV2 class in the HarmonixDsp plugin.

Developers should be aware that this variable affects the performance and quality of audio deinterleaving in the MetaSound wave player. A larger block size may improve performance but could potentially introduce more latency, while a smaller block size might reduce latency but increase CPU usage.

Best practices when using this variable include:

  1. Keeping it as a power of two for optimal performance, as evidenced by the code that rounds it up to the nearest power of two.
  2. Balancing between performance and latency based on the specific needs of the game or application.
  3. Testing different values to find the optimal setting for the particular use case.

Regarding the associated variable DeinterleaveBlockSizeInFrames:

The purpose of DeinterleaveBlockSizeInFrames is to define the block size used for deinterleaving audio in various parts of the audio rendering system, including both the MetaSound plugin and the HarmonixDsp plugin.

This variable is used in the StreamingAudioRendererV2 class, which is part of the HarmonixDsp plugin. It’s used to determine the size of decode buffers and the number of frames to generate when decoding source audio.

The value of this variable is set in different places, including a static constexpr declaration in the StreamingAudioRendererV2 class (with a value of 256) and the previously mentioned console variable in the MetaSound plugin.

Developers should be aware that this variable directly affects the audio decoding and rendering process. Its value impacts memory usage, CPU performance, and potentially audio quality or latency.

Best practices for using this variable include:

  1. Ensuring consistency across different parts of the audio system that use this value.
  2. Considering the trade-offs between buffer size, performance, and latency when adjusting this value.
  3. Testing thoroughly when changing this value to ensure it doesn’t introduce audio artifacts or syncing issues.

#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:321

Scope (from outer to inner):

file
namespace    Metasound

Source code excerpt:

	static int32 DeinterleaveBlockSizeInFrames = 512;
	FAutoConsoleVariableRef CVarMetaSoundWavePlayerDeinterleaveBlockSizeInFrames(
		TEXT("au.MetaSound.WavePlayer.DeinterleaveBlockSizeInFrames"),
		DeinterleaveBlockSizeInFrames,
		TEXT("Block size in frames used for deinterleaving audio in the MetaSound wave player node.\n")
		TEXT("Default: 512"),
		ECVF_Default);

	/** MetaSound operator for the wave player node. */

#Associated Variable and Callsites

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

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

Scope (from outer to inner):

file
function     void FStreamingAudioRendererV2::SetAudioData

Source code excerpt:

	int32 WaveProxyNumChannels = WaveProxyReader->GetNumChannels();

	int32 DecodeBufferSize = WaveProxyNumChannels * DeinterleaveBlockSizeInFrames;
	DecodeBuffer.Reset(DecodeBufferSize);
	DecodeBuffer.AddUninitialized(DecodeBufferSize);

	NumDeinterleaveChannels = WaveProxyNumChannels;

	LastLoopFrameCache.SetNumUninitialized(NumDeinterleaveChannels);

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

Scope (from outer to inner):

file
function     void FStreamingAudioRendererV2::DecodeSourceAudio

Source code excerpt:

void FStreamingAudioRendererV2::DecodeSourceAudio(Audio::TCircularAudioBuffer<float>& OutBuffer)
{
	const int32 NumSamplesToGenerate = DeinterleaveBlockSizeInFrames * WaveProxyReader->GetNumChannels();
	check(NumSamplesToGenerate == DecodeBuffer.Num());
	
	if (OutBuffer.Remainder() == 0)
	{
		return;
	}

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

Scope (from outer to inner):

file
class        class FStreamingAudioRendererV2 : public IAudioDataRenderer

Source code excerpt:

	// needs to be small enough to avoid audio artifacts and syncing issues
	// 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:319

Scope (from outer to inner):

file
namespace    Metasound

Source code excerpt:


	// Block size for deinterleaving audio. 
	static int32 DeinterleaveBlockSizeInFrames = 512;
	FAutoConsoleVariableRef CVarMetaSoundWavePlayerDeinterleaveBlockSizeInFrames(
		TEXT("au.MetaSound.WavePlayer.DeinterleaveBlockSizeInFrames"),
		DeinterleaveBlockSizeInFrames,
		TEXT("Block size in frames used for deinterleaving audio in the MetaSound wave player node.\n")
		TEXT("Default: 512"),
		ECVF_Default);

	/** MetaSound operator for the wave player node. */
	class FWavePlayerOperator : public TExecutableOperator<FWavePlayerOperator>

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

Scope (from outer to inner):

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

Source code excerpt:

				WaveProxyReader = FSoundWaveProxyReader::Create(WaveProxy.ToSharedRef(), WaveReaderSettings);

				DeinterleaveBufferBlockSizeInFrames = FMath::IsPowerOfTwo(DeinterleaveBlockSizeInFrames) ? 
					DeinterleaveBlockSizeInFrames : FMath::RoundUpToPowerOfTwo(DeinterleaveBlockSizeInFrames);

				if (WaveProxyReader.IsValid())
				{
					UpdateSampleRateFrameRatio();
					int32 WaveProxyNumChannels = WaveProxyReader->GetNumChannels();