Playback options
Sound output can be configured using playback options. Currently the output value can be adjusted.
Note
Playback options are tied to a playback device, so querying or changing the values only makes sense after a device has been opened.
Available values
The following values are available for the ident parameter:
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. The maximum possible value is 30.
Caution
Be careful with high positive values, as you can really cause bad audio quality due to clipping.
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 negatively affects 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 through
ts3client_playWaveFile()andts3client_playWaveFileHandle(). Reasonable values range from -40 (very quiet) to 0 (loudest).
Query values
Playback options can be queried with:
-
unsigned int ts3client_getPlaybackConfigValueAsFloat(uint64 serverConnectionHandlerID, const char *ident, float *result)
Retrieve floating point playback configuration settings.
- Parameters:
serverConnectionHandlerID – the connection handler to query the playback setting for.
ident – the name of the configuration setting to retrieve. Valid values are volume_modifier and volume_factor_wave
result – address of a variable to receive the current value of the queried setting
- Returns:
An Error code from the Ts3ErrorType enum indicating either success or the failure reason
Setting values
To change playback options, call
-
unsigned int ts3client_setPlaybackConfigValue(uint64 serverConnectionHandlerID, const char *ident, const char *value)
Set playback configuration settings.
- Parameters:
serverConnectionHandlerID – the connection handler to set the playback setting on.
ident – the name of the configuration setting to set. Valid values are volume_modifier and volume_factor_wave
value – the new value to set as an utf8 encoded c string. Appropriate conversion takes place within the client lib.
- Returns:
An Error code from the Ts3ErrorType enum indicating either success or the failure reason
Example
1unsigned int error;
2float value;
3
4if ((error = ts3client_setPlaybackConfigValue(scHandlerID, "volume_modifier", "5.5")) != ERROR_ok) {
5 printf("Error setting playback config value: %04X\n", error);
6 return;
7}
8
9if ((error = ts3client_getPlaybackConfigValueAsFloat(scHandlerID, "volume_modifier", &value)) != ERROR_ok) {
10 printf("Error getting playback config value: %04X\n", error);
11 return;
12}
13
14printf("Volume modifier playback option: %f\n", value);
Adjust individual clients
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(uint64 serverConnectionHandlerID, anyID clientID, float value)
Adjust playback volume of an individual client.
Allows adjustment of single clients in addition to the global playback volume_modifier configuration option. Individual client volume adjustments are temporary and only valid as long as the client is visible. Once the target client leaves to an unsubscribed channel or disconnects from the server, this setting is discarded. If desired, the adjustment needs to be made again after the client reconnects or becomes visible again.
- Parameters:
serverConnectionHandlerID – the connection handler for the server on which the client is located
clientID – the id of the client to adjust the volume for.
value – the volume modifier to apply to the client.
- Returns:
An Error code from the Ts3ErrorType enum indicating either success or the failure reason
Note
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
1unsigned int error;
2anyID clientID = 123;
3float value = 10.0f;
4
5if ((error = ts3client_setClientVolumeModifier(scHandlerID, clientID, value)) != ERROR_ok) {
6 printf("Error setting client volume modifier: %04X\n", error);
7 return;
8}