The Spatial Clustering plugin dynamically groups audio objects by proximity, reducing system audio object consumption in computationally demanding scenarios.
Unlike traditional Effect Plug-Ins which are agnostic to Audio Objects, Object Processors have direct control over Audio Objects (AkAudioObject) passing through a bus, enabling the processing of their metadata and spatial characteristics.
- Dynamic Object Clustering: Automatically groups nearby spatial audio objects in real-time using a density-aware clustering algorithm
- Resource Optimization: Significantly reduces active audio object count while preserving spatial accuracy
- Adaptive Cluster Management: Automatically adjusts cluster count based on scene complexity and handles rapid object movement
- Large-scale battle scenes with multiple sound sources
- Particle system audio (rain, debris, ambient effects)
- Crowd simulations
- Dense environmental sound design
- Vehicle/machinery sounds with multiple components
Most spatial audio endpoints (Dolby, Sonic, DTS) offer up to 128 concurrent spatial audio objects. In EVE Online and Frontier's massive space battles, these resources get depleted rapidly, as each spaceship generates multiple audio objects for its engines, turrets, missile launchers, and combat effects.
We developed this plugin to mix nearby sources into a single output positioned at their centroid. Human spatial resolution is limited at small angular separations, so a listener can't really tell several close sources apart from one source at the average position. The freed audio object slots then become available for sounds elsewhere in the scene.
The plugin ships as part of the EVE Online and EVE Frontier audio engine. In intense battles we measured up to 60% reduction in audio thread CPU usage.
Scene with 20 ships firing at the player:
- System audio object consumption is constantly being exceeded
- Text in each unique location is obscured since quite a lot of objects are stacked upon each other
- No control over which objects are spatialized and which are redirected into the main mix.
Same scene with plugin enabled:
- System audio object consumption is drastically reduced (20-24 objects)
- Clear, distinct spatial positioning for each cluster
- More resources for sound designers to add unique locations of spatialized objects
- Place the plugin strategically in busses that need clustering (e.g. turrets, missiles, engines)
- Use tighter clustering for dense sources (turret fire) vs spread-out sounds (shields)
- In Audio Devices -> System monitor the system audio object consumption in real-time
- From the Wwise Authoring tool use Views->Profiler->Audio Object 3D Viewer profiler for a visual spatial representation of the clusters
- Go to Views->Profiler->Audio Object List and select different busses to change the focus of the Audio Object 3D Viewer
To place breakpoints and debug the plugin follow the steps here
- Objects within a defined distance threshold are grouped into clusters
- Each cluster is represented by a single spatial output audio object positioned at the cluster's centroid
- Each input object's buffer is mixed into a single output buffer using Wwise's
MixNinNChannels()API - Objects that are too far from any cluster or don't have spatialization remain independent
- Number of clusters is automatically determined based on number of input objects per frame
- Clusters are created and destroyed dynamically as objects move
- Cluster merging ensures clusters from previous frames merge with current frames if within radius
- Smooth transitions prevent audio artifacts when objects change clusters
- Interpolation for rapid position changes of input objects in clusters
For the purpose of this project we developed a density-aware spatial clustering algorithm for real-time 3D audio. Given a set of audio object positions and a distance threshold, it groups nearby objects into clusters each frame and represents each cluster as a single output object at the group's centroid.
-
Initialization: Initial cluster centers are picked based on local object density using Gaussian weighting, biased toward the listener position. Additional centers are placed using K-means++ and selection stops early if all remaining objects are already within range of an existing center.
-
Assignment: Each object is assigned to its nearest cluster center if it falls within the distance threshold. Objects too far from any center are grouped with other nearby distant objects to form new clusters.
-
Update Step: Cluster centers are recalculated as the average position of their members. Empty clusters are removed. The algorithm iterates until assignments stabilize or SSE improvement becomes negligible.
See Audiokinetic's Creating Audio Plug-ins for the full toolchain setup (SDK install, environment variables, compiler requirements).
- A C++ toolchain supported by Wwise's plugin build system
- Wwise 2025.1+ (it will work for previous versions although you might need to adapt some of the code)
- Python 3
- Generate solutions:
py -3 %WWISEROOT%\Scripts\Build\Plugins\wp.py premake Authoring_Windows
- Build the required solutions:
ObjectCluster_Windows_vc170_static.sln(Static library)ObjectCluster_Windows_vc170_shared.sln(Runtime DLL)ObjectCluster_Authoring_Windows_vc170.sln(Authoring DLL)
We welcome contributions: feature requests, bug fixes, documentation improvements, or new functionality. Contribution guidelines and PR templates are still being finalized as we open source the wider engine, so please bear with us while that work lands.
- Search existing open and closed issues before creating a new one
- For feature requests, include the use case
- For bug reports, include steps to reproduce and expected behavior
- Fork the repository and create a feature branch
- Build and test your changes at runtime before submitting.
- Submit a PR with a clear description of what changed and why
Wwise offers a free personal license that includes the C++ SDK and CLI tools needed to build this plugin. To get started, see Creating Audio Plug-ins in the Wwise docs.
Once the plugin builds, you'll want a scene to exercise it in. A few options:
- Unreal Engine 5 or Unity with the Wwise integration.
- Wwise Integration Demo Sample: a lightweight executable with various demos that you can build and modify yourself.
- Wwise sample games provided by Audiokinetic.
We don't yet ship a dedicated sample scene for spatial audio testing. That's on the list to add.
© 2024 - present CCP ehf.
This software was developed by CCP Games for spatial audio object clustering in EVE Online and EVE Frontier, using the Audiokinetic Wwise SDK.
This project is licensed under the Apache License 2.0.