AudioSampleRate

AudioSampleRate

#Overview

name: AudioSampleRate

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 23 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of AudioSampleRate is to define the number of audio samples processed per second in various audio-related systems within Unreal Engine 5. This setting is crucial for determining the quality and performance of audio output in different contexts, such as media capture, streaming, and platform-specific audio configurations.

AudioSampleRate is utilized by several Unreal Engine subsystems, plugins, and modules, including:

  1. AjaMedia and BlackmagicMedia plugins for media capture and output
  2. Platform-specific settings for Windows, Mac, Android, and iOS
  3. Audio mixer core
  4. GameplayMediaEncoder for live streaming

The value of this variable is typically set in platform-specific configuration files or through blueprint-accessible properties in various classes. For example, in platform settings classes like UWindowsTargetSettings, UMacTargetSettings, and UAndroidRuntimeSettings.

AudioSampleRate often interacts with other audio-related variables such as AudioCallbackBufferFrameSize, AudioNumBuffersToEnqueue, and AudioNumChannels. These variables collectively determine the audio processing pipeline’s behavior.

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

  1. Different platforms may have different supported sample rates.
  2. Changing the sample rate can affect audio quality, latency, and CPU usage.
  3. Some systems require specific sample rates (e.g., 44100 Hz or 48000 Hz for live streaming).

Best practices when using this variable include:

  1. Choose a sample rate appropriate for the target platform and use case.
  2. Consider the trade-offs between audio quality, performance, and compatibility when selecting a sample rate.
  3. Ensure that all audio-related settings are consistent across the project to avoid conflicts or unexpected behavior.
  4. Test thoroughly on target platforms to verify that the chosen sample rate works well with the game’s audio requirements.

#Setting Variables

#References In INI files

Location: <Workspace>/Projects/Lyra/Config/DefaultEngine.ini:302, section: [/Script/WindowsTargetPlatform.WindowsTargetSettings]

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Plugins/Media/AjaMedia/Source/AjaMediaOutput/Private/AjaMediaCapture.cpp:577

Scope (from outer to inner):

file
function     bool UAjaMediaCapture::CreateAudioOutput

Source code excerpt:

		Args.TargetFrameRate = FrameRate;
		Args.MaxSampleLatency = Align(InAjaMediaOutput->AudioBufferSize, 4);
		Args.OutputSampleRate = static_cast<uint32>(InAjaMediaOutput->AudioSampleRate);
		Args.AudioDeviceHandle = InAudioDeviceHandle;
		AudioOutput = GEngine->GetEngineSubsystem<UMediaIOCoreSubsystem>()->CreateAudioOutput(Args);
		return AudioOutput.IsValid();
	}
	return false;
}

#Loc: <Workspace>/Engine/Plugins/Media/AjaMedia/Source/AjaMediaOutput/Public/AjaMediaOutput.h:90

Scope (from outer to inner):

file
class        class UAjaMediaOutput : public UMediaOutput

