Preprocessor options

## Preprocessor options

Sound input is preprocessed by the Client Lib before the data is encoded and sent to the TeamSpeak 3 server. The preprocessor is responsible for noise suppression, automatic gain control (AGC), voice activity detection (VAD) and echo canceling.

The preprocessor can be controlled by setting various preprocessor flags. These flags are unique to each server connection.

| Note
Preprocessor flags are tied to a capture device, so changing the values only makes sense after a device has been opened.

Preprocessor flags can be queried using

`unsigned int ts3client_getPreProcessorConfigValue(` | serverConnectionHandlerID, |
| ident, |
| result`)`; |

`anyID serverConnectionHandlerID`;
`const char* ident`;
`char** result`;

Parameters

- `serverConnectionHandlerID`

  The server connection handler ID.

- `ident`

  The proprocessor flag to be queried. The following keys are available:

  - “name”

    Type of the used preprocessor. Currently this returns a constant string “Speex preprocessor”.

  - “denoise”

    Check if noise suppression is enabled. Returns “true” or “false”.

  - “vad”

    Check if Voice Activity Detection is enabled. Returns “true” or “false”.

  - “voiceactivation_level”

    Checks the Voice Activity Detection level in decibel. Returns a string with a numeric value, convert this to an integer.

  - “vad_extrabuffersize”

    Checks Voice Activity Detection extrabuffer size. Returns a string with a numeric value.

  - “agc”

    Check if Automatic Gain Control is enabled. Returns “true” or “false”.

  - “agc_level”

    Checks AGC level. Returns a string with a numeric value.

  - “agc_max_gain”

    Checks AGC max gain. Returns a string with a numeric value.

  - “echo_canceling”

    Check if echo canceling is enabled. Returns “true” or “false”.

  - “is_playback_echo_canceled”

    Query a server connection handler to see if its playback device is being echo canceled.

  - “canceled_amount”

    Returns a number indicating how much echo is being removed by the echo canceler, if enabled for the playback device of the specified server connection handler.

- `result`

  Address of a variable that receives the result as a string encoded in UTF-8 format. If no error occured the returned string must be released using `ts3client_freeMemory`.

Returns `ERROR_ok` on success, otherwise an error code as defined in `public_errors.h`. If an error has occured, the result string is uninitialized and must not be released.

To configure the proprocessor use

`unsigned int ts3client_setPreProcessorConfigValue(` | serverConnectionHandlerID, |
| ident, |
| value`)`; |

`anyID serverConnectionHandlerID`;
`const char* ident`;
`const char* value`;

Parameters

- `serverConnectionHandlerID`

  The server connection handler ID.

- `ident`

  The preprocessor flag to be configure. The following keys can be changed:

  - “denoise”

    Enable or disable noise suppression. Value can be “true” or “false”. Enabled by default.

  - “vad”

    Enable or disable Voice Activity Detection. Value can be “true” or “false”. Enabled by default.

  - “voiceactivation_level”

    Voice Activity Detection level in decibel. Numeric value converted to string. A high voice activation level means you have to speak louder into the microphone in order to start transmitting.

    Reasonable values range from -50 to 50. Default is 0.

    To adjust the VAD level in your client, you can call `ts3client_getPreProcessorInfoValueFloat` with the identifier “decibel_last_period” over a period of time to query the current voice input level.

  - “vad_extrabuffersize”

    Voice Activity Detection extrabuffer size. Numeric value converted to string. Should be “0” to “8”, defaults to “2”. Lower value means faster transmission, higher value means better VAD quality but higher latency.

  - “agc”

    Enable or disable Automatic Gain Control. Value can be “true” or “false”. Enabled by default.

  - “agc_level”

    AGC level. Numeric value converted to string. Default is “16000”.

  - “agc_max_gain”

    AGC max gain. Numeric value converted to string. Default is “30”.

  - “echo_canceling”

    Enable or disable echo canceling. Value can be “true” or “false”. Disabled by default.

  - “set_echo_cancelers_playback”

    Set the playback device of the selected server connection handler to be the device used for echo canceling. Pass an empty string as `value` to `ts3client_setPreProcessorConfigValue`, the playback device is automatically selected by the specified server connection handler.

- `value`

  String value to be set for the given preprocessor identifier. In case of on/off switches, use “true” or “false”.

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

| Note
It is not necessary to change all those values. The default values are reasonable. “voiceactivation_level” is often the only value that needs to be adjusted.

The following function retrieves preprocessor information as a floating-point variable instead of a string:

`unsigned int ts3client_getPreProcessorInfoValueFloat(` | serverConnectionHandlerID, |
| ident, |
| result`)`; |

`anyID serverConnectionHandlerID`;
`const char* ident`;
`float* result`;

Parameters

- `serverConnectionHandlerID`

  The server connection handler ID.

- `ident`

  The proprocessor flag to be queried. Currently the only valid identifier for this function is “decibel_last_period”, which can be used to adjust the VAD level as described above.

- `result`

  Address of a variable that receives the result value as a float.

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

Encoder options |  | Playback options