diff options
Diffstat (limited to 'docs/4_APIs_and_Services/4.6_Audio_Framework/4.6.1_Overview.md')
-rw-r--r-- | docs/4_APIs_and_Services/4.6_Audio_Framework/4.6.1_Overview.md | 167 |
1 files changed, 167 insertions, 0 deletions
diff --git a/docs/4_APIs_and_Services/4.6_Audio_Framework/4.6.1_Overview.md b/docs/4_APIs_and_Services/4.6_Audio_Framework/4.6.1_Overview.md new file mode 100644 index 0000000..672f6da --- /dev/null +++ b/docs/4_APIs_and_Services/4.6_Audio_Framework/4.6.1_Overview.md @@ -0,0 +1,167 @@ +--- +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. |