libpulse 0.7

Asyncio interface to the Pulseaudio and Pipewire pulse library.

Overview

libpulse is a Python package based on asyncio, that uses ctypes to interface with the pulse library of the PulseAudio and PipeWire sound servers.

The interface is meant to be complete. That is, all the constants, structures, plain functions and async functions are made available by importing the libpulse module of the libpulse package.

Async functions are those pulse functions that return results through a callback. They are implemented as asyncio coroutines that return the callback results. They have the same name as the corresponding pulse async function.

Non-async pulse functions have their corresponding ctypes foreign functions defined in the libpulse module namespace under the same name as the corresponding pulse function. They may be called directly.

Calling an async function or a plain function is simple:

import asyncio
import libpulse.libpulse as libpulse

async def main():
    async with libpulse.LibPulse('my libpulse') as lp_instance:
        # A plain function.
        server = libpulse.pa_context_get_server(lp_instance.c_context)
        print('server:', server.decode())

        # An async function.
        sink = await lp_instance.pa_context_get_sink_info_by_index(0)
        print('sample_spec rate:', sink.sample_spec.rate)
        print('proplist names:', list(sink.proplist.keys()))

asyncio.run(main())

Another example processing pulse events:

import asyncio
import libpulse.libpulse as libpulse

async def main():
    async with libpulse.LibPulse('my libpulse') as lp_instance:
        await lp_instance.pa_context_subscribe(
                                libpulse.PA_SUBSCRIPTION_MASK_ALL)
        iterator = lp_instance.get_events_iterator()

        async for event in iterator:
            # Start playing some sound to print the events.
            # 'event' is an instance of the PulseEvent class.
            print(event.__dict__)

asyncio.run(main())

The libpulse package also includes the pactl-py command, which is a Python implementation of the pactl command running on Pulseaudio and Pipewire. The output of most pactl-py subcommands can be parsed by Python. When this output is redirected to a file, the file can be imported as a Python module. For example start an interactive Python session and inspect the cards object with all its nested sructures and dereferenced pointers with:

$ pactl-py list cards > cards.py && python -i cards.py

Requirements

Python version 3.8 or more recent.

Documentation

The libpulse documentation is hosted at Read the Docs:

The stable documentation of the last released version.

The latest documentation of the current GitLab development version.

To access the documentation as a pdf document one must click on the icon at the down-right corner of any page. It allows to switch between stable and latest versions and to select the corresponding pdf document.

The documentation describing the C language API of the pulse library is at PulseAudio Documentation.

Installation

Install libpulse with pip:

$ python -m pip install libpulse