Source code excerpt:

	/** Audio output sample rate. */
	UPROPERTY(BlueprintReadWrite, EditAnywhere, Category = "Output")
	EAjaMediaOutputAudioSampleRate AudioSampleRate = EAjaMediaOutputAudioSampleRate::SR_48k;

	/** Whether to output audio on the audio thread instead of the rendering thread. Only available in Ping Pong mode. (Experimental) */
    UPROPERTY(BlueprintReadWrite, EditAnywhere, Category = "Output", meta = (EditCondition = "bOutputWithAutoCirculating == false"))
	bool bOutputAudioOnAudioThread = false;

	/**

#Loc: <Workspace>/Engine/Plugins/Media/BlackmagicMedia/Source/BlackmagicCore/Private/BlackmagicLib.cpp:102

Scope (from outer to inner):

file
namespace    BlackmagicDesign
function     FOutputChannelOptions::FOutputChannelOptions

Source code excerpt:

		: CallbackPriority(0)
		, PixelFormat(EPixelFormat::pf_8Bits)
		, AudioSampleRate(EAudioSampleRate::SR_48kHz)
		, AudioBitDepth(EAudioBitDepth::Signed_32Bits)
		, NumAudioChannels(EAudioChannelConfiguration::Channels_2)
		, TimecodeFormat(ETimecodeFormat::TCF_None)
		, bOutputKey(false)
		, bOutputVideo(true)
		, bOutputAudio(false)

#Loc: <Workspace>/Engine/Plugins/Media/BlackmagicMedia/Source/BlackmagicCore/Private/BlackmagicOutputChannel.cpp:634

Scope (from outer to inner):

file
namespace    BlackmagicDesign
namespace    Private
function     uint32_t FOutputChannel::GetNumAudioSamplesPerFrame

Source code excerpt:

		uint32_t FOutputChannel::GetNumAudioSamplesPerFrame()
		{
			const uint32_t SampleRate = ChannelOptions.AudioSampleRate == EAudioSampleRate::SR_48kHz ? 48000 : 96000;
			return SampleRate * ChannelOptions.FormatInfo.FrameRateDenominator / ChannelOptions.FormatInfo.FrameRateNumerator;
		}

		uint8_t FOutputChannel::GetAudioBitDepth()
		{
			return ChannelOptions.AudioBitDepth == EAudioBitDepth::Signed_16Bits ? 16 : 32;

#Loc: <Workspace>/Engine/Plugins/Media/BlackmagicMedia/Source/BlackmagicCore/Private/BlackmagicOutputChannel.cpp:874

Scope (from outer to inner):

file
namespace    BlackmagicDesign
namespace    Private
function     bool FOutputChannel::InitializeAudio

Source code excerpt:

			check(DeckLinkOutput);

			AudioSamplesWaterLevel = NumVideoPrerollFrames * (uint32_t)ChannelOptions.AudioSampleRate / (ChannelOptions.FormatInfo.FrameRateNumerator / ChannelOptions.FormatInfo.FrameRateDenominator) ;

			BMDAudioSampleType SampleType;
			if (ChannelOptions.AudioBitDepth == EAudioBitDepth::Signed_16Bits)
			{
				SampleType = bmdAudioSampleType16bitInteger;
			}

#Loc: <Workspace>/Engine/Plugins/Media/BlackmagicMedia/Source/BlackmagicCore/Public/BlackmagicLib.h:247

Scope (from outer to inner):

file
namespace    BlackmagicDesign

Source code excerpt:

		EPixelFormat PixelFormat;

		EAudioSampleRate AudioSampleRate;
		EAudioBitDepth AudioBitDepth;
		EAudioChannelConfiguration NumAudioChannels;

		uint32_t NumberOfBuffers;

		ETimecodeFormat TimecodeFormat;

#Loc: <Workspace>/Engine/Plugins/Media/BlackmagicMedia/Source/BlackmagicMediaOutput/Private/BlackmagicMediaCapture.cpp:668

Scope (from outer to inner):

file
function     bool UBlackmagicMediaCapture::InitBlackmagic

Source code excerpt:

	ChannelOptions.AudioBitDepth = BlackmagicMediaCaptureHelpers::ConvertAudioBitDepth(InBlackmagicMediaOutput->AudioBitDepth);
	ChannelOptions.NumAudioChannels = static_cast<BlackmagicDesign::EAudioChannelConfiguration>(InBlackmagicMediaOutput->OutputChannelCount);
	ChannelOptions.AudioSampleRate = static_cast<BlackmagicDesign::EAudioSampleRate>(InBlackmagicMediaOutput->AudioSampleRate);

	ChannelOptions.FormatInfo.FieldDominance = BlackmagicMediaCaptureHelpers::GetFieldDominanceFromMediaStandard(InBlackmagicMediaOutput->OutputConfiguration.MediaConfiguration.MediaMode.Standard);
	ChannelOptions.PixelFormat = BlackmagicMediaCaptureHelpers::ConvertPixelFormat(InBlackmagicMediaOutput->PixelFormat);
	ChannelOptions.TimecodeFormat = BlackmagicMediaCaptureHelpers::ConvertTimecodeFormat(InBlackmagicMediaOutput->TimecodeFormat);
	ChannelOptions.LinkConfiguration = BlackmagicMediaCaptureHelpers::ConvertTransportType(InBlackmagicMediaOutput->OutputConfiguration.MediaConfiguration.MediaConnection.TransportType, InBlackmagicMediaOutput->OutputConfiguration.MediaConfiguration.MediaConnection.QuadTransportType);

#Loc: <Workspace>/Engine/Plugins/Media/BlackmagicMedia/Source/BlackmagicMediaOutput/Private/BlackmagicMediaCapture.cpp:739

Scope (from outer to inner):

file
function     bool UBlackmagicMediaCapture::CreateAudioOutput

Source code excerpt:

		Args.TargetFrameRate = FrameRate;
		Args.MaxSampleLatency = Align(InBlackmagicMediaOutput->AudioBufferSize, 4);
		Args.OutputSampleRate = static_cast<uint32>(InBlackmagicMediaOutput->AudioSampleRate);
		Args.AudioDeviceHandle = InAudioDeviceHandle;
		AudioOutput = GEngine->GetEngineSubsystem<UMediaIOCoreSubsystem>()->CreateAudioOutput(Args);
		return AudioOutput.IsValid();
	}
	return false;
}

#Loc: <Workspace>/Engine/Plugins/Media/BlackmagicMedia/Source/BlackmagicMediaOutput/Public/BlackmagicMediaOutput.h:62

Scope (from outer to inner):

file
class        class UBlackmagicMediaOutput : public UMediaOutput

Source code excerpt:

	/** Sample rate of the audio output. */
	UPROPERTY(BlueprintReadWrite, EditAnywhere, Category = "Output")
	EBlackmagicMediaOutputAudioSampleRate AudioSampleRate = EBlackmagicMediaOutputAudioSampleRate::SR_48k;

	/** Number of audio channels to output. */
	UPROPERTY(BlueprintReadWrite, EditAnywhere, Category = "Output")
	EBlackmagicMediaAudioOutputChannelCount OutputChannelCount = EBlackmagicMediaAudioOutputChannelCount::CH_2; 
	
	/** Bit depth of each audio sample. */

