au.Debug.SetBaseSoundMix

au.Debug.SetBaseSoundMix

#Overview

name: au.Debug.SetBaseSoundMix

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

It is referenced in 10 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of au.Debug.SetBaseSoundMix is to set the base sound mix for the audio system, which allows for special EQing (equalization) and overall audio adjustments in the game.

This setting variable is primarily used in the Unreal Engine’s audio subsystem, specifically within the FAudioDevice class. It is part of the Engine module and is utilized for managing the game’s audio settings.

The value of this variable is typically set through the following means:

  1. Via console commands, as seen in the HandleSetBaseSoundMixCommand function.
  2. Programmatically, using the SetBaseSoundMix function in the FAudioDevice class.
  3. Through Blueprint functions, as indicated by the UGameplayStatics::SetBaseSoundMix function.

The au.Debug.SetBaseSoundMix variable interacts closely with the BaseSoundMix and DefaultBaseSoundMix variables within the FAudioDevice class. It’s also associated with the SetBaseSoundMix function, which is exposed to Blueprints through the UGameplayStatics class.

Developers should be aware of the following when using this variable:

  1. Changes to the base sound mix affect the overall audio output of the game.
  2. Setting a new base sound mix will override the previous one.
  3. The base sound mix can be reset to the default by passing nullptr or removing the current sound mix.

Best practices for using this variable include:

  1. Use it sparingly and for significant audio changes, as it affects the entire audio system.
  2. Consider using PushSoundMixModifier for temporary or localized audio changes instead.
  3. Always check if the audio device is valid before attempting to set the base sound mix.
  4. Be mindful of performance implications when changing sound mixes frequently.

Regarding the associated variable SetBaseSoundMix: This is a function rather than a variable, exposed in the UGameplayStatics class for use in Blueprints. It serves as a wrapper for the FAudioDevice::SetBaseSoundMix function, allowing developers to change the base sound mix from both C++ code and Blueprints. The function takes a WorldContextObject to ensure it’s called in the correct world context, and a USoundMix object to set as the new base sound mix. It’s important to note that this function will have no effect if sound is disabled in the engine or if the world doesn’t allow audio playback.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/AudioDevice.cpp:2278

Scope (from outer to inner):

file
function     bool FAudioDevice::Exec

Source code excerpt:

		return HandleListSoundDurationsCommand(Cmd, Ar);
	}
	else if (ParseAudioExecCmd(&Cmd, TEXT("SetBaseSoundMix")))
	{
		return HandleSetBaseSoundMixCommand(Cmd, Ar);
	}
	else if (ParseAudioExecCmd(&Cmd, TEXT("IsolateDryAudio")))
	{
		return HandleIsolateDryAudioCommand(Cmd, Ar);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Classes/Kismet/GameplayStatics.h:927

Scope (from outer to inner):

file
class        class UGameplayStatics : public UBlueprintFunctionLibrary

Source code excerpt:

	static ENGINE_API bool AreSubtitlesEnabled();

	// --- Audio Functions ----------------------------
	/** Set the sound mix of the audio system for special EQing */
	UFUNCTION(BlueprintCallable, Category="Audio", meta=(WorldContext = "WorldContextObject"))
	static ENGINE_API void SetBaseSoundMix(const UObject* WorldContextObject, class USoundMix* InSoundMix);

	/** Primes the sound, caching the first chunk of streamed audio. */
	UFUNCTION(BlueprintCallable, Category = "Audio")
	static ENGINE_API void PrimeSound(USoundBase* InSound);

	/** Get list of available Audio Spatialization Plugin names */
	UFUNCTION(BlueprintCallable, Category = "Audio", meta = (WorldContext = "WorldContextObject"))
	static ENGINE_API TArray<FName> GetAvailableSpatialPluginNames(const UObject* WorldContextObject);

	/** Get currently active Audio Spatialization Plugin name */
	UFUNCTION(BlueprintCallable, Category = "Audio", meta = (WorldContext = "WorldContextObject"))

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/AudioDevice.cpp:1498

Scope (from outer to inner):

file
function     bool FAudioDevice::HandleSetBaseSoundMixCommand

Source code excerpt:

		}
	}

	if (SoundMix)
	{
		SetBaseSoundMix(SoundMix);
	}
	else
	{
		Ar.Logf(TEXT("Unknown SoundMix: %s"), *NewMix.ToString());
	}
	return true;
}

bool FAudioDevice::HandleIsolateDryAudioCommand(const TCHAR* Cmd, FOutputDevice& Ar)
{
	Ar.Logf(TEXT("Dry audio isolated"));

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/AudioDevice.cpp:2275

Scope (from outer to inner):

file
function     bool FAudioDevice::Exec

Source code excerpt:

	}
	else if (ParseAudioExecCmd(&Cmd, TEXT("ListSoundDurations")))
	{
		return HandleListSoundDurationsCommand(Cmd, Ar);
	}
	else if (ParseAudioExecCmd(&Cmd, TEXT("SetBaseSoundMix")))
	{
		return HandleSetBaseSoundMixCommand(Cmd, Ar);
	}
	else if (ParseAudioExecCmd(&Cmd, TEXT("IsolateDryAudio")))
	{
		return HandleIsolateDryAudioCommand(Cmd, Ar);
	}
	else if (ParseAudioExecCmd(&Cmd, TEXT("IsolateReverb")))
	{
		return HandleIsolateReverbCommand(Cmd, Ar);
	}

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/AudioDevice.cpp:2462

