Install and Use the Oculus Spatializer for Wwise
在此專頁上
The Oculus Spatializer Plugin (OSP) is an add-on plugin for the Audiokinetic Wwise tool set that allows monophonic sound sources to be spatialized in 3D relative to the user’s head location. This integration guide describes how to install and use the OSP in both the Wwise application and the end-user application.
Prerequisite:
- Prior to installing this plug-in, make sure to install Audiokinetic Wwise on your system.
Download the Spatializer Package
Download the Oculus Spatializer Wwise package from the Oculus Spatializer Wwise page.
Package Contents
The download package contains the following folders, indicating the version of Wwise the files should be used with.
Wwise2018.1Wwise2017.2Wwise2017.1Wwise2016Unity
In each Wwise folder you will find the following subfolders:
Android- Provides files to add to Android apps.Include- ContainsOculusSpatializer.h, which is used to integrate Wwise into a Windows app. It contains important registration values that the app must use to register OSP within Wwise. In addition, it contains code to register the plugin with the Wwise run-time. For more information, see Integrate the Oculus Spatializer in your App.Macub- Provides library file to add to macOS apps.Win32- Provides library file for the 32-bit Windows Wwise Authoring tool and apps.x64- library file for 64-bit Windows Wwise Authoring Tool and apps.
The Unity folder contains a C# script file.
Set up and/or Update the Spatializer Plugin
Install the Oculus Spatializer to add it as a Wwise Mixer Plug-in to use in your soundbanks.
Set up on Windows
- Navigate to the download package folder that matches your version of Wwise.
- If installing on 64-bit Windows, copy
\x64\bin\pluginstoAudiokinetic\Wwise{version}\Authoring\x64\Release\bin\plugins - If installing on 32-bit Windows, copy
\Win32\bin\pluginstoAudiokinetic\Wwise{version}\Authoring\Win32\Release\bin\plugins
Set up on macOS
For these steps, note:
{full version}represents the major and minor version of Wwise (ex: 2018.1.8.6907){version}represents the major version of Wwise (ex: 2018)- Make sure to preserve the spaces and slashes in the commands
To set up:
- Open the Finder, and then go to the
Applications/Audiokinetic/Wwise{full version}folder. - Control-click Wwise.app, and then select Show Package Contents
- Go to the
Contents/SharedSupport/Wwise{version}/support/wwise/drive_c/Program Files/Audiokinetic/Wwise/Authoring/Win64/Release/bin/pluginsfolder. This is the Wwise.app/pluginsfolder. - From a new Finder window, copy the contents of the
Wwise{version}/Win64/bin/pluginsfolder to the Wwise.app/pluginsfolder. - Open the Terminal application.
- Change directories to the Wwise installation directory by entering:
cd /Applications/Audiokinetic/Wwise\ {full version}/Wwise.app/Contents/SharedSupport/Wwise{version}. - Enter:
CX_ROOT=/Applications/Audiokinetic/Wwise\ {full version}/Wwise.app/Contents/SharedSupport/Wwise{version} WINEPREFIX=/Applications/Audiokinetic/Wwise\ {full version}/Wwise.app/Contents/SharedSupport/Wwise{version}/support/wwise ./bin/wineprefixcreate --snapshot
Update the Spatializer
To migrate to a new version of the Oculus Spatializer Plugin for Wwise, follow these steps:
- Delete any existing versions of
OculusSpatializer.dllandOculusSpatializer.xml. - Copy the new versions of
OculusSpatializerWwise.dllandOculusSpatializerWwise.xml(32 bit or 64 bit) from the Audio SDK over the existing versions in your Wwise Authoring tool installation directory. - Copy the new versions of
OculusSpatializerWwise.dll(32 bit or 64 bit) over the existing version in your application directory. - Open the Wwise Authoring tool and generate sound banks.
- Launch your application and load newly generated sound banks.
Use the Spatializer in Wwise
Before you get started using the spatializer, in the main menu, set your audio output configuration to a 2.1 or 2 Stereo Channel Configuration (Speakers or Headphones). The spatializer will not work on higher channel configurations. Also note that only mono (1-channel) and stereo (2-channel) sounds are spatialized. Any sounds with a higher channel count will not be spatialized.
Set up an Audio Bus
First you should set up an audio bus that uses the spatialzier. Up to 64 sounds running through the bus are spatialized. Subsequent sounds use Wwise native 2D panning until the spatialized sound slots are free to be reused. Note that if you add the plugin to a second bus, you may experience some unwanted noise on the audio output.
- Launch Wwise.
Create a new audio bus and place it under one of the master buses. Note that the plugin may only be added to one bus.
Note: Mixer bus plugins may not be added to master buses.
Click on the newly-created bus and then click on the Mixer Plug-in tab in the Audio Bus Property Editor. Select the >>, find the Oculus Spatializer selection, and add a Default (Custom) preset:
Note: If the Mixer Plug-in tab is not visible, click the “+” tab and verify that Mixer Plugin is checked.
The following image shows an example.
Under the Mixer Plug-in tab, click on the ellipses ... button at the right side of the property window. This will open up the Effect Editor (global properties) for OSP:
Global Properties
The following properties are found within the OSP effect editor:
| Property | Description |
|---|---|
| Bypass Use native panning | Disables spatialization. All sounds routed through this bus receive Wwise native 2D panning. |
| Gain (+/-24db) | Sets a global gain to all spatialized sounds. Because the spatializer attenuates the overall volume, it is important to adjust this value so spatialized sounds play at the same volume level as non-spatialized (or native panning) sounds. |
| Global Scale(1 unit = 1 m) | The scale of positional values fed into the spatializer must be set to meters. Some applications have different scale values assigned to a unit. For such applications, use this field to adjust the scale for the spatializer. Unity defaults to 1 meter per unit. Example: for an application with unit set to equal 1 cm, set the Global Scale value to 0.01 (1 cm = 100 m). |
| Reflections Engine On | Enables early reflections. This greatly enhances the spatialization effect, but incurs a CPU hit. When enabled, make sure the room size roughly matches the room in the game, and that the room is large enough to contain the sound. If a sound goes outside the room size (relative to the listener’s position), early reflections will not be heard. In addition, be sure to set non-cubical room dimensions. A perfectly cubical room may create reinforcing echoes that can cause sounds to be poorly spatialized. The shoebox model works best when simulating rooms. For large spaces and outdoor areas, it should be complemented with a separate reverb. |
| Late Reverberation | If this field is set, a fixed reverberation calculated from the early reflection room size and reflection values will be mixed into the output (see below). This can help diffuse the output and give a more natural sounding spatialization effect. Reflections Engine On must be enabled for reverberations to be applied. |
| Shared Reverb Attenuation Range Min / Max | Controls the attenuation calculations for the spatial reverb. For more information, see the Attenuation and Reflections section of the feature guide. |
| Reflections Range Max | Range of the attenuation curve for reflections. This is the distance at which the reflections go silent, so it should roughly match the attenuation curve in Wwise. For more information, see Attenuation and Reflections. |
| Room Dimensions Width / Height / Length | Sets the dimensions of the room model used to calculate reflections. The greater the dimensions, the further apart the reflections. Value range is 1-200 meters for each axis. |
| Wall Reflection Coefficients | Sets the percentage of sound reflected by walls for each wall specified for a room (Left/Right,Forward/Backward, Up/Down). At 0, the reflection is fully absorbed. At 1.0, the reflection bounces from the wall without any absorption. Capped at 0.97 to avoid feedback. |
Set the Audio Bus for a Sound
For a sound to be spatialized, follow these steps.
Under General Settings, make sure sounds are set to use the audio bus configured with the Oculus Spatializer
On the Positioning tab, ensure sound positioning is set to 3D
When a sound us set to use the spatializer audio bus, a Mixer plug-in tab will show up on the sounds Sound Property Editor.
Following is a description of the properties.
Sound Properties
The following properties are applied per sound source.
| Property | Description |
|---|---|
| Bypass Spatializer | Disables spatialization. Individual voices / actor-mixer channels may skip spatialization processing and go directly to native Wwise panning. |
| Reflections Enabled | Enables early reflections. This greatly enhances the spatialization effect, but incurs a CPU hit. |
| Oculus Attenuation Enabled | If selected, the audio source will use an internal amplitude attenuation falloff curve controlled by the Range Min/Max parameters. |
| Attenuation Range Min | Sets the distance at which the audio source amplitude starts attenuating, in meters. It also influences the reflection/reverb system, even if Oculus attenuation is disabled. |
| Attenuation Range Max | Sets the distance at which the audio source amplitude reaches full volume attenuation, in meters. It also influences the reflection/reverb system, even if Oculus attenuation is disabled. |
| Volumetric Radius | Expands the sound source from a point source to a spherical volume. The radius of the sphere is defined in meters. For a point source, use a value of 0. |
| Treat Sound As Ambisonic | Treats sound as ambisonic instead of applying spatialization. Recommended for ambient or environmental sounds, that is, any sound not produced by a visible actor in the scene. Note: Attached sound must be in AmbiX format. Please see Ambisonics in Supported Features for more information. |
| Ambisonic Virtual Speaker Mode | Decodes ambisonics as an array of eight point-sourced and spatialized speakers, each located at the vertex of a cube located around the listener. If the check box is not selected, ambisonics are decoded by OculusAmbi, our novel spherical harmonic decoder. OculusAmbi has a flatter frequency response, has less smearing, uses less compute resources, and externalizes audio better than virtual speakers. However, some comb filtering may become audible in broadband content such as wind and rushing water sounds. For broadband content, we recommend using the virtual speaker mode. |
Notes and Best Practices
Note that the room model used to calculate reflections follows the listener’s position and rotates with the listener’s orientation.
All global properties may be set to an RTPC, for real-time control within the user application.
A stereo sound will be collapsed down to a monophonic sound by having both channels mixed into a single channel and attenuated. Keep in mind that by collapsing the stereo sound to a mono sound, phasing anomalies with the audio spectrum may occur. It is highly recommended that the input sound is authored as a mono sound.
Spatialized sounds will not be able to use stereo spread to make a sound encompass the listener as it gets closer (this a common practice for current spatialization techniques).
Starting with version 1.40 of the Wwise plugin, the volume set on a sound is applied pre-send. This means any volume setting including RTPC automation are consistent with the direct sound and reverb. For projects using the shared reverb this will change the mix.