3D Sound

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

Generally the struct TS3_VECTOR describes a vector in 3D space:

typedef struct {
    float x;        /* X coordinate in 3D space. */
    float y;        /* Y coordinate in 3D space. */
    float z;        /* Z coordinate in 3D space. */
} TS3_VECTOR;

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

`unsigned int ts3client_systemset3DListenerAttributes(`	`serverConnectionHandlerID`,
	`position`,
	`forward`,
	`up)`;

uint64 serverConnectionHandlerID;
const TS3_VECTOR* position;
const TS3_VECTOR* forward;
const TS3_VECTOR* up;

serverConnectionHandlerID
ID of the server connection handler on which the 3D sound listener attributes are to be set.
position
3D position of the own client.
If passing NULL, the parameter is ignored and the value not updated.
forward
Forward orientation of the listener. The vector must be of unit length and perpendicular to the up vector.
If passing NULL, the parameter is ignored and the value not updated.
up
Upward orientation of the listener. The vector must be of unit length and perpendicular to the forward vector.
If passing NULL, the parameter is ignored and the value not updated.

Returns ERROR_ok on success, otherwise an error code as defined in public_errors.h.

To adjust 3D sound system settings use:

`unsigned int ts3client_systemset3DSettings(`	`serverConnectionHandlerID`,
	`distanceFactor`,
	`rolloffScale)`;

uint64 serverConnectionHandlerID;
float distanceFactor;
float rolloffScale;

serverConnectionHandlerID
ID of the server connection handler on which the 3D sound system settings are to be adjusted.
distanceFactor
Relative distance factor. Default is 1.0 = 1 meter
rolloffScale
Scaling factor for 3D sound rolloff. Defines how fast sound volume will attenuate. As higher the value, as faster the sound is toned with increasing distance.

Returns ERROR_ok on success, otherwise an error code as defined in public_errors.h.

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

`unsigned int ts3client_channelset3DAttributes(`	`serverConnectionHandlerID`,
	`clientID`,
	`position)`;

uint64 serverConnectionHandlerID;
anyID clientID;
const TS3_VECTOR* position;

serverConnectionHandlerID
ID of the server connection handler on which the 3D sound channel attributes are to be adjusted.
clientID
ID of the client to adjust.
position
Vector specifying the position of the given client in 3D space.

Returns ERROR_ok on success, otherwise an error code as defined in public_errors.h.

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

`void onCustom3dRolloffCalculationClientEvent(`	`serverConnectionHandlerID`,
	`clientID`,
	`distance`,
	`volume)`;

uint64 serverConnectionHandlerID;
anyID clientID;
float distance;
float* volume;

serverConnectionHandlerID
ID of the server connection handler on which the volume attenuation calculation occured.
clientID
ID of the client which is being 3D positioned.
distance
The distance between the listener and the client.
volume
The volume which the Client Lib calculated. This can be changed in this 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.

`void onCustom3dRolloffCalculationWaveEvent(`	`serverConnectionHandlerID`,
	`waveHandle`,
	`distance`,
	`volume)`;

uint64 serverConnectionHandlerID;
uint64 waveHandle;
float distance;
float* volume;

serverConnectionHandlerID
ID of the server connection handler on which the volume attenuation calculation occured.
waveHandle
Handle for the playing wave file, returned by ts3client_playWaveFileHandle.
distance
The distance between the listener and the client.
volume
The volume which the Client Lib calculated. This can be changed in this callback.

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

`unsigned int ts3client_set3DWaveAttributes(`	`serverConnectionHandlerID`,
	`waveHandle`,
	`position)`;

uint64 serverConnectionHandlerID;
uint64 waveHandle;
const TS3_VECTOR* position;

serverConnectionHandlerID
ID of the server connection handler on which the volume attenuation calculation occured.
waveHandle
Handle for the playing wave file, returned by ts3client_playWaveFileHandle.
position
The 3D position of the sound.
volume
The volume which the Client Lib calculated. This can be changed in this callback.

Returns ERROR_ok on success, otherwise an error code as defined in public_errors.h.


Playing wave files		Query available servers, channels and clients