#Loc: <Workspace>/Engine/Source/Developer/Mac/MacTargetPlatform/Classes/MacTargetSettings.h:129

Scope (from outer to inner):

file
class        class UMacTargetSettings : public UObject

Source code excerpt:

	/** Sample rate to run the audio mixer with. */
	UPROPERTY(config, EditAnywhere, Category = "Audio", Meta = (DisplayName = "Audio Mixer Sample Rate"))
	int32 AudioSampleRate;

	/** The amount of audio to compute each callback block. Lower values decrease latency but may increase CPU cost. */
	UPROPERTY(config, EditAnywhere, Category = "Audio", meta = (ClampMin = "512", ClampMax = "4096", DisplayName = "Callback Buffer Size"))
	int32 AudioCallbackBufferFrameSize;

	/** The number of buffers to keep enqueued. More buffers increases latency, but can compensate for variable compute availability in audio callbacks on some platforms. */

#Loc: <Workspace>/Engine/Source/Developer/Windows/WindowsTargetPlatform/Classes/WindowsTargetSettings.h:66

Scope (from outer to inner):

file
class        class UWindowsTargetSettings : public UObject

Source code excerpt:

	/** Sample rate to run the audio mixer with. */
	UPROPERTY(config, EditAnywhere, Category = "Audio", Meta = (DisplayName = "Audio Mixer Sample Rate"))
	int32 AudioSampleRate;

	/** The amount of audio to compute each callback block. Lower values decrease latency but may increase CPU cost. */
	UPROPERTY(config, EditAnywhere, Category = "Audio", meta = (ClampMin = "64", ClampMax = "4096", DisplayName = "Callback Buffer Size"))
	int32 AudioCallbackBufferFrameSize;

	/** The number of buffers to keep enqueued. More buffers increases latency, but can compensate for variable compute availability in audio callbacks on some platforms. */

#Loc: <Workspace>/Engine/Source/Developer/Windows/WindowsTargetPlatform/Private/WindowsTargetPlatformClasses.cpp:16

Scope (from outer to inner):

file
function     UWindowsTargetSettings::UWindowsTargetSettings

Source code excerpt:

{
	// Default windows settings
	AudioSampleRate = 48000;
	AudioCallbackBufferFrameSize = 1024;
	AudioNumBuffersToEnqueue = 1;
	AudioNumSourceWorkers = 4;
}

static bool FilterShaderPlatform_D3D12(const FString& InShaderPlatform)

#Loc: <Workspace>/Engine/Source/Runtime/Android/AndroidRuntimeSettings/Classes/AndroidRuntimeSettings.h:564

Scope (from outer to inner):

file
class        class UAndroidRuntimeSettings : public UObject

