au.DisableAudioSuspendOnAudioInterrupt

au.DisableAudioSuspendOnAudioInterrupt

#Overview

name: au.DisableAudioSuspendOnAudioInterrupt

The value of this variable can be defined or overridden in .ini config files. 1 .ini config file referencing this setting variable.

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of au.DisableAudioSuspendOnAudioInterrupt is to control whether the audio device suspension callback is disabled when the audio session is interrupted on iOS devices.

This setting variable is primarily used in the iOS-specific launch module of Unreal Engine 5. It’s part of the audio system and specifically deals with how the engine handles audio interruptions on iOS devices.

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

The associated variable DisableAudioSuspendOnAudioInterruptCvar directly interacts with au.DisableAudioSuspendOnAudioInterrupt. They share the same value, with DisableAudioSuspendOnAudioInterruptCvar being the actual integer variable used in the code logic.

Developers must be aware that this variable specifically affects iOS audio behavior. When set to 1 (default), it disables the callback that would normally suspend the audio device during an audio session interruption. When set to 0, it allows the normal suspension behavior.

Best practices when using this variable include:

  1. Consider the implications on audio behavior in iOS applications, especially those that need to handle audio interruptions gracefully.
  2. Test the application thoroughly with both settings (0 and 1) to ensure desired behavior in different scenarios of audio interruptions.
  3. Document any custom setting of this variable in project documentation for future reference.

Regarding the associated variable DisableAudioSuspendOnAudioInterruptCvar:

Its purpose is to serve as the actual integer storage for the au.DisableAudioSuspendOnAudioInterrupt console variable.

This variable is used in the iOS-specific launch module, particularly in the Suspend and Resume functions of the FAppEntry class.

The value of this variable is set through the console variable system, initialized to 1 by default.

It directly interacts with au.DisableAudioSuspendOnAudioInterrupt, effectively controlling the same behavior.

Developers should be aware that this variable is used in conditional statements to determine whether to run certain audio-related tasks when suspending or resuming the application due to an audio interruption.

Best practices include:

  1. Avoid directly modifying this variable; instead, use the console variable system to change au.DisableAudioSuspendOnAudioInterrupt.
  2. When debugging iOS audio issues, check the value of this variable to understand the current behavior regarding audio suspension during interruptions.

#Setting Variables

#References In INI files

Location: <Workspace>/Projects/Lyra/Config/IOS/IOSEngine.ini:15, section: [ConsoleVariables]

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Launch/Private/IOS/LaunchIOS.cpp:35

Scope: file

Source code excerpt:

static int32 DisableAudioSuspendOnAudioInterruptCvar = 1;
FAutoConsoleVariableRef CVarDisableAudioSuspendOnAudioInterrupt(
    TEXT("au.DisableAudioSuspendOnAudioInterrupt"),
    DisableAudioSuspendOnAudioInterruptCvar,
    TEXT("Disables callback for suspending the audio device when we are notified that the audio session has been interrupted.\n")
    TEXT("0: Not Disabled, 1: Disabled"),
    ECVF_Default);

static const double cMaxAudioContextResumeDelay = 0.5;    // Setting this to be 0.5 seconds

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Launch/Private/IOS/LaunchIOS.cpp:33

Scope: file

Source code excerpt:

FGameLaunchDaemonMessageHandler GCommandSystem;

static int32 DisableAudioSuspendOnAudioInterruptCvar = 1;
FAutoConsoleVariableRef CVarDisableAudioSuspendOnAudioInterrupt(
    TEXT("au.DisableAudioSuspendOnAudioInterrupt"),
    DisableAudioSuspendOnAudioInterruptCvar,
    TEXT("Disables callback for suspending the audio device when we are notified that the audio session has been interrupted.\n")
    TEXT("0: Not Disabled, 1: Disabled"),
    ECVF_Default);

static const double cMaxAudioContextResumeDelay = 0.5;    // Setting this to be 0.5 seconds
static double AudioContextResumeTime = 0;

#Loc: <Workspace>/Engine/Source/Runtime/Launch/Private/IOS/LaunchIOS.cpp:64

Scope (from outer to inner):

file
function     void FAppEntry::Suspend

Source code excerpt:

		{
			FAudioDeviceHandle AudioDevice = GEngine->GetMainAudioDevice();
			if (bIsInterrupt && DisableAudioSuspendOnAudioInterruptCvar)
			{
				if (FTaskGraphInterface::IsRunning() && !IsEngineExitRequested())
				{
					FFunctionGraphTask::CreateAndDispatchWhenReady([]()
					{
						FAudioThread::RunCommandOnAudioThread([]()

#Loc: <Workspace>/Engine/Source/Runtime/Launch/Private/IOS/LaunchIOS.cpp:159

Scope (from outer to inner):

file
function     void FAppEntry::Resume

Source code excerpt:

			FAudioDeviceHandle AudioDevice = GEngine->GetMainAudioDevice();
        
			if (bIsInterrupt && DisableAudioSuspendOnAudioInterruptCvar)
			{
				if (FTaskGraphInterface::IsRunning())
				{
					FFunctionGraphTask::CreateAndDispatchWhenReady([]()
					{
						FAudioThread::RunCommandOnAudioThread([]()