3D Sound

TeamSpeak 3 supports 3D sound to assign each speaker a unique position in 3D space. Functions to modify the 3D position, velocity and orientation of own and foreign clients are discussed in this chapter.

Positions are described using TS3_VECTOR

struct TS3_VECTOR

Describes a client position in 3 dimensional space, used for 3D Sound.

Public Members

float x: X co-ordinate in 3D space.

float y: Y co-ordinate in 3D space.

float z: Z co-ordinate in 3D space.

Adjust general settings

To adjust 3D sound system settings use

unsigned int ts3client_systemset3DSettings(uint64 serverConnectionHandlerID, float distanceFactor, float rolloffScale)

Change 3D sound attenuation and distance settings.

Parameters:

serverConnectionHandlerID – the connection handler for which to adjust the settings.
distanceFactor – relative distance factor in meters. Default is 1.0. Use to adjust the distance between two TS3_VECTOR. Distance on x axis in meters = (a.x - b.x) * distanceFactor
rolloffScale – Defines how fast sound volume will attenuate with distance. A higher value will cause sound to be toned down faster with increasing distance.

Returns:

An Error code from the Ts3ErrorType enum indicating either success or the failure reason

Own client position

To set the position, velocity and orientation of the own client in 3D space, call

unsigned int ts3client_systemset3DListenerAttributes(uint64 serverConnectionHandlerID, const TS3_VECTOR *position, const TS3_VECTOR *forward, const TS3_VECTOR *up)

Set position, orientation and velocity of own client in 3D space.

Parameters:

serverConnectionHandlerID – the connection handler for which to set the specified 3D settings.
position – 3D position of own client, pass NULL to ignore.
forward – Forward orientation. Vector must be of unit length and perpendicular to the up vector. Pass NULL to ignore.
up – Upward orientation. Vector must be of unit length and perpendicular to the forward vector. Pass NULL to ignore.

Returns:

An Error code from the Ts3ErrorType enum indicating either success or the failure reason

Other client position

To adjust a clients position and velocity in 3D space, call

unsigned int ts3client_channelset3DAttributes(uint64 serverConnectionHandlerID, anyID clientID, const TS3_VECTOR *position)

Adjusts other clients position in 3D space.

Parameters:

serverConnectionHandlerID – the connection handler for the server on which the client specified by clID is located.
clientID – the client id of the other client we want to adjust the position of.
position – the desired position in 3D space of the other client

Returns:

An Error code from the Ts3ErrorType enum indicating either success or the failure reason

Wave file position

This method is used to 3D position a wave file that was opened previously with ts3client_playWaveFileHandle().

unsigned int ts3client_set3DWaveAttributes(uint64 serverConnectionHandlerID, uint64 waveHandle, const TS3_VECTOR *position)

Set the 3D position of a wave handle as retrieved by ts3client_playWaveFileHandle.

Callbacks

The following callback funtion is called to calculate volume attenuation for distance in 3D positioning of clients.

struct ClientUIFunctions

Defines available callbacks that you can receive.

Set the members of this struct to a function to call when the specific event happens.

Public Members

void (*onCustom3dRolloffCalculationClientEvent)(uint64 serverConnectionHandlerID, anyID clientID, float distance, float *volume)

called to calculate the volume attenuation for the distance in 3D positioning of clients

Param serverConnectionHandlerID:: specifies on which connection the callback was called
Param clientID:: id of the client for which the position is calculated
Param distance:: the distance from own client to the client
Param volume:: the volume calculated by the client lib. Can be modified in the callback.

The following event is called to calculate volume attenuation for distance in 3D positioning of a wave file that was opened previously with ts3client_playWaveFileHandle().

struct ClientUIFunctions

Defines available callbacks that you can receive.

Set the members of this struct to a function to call when the specific event happens.

Public Members

void (*onCustom3dRolloffCalculationWaveEvent)(uint64 serverConnectionHandlerID, uint64 waveHandle, float distance, float *volume)

called to calculate the volume attenuation for the distance in 3D positioning of wave files