Source code excerpt:

	/** Sample rate to run the audio mixer with. */
	UPROPERTY(config, EditAnywhere, Category = "Audio", Meta = (DisplayName = "Audio Mixer Sample Rate"))
	int32 AudioSampleRate;

	/** The amount of audio to compute each callback block. Lower values decrease latency but may increase CPU cost. */
	UPROPERTY(config, EditAnywhere, Category = "Audio", meta = (ClampMin = "512", ClampMax = "4096", DisplayName = "Callback Buffer Size"))
	int32 AudioCallbackBufferFrameSize;

	/** The number of buffers to keep enqueued. More buffers increases latency, but can compensate for variable compute availability in audio callbacks on some platforms. */

#Loc: <Workspace>/Engine/Source/Runtime/Android/AndroidRuntimeSettings/Private/AndroidRuntimeSettings.cpp:29

Scope (from outer to inner):

file
function     UAndroidRuntimeSettings::UAndroidRuntimeSettings

Source code excerpt:

	, bSupportAdMob(true)
	, bBlockAndroidKeysOnControllers(false)
	, AudioSampleRate(44100)
	, AudioCallbackBufferFrameSize(1024)
	, AudioNumBuffersToEnqueue(4)
	, CacheSizeKB(65536)
	, MaxSampleRate(48000)
	, HighSampleRate(32000)
    , MedSampleRate(24000)

#Loc: <Workspace>/Engine/Source/Runtime/AudioMixerCore/Private/AudioMixer.cpp:927

Scope (from outer to inner):

file
function     FAudioPlatformSettings FAudioPlatformSettings::GetPlatformSettings

Source code excerpt:

	FString TempString;

	if (GConfig->GetString(PlatformSettingsConfigFile, TEXT("AudioSampleRate"), TempString, GEngineIni))
	{
		Settings.SampleRate = FMath::Max(FCString::Atoi(*TempString), 8000);
	}

	if (GConfig->GetString(PlatformSettingsConfigFile, TEXT("AudioCallbackBufferFrameSize"), TempString, GEngineIni))
	{

#Loc: <Workspace>/Engine/Source/Runtime/GameplayMediaEncoder/Private/IbmLiveStreaming.cpp:227

Scope (from outer to inner):

file
function     bool FIbmLiveStreaming::Start

Source code excerpt:


	// Get SampleRate and NumChannels
	uint32 AudioSampleRate, AudioNumChannels, AudioBitrate;
	TRefCountPtr<IMFMediaType> AudioOutputType;
	verify(MediaEncoder->GetAudioOutputType(AudioOutputType));
	CHECK_HR(AudioOutputType->GetUINT32(MF_MT_AUDIO_SAMPLES_PER_SECOND, &AudioSampleRate));
	CHECK_HR(AudioOutputType->GetUINT32(MF_MT_AUDIO_NUM_CHANNELS, &AudioNumChannels));
	CHECK_HR(AudioOutputType->GetUINT32(MF_MT_AUDIO_AVG_BYTES_PER_SECOND, &AudioBitrate));

	if (CVarLiveStreamingClientId.GetValueOnAnyThread().IsEmpty() ||
		CVarLiveStreamingClientSecret.GetValueOnAnyThread().IsEmpty() ||
		CVarLiveStreamingChannel.GetValueOnAnyThread().IsEmpty())

#Loc: <Workspace>/Engine/Source/Runtime/GameplayMediaEncoder/Private/IbmLiveStreaming.cpp:246

Scope (from outer to inner):

file
function     bool FIbmLiveStreaming::Start

Source code excerpt:

		CVarLiveStreamingClientSecret.GetValueOnAnyThread(),
		CVarLiveStreamingChannel.GetValueOnAnyThread(),
		AudioSampleRate, AudioNumChannels, AudioBitrate);
}

