README.md 5.3 KB
Newer Older
1
## VAUnity
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
2

3
VAUnity provides C# scripts to connect a VA auralization server with a Unity scene in order to create a synchronized audio-visual VR environment for an arbitrary combination of audio rendering and reproduction modules. The basic concept is to run a VA server and control it via the C# binding ([VACS](http://git.rwth-aachen.de/ita/VACS)) by adding classes to existing GameObjects in Unity. By enriching GameObjects with VA-specific classes, VA is triggered to create corresponding entities (like sources and receivers). Control information (such as translatory and rotatory movement) is propagated to the audio rendering instance(s). The Unity audio engine should be disabled. However, to enable VA support for Unity, the Unity project resources must be at hand and the scenes have to be extended manually by *VAUnity C# scripts* (mainly drag&drop). It is not possible to use VAUnity as an audio plugin for a deployed Unity project.
4 5


Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
6

7 8
### License

9
Copyright 2015-2018 Institute of Technical Acoustics (ITA), RWTH Aachen University
10 11 12 13 14 15 16 17 18 19 20 21 22

Licensed under the Apache License, Version 2.0 (the "License");
you may not use files of this project except in compliance with the License.
You may obtain a copy of the License at

<http://www.apache.org/licenses/LICENSE-2.0>

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

23 24


25
### Quick build guide for the unpatient and experienced users
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
26

27
Clone this project inside your Assets folder and place a copy the VA C# bindings from your VA deploy package as well. Add a `VAU Adapter` component to any existing GameObject and extend further GameObjects with corresponding `VAU*` components. Run a VA server before running the Unity scene. At least a listener with and and attached HRTF and a sound source with an attached signal source is required.
28 29 30



31
## Unity & VA example scene tutorial
32 33


34
### Objective
35 36 37 38

This section describes how to create an example scene in Unity that controls a VA server for binaural audio rendering. In the end, the visual camera will act as a binaural sound receiver and can be moved from a first person viewpoint to inspect one static and one circulating sound source.


39
### Software installation
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
40

41
Obtain a current VA full package from [virtualacoustics.org](http://www.virtualacoustics.org). Make sure that the subfolders `unity` and `csharp` are included.
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
42 43


44 45 46
Run a VA server with a binaural free-field rendering instance, e.g. by executing the `run_VAServer.bat` script (the untouched default VA configuration file will suffice).


47
### Unity project
48 49

Download, install and run Unity. Create a new project. Now, open the project folder in the file browser outside Unity. It should include a folder named `Assets`. Here, create a new directory `Plugins` and a subfolder `VA`. From your VA binary package, copy the directory `csharp` into the newly created folder structure (`Assets/Plugins/VA`). Now, either clone the VAUnity repository into the `VA` directory or copy the files from the binary package (folder name: `unity`).
50
After Unity has detected the new assets the scripts are available and can be assigned to any GameObject as components. You can easily list the scripts as they all have the prefix `VAU`.
51 52


53
### Set up and connect to VA
54

55
To set up a connection to VA on startup, add the `VAU Adapter` script to a newly created empty GameObject named `VA`.
56 57


58
### Prepare resource
59 60

Create an empty GameObjects called `HRTF` and add an existing C# script named `VAU Default HRIR` to the `HRTF` object.
61
Place a WAV audio sample in your assets folder. It will be used as signal source.
62
Create an empty GameObject called `AudioSignal` and add en existing C# script named `VAU Signal Source Audio File`. Type in the full name (including file ending) of the WAV file as FilePath.
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
63 64


65
### Listener
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
66

67
Drag&drop the `VAU Listener` script onto the camera rig / ears to create a dynamic listener in VA. The Script will update the pose accordingly based on the transform, i.e. if the movement is connected to a tracking device (e.g. VR glasses), the tracked data will be forwared to VA. To enable binaural rendering, drag&drop the `HRTF` GameObject onto the `Directivity` parameter of the `VAU Listener` component. 
68

Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
69

70
### Sound source
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
71

72
Drag&drop the `VAU Sound Source` script onto any sound object to create a VA sound source. The Script will update the pose accordingly based on the transform, i.e. if the movement is connected to a tracking device (e.g. VR controller), the tracked data will be forwared to VA. Also, drag&trop the `AudioSignal` GameObject onto the `Signal Source` property of the `VAU Sound Source` component.
73

Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
74

75
### Auralization modes
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
76

77
You can control the auralization modes via the `VAU Auralizaton Mode` script. Auralization modes are either controlling sound sources, listeners or are set globally. VA will only auralize a certain effect, if the corresponding mode is activated for all three components, i.e. a logic AND combination is applied.
78

Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
79

80
## Extensions
Dipl.-Ing. Jonas Stienen's avatar
Dipl.-Ing. Jonas Stienen committed
81

82
Have a look at the [VAUnityExtensions](http://git.rwth-aachen.de/ita/VAUnityExtensions) project to get 3D user interfaces that control VA using menus, like muting, sound level control, direct auralization mode manipulation and more.