au.vorbis.ReadFailiureTimeout

au.vorbis.ReadFailiureTimeout

#Overview

name: au.vorbis.ReadFailiureTimeout

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

• type: Var
• help: When set to 1, we bail on decoding Ogg Vorbis sounds if we were not able to successfully decode them after several attempts.\n

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of au.vorbis.ReadFailiureTimeout is to control the behavior of Ogg Vorbis audio decoding in Unreal Engine 5, specifically to determine whether the engine should stop attempting to decode a sound file after multiple failed attempts.

This setting variable is primarily used in the VorbisAudioDecoder module, which is part of Unreal Engine’s audio system. It’s specifically related to the decoding of Ogg Vorbis audio files.

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

The associated variable VorbisReadFailiureTimeoutCVar directly interacts with au.vorbis.ReadFailiureTimeout. They share the same value, with VorbisReadFailiureTimeoutCVar being the actual integer variable used in the code.

Developers must be aware that when this variable is set to 1 (which is the default), the engine will stop attempting to decode an Ogg Vorbis sound file after several failed attempts. This can prevent the engine from getting stuck in an infinite loop if there’s an issue with a particular audio file.

Best practices when using this variable include:

1. Keeping it enabled (set to 1) in most cases to prevent potential hangs or performance issues.
2. Only disabling it (setting to 0) when debugging specific audio decoding issues.
3. Being aware that disabling this timeout could lead to infinite loops if there are problematic audio files.

Regarding the associated variable VorbisReadFailiureTimeoutCVar:

• Its purpose is to store the actual integer value of the au.vorbis.ReadFailiureTimeout setting.
• It’s used directly in the code to determine whether to timeout on decompression failures.
• It’s defined as a static integer and initialized with the same default value (1) as au.vorbis.ReadFailiureTimeout.
• It’s used in the StreamCompressedData function of the FVorbisAudioInfo class to determine if the decoding process should timeout.
• Developers should not modify this variable directly, but instead use the au.vorbis.ReadFailiureTimeout console variable to change its value.

When working with this variable, developers should ensure that their Ogg Vorbis audio files are properly formatted to avoid triggering the timeout mechanism unnecessarily.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/VorbisAudioDecoder/Module/Private/VorbisAudioInfo.cpp:33

Scope: file

Source code excerpt:

static int32 VorbisReadFailiureTimeoutCVar = 1;
FAutoConsoleVariableRef CVarVorbisReadFailiureTimeout(
	TEXT("au.vorbis.ReadFailiureTimeout"),
	VorbisReadFailiureTimeoutCVar,
	TEXT("When set to 1, we bail on decoding Ogg Vorbis sounds if we were not able to successfully decode them after several attempts.\n"),
	ECVF_Default);

/**
 * Channel order expected for a multi-channel ogg vorbis file.

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/VorbisAudioDecoder/Module/Private/VorbisAudioInfo.cpp:31

Scope: file

Source code excerpt:

#endif

static int32 VorbisReadFailiureTimeoutCVar = 1;
FAutoConsoleVariableRef CVarVorbisReadFailiureTimeout(
	TEXT("au.vorbis.ReadFailiureTimeout"),
	VorbisReadFailiureTimeoutCVar,
	TEXT("When set to 1, we bail on decoding Ogg Vorbis sounds if we were not able to successfully decode them after several attempts.\n"),
	ECVF_Default);

/**
 * Channel order expected for a multi-channel ogg vorbis file.
 * Ordering taken from http://xiph.org/vorbis/doc/Vorbis_I_spec.html#x1-800004.3.9

#Loc: <Workspace>/Engine/Source/Runtime/VorbisAudioDecoder/Module/Private/VorbisAudioInfo.cpp:723

Scope (from outer to inner):

file
function     bool FVorbisAudioInfo::StreamCompressedData

Source code excerpt:

			constexpr int32 NumReadFailiuresUntilTimeout = 64;
			const bool bDidTimeoutOnDecompressionFailiures = (VorbisReadFailiureTimeoutCVar > 0) && (TimesLoopedWithoutDecompressedAudio >= NumReadFailiuresUntilTimeout);

			UE_CLOG(bDidTimeoutOnDecompressionFailiures, LogAudio, Error, TEXT("Timed out trying to decompress a looping sound after %d attempts; aborting."), VorbisReadFailiureTimeoutCVar);

			// If we're looping, then we need to make sure we wrap the stream chunks back to 0
			if (bLooping && !bDidTimeoutOnDecompressionFailiures)
			{
				NextStreamingChunkIndex = 0;
			}