Sequencer.Audio.MaxDesyncTolerance

Sequencer.Audio.MaxDesyncTolerance

#Overview

name: Sequencer.Audio.MaxDesyncTolerance

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

• type: Var
• help: Controls how many seconds an audio track can be out of sync in a Sequence before we attempt a time correction.\n

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of Sequencer.Audio.MaxDesyncTolerance is to control the maximum allowed desynchronization between audio tracks and other elements in an Unreal Engine Sequence before a time correction is attempted. This setting is primarily used in the audio system of the Sequencer, which is part of Unreal Engine’s cinematics and cutscene creation tools.

This setting variable is relied upon by the MovieSceneTracks module, specifically within the MovieSceneAudioSystem. It’s used in the audio playback synchronization logic for sequenced audio tracks.

The value of this variable is set using an FAutoConsoleVariableRef, which means it can be adjusted at runtime through the console or configuration files. The default value is 0.5 seconds, as seen in the initialization of MaxSequenceAudioDesyncToleranceCVar.

The associated variable MaxSequenceAudioDesyncToleranceCVar directly interacts with Sequencer.Audio.MaxDesyncTolerance. They share the same value, with MaxSequenceAudioDesyncToleranceCVar being the actual float variable used in the code.

Developers should be aware that this variable affects the tolerance for audio desynchronization in Sequences. If the desync between the audio time and the current game time exceeds this tolerance, the system will attempt to resynchronize the audio.

Best practices when using this variable include:

1. Adjusting it based on the specific needs of your project. A lower value will result in more frequent resynchronization attempts, which might be necessary for precise audio timing.
2. Monitoring performance impact, as frequent resynchronization could potentially affect performance in complex sequences.
3. Using it in conjunction with other audio-related settings in the Sequencer for optimal results.

Regarding the associated variable MaxSequenceAudioDesyncToleranceCVar:

• Its purpose is to store the actual float value used in the code for the maximum desync tolerance.
• It’s used directly in the EnsureAudioIsPlaying function to check if the audio needs resynchronization.
• The value is set through the Sequencer.Audio.MaxDesyncTolerance console variable.
• Developers should be aware that modifying MaxSequenceAudioDesyncToleranceCVar directly in code will not persist, as it’s controlled by the console variable.
• Best practice is to adjust the Sequencer.Audio.MaxDesyncTolerance console variable rather than modifying MaxSequenceAudioDesyncToleranceCVar directly in code.

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

Scope: file

Source code excerpt:

static float MaxSequenceAudioDesyncToleranceCVar = 0.5f;
FAutoConsoleVariableRef CVarMaxSequenceAudioDesyncTolerance(
	TEXT("Sequencer.Audio.MaxDesyncTolerance"),
	MaxSequenceAudioDesyncToleranceCVar,
	TEXT("Controls how many seconds an audio track can be out of sync in a Sequence before we attempt a time correction.\n"),
	ECVF_Default);

static bool bIgnoreAudioSyncDuringWorldTimeDilationCVar = true;
FAutoConsoleVariableRef CVarIgnoreAudioSyncDuringWorldTimeDilation(

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

DECLARE_CYCLE_STAT(TEXT("Audio System Evaluate"), MovieSceneEval_AudioTasks, STATGROUP_MovieSceneECS);

static float MaxSequenceAudioDesyncToleranceCVar = 0.5f;
FAutoConsoleVariableRef CVarMaxSequenceAudioDesyncTolerance(
	TEXT("Sequencer.Audio.MaxDesyncTolerance"),
	MaxSequenceAudioDesyncToleranceCVar,
	TEXT("Controls how many seconds an audio track can be out of sync in a Sequence before we attempt a time correction.\n"),
	ECVF_Default);

static bool bIgnoreAudioSyncDuringWorldTimeDilationCVar = true;
FAutoConsoleVariableRef CVarIgnoreAudioSyncDuringWorldTimeDilation(
	TEXT("Sequencer.Audio.IgnoreAudioSyncDuringWorldTimeDilation"),

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

Scope (from outer to inner):

file
namespace    UE::MovieScene
function     void EnsureAudioIsPlaying

Source code excerpt:

				float Desync = PartialDesyncComputation + AudioTime - CurrentGameTime;

				if (!FMath::IsNearlyZero(MaxSequenceAudioDesyncToleranceCVar) && FMath::Abs(Desync) > MaxSequenceAudioDesyncToleranceCVar)
				{
					UE_LOG(LogMovieScene, Verbose, TEXT("Audio Component detected a significant mismatch in (assumed) playback time versus the desired time. Desync: %6.2f(s) Desired Time: %6.2f(s). Component: %s sound: %s"), Desync, AudioTime, *AudioComponent.GetName(), *GetNameSafe(AudioComponent.Sound));
					bSoundNeedsTimeSync = true;
				}
			}
		}