LibPulse class

class LibPulse(name, server=None, flags=PA_CONTEXT_NOAUTOSPAWN)

name: Application name that will be passed to pa_context_new() upon instantiation.
server and flags: They are passed to pa_context_connect() when called by the async context manager. See the pa_context_connect() pulse documentation.

LibPulse must not be instantiated directly. It is instatiated by the async context manager statement that connects to the PulseAudio or Pipewire server when it is entered, see Connecting to the sound server. It must be instanciated this way:

import asyncio
import libpulse.libpulse as libpulse

async def main():
    async with libpulse.LibPulse('my libpulse') as lp_instance:
        ...

asyncio.run(main())

Class attributes

The pulse async functions are implemented as LibPulse methods that are asyncio coroutines. Those methods are grouped in four lists according to their signature and the signature of their callback:

context_methods:

These methods return an object that should be checked against None or PA_INVALID_INDEX when the callback of the async function sets an index. An example of a method that returns an index is pa_context_load_module().

The pa_context_send_message_to_object() method is special in that it returns a list of two elements. The first one is an int of type pa_operation_state that is PA_OPERATION_DONE in case of success, and the second one is the response as a bytes object.

context_success_methods:

These methods always return PA_OPERATION_DONE or raise LibPulseOperationError upon failure.

context_list_methods:

These methods return a list of objects of the same type.

Method names in this list that end with info_by_name, info_by_index, _info or _formats return a single object instead of a list.

stream_success_methods:

One must refer to the PulseAudio documentation of the function.

The type of the object (or of the objects in a list) returned by these methods is int, float, bytes or PulseStructure.

Instance attributes

c_context

ctypes object corresponding to the pulse pa_context * opaque pointer used as the first parameter of pulse functions whose name starts with pa_context.

It is used when calling a non-async function that needs it. It is not used when waiting on a LibPulse coroutine method when the C pulse async function does, as the LibPulse instance does set it instead. See Pulse methods parameters.

libpulse_tasks

An instance of AsyncioTasks. The Session management section explains how to use this object for the creation of asyncio tasks.

loop

The asyncio loop of this LibPulse instance.

state

The pulse context state. A tuple whose first element is one of the constants of the pa_context_state enum as a string. The second element is one of the constants of the pa_error_code enum as a string.

Public methods

async def get_current_instance()

A static method.

There may be only one LibPulse instance per asyncio loop and one asyncio loop per thread. The libpulse implementation supports multiple threads with one LibPulse instance per thread.

Return the current LibPulse instance, None if the async context manager has exited. Raise LibPulseStateError if the instance is not in the PA_CONTEXT_READY state.

This is used by the LibPulse instance callbacks that are static methods to get the instance they are running on.

get_events_iterator()

Return an Asynchronous Iterator of libpulse events. There can only be one such iterator at any given time.

Use the iterator in an async for loop to loop over PulseEvent instances whose types have been selected by a previous call to the pa_context_subscribe() coroutine. pa_context_subscribe() may be called while the loop on the iterator is running to change the kind of events one is interested in. The async for loop may be terminated by invoking the close() method of the iterator from within the loop or from another asyncio task.

Pulse methods parameters

Pulse methods are those coroutines that are listed in one of the Class attributes and whose return values are also described there.

Some parameters of the Pulse methods are omitted upon invocation:

pa_context * c: The type of the first parameter of the pulse async functions whose name starts with pa_context is pa_context *. This parameter is omitted upon invocation of the corresponding LibPulse method (the Libpulse instance already knows it as one of its attributes named c_context).
pa_*_cb_t cb: One of the parameters of the pulse async functions is the type of the callback. This parameter is omitted upon invocation of the corresponding LibPulse method as the Libpulse instance already knows this type from the signature of the function in the pulse_functions module.
void * userdata: The type of the last parameter of the pulse async functions is void *. The parameter is meant to be used to match the callback invocation with the pulse function that triggered it when the implementation is done in C language. This last parameter is not needed and omitted upon invocation of the corresponding LibPulse method (the callback is implemented as a nested function in the method definition, more details at Callbacks).

For example pa_context_get_server_info() is invoked as:

server_info = await lp_instance.pa_context_get_server_info()

Not implemented

The following pulse async functions are not implemented as LibPulse methods:

pa_signal_new() and pa_signal_set_destroy():: Signals are handled by asyncio and the hook signal support built into the pulse main loop is not needed.

For the following async functions, the callback has to be implemented by the user of the libpulse API:

pa_context_rttime_new()
pa_stream_write()
pa_stream_write_ext_free()