docs/5_Component_Documentation/6_pipewire_wireplumber.md

   1 ---
   2 title: PipeWire / WirePlumber
   3 ---
   4
   5 # PipeWire / WirePlumber
   6
   7 ## Overview
   8
   9 AGL uses the PipeWire daemon service to provide audio playback and capture capabilities.
  10 PipeWire is accompanied by a secondary service, WirePlumber (also referred to as the
  11 *session manager*), which provides policy management, device discovery, configuration and more.
  12
  13 Applications can connect to the PipeWire service through its UNIX socket, by using either the
  14 *libpipewire* or *libwireplumber* libraries as a front-end to that socket.
  15
  16 Upstream documentation for these components can be found at the links below:
  17
  18 - [PipeWire documentation](https://docs.pipewire.org/)
  19
  20 - [WirePlumber documentation](https://pipewire.pages.freedesktop.org/wireplumber/)
  21
  22 - [PipeWire Wiki](https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/home)
  23
  24 ## APIs
  25
  26 ### libpipewire
  27
  28 The main entry point for applications to access the audio system is the API offered by
  29 *libpipewire*. The functionality offered by *libpipewire* is vast and it is beyond the
  30 scope of this document to describe it all.
  31
  32 For playback and capture, applications should use *struct pw_stream* and its associated methods.
  33 See [PipeWire: Tutorial - Part 4: Playing a tone](https://docs.pipewire.org/page_tutorial4.html)
  34 for a starting point.
  35
  36 ### GStreamer (Recommended)
  37
  38 For convenience, applications that use GStreamer can use the PipeWire GStreamer elements to
  39 plug the functionality offered by *struct pw_stream* directly in the GStreamer pipeline. These
  40 elements are called *pipewiresrc* and *pipewiresink*
  41
  42 Example:
  43
  44 ```shell
  45 > gst-launch-1.0 audiotestsrc ! pipewiresink
  46 ```
  47
  48 Through these elements, it is possible to specify the application role by setting it in the
  49 *stream-properties* property of the element, as shown below:
  50
  51 ```shell
  52 > gst-launch-1.0 audiotestsrc ! pipewiresink stream-properties="p,media.role=Multimedia""
  53 ```
  54
  55 or, in the C API:
  56
  57 ```c
  58 gst_util_set_object_arg (sink, "stream-properties", "p,media.role=Multimedia");
  59 ```
  60
  61 Of course, it is also possible to use *alsasink* and *alsasrc* and route audio through the
  62 virtual ALSA device that is mentioned below. This is also the default behavior of *playbin*
  63 and similar auto-plugging elements, because the PipeWire GStreamer elements are not autoplugged
  64 (this may change in a future version).
  65
  66 ### ALSA
  67
  68 PipeWire offers a virtual ALSA device (called *pipewire*) that redirects audio to PipeWire
  69 through an ALSA PCM plugin. This device is the default one, so unless you explicitly specify
  70 a device in your ALSA client application, audio will go through PipeWire instead.
  71
  72 Example:
  73
  74 ```shell
  75 > aplay sound.wav  # the default device is 'pipewire'
  76 > aplay -D pipewire sound.wav
  77 ```
  78
  79 In order to specify the application role while using the ALSA compatibility device, pass the role
  80 as a device parameter like this:
  81
  82 ```shell
  83 > aplay -D pipewire:ROLE=Navigation turnleft.wav
  84 ```
  85
  86 ### Audiomixer service
  87
  88 See the separate [agl-service-audiomixer](https://git.automotivelinux.org/apps/agl-service-audiomixer/about/) documentation.
  89
  90 ### libwireplumber
  91
  92 The WirePlumber library provides API that wraps libpipewire and makes it easier to work with
  93 when you are writing control applications, such as a volume mixer. The audiomixer service is in
  94 fact implemented using *libwireplumber*.
  95
  96 WirePlumber also provides support for lua-based scripting. Standalone scripts, executed with the
  97 *wpexec* tool, may be used  as a means to rapidly make use of the API provided by *libwireplumber*
  98
  99 ## Tools
 100
 101 * **wpctl**: allows inspecting the devices, choosing which source & sink are the default ones
 102   and allows volume/mute adjustments to be made on the command line. Try `wpctl status` and
 103   `wpctl help` to get started with it
 104
 105 * **wpexec**: allows running wireplumber lua scripts standalone, which is useful to implement
 106   custom scripts to interact with PipeWire
 107
 108 * **pw-cli**: this is the main tool for interacting with pipewire directly
 109
 110 * **pw-dump**: dumps all the objects in the pipewire graph to a big JSON. The output of this
 111   tool is very useful to include in bug reports. It is also suitable for implementing scripts
 112   that parse information with jq
 113
 114 * **pw-dot** is a useful debug tool that dumps the objects in a dot graph for easy visualization
 115
 116 * **pw-cat / pw-play / pw-record**: This is a set of tools similar to aplay/arecord, for simple
 117   audio operations
 118
 119 * **pw-top**: This is a performance measurement tool that shows realtime timing information
 120   about the audio pipeline. Before running this tool, you will need to uncomment the loading
 121   of "libpipewire-module-profiler" in /etc/pipewire/pipewire.conf and restart pipewire
 122
 123 ## Systemd Integration
 124
 125 The PipeWire service, `pipewire.service`, is activated on demand, via systemd socket activation,
 126 by `pipewire.socket`. The WirePlumber service, `wireplumber.service`, is bound to the pipewire
 127 service and therefore started and stopped together with the PipeWire service.
 128
 129 If you wish to manually stop or restart both services, you can do so by using *systemctl*,
 130 operating on the *.socket* unit:
 131
 132 ```shell
 133 > systemctl restart pipewire.socket
 134 > systemctl stop pipewire.socket
 135 ```
 136
 137 ## Debugging
 138
 139 The PipeWire daemon can be configured to be more verbose by editing
 140 **/etc/pipewire/pipewire.conf** and setting `log.level=n` (n=0-5) in section
 141 `context.properties`.
 142
 143 Similarly, the WirePlumber daemon can be configured to be more verbose by editing
 144 **/etc/wireplumber/wireplumber.conf** and setting `log.level=n` (n=0-5) in section
 145 `context.properties`.
 146
 147 All messages will be available in the systemd journal, inspectable with journalctl.
 148
 149 For applications, at runtime, `PIPEWIRE_DEBUG` can be set to a value between 0 and 5,
 150 with 5 being the most verbose and 0 the least verbose.
 151
 152 For applications that use *libwireplumber* the equivalent environment variable is
 153 `WIREPLUMBER_DEBUG`, which also takes values between 0 and 5.
 154
 155 The default debug level for the daemons is 2, while for applications it's 0
 156 (with few exceptions).
 157
 158 More information is also available on
 159 [WirePlumber's documentation on debug logging](https://pipewire.pages.freedesktop.org/wireplumber/daemon-logging.html)