[−][src]Module libpulse_binding::volume
Constants and routines for volume handling.
Overview
Sinks, sources, sink inputs, source outputs and samples can all have their own volumes. To deal with these, The PulseAudio library contains a number of functions that ease handling.
The basic volume type in PulseAudio is the Volume
type. Most of the time, applications will
use the aggregated ChannelVolumes
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.
There is no single well-defined meaning attached to the 100% volume for a sink input. In fact,
it depends on the server configuration. With flat volumes enabled, it means the maximum volume
that the sound hardware is capable of, which is usually so high that you absolutely must not set
sink input volume to 100% unless the the user explicitly requests that (note that usually you
shouldn’t set the volume anyway if the user doesn’t explicitly request it, instead, let
PulseAudio decide the volume for the sink input). With flat volumes disabled the sink input
volume is relative to the sink volume, so 100% sink input volume means that the sink input is
played at the current sink volume level. In this case 100% is often a good default volume for a
sink input, although you still should let PulseAudio decide the default volume. It is possible
to figure out whether flat volume mode is in effect for a given sink by calling
::context::introspect::Introspector::get_sink_info_by_name
.
Calculations
The Volume
s in PulseAudio are cubic in nature and applications should not perform
calculations with them directly. Instead, they should be converted to and from either dB or a
linear scale.
The VolumeDB
type represents decibel (dB) converted values, and VolumeLinear
, linear.
The From
trait has been implemented for your convenience, allowing such conversions.
For simple multiplication, Volume::multiply
and ChannelVolumes::sw_multiply
can be used.
It’s often unknown what scale hardware volumes relate to. Don’t use the above functions on sink
and source volumes, unless the sink or source in question has the
::def::sink_flags::DECIBEL_VOLUME
or ::def::source_flags::DECIBEL_VOLUME
flag set. The
conversion functions are rarely needed anyway, most of the time it’s sufficient to treat all
volumes as opaque with a range from VOLUME_MUTED
(0%) to VOLUME_NORM
(100%).
Structs
ChannelVolumes | A structure encapsulating a per-channel volume |
Volume | Software volume expressed as an integer. |
VolumeDB | Software volume expressed in decibels (dBs). |
VolumeLinear | Software volume expressed as linear factor. |
Constants
DECIBEL_MINUS_INFINITY | Minus Infinity. |
VOLUME_INVALID | |
VOLUME_MAX | |
VOLUME_MUTED | |
VOLUME_NORM |