THX Spatial Audio+

Table of Contents

• Introduction
• Installation
• Usage
  • Authoring
  • SoundBanks
  • Memory
  • Startup
• Parameters
  • Room Direct
  • Late Reverb
  • Early Reflections
  • Emitters
• Presets
• Passthrough
• UE5
  • Packaging
• Troubleshooting
• Upgrading from 1.0.x
• Upgrading from 1.1.x

---

Introduction

THX Spatial Audio+ is a spatial audio processing plugin for Audiokinetic Wwise.

Specifications:

• Plugin Version: 1.2.0
• Platform: Windows x64
• Wwise Version: 2024.1 and 2025.1
• Channel Configuration: 7.1.4 input (12 channels) to Stereo output (2 channels)

Installation

1. Download the plugin from this link.

   

2. Follow the Audiokinetic documentation to install the plugin.

   • Start the Audiokinetic Launcher.
   • Open the Plug-ins tab.
   • Choose the Wwise version and click Add from directory.

   

3. Select the folder with the unzipped files and press Modify.

   • The plugin will be installed to the selected version of Wwise.

   

4. Follow additional steps to install plugins to the engine integration. The Unreal/Unity Audiokinetic documentation can be found here.

   • Go to the Unreal Engine tab in the launcher.
   • Select the project using integration and click Modify Wwise in Project.

   

   • Click Modify on the next page.

   

Note: UE5 Wwise Integration uses dynamic libraries by default. That is the suggested way of usage.

Usage

Authoring

1. Create a new Wwise project.

2. Add a child Audio Bus to the Master Audio Bus.

   

3. Choose 7.1.4 channel configuration for this new bus.

   

4. Add the THX Spatial Audio+ plugin to this Audio Bus.

   

5. Create a test SFX in the Containers (Actor-Mixer) hierarchy.

   

6. Route it to the Audio Bus created with the THX Spatial Audio+ plugin.

   

7. Enable 3D positioning for this SFX.

   

8. When playing the SFX, THX Spatial Audio+ processing will be applied.

SoundBanks

Since version 1.1.0, the HRTF data the plugin needs ships as plug-in media inside a SoundBank (about 32 MB). There is no separate data.bin file to deploy.

Wwise never puts plug-in media into Init.bnk, where bus effects live. So, in addition to the Init bank:

1. Add the THX Spatial Audio+ Effect ShareSet (or the Audio Bus that carries the effect) to another SoundBank.
2. Generate SoundBanks with the same plugin version as the game's sound engine.
3. In the game, load that SoundBank before the THX bus is instantiated (i.e., before anything plays through it).

To check the result, open the generated SoundBank: the bank that carries the effect should be about 32 MB larger than it would be without THX.

Note: If the HRTF media is not loaded, the effect fails to initialize, Wwise drops it, and the 7.1.4 bus is down-mixed without binaural rendering. A Release build of the game reports nothing; Debug and Profile builds post the reason to the Wwise Profiler (see Troubleshooting).

Memory

The plugin allocates the HRTF data and its processing from the Wwise memory manager, under the AkMemID_ProcessingPlugin category. If your game caps that category, leave room for the plugin. If the allocation is refused, the effect is disabled on that bus, and the Wwise Profiler names the category and how many KB were refused.

Startup

Since version 1.2.0, the plugin loads the HRTF data and prepares its renderer on a background thread (named THX Spatial Audio+) instead of the audio thread. Bringing up a THX bus therefore costs the audio thread almost nothing, and selecting THX Spatial Audio+ at runtime no longer causes audio starvation.

• Until the renderer is ready, the bus outputs a plain stereo downmix of the 7.1.4 input (the standard -3 dB downmix, LFE dropped).
• Once it is ready, the output crossfades from the downmix into the binaural render over 20 ms.
• Switching the bus off and on again is fast: the plugin keeps the last HRTF set loaded between instances, so a game that toggles the renderer does not rebuild it each time. That HRTF set is released when the sound engine terminates.
• Offline rendering (for example, bounces) prepares the renderer inline, as before, so the downmix never plays and the output stays identical from run to run.

Debug and Profile builds post the time the downmix played to the Wwise Profiler (renderer prepared on the control thread N ms after Init(); crossfading from the downmix over 20 ms).

Parameters

THX Spatial Audio+ provides a set of parameters to control the binauralization effect.

Room Direct

Controls the direct path of the signal, representing the audio reaching the listener without reflections or reverb.

