Module libpulse_binding::volume [−] [src]

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 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.

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 volumes in PulseAudio are cubic 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: sw_volume_from_db, sw_volume_to_db
Linear: sw_volume_from_linear, sw_volume_to_linear

For simple multiplication, sw_volume_multiply and CVolume::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

CVolume

A structure encapsulating a per-channel volume

Constants

CVOLUME_PRINT_DB_MAX	The maximum length of strings returned by `CVolume::print_db`, as per the underlying C function. Please note that this value can change with any release without warning and without being considered API or ABI breakage. You should not use this definition anywhere where it might become part of an ABI.
CVOLUME_PRINT_MAX	The maximum length of strings returned by `CVolume::print`, as per the underlying C function. Please note that this value can change with any release without warning and without being considered API or ABI breakage. You should not use this definition anywhere where it might become part of an ABI.
CVOLUME_PRINT_VERBOSE_MAX	The maximum length of strings returned by `CVolume::print_verbose`, as per the underlying C function. Please note that this value can change with any release without warning and without being considered API or ABI breakage. You should not use this definition anywhere where it might become part of an ABI.
DECIBEL_MININFTY	This floor value is used as minus infinity when using `sw_volume_to_db` / `sw_volume_from_db`.
VOLUME_INVALID	Special 'invalid' volume
VOLUME_MAX	Maximum valid volume we can store
VOLUME_MUTED	Muted (minimal valid) volume (0%, -inf dB)
VOLUME_NORM	Normal volume (100%, 0 dB)
VOLUME_PRINT_DB_MAX	The maximum length of strings returned by `print_db`, as per the underlying C function. Please note that this value can change with any release without warning and without being considered API or ABI breakage. You should not use this definition anywhere where it might become part of an ABI.
VOLUME_PRINT_MAX	The maximum length of strings returned by `print`, as per the underlying C function. Please note that this value can change with any release without warning and without being considered API or ABI breakage. You should not use this definition anywhere where it might become part of an ABI.
VOLUME_PRINT_VERBOSE_MAX	The maximum length of strings returned by `print_verbose`, as per the underlying C function. Please note that this value can change with any release without warning and without being considered API or ABI breakage. You should not use this definition anywhere where it might become part of an ABI.

Functions

print	Pretty print a volume
print_db	Pretty print a volume but show dB values.
print_verbose	Pretty print a volume in a verbose way.
sw_volume_divide	Divide two volume specifications, return the result.
sw_volume_from_db	Convert a decibel value to a volume (amplitude, not power). This is only valid for software volumes!
sw_volume_from_linear	Convert a linear factor to a volume. `0.0` and less is muted while `1.0` is `VOLUME_NORM`. This is only valid for software volumes!
sw_volume_multiply	Multiply two volume specifications, return the result. This uses `VOLUME_NORM` as neutral element of multiplication. This is only valid for software volumes!
sw_volume_to_db	Convert a volume to a decibel value (amplitude, not power). This is only valid for software volumes!
sw_volume_to_linear	Convert a volume to a linear factor. This is only valid for software volumes!
volume_clamp	Clamp volume to the permitted range.
volume_is_valid	Check if volume is valid.
volume_ui_max	Recommended maximum volume to show in user facing UIs. Note: UIs should deal gracefully with volumes greater than this value and not cause feedback loops etc. - i.e. if the volume is more than this, the UI should not limit it and push the limited value back to the server.

Type Definitions

Volume	The basic volume type
VolumeDB	Volume expressed in dB