Unity Spatial Audio

Unity Plugin 

Overview 

The included Unity Plugin enables developers to utilize the HP VR Spatial Audio framework inside the Unity Engine.  

Adding the plugin to your project 

A Unity assetpackage containing all the required files resides in the installation folder for the HP VR Spatial Audio SDK under the Unity subdirectory. To add the plugin to your project, use the custom assetpackage import option in the Unity editor: 

 

Navigate to the HP VR Spatial Audio SDK installation (default: C:\Program Files\HP\HP VR Spatial Audio\Unity) and select the HPVRSpatialAudio.unitypackage file. 

Setup 

 

Open the Project Settings menu from “Edit-> Project Settings”, In the “Audio” section of the menu change “Spatializer Plugin” from “None” to “HP VR Spatial Audio”  

In order to use HP VR Spatial Audio, you must first configure your license for the current project. Select “HP VR Spatial Audio->Configure” from the menu bar and enter your license information in the configuration window. The information is stored as an asset (ScriptableObject) in the Resources folder of your current project. If the plugin is not configured, then Unity’s default audio will be used.  

Set Custom Encryption Keys 

The HPVRSpatialAudioSettings script encrypts the Client ID and Access Key license information to prevent this data from being stored as plain text in built applications. Default values are provided for the encryption keys. To customize the encryption, set the variables ENCRYPT_KEY and ENCRYPT_IV to 32 byte and 16 byte strings, respectively. 

 

Usage 

“HP VR Spatial Audio” needs to be explicitly enabled by a game object in your scene. This is done by calling the enableSpatialAudio() function in the HPVRSpatialAudioEnabler class. This function only needs to be called one time successfully during the game. “HP VR Spatial Audio”, once enabled, will remain enabled for the lifetime of the process. The enablement call will happen asynchronously to avoid blocking game threads while the license checkout is happening. The HPVRSpatialAudioEnabler class provides helper functions to get the status and error code from the call to enableHPVRSpatialAudio.  

 

To use “HP VR Spatial Audio” add a HPVRSpatializerUserParams component to a game object with an Audio Source component.  

 

Params: 

  • Should Spatialize: Set to true to use HP VR Spatial Audio, false will use Unity Audio. (Default: true) 

  • Note: Set this value instead of the “Spatialize” value in the Audio Source component 

  • Distance Attn: AudioSource distance attenuation. (Default: 1.0, Range: 0.0 - 1.0) 

  • Fixed Volume: Fixed volume amount. (Default: 0.0, Range: 0.0 - 1.0) 

  • Custom Rolloff: Custom volume falloff amount (logarithmic). (Default: 0.0, Range: 0.0 - 1.0) 

  • HRTF Angle Threshold: The minimum change in angle (degrees) between an Audio Source and listener before recalculating HRTF.  (Default:1.0, Range:0.0 - 10.0) 

 

Some parameters in the Audio Source component are used by the HP VR Spatial Audio: 

 

  • Stereo Pan: Only valid for Mono and Stereo AudioClips. Mono sounds will be panned at constant power left and right. Stereo sounds will have each left/right value faded up and down according to the specified pan value. (Range: -1.0, 1.0) 

  • Spatial Bend: Sets how much this AudioSource is treated as a 3D source. 3D sources are affected by spatial position and spread. If 3D Pan Level is 0, all spatial attenuation is ignored.  (Range: 0.0 - 1.0 ) 

  • Spread: Sets the spread of a 3D sound in speaker space. (Range: 0 – 360) 

 

 

Caveats: 

  • Once HP VR Spatial Audio enabled, the license will be checked out for the lifetime of the process, if you are running in the editor you will need to close it to check the license back in 

  • Turning Spatial Audio on/off for a game object should be done through the HPVRSpatializerUserParams “Should Spatialize” property, instead of the AudioSource “Spatialize” property. HPVRSpatializerUserParams will set the “Spatialize” in AudioSource depending on value “Should Spatialize” and whether HP VR Spatial Audio has been enabled. 

Enable Result 

Spatial Audio enablement happens asynchronously, if you want the result of the call, HPVRSpatialAudioEnabler provides enablement results through the function getEnableResult. Each result has a status enum and a message. The statuses are: 

  • Not Started: No call has been made to enable spatial audio. 

  • In Progress: The call to enable spatial audio is currently in progress. 

  • Enabled: HP VR Spatial Audio has been enabled.  

  • Failed: HP VR Spatial Audio failed to be enabled. Check the message string for a more detailed explanation.