• Room Direct Enabled: Enables or disables the direct path of the signal.
• Direct Gain: Controls the gain level of the direct signal in decibels.
• EQ: A 10-band equalizer applied to the direct signal path.
  • Direct EQ Enabled: Enables or disables the 10-band equalizer.
  • Band Enabled: Enables or disables the EQ band.
  • Band Filter type: Selects the filter type for each EQ band (Peak, Low Shelf, High Shelf, High Pass, Low Pass, Notch, Band Pass, All Pass).
  • Band Frequency: Sets the center frequency of the EQ band in Hz.
  • Band Gain: Controls the gain of the EQ band in decibels.
  • Band Q: Controls the Q-factor (bandwidth) of the EQ band.

Late Reverb

Generates the late reverb to simulate the acoustic characteristics of a room.

• Late Reverb Enabled: Enables or disables the late reverb processing.
• Late Reverb Gain: Controls the gain level of the late reverb in decibels.
• Num Comb Filters: Sets the number of comb filters used to generate the reverb.
• Num All-Pass Filters: Sets the number of all-pass filters.
• Comb Filter Delay Mult: Multiplies the delay times of comb filters, affecting perceived room size.
• Room Size: Controls the perceived size of the reverb space.
• All-Pass Feedback: Controls the feedback amount in all-pass filters.
• Damp: Controls high-frequency damping to reduce brightness.
• Width: Controls the stereo width of the reverb output.
• Stereo Spread: Creates stereo separation and spatial width.
• Wet: Controls the level of the wet (reverberated) signal in the output mix.
• Pre EQ: 10-band equalizers applied before processing.
• Post EQ: 10-band equalizers applied after processing.

Early Reflections

Calculates and processes early reflections, simulating the first few sound reflections arriving before the reverb tail.

• Early Reflections Enabled: Enables or disables early reflections processing.
• Early Reflections Gain: Controls the gain level of early reflections in decibels.
• Early Stagger Enabled: Adds a random delay offset to each reflection for natural patterns.
• Virtual Room Dimensions: Defines virtual room dimensions (Length, Width, Height) for timing calculations.
  • Length: 2.5 to 50 m (default 15 m).
  • Width: 1 to 50 m (default 20 m).
  • Height: 1 to 50 m (default 6.5 m).
  • Since version 1.2.0, values outside these ranges are clamped to the nearest limit at runtime. This covers values that bypass the Authoring UI, such as ShareSets created with 1.0.x (which allowed a shorter Length) or properties written through WAAPI.
• Number of Reflections: Sets the maximum number of reflections to process per emitter.
• EQ: 10-band equalizer applied to the early reflections path.

Emitters

Defines virtual emitter (loudspeaker) positions in spherical coordinates relative to the listener. They represent the 7.1.4 channels: L+R (left/right), C (center), LFE (subwoofer), LRS+RRS (rear surround), LS+RS (surround), LTF+RTF (top front), LTR+RTR (top rear).

• Azimuth: Horizontal angle of the emitter relative to the listener (degrees from front center).
• Elevation: Vertical angle of the emitter relative to the listener (degrees from horizontal plane).
• Radius: Distance from the listener to the emitter position in meters.

Presets

To import the presets, use Project -> "Import Factory Assets..." and then select "THXSpatialAudioPlus". The following presets are provided (as ShareSets):

• THX_Default
• THX_Large
• THX_Medium
• THX_Small
• THX_Studio

Note: Presets imported from version 1.1.1 or earlier carry no HRTF media, so SoundBanks generated from them come out without it. Migrate them as described in Upgrading from 1.1.x. Presets imported from 1.2.0 do not need this.

Passthrough

Since THX Spatial Audio+ binauralization shall be placed at the last stage of processing, we suggest the following workflow for passthrough compatibility.

• Setup a Spatial Mix buffer as described in Authoring.
• Insert Wwise 3D Audio Mixer effect to Audio Objects bus, which mixes all objects to 7.1.4 channels.
• The plugin renders the 7.1.4 mix to stereo. The resulting two-channel output is then mixed with the Passthrough bus and sent to the output device (WASAPI).

UE5

Packaging

When packaging your Unreal Engine project, THXSpatialAudioPlus.dll is automatically copied to the packaging output (e.g., Plugins\WwiseSoundEngine\ThirdParty\x64_vc170\Release\bin).

Since version 1.1.0, nothing else needs to be staged next to the DLL: the HRTF data travels in the SoundBank that carries the THX effect (see SoundBanks). Make sure that SoundBank is packaged and loaded before the THX bus is used.

Note: If you modified WwiseSoundEngineVersionBase.Build.cs to stage data.bin for version 1.0.x, that change is no longer needed and can be reverted.

Troubleshooting

If the 7.1.4 bus plays down-mixed instead of binaural, THX Spatial Audio+ failed to start. Run a Debug or Profile build connected to the Wwise Profiler and look for one of these messages:

