pulsectl

library24.12.0pypypi✓ verified 90d ago

Python high-level interface and ctypes-based bindings for PulseAudio (libpulse). Version 24.12.0 provides an object-oriented wrapper for controlling PulseAudio volume, sinks, sources, and more.

communication

pip install pulsectl

github ↗package ↗

INSTALL

IMPORT

SIG · PULSECTL

pulsectl

communicationpythonv24.12.0

Install

1.6s avg

Import

—

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v24.12.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.000s · 18MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.000s · 19MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Pulse

✓ from pulsectl import Pulse

PulseVolumeInfo

✓ from pulsectl import PulseVolumeInfo

Connect to PulseAudio, list sinks, and set volume.

from pulsectl import Pulse with Pulse('my-app') as pulse: sink_list = pulse.sink_list() for sink in sink_list: print(sink.description, sink.volume) # Set volume of first sink if sink_list: pulse.volume_set_all_chans(sink_list[0], 0.5)

Debug

Known issues

breakingin version 24.12.0, the 'Pulse' context manager no longer uses pulseaudio server string; removed deprecated 'connect_to_server' method.

fix

Use Pulse('app-name') with PulseAudio autodetection. Do not pass server string.

affects: >=24.0.0

deprecatedThe 'sink_input_set_volume' method is deprecated; use 'volume_set_all_chans' on sink input objects.

fix

Replace pulse.sink_input_set_volume(index, volume) with pulse.volume_set_all_chans(sink_input, volume).

affects: >=20.0.0

gotchaRunning without a running PulseAudio server or inside a Docker container will raise a PulseError.

fix

Ensure PulseAudio is running (pulseaudio --start) or handle PulseError gracefully.

affects: all

gotchaVolume values are floats between 0.0 and 1.0 (or greater for pa_volume_t range), not percentages or decibels.

fix

Use values in [0.0, 1.0] scale, e.g., 0.5 for 50% volume.

affects: all

Errors

Common errors & fixes

pulsectl.PulseError: Failed to create mainloop: No such file or directory

PulseAudio server not running or socket not accessible.

fix

Start PulseAudio with 'pulseaudio --start' or set PULSE_SERVER environment variable.

AttributeError: module 'pulsectl' has no attribute 'Pulse'

Installed old version (<3.0) or import of wrong module.

fix

Run 'pip install --upgrade pulsectl' and use 'from pulsectl import Pulse'.

pulsectl.PulseError: Connection refused

PulseAudio native protocol socket is not listening (e.g., in container without shared socket).

fix

Forward PulseAudio socket with '-v /run/user/$(id -u)/pulse:/run/user/$(id -u)/pulse' or set PULSE_SERVER=tcp:host:port.

Upgrade

Version history

24.12.0latest on PyPI · released Dec 26, 2024

Audit

Dependencies

typing_extensionsoptionalOptional dependency for type hints in Python <3.11

Agent activity

28 hits · last 30 days

node

Anthropic

OpenAI (training)

Resources

githubhttp://github.com/mk-fg/python-pulse-control ↗

packagehttps://pypi.org/project/pulsectl/ ↗