au.adpcm.OnlySeekForwardOneChunk

au.adpcm.OnlySeekForwardOneChunk

#Overview

name: au.adpcm.OnlySeekForwardOneChunk

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

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of au.adpcm.OnlySeekForwardOneChunk is to control the seeking behavior in the ADPCM (Adaptive Differential Pulse-Code Modulation) audio decoder when encountering missing or failed chunks during audio playback.

This setting variable is primarily used in the AdpcmAudioDecoder module of Unreal Engine 5, which is responsible for decoding ADPCM-compressed audio data.

The value of this variable is set through the Unreal Engine’s console variable system. It is initialized with a default value of 1 in the C++ code.

The associated variable ADPCMOnlySeekForwardOneChunkCVar directly interacts with au.adpcm.OnlySeekForwardOneChunk. They share the same value, with ADPCMOnlySeekForwardOneChunkCVar being the C++ representation of the console variable.

Developers must be aware that when this variable is set to 1 (the default), the audio decoder will not continue to seek forward after failing to load two chunks in a row. This behavior is designed to prevent potential issues with continuous seeking when chunks are consistently missing or failing to load.

Best practices when using this variable include:

  1. Keeping it at the default value (1) unless there’s a specific need to change it.
  2. If audio playback is experiencing issues with missing chunks, developers might consider setting it to 0 to allow continuous seeking, but should be cautious of potential performance impacts.
  3. Monitoring audio playback behavior closely when modifying this setting, as it can significantly affect how the engine handles missing or corrupted audio data.

Regarding the associated variable ADPCMOnlySeekForwardOneChunkCVar:

The purpose of ADPCMOnlySeekForwardOneChunkCVar is to serve as the C++ representation of the au.adpcm.OnlySeekForwardOneChunk console variable within the engine’s code.

This variable is used directly in the ADPCM audio decoding logic, specifically in the FADPCMAudioInfo::StreamCompressedData function. It controls whether the decoder should stop seeking forward after missing one chunk.

The value of this variable is set through the console variable system, mirroring the value of au.adpcm.OnlySeekForwardOneChunk.

It interacts closely with other variables in the audio decoding process, such as ADPCMDisableSeekForwardOnChunkMissesCVar, to determine the appropriate seeking behavior when chunks are missed.

Developers should be aware that this variable directly affects the runtime behavior of the ADPCM audio decoder. Changes to its value will immediately impact how the decoder handles missing chunks during playback.

Best practices for using ADPCMOnlySeekForwardOneChunkCVar include:

  1. Avoid modifying it directly in code; instead, use the console variable system to change its value.
  2. Consider the implications on audio playback quality and performance when adjusting this variable.
  3. Use it in conjunction with other ADPCM-related variables to fine-tune the audio decoding behavior for specific use cases or performance requirements.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/AdpcmAudioDecoder/Module/Private/ADPCMAudioInfo.cpp:27

Scope: file

Source code excerpt:

static int32 ADPCMOnlySeekForwardOneChunkCVar = 1;
FAutoConsoleVariableRef CVarADPCMOnlySeekForwardOneChunk(
	TEXT("au.adpcm.OnlySeekForwardOneChunk"),
	ADPCMOnlySeekForwardOneChunkCVar,
	TEXT("When set to 1, we will not continue to seek forward after failing to load two chunks in a row.\n"),
	ECVF_Default);

static float ChanceForIntentionalChunkMissCVar = 0.0f;
FAutoConsoleVariableRef CVarChanceForIntentionalChunkMiss(

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/AdpcmAudioDecoder/Module/Private/ADPCMAudioInfo.cpp:25

Scope: file

Source code excerpt:

	ECVF_Default);

static int32 ADPCMOnlySeekForwardOneChunkCVar = 1;
FAutoConsoleVariableRef CVarADPCMOnlySeekForwardOneChunk(
	TEXT("au.adpcm.OnlySeekForwardOneChunk"),
	ADPCMOnlySeekForwardOneChunkCVar,
	TEXT("When set to 1, we will not continue to seek forward after failing to load two chunks in a row.\n"),
	ECVF_Default);

static float ChanceForIntentionalChunkMissCVar = 0.0f;
FAutoConsoleVariableRef CVarChanceForIntentionalChunkMiss(
	TEXT("au.adpcm.ChanceForIntentionalChunkMiss"),

#Loc: <Workspace>/Engine/Source/Runtime/AdpcmAudioDecoder/Module/Private/ADPCMAudioInfo.cpp:717

Scope (from outer to inner):

file
function     bool FADPCMAudioInfo::StreamCompressedData

Source code excerpt:

						// If we have a seek pending, or we're in the middle of playing back the file, seek forward in the chunk offset to where we would have been.
						// If we've already seeked forward one chunk and haven't loaded the next chunk in time and are skipping to the next one, we stop seeking to prevent snowballing chunk load requests.
						const bool bAlreadySeekedFowardOneChunk = ADPCMOnlySeekForwardOneChunkCVar && bSeekedFowardToNextChunk;
						const bool bShouldSeekForwardOnMissedChunk = !ADPCMDisableSeekForwardOnChunkMissesCVar && !bAlreadySeekedFowardOneChunk && (bSeekPendingRead || CurrentChunkIndex > FirstChunkSampleDataIndex);

						if (bShouldSeekForwardOnMissedChunk)
						{
							const uint32 NumBlocksForCallback = BufferSize / (UncompressedBlockSize * NumChannels);
							const uint32 NumCompressedBytesForCallback = NumBlocksForCallback * CompressedBlockSize * NumChannels;