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