pulsectl (python-pulse-control)

In PulseAudio, volume is not a single number but a list of numbers (one per channel). In pulsectl, these are represented by PulseVolumeInfo objects.

Key Concepts

• Per-channel values: A list of floats representing volume for each channel (e.g., left, right).
• value_flat: A property on PulseVolumeInfo that provides the average level across all channels.
• Volume Range:
  • 0.0: Muted (PA_VOLUME_MUTED).
  • 1.0: Normal volume (PA_VOLUME_NORM).
  • > 1.0: Software-boosted volume (up to 65536.0). It is recommended to keep values in the 0.0 to 1.0 range and adjust hardware volume instead to avoid quality loss.

Usage Patterns

• Direct channel control: Create a PulseVolumeInfo from a list of channel levels: PulseVolumeInfo([0.15, 0.25]).
• Uniform channel control: Create a PulseVolumeInfo with a single value applied to all channels: PulseVolumeInfo(0.5, n_channels).
• Convenience methods: Use pulse.volume_set_all_chans(object, value) to quickly set the volume of an object to a single numeric value across all channels without manually constructing a PulseVolumeInfo object.

from pulsectl import Pulse, PulseVolumeInfo
import time

with Pulse('volume-example') as pulse:
    sink_input = pulse.sink_input_list()[0]

    # Accessing volume
    volume = sink_input.volume
    print(volume.values)   # list of per-channel values (floats)
    print(volume.value_flat) # average level across channels (float)

    # Setting volume via flat value
    volume.value_flat = 0.3
    pulse.volume_set(sink_input, volume)

    # Setting volume via PulseVolumeInfo
    n_channels = len(volume.values)
    new_volume = PulseVolumeInfo(0.5, n_channels)
    pulse.volume_set(sink_input, new_volume)

    # Most common way for simple tasks:
    pulse.volume_set_all_chans(sink_input, 0.2)

The pulsectl module uses a blocking interface that wraps the libpulse event loop. When you call a method like pulse.mute(), the module runs the libpulse event loop until the operation completes.

Breaking the event loop

If you are using event_listen() and need to perform other Pulse operations, you can raise a pulsectl.PulseLoopStop exception inside your callback. This causes event_listen() to return, allowing you to run subsequent Pulse calls before restarting the listener.

Thread Safety

Because the libpulse event loop cannot be run from different threads simultaneously, you should initialize your client with threading_lock=True (or pass a specific lock instance) to ensure thread-safe access to the event loop.

Async Integration

For asyncio or twisted applications, it is highly recommended to use the pulsectl-asyncio module instead of trying to integrate this blocking module into an async loop.

The Pulse instance provides methods to list various PulseAudio entities. These methods return "Pulse-Something-Info" objects (e.g., PulseSinkInfo, PulseSourceInfo, PulseSinkInputInfo), which are thin wrappers around C structs containing metadata like name, index, mute status, and channel volumes.

• pulse.sink_list(): Returns a list of available output sinks.
• pulse.source_list(): Returns a list of available input sources.
• pulse.sink_input_list(): Returns a list of active audio streams (inputs) currently playing through sinks.
• pulse.card_list(): Returns a list of audio cards.

Metadata such as application names or window information can be accessed via the .proplist attribute on PulseSinkInputInfo objects.

import pulsectl

with pulsectl.Pulse('my-client') as pulse:
    # List sinks
    sinks = pulse.sink_list()
    
    # List active audio inputs (e.g., players)
    inputs = pulse.sink_input_list()
    if inputs:
        print(inputs[0].proplist)  # Access metadata

    # List sources (microphones/monitors)
    sources = pulse.source_list()