au.Quartz.HeadlessClockSampleRate

au.Quartz.HeadlessClockSampleRate

#Overview

name: au.Quartz.HeadlessClockSampleRate

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

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of au.Quartz.HeadlessClockSampleRate is to set the sample rate for Quartz Clocks and Metronomes when no Mixer Device is present in the Unreal Engine audio system. This setting is particularly important for the audio subsystem, specifically the Quartz timing framework within the AudioMixer module.

The AudioMixer module relies on this setting variable when operating in a headless mode or when no audio device is available. It’s used in the FQuartzClock class, which is part of the Audio namespace.

The value of this variable is set through the Unreal Engine console variable system. It’s initialized with a default value of 100000.0f and can be modified at runtime using console commands.

This variable interacts closely with the associated variable HeadlessClockSampleRateCvar. They share the same value, with HeadlessClockSampleRateCvar being the actual storage for the sample rate value, while au.Quartz.HeadlessClockSampleRate is the console variable name used to access and modify it.

Developers must be aware that this variable is crucial for timing accuracy in audio-related operations when working in environments without a dedicated audio device. It directly affects the behavior of Quartz Clocks and Metronomes in such scenarios.

Best practices when using this variable include:

  1. Ensure it’s set to an appropriate value for your project’s audio requirements.
  2. Be cautious when modifying it at runtime, as it could affect ongoing audio operations.
  3. Consider the implications on timing and synchronization when changing this value.
  4. Use it in conjunction with other audio settings to achieve the desired audio behavior in headless environments.

Regarding the associated variable HeadlessClockSampleRateCvar:

The purpose of HeadlessClockSampleRateCvar is to store the actual value of the sample rate used by Quartz Clocks and Metronomes in headless mode. It’s a static float variable that directly holds the sample rate value.

This variable is used within the AudioMixer module, specifically in the FQuartzClock class implementations. It’s referenced when initializing clocks, changing tick rates, and adding quantized commands.

The value of HeadlessClockSampleRateCvar is set indirectly through the au.Quartz.HeadlessClockSampleRate console variable. They are linked using the FAutoConsoleVariableRef system.

HeadlessClockSampleRateCvar interacts primarily with the au.Quartz.HeadlessClockSampleRate console variable and is used in various methods of the FQuartzClock class.

Developers should be aware that modifying HeadlessClockSampleRateCvar directly is not recommended. Instead, they should use the console variable system to change the value of au.Quartz.HeadlessClockSampleRate.

Best practices for HeadlessClockSampleRateCvar include:

  1. Treat it as a read-only variable in most scenarios.
  2. Use the console variable system to modify its value indirectly.
  3. Be aware of its usage in critical audio timing calculations within the FQuartzClock class.
  4. Consider its impact on audio performance and accuracy when working with Quartz timing in headless environments.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/AudioMixer/Private/Quartz/AudioMixerClock.cpp:9

Scope: file

Source code excerpt:

static float HeadlessClockSampleRateCvar = 100000.f;
FAutoConsoleVariableRef CVarHeadlessClockSampleRate(
	TEXT("au.Quartz.HeadlessClockSampleRate"),
	HeadlessClockSampleRateCvar,
	TEXT("Sample rate to use for Quartz Clocks/Metronomes when no Mixer Device is present.\n")
	TEXT("0: Not Enabled, 1: Enabled"),
	ECVF_Default);

namespace Audio

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/AudioMixer/Private/Quartz/AudioMixerClock.cpp:7

Scope: file

Source code excerpt:



static float HeadlessClockSampleRateCvar = 100000.f;
FAutoConsoleVariableRef CVarHeadlessClockSampleRate(
	TEXT("au.Quartz.HeadlessClockSampleRate"),
	HeadlessClockSampleRateCvar,
	TEXT("Sample rate to use for Quartz Clocks/Metronomes when no Mixer Device is present.\n")
	TEXT("0: Not Enabled, 1: Enabled"),
	ECVF_Default);

namespace Audio
{

#Loc: <Workspace>/Engine/Source/Runtime/AudioMixer/Private/Quartz/AudioMixerClock.cpp:131

Scope (from outer to inner):

file
namespace    Audio
function     FQuartzClock::FQuartzClock

Source code excerpt:

		else
		{
			Metronome.SetSampleRate(HeadlessClockSampleRateCvar);
		}

		UpdateCachedState();
	}

	FQuartzClock::~FQuartzClock()

#Loc: <Workspace>/Engine/Source/Runtime/AudioMixer/Private/Quartz/AudioMixerClock.cpp:152

Scope (from outer to inner):

file
namespace    Audio
function     void FQuartzClock::ChangeTickRate

Source code excerpt:

		else
		{
			InNewTickRate.SetSampleRate(HeadlessClockSampleRateCvar);
		}

		Metronome.SetTickRate(InNewTickRate, NumFramesLeft);
		FQuartzClockTickRate CurrentTickRate = Metronome.GetTickRate();

		// ratio between new and old rates

#Loc: <Workspace>/Engine/Source/Runtime/AudioMixer/Private/Quartz/AudioMixerClock.cpp:609

Scope (from outer to inner):

file
namespace    Audio
function     void FQuartzClock::AddQuantizedCommand

Source code excerpt:

	void FQuartzClock::AddQuantizedCommand(FQuartzQuantizedRequestData& InQuantizedRequestData)
	{
		float SampleRate = HeadlessClockSampleRateCvar;
		if (FMixerDevice* MixerDevice = GetMixerDevice())
		{
			SampleRate = MixerDevice->GetSampleRate();
		}

		FQuartzQuantizedCommandInitInfo Info(InQuantizedRequestData, SampleRate);