SoundToolKit Unreal Engine Plugin

stk_main

Description

SoundToolKit is a state-of-the-art audio engine using the newest scene scanning methods. It enables creation of realistic spatial sound in 3D environment, providing the best auditory experience. SoundToolKit is based on real-time simulation of acoustic phenomena that occur in real life due to geometry and scientifically measured materials used in particular scene. Thanks to advanced degree of automation, SoundToolKit allows game developers to shift their attention to more crucial matters while getting immersive, dynamic 3D sound generated out-of-the-box by a dedicated audio engine.

SoundToolKit comes with a multitude of features:

  1. Real-time audio processing based on actual game scene geometry.
  2. Real-time simulation of various acoustic phenomena:
  3. Automatic and dynamic reverberation based on provided scene geometry
  4. Different acoustic materials which boost overall sound experience
  5. 3D sound with a HRTF capability
  6. Ability to affect acoustic medium properties

On top of that SoundToolKit plugin extends that with a set of useful features for game developers:

Requirements

First Launch

Enabling AudioMixer

SoundToolKit plugin depends on features introduced with the new UE4 audio engine. For that reason AudioMixer functionality must be enabled for the plugin to work properly. In order to enable AudioMixer you must do the following:

  1. In your engine folder edit the WindowsEngine.ini file located here:
    \Engine\Config\Windows\WindowsEngine.ini
    Or your project folder, here:
    \Config\Windows\WindowsEngine.ini
    (If you don’t have one, you can create one)

  2. Enter the following:

[Audio] AudioDeviceModuleName=AudioMixerXAudio2

It is also possible to enable AudioMixer by passing -audiomixer parameter when launching the project, for example by creating a shortcut:

audiomixer_shortcut

Or by adding it to Command Arguments in project properties in Visual Studio:

audiomixer_commandargs

Enabling Plugin

After AudioMixer is enabled, it is also necessary to enable the plugin itself, which can be achieved by doing the following:

  1. In the UE4 Editor go to Edit > Project Settings,
  2. Select Windows in the Platforms section,
  3. Set Spatialization Plugin, Reverb Plugin and Occlusion Plugin to SoundToolKit.

enable_plugin

Enabling Plugin Content

The plugin comes with a number of dedicated assets. Making use of them will improve the experience of working with the SoundToolKit plugin. However, such assets are hidden by default. In order to see them, in Content Browser there is a View Options dropdown where Show Plugin Content and Show Engine Content should be checked.

stk_plugin_content

Plugin Output Logs

It is advised to open the Output Log window. SoundToolKit plugin notifies about it's state, warnings etc. via UE's logs system.

stk_output_logs

You can also enable extended logging by passing a following command to the console Log LogSoundToolKit Verbose.

StkProjectData Asset

After first launch of the project in UE editor, the StkProjectData.uasset file is created in Content directory. Do not delete this file as this asset is required by SoundToolKit to work properly.

stk_project_data_asset

Overview

Actors

In editor's Place mode tab there is a SoundToolKit category with actors available in the plugin. There are three types of actors.

stk_actors

Stk Scene

Stk Scene enables extended control over sound effects on the scene. It it also responsible for serializing the geometry of the acoustic scene to achieve a significant reduction of the loading times of acoustic meshes utilized by SoundToolKit. All the controls of StkScene are available only via actor instance that is created on Persistent Level. Hover the cursor over any control to see its description. This actor needs to be present on every scene in order for the plugin to work properly. One of the first things the user has to do is to place this actor on the scene. There must be exactly one actor of this type per every level.

stk_scene_actor

Stk Extensions

Stk Extensions is an editor-only actor equipped with visualisation-based debugging tools. One of it's features is toggling the visibility of acoustic scene that is currently utilized by SoundToolKit - on top of the visual scene of the game. Doing so allows to see if the acoustic scene matches the game scene well. Additionally, the actor enables rendering the visual representation of the sound paths processed by SoundToolKit plugin. Sound paths simulate how sound behaves in interaction with acoutic scene. They are composed of segments, each segment being generated by one of the acoustic effects (reflection, transmission, diffraction etc.) taking place on contact with a given mesh of the acoustic scene. Each path is marked as one of 7 possible types, each with it's own color:

Hover the cursor over the control to see its description.

stk_extensions_actor

Stk Diagnostics

Stk Diagnostics is an editor-only actor that provides extensive information about the state of SoundToolKit engine via indicators. It can also track all currently active sound sources on the scene and display informations about their configuration. Properly configured sound source should have Spatialization Enabled and Processed by Sound Tool Kit ticked. Typically Processed by Unreal Engine should be disabled - this means that UE does not apply any additional effects on output sound for this sound source (all effects like attenuation etc are calculated by SoundToolKit solely).

stk_diagnostics_actor

Assets

To create any SoundToolKit asset object:

  1. Right-click in the Content Browser to open a context menu.
  2. Navigate to SoundToolKit category.

stk_assets_menu

Stk Acoustic Model

Stk Acoustic Model is an abstraction of a group of acoustic meshes. It defines which meshes are loaded and unloaded into the SoundToolKit engine as one entity (ex. meshes that build one building should probably be placed inside the same acoustic model). When level streaming is utilized in the game, meshes from different sub-levels are treated as separate entities inside the SoundToolKit engine even if they have the same acoustic model assigned.

stk_acoustic_model_asset

Stk Acoustic Material

Stk Acoustic Material defines how sound will behave on contact with acoustic meshes. SoundToolKit plugin comes with over 100 predefined types of acoustic materials. On top of that, it is also possible to create custom materials by adding a new Acoustic Material asset. There are three effects defined by the material, each in 8 octave frequency bands: reflection, scattering and transmission.

