SetBaseSoundMix

SetBaseSoundMix

#Overview

name: SetBaseSoundMix

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

It is referenced in 8 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of SetBaseSoundMix is to set the base sound mix for the audio system, which affects the overall audio equalization and processing of the game’s sound output.

SetBaseSoundMix is primarily used by the Unreal Engine’s audio system, specifically within the FAudioDevice class. It is also exposed through the UGameplayStatics class for use in Blueprint scripting.

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

  1. Calling UGameplayStatics::SetBaseSoundMix from game code or Blueprints
  2. Using the “SetBaseSoundMix” console command
  3. Setting the DefaultBaseSoundMix in the FAudioDevice

This variable interacts with other audio-related variables and systems, particularly:

  1. The BaseSoundMix member of FAudioDevice
  2. The DefaultBaseSoundMix member of FAudioDevice
  3. The SoundClasses system for audio processing

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

  1. Setting a new base sound mix will affect all audio output in the game
  2. It should be used carefully to avoid unexpected changes in audio quality or balance
  3. The base sound mix is different from pushed sound mix modifiers, which are temporary and stackable

Best practices when using this variable include:

  1. Use it to set up the overall audio environment for different game states or levels
  2. Avoid changing the base sound mix frequently, as it can lead to jarring audio transitions
  3. Ensure that the chosen sound mix is appropriate for the current game context and doesn’t negatively impact important audio cues
  4. Consider using PushSoundMixModifier for temporary audio adjustments instead of changing the base mix
  5. Always test audio changes thoroughly to ensure they enhance rather than detract from the player experience

#References in C++ code

#Callsites

This variable is referenced in 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/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.