3D HRTF Audio Database Player

Object Description
The 3D HRTF Audio Database Player object simulates three dimensional sound of a moving entity (such as an overflying aircraft) by playing wave files through two output channels using Head Relative Transform Functionality (HRTF). It is ideally suited for 3D audio in stereo headphones. Since it's a database player, multiple wave files can be selected and played through the use of an index. Dynamic controls for the player include volume, frequency, position, velocity, database index, loop enable, and play enable. Output pins provide a play status and a handle for future expansion. Static data includes a sound device channel, database name, database table name, minimum distance, and maximum distance. The position and velocity pins are represented by Cartesian coordinates, which are values on three axes: the x-axis, the y-axis, and the z-axis. The axes correlate to a head relative viewpoint as shown in the figure below. Values increase on the x-axis from left to right, on the y-axis from down to up, and on the z-axis from back to front. As sound propagates away from the source, the sound pressure level decreases at a rate based on a number of factors. For VPLus HRTF 3D Audio objects, this rate is established by the minimum and maximum distance static data (on an individual player basis), and by a VPLus-internal roll-off constant (which applies to all 3D HRTF players). The figure below illustrates the differences between an extremely loud sound (such as a jet aircraft), and a relatively quiet sound (such as a bee). If you were to have both sounds playing in a VPLus design, you would want to set the min/max distances to small numbers for the bee (e.g., min of 0.02, max of 10), and large numbers for the jet (e.g., min of 100, max of 1000). Since this is a database player (much like object 2008), a database has to be constructed to map indices to wave file names. This database can be constructed with any tool capable of ODBC (Open DataBase Connectivity) interoperability. One table exists in the database with three columns defined as follows (ensure that the KEY field has no duplicate entries): The name of an ODBC data source needs to be established in order for the Database Player to open it and find the table. This Data Source Name (DSN) must match the Database Name set in static data. The name of the table in the database must match the Table Name also set in static data. The Table Name must NOT contain any blank characters. To set the ODBC Data Source Name: Note: Also see the 3D HRTF Audio Player Looped.
Special Notes
SimPhonics uses the DirectSound component of Microsoft's DirectX Software Development Kit (SDK). Within DirectSound, Microsoft employs HRTF 3D audio. The following list describes how to best configure your system to take advantage of DirectSound's 3D HRTF audio. This player needs a stereo device to be able to play its wave files. This means that a channel must be odd-numbered for it to work. A run-time error message will be generated otherwise. It is advisable to use a high-quality pair of headphones to appreciate the subtle effects of the HRTF audio. Configure your audio device to use Stereo headphones. Go here to find out how.
Input Pins
Volume	The Volume pin controls the audio output level of this object. The valid range of this parameter is 0.0 (no volume) to 1.0 (full volume).
Frequency	The Frequency pin is a factor multiplied with the original sampling rate of the wave file to produce a rate at which the file will play. The sampling rate can range from 0 to 100,000. Normally, wave files have sampling rates of either 44,100 or 22,050 Hz. A factor of 2 would cause this object to change the sampling rate to 88,200, effectively doubling the pitch. A factor of 0 will essentially stop the player since this would equate to 0 samples per second. This pin can be used to "pitch bend" the audio while it is playing.
X, Y, Z position	These pins establish the position of the sound with respect to the listener's head (see 3D Audio Coordinate System figure above). Units: Meters Range: Any floating point number.
X, Y, Z velocity	These pins establish the velocity of the sound with respect to the listener's head (see 3D Audio Coordinate System figure above). Units: Meters per Second Range: Any floating point number.
Database ID	The Database ID pin value maps to the index field in the database and identifies the wave file to be played. This number can be changed during run-time without stopping execution. Note: Wait at least two frames between value changes on this pin. Otherwise, the new wave file will not be loaded and played.
loop	This pin will enable looping with any non-zero value. If the pin is 0, the wave file will play once and stop.
Enable	The Enable pin is used to turn the object on or off. The player is activated with any non-zero value. If the object is playing, returning this input to zero will stop the player.
Output Pins
Playing	The Playing pin produces a 1 when a wave file is playing, and a 0 otherwise.
handle	The handle pin is located under the Playing pin and is reserved for future expansion.
Static Data
Channel	This is the channel number of the audio output device. This number is assigned by the Platform Configure dialog box in the V+ Run Time System and indicates which audio output device this object is to use for playing the wave file. Since this player requires a stereo device to play on, the channel must be odd-numbered. A run-time error will be generated otherwise. To set the Channel: More about Devices and Channels:
Database Name	The DSN corresponding to the database containing the wave file names. To set the Database Name:
Table Name	The name of the database table containing the wave file names. This name must NOT contain any blank characters. To set the Table Name:
Min Distance	The minimum distance at which the sound can be heard. Units: Meters Range: Any non-negative floating point number.
Max Distance	The maximum distance at which the sound can be heard. Units: Meters Range: Any non-negative floating point number.
Example
The example below demonstrates the use of the 3D HRTF Audio Database Player. The position of the sound is 100 meters to the left of the listener. It is playing a wave file from the VPLusDatabasePlayerWavefiles table within the VPLus Database Player database. The Database ID selected is 5 which maps to the Helicopter 45.wav file. The screenshot below the example is from the Microsoft Access database VPLus Database Player.mdb. It lists all the files that can be played by the this player. The VPLus Database Player.mdb file resides in the C:\Program Files\VPLus\VPLus Help Examples directory.