Pulseaudio Interface

class shc.interfaces.pulse.PulseAudioInterface(pulse_client_name: str = 'smarthomeconnect', pulse_server_socket: Optional[str] = None, auto_reconnect: bool = True, failsafe_start: bool = False)

Interface for controlling a Pulseaudio server and receiving status feedback, esp. sink and source volumes, muting, and level monitoring.

The interface is based on the pulsectl and pulsectl-asyncio python packages, which internally use C function bindings to the Pulseaudio client shared library libpulse. Thus, this library must be installed on the system where SHC is running, for the PulseAudio interface to work. In Debian and Ubuntu, its contained in the libpulse0 package, on Arch Linux the package is named libpulse.

Currently the interface provides connectors for the following tasks:

  • subscribe to, read and change volume of a Pulseaudio sink (output device) or source (input device)

  • subscribe to, read and change mute state of a Pulseaudio sink or source

  • subscribe to and read state (running vs. idle/suspended) of a sink or source

  • monitor audio level of a sink or source

  • subscribe to, read and change the current default sink or default source by name

All of the sink/source connectors are available in two different flavors: They can either be bound to a specific sink/source by name or follow the current default sink/source of the Pulseaudio server. Reading from connectors with a fixed sink/source name will raise an :class`shc.UninitializedError` if no such sink/source is present. They will automatically become active as soon as the sink/source appears. Default sink/source connectors will always publish the new respective value when the default sink/source changes on the server.

Named sink/source connectors:

Default sink/source connectors:

Server state connectors:

All *_volume connectors use the PulseVolumeRaw type for representing the sink’s/source’s volume setting, which contains a float volume setting for each individual channel of the sink/source (e.g. 6 individual values for a 5.1 surround codec). Typically, you’ll want to show and control the volume in more tangible components like master volume, balance, fade (front/rear) and subwoofer balance. For this, the raw volume can be converted into the PulseVolumeComponents type, representing these components as separate fields (but still keeping the information about any further derivations in the individual channels). Thus, a typical application of the volume connectors would look like this:

interface = PulseAudioInterface()
volume_components = shc.Variable(PulseVolumeComponents)\
    .connect(interface.default_sink_volume(), convert=True)  # convert PulseVolumeRaw and PulseVolumeComponents

slider = shc.web.widgets.Slider("Volume").connect(volume_components.field('volume'))
balance_slider = shc.web.widgets.Slider("Balance").connect(volume_components.field('balance'), convert=True)
Parameters:

  • pulse_client_name – Client name reported to the Pulseaudio server when connecting.

  • pulse_server_socket – Address of the Pulseaudio server socket, e.g. “unix:/run/user/1000/pulse/native”. If not specified or None, the system default Pulseaudio instance is used.

  • auto_reconnect – If True (default), the interface tries to reconnect automatically with exponential backoff (1.25 ^ n seconds sleep), when the Pulseaudio event subscription exits unexpectedly, e.g. due to a connection loss with the Pulseaudio server. Otherwise, the complete SHC system is shut down on such errors.

  • failsafe_start – If True and auto_reconnect is True, the interface allows SHC to start up, even if the connection and event subscription with the Pulseaudio server fails in the first try. The connection is retried in background with exponential backoff (see auto_reconnect option). Otherwise (default), the first connection attempt on startup is not retried and will raise an exception from start() on failure, even if auto_reconnect is True.

default_sink_muted() → SinkMuteConnector
default_sink_name() → DefaultNameConnector
default_sink_peak_monitor(frequency: int = 1) → SinkPeakConnector
default_sink_running() → SinkStateConnector
default_sink_volume() → SinkVolumeConnector
default_source_muted() → SourceMuteConnector
default_source_name() → DefaultNameConnector
default_source_peak_monitor(frequency: int = 1) → SourcePeakConnector
default_source_running() → SourceStateConnector
default_source_volume() → SourceVolumeConnector
sink_muted(sink_name: str) → SinkMuteConnector
sink_peak_monitor(sink_name: str, frequency: int = 1) → SinkPeakConnector
sink_running(sink_name: str) → SinkStateConnector
sink_volume(sink_name: str) → SinkVolumeConnector
source_muted(source_name: str) → SourceMuteConnector
source_peak_monitor(source_name: str, frequency: int = 1) → SourcePeakConnector
source_running(source_name: str) → SourceStateConnector
source_volume(source_name: str) → SourceVolumeConnector
namedtuple shc.interfaces.pulse.PulseVolumeRaw(values: list = [], map: list = [])

“raw” representation of the volume setting of a Pulseaudio sink or source with individual channel volume values.

Fields:

  1.  values (list) – List of float values of the volume setting of each individual channel of the sink/source from 0.0 to 1.0

  2.  map (list) – Pulseaudio channel map as a list of integer channel positions, according to the libpulse pa_channel_position enum. E.g. [0] for mono; [1, 2] for normal stereo (left, right); [1, 2, 5, 6, 3, 7] for typical 5.1 surround devices. See https://freedesktop.org/software/pulseaudio/doxygen/channelmap_8h.html for reference. This is required for converting into the component-based PulseVolumeComponents representation.

namedtuple shc.interfaces.pulse.PulseVolumeComponents(volume: RangeFloat1 = 1.0, balance: Balance = 0.0, fade: Balance = 0.0, lfe_balance: Balance = 0.0, normalized_values: list = [], map: list = [])

abstract “component-based” representation of the volume setting of a Pulseaudio sink or source

Fields:

  1.  volume (RangeFloat1) – Master volume of the sink/source. Corresponds to the maximum individual channel volume

  2.  balance (Balance) – left/right balance (-1.0 means 100% left, +1.0 means 100% right).

  3.  fade (Balance) – rear/front balance (-1.0 means 100% rear speakers, +1.0 means 100% front speakers). If no surround channels are present, it is always 0.0.

  4.  lfe_balance (Balance) – subwoofer balance (-1.0 means no subwoofer, +1.0 means only subwoofer). If no subwoofer/LFE channel is present, the value is always 0.0

  5.  normalized_values (list) – The channel values after resetting the master volume, balance, fade and lfe_balance to their default values. This allows to modify these volume components but keep additional individual channel differences intact.

  6.  map (list) – Pulseaudio channel map as a list of integer channel positions, according to the libpulse pa_channel_position enum. E.g. [0] for mono; [1, 2] for normal stereo (left, right); [1, 2, 5, 6, 3, 7] for typical 5.1 surround devices. See https://freedesktop.org/software/pulseaudio/doxygen/channelmap_8h.html for reference. This is required for the conversion functions to/from PulseVolumeRaw.

as_channels() → PulseVolumeRaw

Assemble a PulseVolumeRaw volume object from the component-based representation and the additional derivations in the normalized_values field.

This method uses C function bindings from libpulse to apply the balance, face, etc. to the channel volume values, using the channel map. Thus, the libpulse C shared library is required to use this method.

This method is the SHC default converter from PulseVolumeComponents to PulseVolumeRaw.

classmethod from_channels(raw_volume: PulseVolumeRaw) → PulseVolumeComponents

Convert a PulseVolumeRaw volume object into the component-based representation.

This method uses C function bindings from libpulse to calculate the balance, face, etc. from the channel volume values and the channel map. Thus, the libpulse C shared library is required to use this method.

This method is the SHC default converter from PulseVolumeRaw to PulseVolumeComponents.