Scope (from outer to inner):

file
function     void FAudioDevice::SetDefaultBaseSoundMix

Source code excerpt:


		return;
	}

	DefaultBaseSoundMix = SoundMix;
	SetBaseSoundMix(SoundMix);
}

void FAudioDevice::RemoveSoundMix(USoundMix* SoundMix)
{
	check(IsInAudioThread());

	if (SoundMix)
	{
		// Not sure if we will ever destroy the default base SoundMix
		if (SoundMix == DefaultBaseSoundMix)
		{

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/AudioDevice.cpp:2482

Scope (from outer to inner):

file
function     void FAudioDevice::RemoveSoundMix

Source code excerpt:

		ClearSoundMix(SoundMix);

		// Try setting to global default if base SoundMix has been cleared
		if (BaseSoundMix == nullptr)
		{
			SetBaseSoundMix(DefaultBaseSoundMix);
		}
	}
}

void FAudioDevice::RecurseIntoSoundClasses(USoundClass* CurrentClass, FSoundClassProperties& ParentProperties)
{
	// Iterate over all child nodes and recurse.
	for (USoundClass* ChildClass : CurrentClass->ChildClasses)
	{
		// Look up class and propagated properties.
		FSoundClassProperties* Properties = SoundClasses.Find(ChildClass);

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/AudioDevice.cpp:3654

Scope (from outer to inner):

file
function     void FAudioDevice::SetBaseSoundMix

Source code excerpt:

		ActiveSoundUpdate->OnNotifyPendingDelete(ActiveSound);
		return true;
	});
}

void FAudioDevice::SetBaseSoundMix(USoundMix* NewMix)
{
	if (!IsInAudioThread())
	{
		DECLARE_CYCLE_STAT(TEXT("FAudioThreadTask.SetBaseSoundMix"), STAT_AudioSetBaseSoundMix, STATGROUP_AudioThreadCommands);

		FAudioDevice* AudioDevice = this;
		FAudioThread::RunCommandOnAudioThread([AudioDevice, NewMix]()
		{
			AudioDevice->SetBaseSoundMix(NewMix);

		}, GET_STATID(STAT_AudioSetBaseSoundMix));

		return;
	}

	if (NewMix && NewMix != BaseSoundMix)
	{
		USoundMix* OldBaseSoundMix = BaseSoundMix;
		BaseSoundMix = NewMix;

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/GameplayStatics.cpp:1902

Scope (from outer to inner):

file
function     void UGameplayStatics::SetBaseSoundMix

Source code excerpt:

		return GEngine->bSubtitlesEnabled;
	}
	return 0;
}

void UGameplayStatics::SetBaseSoundMix(const UObject* WorldContextObject, USoundMix* InSoundMix)
{
	if (!InSoundMix || !GEngine || !GEngine->UseSound())
	{
		return;
	}

	UWorld* ThisWorld = GEngine->GetWorldFromContextObject(WorldContextObject, EGetWorldErrorMode::LogAndReturnNull);
	if (!ThisWorld || !ThisWorld->bAllowAudioPlayback)
	{
		return;
	}

	if (FAudioDeviceHandle AudioDevice = ThisWorld->GetAudioDevice())
	{
		AudioDevice->SetBaseSoundMix(InSoundMix);
	}
}

void UGameplayStatics::PushSoundMixModifier(const UObject* WorldContextObject, USoundMix* InSoundMixModifier)
{
	if (!InSoundMixModifier || !GEngine || !GEngine->UseSound())
	{
		return;
	}

	UWorld* ThisWorld = GEngine->GetWorldFromContextObject(WorldContextObject, EGetWorldErrorMode::LogAndReturnNull);

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/GameplayStatics.cpp:1917

Scope (from outer to inner):

file
function     void UGameplayStatics::SetBaseSoundMix

Source code excerpt:

	if (FAudioDeviceHandle AudioDevice = ThisWorld->GetAudioDevice())
	{
		AudioDevice->SetBaseSoundMix(InSoundMix);
	}
}

void UGameplayStatics::PushSoundMixModifier(const UObject* WorldContextObject, USoundMix* InSoundMixModifier)
{
	if (!InSoundMixModifier || !GEngine || !GEngine->UseSound())

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Public/AudioDevice.h:1070

Scope (from outer to inner):

file
class        class FAudioDevice : public FExec

Source code excerpt:


	friend class FAudioEffectsManager;
	/**
	 * Sets a new sound mix and applies it to all appropriate sound classes
	 */
	ENGINE_API void SetBaseSoundMix(USoundMix* SoundMix);

	/**
	 * Push a SoundMix onto the Audio Device's list.
	 *
	 * @param SoundMix The SoundMix to push.
	 * @param bIsPassive Whether this is a passive push from a playing sound.
	 */
	ENGINE_API void PushSoundMixModifier(USoundMix* SoundMix, bool bIsPassive = false, bool bIsRetrigger = false);

	/**
	 * Sets a sound class override in the given sound mix.