+++ /dev/null
----
-edit_link: ''
-title: Overview
-origin_url: >-
- https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/audio/pipewire.md
----
-
-<!-- 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 -->
-
-# PipeWire Audio System Overview
-
-## Overview
-
-AGL uses the PipeWire daemon service to provide audio playback and capture
-capabilities. PipeWire is accompanied by a secondary service, WirePlumber
-(also referred to as the *session manager*), which provides policy management,
-device discovery, configuration and more.
-
-Applications can connect to the PipeWire service through its UNIX socket, by
-using the *libpipewire* library as a front-end to that socket.
-
-## Configuration
-
-The Audio System's configuration is mainly done in the session manager.
-The session manager is the service that dictates policy, therefore this is
-the place to configure options such as device properties, device priorities
-and application linking policy.
-
-An extensive listing of configuration options for the session manager,
-WirePlumber, is available in the next chapter,
-[Session Manager Configuration](./wireplumber_configuration.md)
-
-### wireplumber-cli
-
-WirePlumber supports runtime configuration of devices, through the
-`wireplumber-cli` tool. This tool supports the following sub-commands:
-
-* `wireplumber-cli ls-endpoints`:
- This lists all the known audio endpoints, including devices and applications
- that are streaming. In front of the devices, there is a `*` (star) character
- on the "default" device, i.e. the device that is chosen by default to link
- applications to. The volume and mute status of the devices is also shown.
-* `wireplumber-cli set-default [id]`:
- Changes the default endpoint of a specific category (capture or playback,
- determined automatically by the endpoint's type)
- and sets it to be the endpoint with the specified `[id]`. The id is the
- number shown in front of each endpoint's name in `ls-endpoints`.
-* `wireplumber-cli set-volume [id] [vol]`:
- Sets the volume of `[id]` to `[vol]`. `[vol]` must be a floating point
- number between 0.0 (0%) and 1.0 (100%).
-* `wireplumber-cli device-node-props`:
- Lists all the properties of the device nodes, useful for writing `.endpoint`
- configuration files, as discussed in the _Session Management Configuration_
- chapter.
-
-Due to a system limitation, before running this tool on the command line,
-you need to export the `XDG_RUNTIME_DIR` environment variable, like this:
-
-```
-export XDG_RUNTIME_DIR=/run/user/1001
-```
-
-### pipewire.conf
-
-PipeWire also ships with **/etc/pipewire/pipewire.conf**, which can be used to
-configure which pipewire modules are being loaded in the PipeWire deamon. You
-should normally not need to modify anything there, unless you understand what
-you are doing.
-
-## APIs
-
-### Native API - libpipewire
-
-The main entry point for applications to access the audio system is the API
-offered by *libpipewire*. The functionality offered by *libpipewire* is vast
-and it is beyond the scope of this document to describe it all.
-
-For playback and capture, applications should use *struct pw_stream* and its
-associated methods. There are usage examples for it in the PipeWire
-[source code](https://gitlab.freedesktop.org/pipewire/pipewire).
-
-### Native API - GStreamer (Recommended)
-
-For convenience, applications that use GStreamer can use the PipeWire GStreamer
-elements to plug the functionality offered by *struct pw_stream* directly in
-the GStreamer pipeline. These elements are called *pwaudiosrc* and *pwaudiosink*
-
-Example:
-```
-gst-launch-1.0 audiotestsrc ! pwaudiosink
-```
-
-Through these elements, it is possible to specify the application role by setting
-it in the *stream-properties* property of the element, as shown below:
-
-```
-gst-launch-1.0 audiotestsrc ! pwaudiosink stream-properties=p,media.role=Multimedia
-```
-
-or, in the C API:
-
-```
-gst_util_set_object_arg (sink, "stream-properties", "p,media.role=Multimedia");
-```
-
-When using these GStreamer elements, applications **should** handle the
-**GST_MESSAGE_REQUEST_STATE** message on the bus and change their state accordingly.
-This message will be sent when the *session manager* requests a change in the state
-due to a higher priority stream taking over.
-
-### ALSA Compatibility
-
-AGL offers a virtual ALSA device that redirects audio to PipeWire
-through an ALSA PCM plugin. This device is the default one, so unless you
-explicitly specify a device in your ALSA client application, audio will go
-through PipeWire instead.
-
-This mode has limitations, however.
-* There is no way to specify the role of the application. WirePlumber will
-always assume it is a "Multimedia" application
-* There is no way for the application to be notified when another stream
-takes over. When this happens, the audio clock will simply stop progressing and
-the ALSA API will likely block.
-
-### Audiomixer service
-
-See the separate
-[agl-service-audiomixer](https://git.automotivelinux.org/apps/agl-service-audiomixer/about/)
-documentation.
-
-## Runtime mechanics
-
-The PipeWire service is activated on demand, via systemd socket activation.
-The WirePlumber service is always started and stopped together with the PipeWire
-service.
-
-If you wish to manually start/stop/restart the service, you can do so by using
-*systemctl*:
-```
-systemctl start/stop/restart pipewire@1001.service
-```
-
-## Debugging
-
-When something is wrong with the audio setup, it is useful to know how to debug
-it...
-
-### PipeWire & WirePlumber
-
-The PipeWire and WirePlumber daemons can be configured to be more verbose
-by editing **/etc/pipewire/environment**
-
-* Set `G_MESSAGES_DEBUG=all` to enable WirePlumber's debug output.
-* Set `PIPEWIRE_DEBUG=n` (n=1-5) to enable PipeWire's debug output.
-
-All messages will be available in the systemd journal, inspectable with
-journalctl.
-
-`PIPEWIRE_DEBUG` can be set to a value between 1 and 5, with 5 being the
-most verbose and 1 the least verbose.
-
-### AGL applications & services (AppFW)
-
-For AGL applications and services that are installed by the app framework,
-you can set the *PIPEWIRE_DEBUG* environment variable in **/etc/afm/unit.env.d/pipewire**.
-This will enable the debug messages that are printed by *libpipewire* and will
-make them available also in the systemd journal.
Code Review / AGL / documentation.git / blobdiff