Sequencer.Audio.UseAudioClockForAudioDesync

Sequencer.Audio.UseAudioClockForAudioDesync

#Overview

name: Sequencer.Audio.UseAudioClockForAudioDesync

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

• type: Var
• help: When set to 1, we will use the audio render thread directly to query whether audio has went out of sync with the sequence.\n

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of Sequencer.Audio.UseAudioClockForAudioDesync is to control how audio synchronization is handled within the Unreal Engine’s Sequencer system. Specifically, it determines whether the audio render thread should be used directly to query if audio has gone out of sync with the sequence.

This setting variable is primarily used in the MovieSceneTracks module, which is part of Unreal Engine’s cinematics and sequencing system. It directly affects the audio synchronization behavior in the MovieSceneAudioSystem.

The value of this variable is set through a console variable (CVar) system. It’s initialized to 0 by default, but can be changed at runtime or through configuration files.

The associated variable UseAudioClockForSequencerDesyncCVar interacts directly with Sequencer.Audio.UseAudioClockForAudioDesync. They share the same value, with UseAudioClockForSequencerDesyncCVar being the actual integer variable used in the C++ code.

Developers must be aware that when this variable is set to 1, the system will use the audio render thread directly to query whether audio has gone out of sync with the sequence. This can affect performance and behavior of audio synchronization in cinematics.

Best practices when using this variable include:

1. Only enable it (set to 1) when dealing with complex audio synchronization issues in Sequencer.
2. Monitor performance impact when enabled, as it may affect real-time rendering.
3. Use in conjunction with other audio debugging tools to isolate synchronization issues.

Regarding the associated variable UseAudioClockForSequencerDesyncCVar:

• Its purpose is to serve as the actual integer storage for the Sequencer.Audio.UseAudioClockForAudioDesync setting.
• It’s used in the MovieSceneAudioSystem to conditionally change the behavior of audio time querying.
• The value is set through the console variable system, mirroring Sequencer.Audio.UseAudioClockForAudioDesync.
• It interacts directly with the World and AudioDevice objects to determine how audio time is calculated.
• Developers should be aware that this variable directly affects the behavior of the EnsureAudioIsPlaying function in the MovieSceneAudioSystem.
• Best practices include using this variable in conjunction with proper error checking and fallback mechanisms, as seen in the provided code snippets where alternative time sources are used if the AudioDevice is not available.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/MovieSceneTracks/Private/Systems/MovieSceneAudioSystem.cpp:39

Scope: file

Source code excerpt:

static int32 UseAudioClockForSequencerDesyncCVar = 0;
FAutoConsoleVariableRef CVaUseAudioClockForSequencerDesync(
	TEXT("Sequencer.Audio.UseAudioClockForAudioDesync"),
	UseAudioClockForSequencerDesyncCVar,
	TEXT("When set to 1, we will use the audio render thread directly to query whether audio has went out of sync with the sequence.\n"),
	ECVF_Default);

static bool bPlayAudioWhenPlaybackJumps = false;
FAutoConsoleVariableRef CVarPlayAudioWhenPlaybackJumps(

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/MovieSceneTracks/Private/Systems/MovieSceneAudioSystem.cpp:37

Scope: file

Source code excerpt:

	ECVF_Default);

static int32 UseAudioClockForSequencerDesyncCVar = 0;
FAutoConsoleVariableRef CVaUseAudioClockForSequencerDesync(
	TEXT("Sequencer.Audio.UseAudioClockForAudioDesync"),
	UseAudioClockForSequencerDesyncCVar,
	TEXT("When set to 1, we will use the audio render thread directly to query whether audio has went out of sync with the sequence.\n"),
	ECVF_Default);

static bool bPlayAudioWhenPlaybackJumps = false;
FAutoConsoleVariableRef CVarPlayAudioWhenPlaybackJumps(
	TEXT("Sequencer.Audio.PlayAudioWhenPlaybackJumps"),

#Loc: <Workspace>/Engine/Source/Runtime/MovieSceneTracks/Private/Systems/MovieSceneAudioSystem.cpp:536

Scope (from outer to inner):

file
namespace    UE::MovieScene
function     void EnsureAudioIsPlaying

Source code excerpt:

			FAudioDevice* AudioDevice = World ? World->GetAudioDeviceRaw() : nullptr;
			if (UseAudioClockForSequencerDesyncCVar && AudioDevice)
			{
				CurrentGameTime = AudioDevice->GetAudioClock();
			}
			else
			{
				CurrentGameTime = World ? World->GetAudioTimeSeconds() : 0.f;

#Loc: <Workspace>/Engine/Source/Runtime/MovieSceneTracks/Private/Systems/MovieSceneAudioSystem.cpp:615

Scope (from outer to inner):

file
namespace    UE::MovieScene
function     void EnsureAudioIsPlaying

Source code excerpt:

				{
					FAudioDevice* AudioDevice = World->GetAudioDeviceRaw();
					if (UseAudioClockForSequencerDesyncCVar && AudioDevice)
					{
						EvaluationData.PartialDesyncComputation = AudioDevice->GetAudioClock() - AudioTime;
					}
					else
					{
						EvaluationData.PartialDesyncComputation = World->GetAudioTimeSeconds() - AudioTime;