3D Sound

## 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`;

Parameters

- `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`;

Parameters

- `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`;

Parameters

- `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`;

Parameters

- `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`;

Parameters

- `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`;

Parameters

- `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