Soundfield Plugin for Unity
Soundfield is used interchangeably with Magic Leap Spatial Audio (MSA).
The binaries for Windows require that the Visual Studio Redistributable C++ libraries are installed. If the computer is new or Unity shows errors about loading the Soundfield plugin in Unity, you may need to install the runtime libraries.
For more information, please see Microsoft's official documentation here.
Soundfield Plugin Installation
From the Magic Leap Hub
- In the Unity Packages section of the ML Hub Package Manager, you will find the Unity Soundfield package here:
- Download the Unity Soundfield package via the Package Manager. Its location can be accessed from the Open Folder link in the ML Hub's Package Manager:
- Add this package from Unity's own Package Manager as a local file:
- Select the package.json file in the folder you have previously downloaded (shown as an example in a screenshot above).
The plugin will now be ready to use in Unity:
Update an Existing Installation
After updating the Soundfield plugin, if any unexpected/undesirable behaviors occur, it may be necessary to reset the Soundfield components. On simple objects, this can be accomplished with the three-dot menu in the Unity Inspector window for the Soundfield component.
- For each Soundfield component that needs to be reset, click the three-dot menu icon next its name in the Inspector window, then click Reset.
The reset should be performed on the
MLListener component that is co-located with the Unity
AudioListener, as well as the
Resetting the Soundfield component in a prefab can be accomplished through the same process:
- Select the prefab in the Unity project window and click Open in the Inspector window.
- Reset each Soundfield component using the steps described above. The changes made inside the prefab will then be applied to all objects in the project using that prefab.
Whether updating from local disk as with the ML Hub, or from a package repository such as UPM (Unity Package Manager), the Unity project must be restarted before Soundfield will be able to properly use updated files.
In the editor, the Soundfield Gizmos are selectable from the "Gizmos" menu:
When a Soundfield Gizmo is selected, any GameObject that is selected in the project hierarchy will draw the relevant information in the Scene view.
More details on the way Gizmos behave in the editor can be found in the Unity documentation page here.
The Soundfield package provides a
RuntimeGizmos component that allows developers to choose which Gizmos to make visible at runtime, on the device.
When a Gizmo is selected, all the GameObjects with the ML component will be rendered.
MLPointSource Gizmo Types
Depending on the radiation properties, the point source Gizmo changes to indicate the current selection.
Billboarding is enabled
Omnidirectional is enabled
We will use a Camera, an
MLListener, a source, and an obstruction.
The camera object will have the
MLListener component. We also use
AudioListener as a base class.
MLListener should be used per Scene.
For more information, see the Soundfield Components page.
For the source, using our Leaper, remember we use
AudioSource as a base class, so some things will be done there, like selecting an audio clip:
For the obstacle, you can inherit the geometric primitive from the visuals by default. As long as it has a collider, it can obstruct sounds.
Any 3D object with a collider can obstruct sound. If you would like only some of your objects to obstruct, you can create a layer named "MLAudioObstruction" and only the objects within that layer will be considered.
Layers 0-7 in Unity were formerly restricted and should not be used for obstructions. They may work in some cases, but this is not supported. See the Unity TagManager docs for details.
Project Audio Settings
If the DSP Buffer Size property is changed either in editor play mode or at runtime it will cause Unity to stop all the currently playing audio sources. The only way for them to recover will be to start them manually.
When running a project, if an error similar to the below appears in the Unity error console, additional runtimes ("Workloads") may need to be installed, supplied by Microsoft:
Plugins: Failed to load 'C:/AppDirectory/Library/PackageCachefirstname.lastname@example.org/Plugins/x86_64/AudioPluginMSASpatializer.dll' because one or more of its dependencies could not be loaded.