Playback options

## Playback options

Sound output can be configured using playback options. Currently the output value can be adjusted.

Playback options can be queried:

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

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

Parameters

- `serverConnectionHandlerID`

  ID of the server connection handler for which the playback option is queried.

- `ident`

  Identifier of the parameter to be configured. Possible values are:

  - “volume_modifier”

    Modify the voice volume of other speakers. Value is in decibel, so 0 is no modification, negative values make the signal quieter and values greater than zero boost the signal louder than it is. Be careful with high positive values, as you can really cause bad audio quality due to clipping. The maximum possible Value is 30.

    Zero and all negative values cannot cause clipping and distortion, and are preferred for optimal audio quality. Values greater than zero and less than +6 dB might cause moderate clipping and distortion, but should still be within acceptable bounds. Values greater than +6 dB will cause clipping and distortion that will negatively affect your audio quality. It is advised to choose lower values. Generally we recommend to not allow values higher than 15 db.

  - “volume_factor_wave”

    Adjust the volume of wave files played by `ts3client_playWaveFile` and `ts3client_playWaveFileHandle`. The value is a float defining the volume reduction in decibel. Reasonable values range from “-40.0” (very silent) to “0.0” (loudest).

- `result`

  Address of a variable that receives the playback configuration value as floating-point number.

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

To change playback options, call:

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

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

Parameters

- `serverConnectionHandlerID`

  ID of the server connection handler for which the playback option is queried.

- `ident`

  Identifier of the parameter to be configured. The values are the same as in `ts3client_getPlaybackConfigValueAsFloat` above.

- `value`

  String with the value to set the option to, encoded in UTF-8 format.

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

| Note
Playback options are tied to a playback device, so changing the values only makes sense after a device has been opened.

Example code:

    unsigned int error;
    float value;

    if((error = ts3client_setPlaybackConfigValue(scHandlerID, "volume_modifier", "5.5")) != ERROR_ok) {
        printf("Error setting playback config value: %d\n", error);
        return;
    }

    if((error = ts3client_getPlaybackConfigValueAsFloat(scHandlerID, "volume_modifier", &value)) != ERROR_ok) {
        printf("Error getting playback config value: %d\n", error);
        return;
    }

    printf("Volume modifier playback option: %f\n", value);

In addition to changing the global voice volume modifier of all speakers by changing the “volume_modifier” parameter, voice volume of individual clients can be adjusted with:

`unsigned int ts3client_setClientVolumeModifier(` | serverConnectionHandlerID, |
| clientID, |
| value`)`; |

`uint64 serverConnectionHandlerID`;
`anyID clientID`;
`float value`;

Parameters

- `serverConnectionHandlerID`

  ID of the server connection handler on which the client volume modifier should be adjusted.

- `clientID`

  ID of the client whose volume modifier should be adjusted.

- `value`

  The new client volume modifier value as float.

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

When calculating the volume for individual clients, both the global and client volume modifiers will be taken into account.

Client volume modifiers are valid as long as the specified client is visible. Once the client leaves visibility by joining an unsubscribed channel or disconnecting from the server, the client volume modifier will be lost. When the client enters visibility again, the modifier has to be set again by calling this function.

Example:

    unsigned int error;
    anyID clientID = 123;
    float value = 10.0f;

    if((error = ts3client_setClientVolumeModifier(scHandlerID, clientID, value)) != ERROR_ok) {
        printf("Error setting client volume modifier: %d\n", error);
    	return;
    }

Preprocessor options |  | Accessing the voice buffer