pulsectl

What it is and what it does

pulsectl is a ctypes-based wrapper around PulseAudio's libpulse C library, exposing mixer-like controls and introspection operations through a blocking, synchronous Python API. It lets you query and manipulate audio devices (sinks, sources, cards), adjust per-channel volume, set default devices, and listen for server state changes—all without submitting audio samples or managing playback directly.

The module represents audio objects as thin wrappers around C structs (e.g., PulseSinkInfo, PulseVolumeInfo) and exposes most operations as methods on a Pulse client instance. Volume is handled as a list of per-channel floats in a 0–65536 range, with 1.0 representing normal level and >1.0 for software boost. For async use cases, the maintainer recommends pulsectl-asyncio instead.

Use it for:

• Build a volume control CLI or GUI tool that adjusts sink/source levels and switches default devices.
• Monitor PulseAudio server events (device additions, removals, property changes) in a synchronous event loop.
• Automate audio routing and profile switching across multiple sound cards and HDMI outputs.
• Integrate PulseAudio control into a larger audio application without managing low-level C bindings.
• Query audio device properties and capabilities (channel maps, profiles, proplist metadata) for diagnostics.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Provides a high-level Python interface to PulseAudio's libpulse library for synchronous control of audio devices, sinks, sources, and volume management.

Yes, if you need synchronous PulseAudio control on Linux and can accept dormant maintenance. The package is stable (MIT licensed, no known vulnerabilities, low install friction), but has not been actively developed for over 1.5 years. Use it for straightforward mixer tasks; for async patterns or active development, evaluate pulsectl-asyncio or direct libpulse bindings instead.

Install

pulsectl on PyPI

pip install pulsectl

uv add pulsectl

poetry add pulsectl

Installing pulsectl

Before you install

Low friction installation with no runtime dependencies. Maintenance is dormant (596 days since last release), though the repository remains active with a recent commit on 2024-12-26 and modest community interest (180 stars).

License in practice

MIT license permits unrestricted use, modification, and distribution with minimal restrictions—suitable for both open-source and proprietary projects.

Quickstart

import pulsectl

with pulsectl.Pulse('my-app') as pulse:
  for sink in pulse.sink_list():
    pulse.volume_change_all_chans(sink, 0.1)

Requires PulseAudio server running and libpulse library installed on the system; Linux/POSIX only.

Verify before relying

• Whether Python 2 support (listed in classifiers) is actively maintained or tested in recent releases.
• Current state of async support via pulsectl-asyncio and whether it is the recommended path for new projects.

Package facts

Evidence: pulsectl-24.12.0-py2.py3-none-any.whl

Keywords: pulseaudio, libpulse, pulse, pa, bindings, sound, audio, ctypes, control, mixer, volume, mute, source, sink

Tags

More Multimedia packages