bool FIbmLiveStreaming::Start(const FString& ClientId, const FString& ClientSecret, const FString& Channel, uint32 AudioSampleRate, uint32 AudioNumChannels, uint32 AudioBitrate)
{

	MemoryCheckpoint("IbmLiveStreaming: Before start");

	check(IsInGameThread());

#Loc: <Workspace>/Engine/Source/Runtime/GameplayMediaEncoder/Private/IbmLiveStreaming.cpp:264

Scope (from outer to inner):

file
function     bool FIbmLiveStreaming::Start

Source code excerpt:

	FGameplayMediaEncoder::Get()->RegisterListener(this);

	if (!((AudioSampleRate == 44100 || AudioSampleRate == 48000) && (AudioNumChannels == 2)))
	{
		UE_LOG(IbmLiveStreaming, Error, TEXT("Unsupported audio settings"));
		return false;
	}

	custom_c_log_msg = &FIbmLiveStreaming::CustomLogMsg;

#Loc: <Workspace>/Engine/Source/Runtime/GameplayMediaEncoder/Private/IbmLiveStreaming.cpp:278

Scope (from outer to inner):

file
function     bool FIbmLiveStreaming::Start

Source code excerpt:

	Config.ClientSecret = ClientSecret;
	Config.Channel = Channel;
	Config.AudioSampleRate = AudioSampleRate;
	Config.AudioNumChannels = AudioNumChannels;
	Config.AudioBitrate = AudioBitrate;

	UE_LOG(IbmLiveStreaming, Log,
		TEXT("Initializing with ClientId=%s, ClientSecret=%s, Channel=%s, AudioSampleRate=%d, AudioNumChannels=%d"),
		*ClientId, *ClientSecret, *Channel, AudioSampleRate, AudioNumChannels);

	FFormData FormData;
	FormData.AddField(TEXT("grant_type"), TEXT("client_credentials"));
	FormData.AddField(TEXT("client_id"), Config.ClientId);
	FormData.AddField(TEXT("client_secret"), Config.ClientSecret);
	FormData.AddField(TEXT("scope"), TEXT("broadcaster"));

#Loc: <Workspace>/Engine/Source/Runtime/GameplayMediaEncoder/Private/IbmLiveStreaming.cpp:734

Scope (from outer to inner):

file
function     void FIbmLiveStreaming::InjectAudio

Source code excerpt:

		Pkt->data[1] = AACSequenceHeader;
		Pkt->offset = 2;
		aac_lc_write_extradata(Pkt, Config.AudioSampleRate, Config.AudioNumChannels); // This adds another 2 bytes of configuration data 
		Pkt->offset = 0;
		QueueFrame(RTMPAudioDataPacketType, Pkt, 0);
	}

	RawData* Pkt= rawdata_alloc(2 + DataView.Num());
	Pkt->data[0] = ConfigByte;

#Loc: <Workspace>/Engine/Source/Runtime/GameplayMediaEncoder/Private/IbmLiveStreaming.h:43

Scope (from outer to inner):

file
class        class FIbmLiveStreaming final : private IGameplayMediaEncoderListener

Source code excerpt:

	* Starts streaming, using explicit settings
	*/
	bool Start(const FString& ClientId, const FString& ClientSecret, const FString& Channel, uint32 AudioSampleRate, uint32 AudioNumChannels, uint32 AudioBitrate);
	/**
	* Stops streaming
	*/
	void Stop();

	static void StartCmd()

#Loc: <Workspace>/Engine/Source/Runtime/GameplayMediaEncoder/Private/IbmLiveStreaming.h:182

Scope (from outer to inner):

file
class        class FIbmLiveStreaming final : private IGameplayMediaEncoderListener

Source code excerpt:

		FString ClientSecret;
		FString Channel;
		uint32 AudioSampleRate;
		uint32 AudioNumChannels;
		uint32 AudioBitrate;
	} Config;

	FIngest Ingest;

#Loc: <Workspace>/Engine/Source/Runtime/IOS/IOSRuntimeSettings/Classes/IOSRuntimeSettings.h:507

Scope (from outer to inner):

file
class        class UIOSRuntimeSettings : public UObject

Source code excerpt:

	/** Sample rate to run the audio mixer with. */
	UPROPERTY(config, EditAnywhere, Category = "Audio", Meta = (DisplayName = "Audio Mixer Sample Rate"))
	int32 AudioSampleRate;

	/** The amount of audio to compute each callback block. Lower values decrease latency but may increase CPU cost. */
	UPROPERTY(config, EditAnywhere, Category = "Audio", meta = (ClampMin = "512", ClampMax = "4096", DisplayName = "Callback Buffer Size"))
	int32 AudioCallbackBufferFrameSize;

	/** The number of buffers to keep enqueued. More buffers increases latency, but can compensate for variable compute availability in audio callbacks on some platforms. */