docs/4_APIs_and_Services/4.6_Audio_Framework/4.6.1_Overview.md

   1 ---
   2 edit_link: ''
   3 title: Overview
   4 origin_url: >-
   5   https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/audio/pipewire.md
   6 ---
   7
   8 <!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/apis_services/master/audio-developer-guides-audio-book.yml -->
   9
  10 # PipeWire Audio System Overview
  11
  12 ## Overview
  13
  14 AGL uses the PipeWire daemon service to provide audio playback and capture
  15 capabilities. PipeWire is accompanied by a secondary service, WirePlumber
  16 (also referred to as the *session manager*), which provides policy management,
  17 device discovery, configuration and more.
  18
  19 Applications can connect to the PipeWire service through its UNIX socket, by
  20 using the *libpipewire* library as a front-end to that socket.
  21
  22 ## Configuration
  23
  24 The Audio System's configuration is mainly done in the session manager.
  25 The session manager is the service that dictates policy, therefore this is
  26 the place to configure options such as device properties, device priorities
  27 and application linking policy.
  28
  29 An extensive listing of configuration options for the session manager,
  30 WirePlumber, is available in the next chapter,
  31 [Session Manager Configuration](./wireplumber_configuration.md)
  32
  33 ### wireplumber-cli
  34
  35 WirePlumber supports runtime configuration of devices, through the
  36 `wireplumber-cli` tool. This tool supports the following sub-commands:
  37
  38 * `wireplumber-cli ls-endpoints`:
  39    This lists all the known audio endpoints, including devices and applications
  40    that are streaming. In front of the devices, there is a `*` (star) character
  41    on the "default" device, i.e. the device that is chosen by default to link
  42    applications to. The volume and mute status of the devices is also shown.
  43 * `wireplumber-cli set-default [id]`:
  44    Changes the default endpoint of a specific category (capture or playback,
  45    determined automatically by the endpoint's type)
  46    and sets it to be the endpoint with the specified `[id]`. The id is the
  47    number shown in front of each endpoint's name in `ls-endpoints`.
  48 * `wireplumber-cli set-volume [id] [vol]`:
  49    Sets the volume of `[id]` to `[vol]`. `[vol]` must be a floating point
  50    number between 0.0 (0%) and 1.0 (100%).
  51 * `wireplumber-cli device-node-props`:
  52    Lists all the properties of the device nodes, useful for writing `.endpoint`
  53    configuration files, as discussed in the _Session Management Configuration_
  54    chapter.
  55
  56 Due to a system limitation, before running this tool on the command line,
  57 you need to export the `XDG_RUNTIME_DIR` environment variable, like this:
  58
  59 ```
  60 export XDG_RUNTIME_DIR=/run/user/1001
  61 ```
  62
  63 ### pipewire.conf
  64
  65 PipeWire also ships with **/etc/pipewire/pipewire.conf**, which can be used to
  66 configure which pipewire modules are being loaded in the PipeWire deamon. You
  67 should normally not need to modify anything there, unless you understand what
  68 you are doing.
  69
  70 ## APIs
  71
  72 ### Native API - libpipewire
  73
  74 The main entry point for applications to access the audio system is the API
  75 offered by *libpipewire*. The functionality offered by *libpipewire* is vast
  76 and it is beyond the scope of this document to describe it all.
  77
  78 For playback and capture, applications should use *struct pw_stream* and its
  79 associated methods. There are usage examples for it in the PipeWire
  80 [source code](https://gitlab.freedesktop.org/pipewire/pipewire).
  81
  82 ### Native API - GStreamer (Recommended)
  83
  84 For convenience, applications that use GStreamer can use the PipeWire GStreamer
  85 elements to plug the functionality offered by *struct pw_stream* directly in
  86 the GStreamer pipeline. These elements are called *pwaudiosrc* and *pwaudiosink*
  87
  88 Example:
  89 ```
  90 gst-launch-1.0 audiotestsrc ! pwaudiosink
  91 ```
  92
  93 Through these elements, it is possible to specify the application role by setting
  94 it in the *stream-properties* property of the element, as shown below:
  95
  96 ```
  97 gst-launch-1.0 audiotestsrc ! pwaudiosink stream-properties=p,media.role=Multimedia
  98 ```
  99
 100 or, in the C API:
 101
 102 ```
 103 gst_util_set_object_arg (sink, "stream-properties", "p,media.role=Multimedia");
 104 ```
 105
 106 When using these GStreamer elements, applications **should** handle the
 107 **GST_MESSAGE_REQUEST_STATE** message on the bus and change their state accordingly.
 108 This message will be sent when the *session manager* requests a change in the state
 109 due to a higher priority stream taking over.
 110
 111 ### ALSA Compatibility
 112
 113 AGL offers a virtual ALSA device that redirects audio to PipeWire
 114 through an ALSA PCM plugin. This device is the default one, so unless you
 115 explicitly specify a device in your ALSA client application, audio will go
 116 through PipeWire instead.
 117
 118 This mode has limitations, however.
 119 * There is no way to specify the role of the application. WirePlumber will
 120 always assume it is a "Multimedia" application
 121 * There is no way for the application to be notified when another stream
 122 takes over. When this happens, the audio clock will simply stop progressing and
 123 the ALSA API will likely block.
 124
 125 ### Audiomixer service
 126
 127 See the separate
 128 [agl-service-audiomixer](https://git.automotivelinux.org/apps/agl-service-audiomixer/about/)
 129 documentation.
 130
 131 ## Runtime mechanics
 132
 133 The PipeWire service is activated on demand, via systemd socket activation.
 134 The WirePlumber service is always started and stopped together with the PipeWire
 135 service.
 136
 137 If you wish to manually start/stop/restart the service, you can do so by using
 138 *systemctl*:
 139 ```
 140 systemctl start/stop/restart pipewire@1001.service
 141 ```
 142
 143 ## Debugging
 144
 145 When something is wrong with the audio setup, it is useful to know how to debug
 146 it...
 147
 148 ### PipeWire & WirePlumber
 149
 150 The PipeWire and WirePlumber daemons can be configured to be more verbose
 151 by editing **/etc/pipewire/environment**
 152
 153 * Set `G_MESSAGES_DEBUG=all` to enable WirePlumber's debug output.
 154 * Set `PIPEWIRE_DEBUG=n` (n=1-5) to enable PipeWire's debug output.
 155
 156 All messages will be available in the systemd journal, inspectable with
 157 journalctl.
 158
 159 `PIPEWIRE_DEBUG` can be set to a value between 1 and 5, with 5 being the
 160 most verbose and 1 the least verbose.
 161
 162 ### AGL applications & services (AppFW)
 163
 164 For AGL applications and services that are installed by the app framework,
 165 you can set the *PIPEWIRE_DEBUG* environment variable in **/etc/afm/unit.env.d/pipewire**.
 166 This will enable the debug messages that are printed by *libpipewire* and will
 167 make them available also in the systemd journal.