Profiler message	Cause and fix
HRTF plug-in media is not loaded. Add the Effect ShareSet or the bus to a SoundBank other than the Init bank, and load it before the bus is instantiated.	The effect is only in Init.bnk, or the bank carrying it is not loaded yet. See SoundBanks.
upgrading from 1.0.x? data.bin beside the plug-in is no longer read, and SoundBanks generated by THX 1.0.x Authoring carry no HRTF media: regenerate them with 1.1.0.	Posted together with the message above. See Upgrading from 1.0.x.
the HRTF plug-in media could not be loaded. The SoundBank copy may be truncated or corrupt.	Regenerate the SoundBank. If the bank is not about 32 MB larger than without THX, reinstall the plugin and regenerate.
...AkMemID_ProcessingPlugin... (with a size in KB)	The Wwise memory manager refused the allocation. See Memory.
the renderer could not be prepared. The effect is disabled on this bus.	The background preparation failed (see Startup). The bus keeps playing the downmix. Check the other messages posted with it.
the control thread could not be started; the renderer is prepared and its parameters applied on the audio thread.	The plugin falls back to the 1.1.x behavior: it still works, but prepares on the audio thread, which can cause a glitch when the bus starts.

If a bank looks right but the bus still plays down-mixed, the effect may have no HRTF media reference at all (work units or presets from 1.1.1 or earlier). Run check_thx_banks.py as described in Upgrading from 1.1.x.

Upgrading from 1.0.x

Version 1.1.0 changes where the plugin reads its HRTF data and whose memory it uses. A project that worked on 1.0.x can lose THX processing after the upgrade, with nothing in a Release build to say so.

• The HRTF data ships in a SoundBank. 1.0.x read data.bin from beside the plugin DLL; 1.1.0 ignores it. Add the THX Effect ShareSet (or its bus) to a SoundBank other than the Init bank and load it before the bus is instantiated, as described in SoundBanks. That bank grows by about 32 MB. The deployed data.bin can be deleted.
• Migrate the work units before opening the project. Work units written by 1.0.x lack the <PluginData> element the plugin needs to attach its HRTF media. Run migrate_wwu.py first, as described in Upgrading from 1.1.x.
• Regenerate all SoundBanks with 1.1.0 Authoring. A bank generated by 1.0.x Authoring carries no HRTF media (it comes out tiny, without any warning), so the 1.1.0 sound engine cannot start the effect from it. Wwise Authoring and the game's sound engine must use the same plugin version.
• Memory counts against the Wwise budget. 1.0.x allocated from the C runtime; 1.1.0 allocates from AkMemID_ProcessingPlugin. See Memory.
• Work units change on first save. Every THX effect gains a PluginMediaSource child, so expect a diff in the Effects and Busses work units the first time the project is saved.
• What does not change. Parameter names, types, and the SoundBank parameter layout are unchanged, so authored values and presets carry over.

Going back to 1.0.x is safe for the project: 1.0.x Authoring opens a 1.1.0 project and keeps every value. Only the SoundBanks have to be regenerated on each side of the switch.

Upgrading from 1.1.x

Version 1.2.0 keeps the parameters, SoundBank layout, and HRTF media of 1.1.x; regenerate the SoundBanks with 1.2.0 Authoring so Authoring and the game's sound engine match. What changes:

• Startup moves off the audio thread. The bus plays a downmix for a short time before the binaural render takes over. See Startup.
• Room dimensions are clamped to their published ranges. See Early Reflections.
• Upgrade tools ship with the release. The release zip contains a tools/ folder, next to the plugin bundle, with two Python scripts and a README.md. They need Python 3.8 or later and nothing else. A project created with 1.2.0 does not need them.

migrate_wwu.py: before opening the project

THX effects in work units written by 1.0.x, and Factory presets imported from 1.1.1 or earlier, have no <PluginData> element. Without it, Wwise Authoring never registers the HRTF media for the effect, and a SoundBank generated from it carries no HRTF data (about 1 KB instead of 32 MB), without any warning. The script adds the empty <PluginData/> element that Wwise would write.

Close the project in Wwise first, otherwise Wwise writes its own copy back over the change on the next save.

python migrate_wwu.py --project "C:/.../Wwise Project"           # report which effects need it
python migrate_wwu.py --project "C:/.../Wwise Project" --apply   # change them; each file gets a .bak- copy

check_thx_banks.py: after generating SoundBanks

Reads the JSON metadata Wwise writes next to the banks and exits with code 1 if a THX effect has no HRTF media reference, or if no bank carries the media (the effect is only in Init.bnk). Turn on JSON metadata generation in the project's SoundBank settings first. It is quick enough to run after every bank build in CI.

python check_thx_banks.py "C:/.../GeneratedSoundBanks/Windows"