Volume Control

Overview

Sinks, sources, sink inputs and samples can all have their own volumes. To deal with these, The PulseAudio libray contains a number of functions that ease handling.

The basic volume type in PulseAudio is the pa_volume_t type. Most of the time, applications will use the aggregated pa_cvolume structure that can store the volume of all channels at once.

Volumes commonly span between muted (0%), and normal (100%). It is possible to set volumes to higher than 100%, but clipping might occur.

Calculations

The volumes in PulseAudio are logarithmic in nature and applications shouldn't perform calculations with them directly. Instead, they should be converted to and from either dB or a linear scale:

• dB - pa_sw_volume_from_dB() / pa_sw_volume_to_dB()
• Linear - pa_sw_volume_from_linear() / pa_sw_volume_to_linear()

For simple multiplication, pa_sw_volume_multiply() and pa_sw_cvolume_multiply() can be used.

Calculations can only be reliably performed on software volumes as it is commonly unknown what scale hardware volumes relate to.

The functions described above are only valid when used with software volumes. Hence it is usually a better idea to treat all volume values as opaque with a range from PA_VOLUME_MUTED (0%) to PA_VOLUME_NORM (100%) and to refrain from any calculations with them.

Convenience Functions

To handle the pa_cvolume structure, the PulseAudio library provides a number of convenienc functions:

• pa_cvolume_valid() - Tests if a pa_cvolume structure is valid.
• pa_cvolume_equal() - Tests if two pa_cvolume structures are identical.
• pa_cvolume_channels_equal_to() - Tests if all channels of a pa_cvolume structure have a given volume.
• pa_cvolume_is_muted() - Tests if all channels of a pa_cvolume structure are muted.
• pa_cvolume_is_norm() - Tests if all channels of a pa_cvolume structure are at a normal volume.
• pa_cvolume_set() - Set the first n channels of a pa_cvolume structure to a certain volume.
• pa_cvolume_reset() - Set the first n channels of a pa_cvolume structure to a normal volume.
• pa_cvolume_mute() - Set the first n channels of a pa_cvolume structure to a muted volume.
• pa_cvolume_avg() - Return the average volume of all channels.
• pa_cvolume_snprint() - Pretty print a pa_cvolume structure.