stk_acoustic_material_asset     stk_acoustic_material_asset_cystom

Stk Spatialization Source Settings

Stk Spatialization Source Settings configures how SoundToolKit spatializes sound. User can set how to attenuate sound with distance or toggle the HRTF (head-related transform function) spatialization method for a given source. SoundToolKit plugin provides 7 predefined attenuation curves:

  1. Nothing,
  2. Linear,
  3. Inverse,
  4. Logarithimic,
  5. Line Source,
  6. Point Source,
  7. Reverse Logarithm.

It is also posible to create custom attenuation curves.

stk_spatialization_source_settings_asset

Stk Occlusion Source Settings

Stk Occlusion Source Settings allows to toggle the reflection, transmission and diffraction effects per sound source.

stk_occlusion_source_settings_asset

Stk Reverb Source Settings

Stk Reverb Source Settings allows to toggle the reverberation effect per sound source.

stk_reverb_sound_settings_asset

Settings

SoundToolKit provides several low-level settings for how the sound is processed. This mechanism is exposed through Project Settings. In order to change one of the parameters of SoundToolKit engine go to Edit -> Project Settings..., then scroll down to Plugins and pick SoundToolKit. To see the description of a setting just hover the cursor over its name.

stk_settings

Blueprints

SoundToolKit comes with blueprint functions that can be use to control acoustic effects on the scene at runtime:

stk_blueprints

Scene Setup

SoundToolKit is an engine that simulates a range of acoustic effects, most of which require geometry - objects, that occlude or reflect sound. This section describes how to mark static meshes on the scene to be used by the plugin as acoutic meshes and how to configure sound sources to be processed by SoundToolKit.

Before any scene setup make sure that every level contains exactly one Stk Scene actor. Once placed on the scene, make sure to not delete this actor.

Acoustic Scene

Acoustic scene can be created from Landscapes and any object with StaticMeshComponent attached (e.g. StaticMeshActor). To mark such objects to be a part of the acoustic scene:

  1. Select an object from editor.
  2. Navigate to SoundToolKit category in object's Details view.

stk_geometry_soundtoolkit_category

The minimal setup required to use this object's geometry as acoustic mesh is to enable the Use as Acoustic Mesh checkbox.

The Acoustic Model is an optional field for grouping the geometry via Stk Acoustic Model assets. For small scenes this field can be left empty - all objects without Stk Acoustic Model assigned are grouped as one entity.

The Acoustic Mesh field can be used to specify custom StaticMesh asset that should be used as acoustic obstacle in place of selected object on the scene. Attaching the custom StaticMesh is a must when a visual geometry representation is complex. Meshes on an acoustic scene should be as simple as possible (the less triangles the acoustic scene includes the better). In other words AcousticMesh is a simplified mesh that reduces processing time. If this field is left empty, the acoustic scene mesh is built using the collision LOD of the StaticMesh. Meshes that are used in the acoustic scene must have Mobility set to Static and Allow CPU Acces checked.

cpu_acess

The Acoustic Materials array field is used to specify the acoustic materials of an object via Stk Acoustic Material assets. Acoustic materials are set per mesh sections. The number and order of acoustic materials should match the visual materials set in StaticMesh properties window. If an array element for a section is left empty, the SoundToolKit's default material is used.

Acoustic meshes can also be created using the Add Static Mesh Component and Add Instanced Static Mesh Component blueprint nodes. Just select the node and navigate to SoundToolKit category in the Details window.

Sound Sources

Configuration of actors such as AmbientSound, SoundCues etc. boils down to setting parameters of it's AudioComponent. Each AudioComponent has slots for Spatialization Plugin Settings, Reverb Plugin Settings and Occlusion Plugin Settings where instances of Stk Spatialization Source Settings, Stk Occlusion Source Settings, Stk Reverb Source Settings can be attached.

stk_attenuation_plugin_settings

In order to register a sound source within SoundToolKit plugin the following conditions must be met:

  1. The sound must be mono,
  2. Allow Spatialization must be cheked in Attenuation category,
  3. Enable Spatialization must be checked in Attenuation Spatialization category,
  4. Spatialization Method must be set to Binaural in Attenuation Spatialization category,
  5. Enable Occlusion must be checked in Attenuation Occlusion category,
  6. Spatialization Plugin Settings, Reverb Plugin Settings and Occlusion Plugin Settings must have appropriate objects selected.

SoundToolKit engine implements features such as sound attenuation, air absorption, reverberation etc., therefore the same features native to Unreal Engine should be disabled. Otherwise e.g. sound attenuation will be applied twice, first by Unreal Engine and then by SoundToolKit.

Debugging

To make sure the acoustic meshes and sound sources are set up correctly Stk Extensions actor can be used to render the acoustic scene and all found sound paths between sources and receiver. With Stk Diagnostics actor the state of the engine and the configuration of all active sounds on scene can be monitored. Remember to track the Output Log window to see the SoundToolKit messages.

stk_extensions_example

Serialization

When the scene's geometry is finished and all the acoustic meshes are set up, use Stk Scene actor to serialize acoustic geometry.

stk_serialization_buttons

stk_serialization

Serialization greatly reduces the loading time of acoustic meshes both upon scene startup and during loading/unloading sub-levels when level streaming is utilized in the game. Remeber to use Serialize Acoustic Scene button after any changes to the acoustic scene. It is strongly advised to serialize the acoustic geometry of every scene right before packaging the project.