Audio Modulation Overview

Overview of a more flexible audio modulation method in Unreal Engine

Windows
MacOS
Linux

The Unreal Engine (UE4) Audio Modulation system is a collection of audio mix tools that provides improved control for designers over common audio parameters from the Blueprint and Component systems.

The system:

  • Creates a generic, flexible, decoupled mix system for the Unreal Audio Engine.

  • Establishes a more robust set of tools for auditioning and debugging a game's audio mix.

  • Provides an API that can be easily extended and used to apply further modulation to audio plugins.

The Audio Modulation plugin must be activated to use this feature. Go to Edit > Plugins > Audio, then check Audio Modulation to enable.

The Root Class: Sound Modulator Base

All modulation types derive from USoundModulatorBase. This Class provides basic lifetime mechanics used for all modulation types, including control buses, control bus mixes, and bus modulators.

The lifetime of a modulator is either explicitly managed by a user or auto-activated, based on whether a referencing sound instance is attempting to utilize the modulator.

Explicit management (via activation and deactivation that is supported in Blueprint) has the benefit of allowing users to feed values to a modulator whether or not it is being used, but this requires more diligence on the part of the sound designer.

An example of when this might be useful includes bussing a character’s ability power to the audio engine, regardless of whether sounds are actively applying the bus value to a control type (volume, LPF, HPF, or pitch, for example).

When not manually activated, a user has less concern about lifetime management of the object, and therefore an inability to provide the initial desired conditions. An example of when this might be useful is when a bus modulator doesn't need to be constantly calculated. A modulator like an LFO may only need to be active while sounds are playing (as the LFO's output would not result in any notable change when a resulting sound is not playing).

All modulation types are auto-activated by default. To force deactivation of a bus modulator, bus, or bus mix to maintain its state, the user can call DeactivateBus, DeactivateBusMix, or DeactivateModulator explicitly from Blueprint. If any of these are called, or if the UObject is destroyed but the modulator is still in use by a sound, the proxy object’s state will effectively be frozen, and will continue to exist until it is no longer referenced, or until the Object is reactivated.

Asset Classes

Click for full image.

Buses store values that can be applied to calculations for referencing sound object parameters. Four basic control bus types that derive from USoundControlBusBase are provided by the standard AudioModulation plugin:

  • USoundVolumeControlBus

  • USoundPitchControlBus

  • USoundLPFControlBus

  • USoundHPFControlBus

Each type provides bus behavior that other types deriving from USoundBase (USoundWaves, USoundCues, and so on) can subscribe to.

Buses provide the most basic sets of behavior for modifying numeric values on the audio thread at the thread's update rate. They provide a default value for the bus, and minimum and maximum bounds for what the bus value can be set to. An array of modulators can also be applied to the bus to provide automated variant behavior.

USoundControlMix

Click for full image.

A control mix contains an array of channels that can be applied to respective buses and dynamically applied at runtime. Mix values are applied linearly over a supplied attack time, and removed over the supplied release time.

Currently, all four base bus types can be modulated using control mixes, with the potential for more types in the future.

Mixes are calculated based on the type of bus. Volume and pitch buses are the product of each gain stage (multiplicative). HPF buses take the lowest provided value of all applied mixes, and LPF buses take the highest.

USoundModulationSettings

Click for full image.

Modulation settings define what is traditionally a patch bay in hardware modulation. It is the most complex type in the modulation system, and the most powerful.

Settings can be referenced by USoundBase, UAudioComponent, and USoundClass types. For each sound instance, a fallback structure is utilized to determine which Settings Object is used. If supplied, the USoundBase version is used. If not supplied, UAudioComponent is used. If the UAudioComponent hasn’t provided settings, the USoundClass value is applied at runtime.

Each bus type has its own settings section, and follows the same basic flow. If no buses are subscribed to, the Default Input Value will be applied. If set, Sample-And-Hold will sample the bus value as soon as a sound is initialized and hold it for the duration of the sound.

For each bus subscribed to and active (inactive buses are ignored), an input Transform field is provided that allows the incoming bus value to be linearly transformed from Input Min/Max (domain) to Output Min/Max (range).

The transformed values that are output for each of these subscribed buses are mixed, then passed to the output section where a final custom Output curve is applied. A custom curve or one of the expressions provided can be applied. The following curves are supplied, with examples for scalar values:

USoundModulationSettings

GREEN: Exponential—inverse; PURPLE: Exponential—scalar; ORANGE: Sin—S-curve;BLUE: Sin; RED: Log

The Mixes section applies the provided ControlBusMixes, while sounds that reference this setting are active, along with other settings that reference the mix.

Mixes attack and release according to the settings provided in the mix itself. The release begins once the sound is complete.

USoundBusModulatorBase/USoundBusModulatorLFO

USoundBusModulatorBase is the base class for all modulators enabled for control buses.

The LFO modulator is the first example of a bus modulator available in beta.

Click for full image.

The LFO bus modulator can be one of the following basic shapes:

Click for full image.

Each LFO shape observes the Amplitude, Frequency, and Offset supplied. Periodic functions will or will not loop, depending on whether the Looping setting is enabled.

Blueprint API

(De)ActivateBus/BusMix/Modulator

These calls provide the ability to manually activate and deactivate Control Buses, Bus Mixes, and Modulators.

UpdateModulator

Changes to Objects of inheriting types of USoundModulatorBase (such as USoundControlBus, USoundControlBusMix, and USoundBusModulatorLFO) that are active must call UpdateModulator to hear updates immediately. This call submits the Object's changes to the audio thread to update the active modulator's proxy. All applicable changes to the USoundModulatorBase instance will be reflected in the respective runtime instance.

For example, if a volume control bus is referenced by a USoundBase type and active (with no mixes applied), updating the default value will instantly update the gain stage supplied by that bus to the USoundBase instance.

CreateLPFBus/HPFBus/PitchBus/VolumeBus/BusMix/LFO

These are convenience functions for creating respective types, setting a default value, and providing the option to activate immediately.

Select Skin
Light
Dark

Welcome to the new Unreal Engine 4 Documentation site!

We're working on lots of new features including a feedback system so you can tell us how we are doing. It's not quite ready for use in the wild yet, so head over to the Documentation Feedback forum to tell us about this page or call out any issues you are encountering in the meantime.

We'll be sure to let you know when the new system is up and running.

Post Feedback