docs: Explain PipeWire role, add graphics

doc/dox/media/SoundStack.svg

@@ -0,0 +1,65 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   width="56.56242mm"
+   height="25.159874mm"
+   viewBox="0 0 56.56242 25.159874"
+   version="1.1"
+   id="svg5"
+   inkscape:version="1.2.2 (b0a8486541, 2022-12-01)"
+   sodipodi:docname="SoundStack.svg"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:svg="http://www.w3.org/2000/svg">
+  <sodipodi:namedview
+     id="namedview7"
+     pagecolor="#ffffff"
+     bordercolor="#000000"
+     borderopacity="0.25"
+     inkscape:showpageshadow="2"
+     inkscape:pageopacity="0.0"
+     inkscape:pagecheckerboard="0"
+     inkscape:deskcolor="#d1d1d1"
+     inkscape:document-units="mm"
+     showgrid="false"
+     inkscape:zoom="1.3986392"
+     inkscape:cx="64.348262"
+     inkscape:cy="154.07834"
+     inkscape:window-width="1920"
+     inkscape:window-height="1043"
+     inkscape:window-x="0"
+     inkscape:window-y="0"
+     inkscape:window-maximized="1"
+     inkscape:current-layer="layer1" />
+  <defs
+     id="defs2" />
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1"
+     transform="translate(-19.106369,-77.182167)">
+    <rect
+       style="fill:#000000;stroke-width:0.264583"
+       id="rect61"
+       width="25.727388"
+       height="10.026114"
+       x="19.106369"
+       y="92.315926" />
+    <rect
+       style="fill:#000000;stroke-width:0.264583"
+       id="rect63"
+       width="11.917834"
+       height="5.8643312"
+       x="30.456688"
+       y="81.722298" />
+    <rect
+       style="fill:#000000;stroke-width:0.264583"
+       id="rect65"
+       width="25.538216"
+       height="24.214012"
+       x="50.130573"
+       y="77.182167" />
+  </g>
+</svg>

doc/dox/overview-for-users.md

@@ -24,7 +24,7 @@ they just use the PulseAudio API provided by PipeWire. Therefore, PulseAudio too
 
 ## PipeWire overview
 
-Normally, a system with PipeWire also runs WirePlumber.
+Normally, a system with PipeWire also runs **WirePlumber.**
 
 **PipeWire** only *provides* the functionality for transporting and transforming audio and video. It is *used* by a session manager.
 
@@ -60,7 +60,7 @@ Some specific properties:
 
 Relationships between different object types (`type` property):
 
-![Object type relationship](pipewire-object-types-relationship.drawio.png)
+![Object type relationship](pipewire-object-types-relationship.drawio.svg)
 
 ```mermaid
 flowchart LR

doc/dox/overview.dox

@@ -1,5 +1,38 @@
 /** \page page_overview Overview
 
+# The role of PipeWire
+
+Today’s Linux systems use ALSA (Advanced Linux Sound Architecture) to play and record sound and video.
+ALSA is built directly into the Linux Kernel including drivers for sound cards, and applications can use ALSA to play sound.
+However, each sound card can only be used by one application at a time – which is one reason why another layer like PipeWire is required:
+It mixes multiple audio streams together and sends that to ALSA directly.
+
+\image html SoundMixing.drawio.svg
+
+There are a number of popular sound servers for Linux like JACK for low latency or PulseAudio.
+PipeWire is the newest one, combining the advantages of its predecessors.
+
+Applications are programmed to support a certain backend, or sometimes they support more than one.
+PipeWire provides API interfaces that look like e.g. ALSA or PulseAudio, so an application only supporting PulseAudio actually works with PipeWire because it looks like PulseAudio to the application.
+Therefore, tools like `pavucontrol` *also* work for PipeWire!
+
+\image html LinuxSoundStack.drawio.svg
+
+# What do I need?
+
+Normally, a system with PipeWire also runs **WirePlumber.**
+
+While **PipeWire** *provides* the functionality for transporting and transforming audio and video, it does not actively react to events like connecting Bluetooth earbuds.
+This is the task of the session manager which *uses* PipeWire.
+
+There is one PipeWire *server* which is used by a number of PipeWire *clients* (the processes that produce/consume multimedia).
+PipeWire, as well as WirePlumber, run in *userspace,* so interfacing with them with `systemd` (and `journald` etc.)
+happens in *user context* with the `--user` flag, for example
+`systemctl --user status pipewire.service` or `journalctl --user -fu wireplumber.service`.
+
+**WirePlumber** provides [Session Management](https://pipewire.pages.freedesktop.org/wireplumber/design/understanding_session_management.html): It enables new devices when they appear on ALSA, creates and configures nodes,
+create links between nodes to route sound from an application to a consumer, etc.
+
 # Concepts
 
 ## The PipeWire Server
@@ -48,9 +81,9 @@ A recommended pattern that is often used is a single client be a daemon that dea
   It provides another, higher-level API compared to the PipeWire one, and runs Lua scripts that implement the management logic using the said API.
   It ships with default scripts and configuration that handle linking policies as well as monitoring and automatic spawning of ALSA, bluez, libcamera and v4l2 devices.
   The API is available for any process, not only from WirePlumber’s Lua scripts.
- 
-### Node implementation 
- 
+
+### Node implementation
+
 With the nodes which they implement, clients can send multimedia data into the graph or obtain multimedia data from the graph.
 A client can create multiple PipeWire nodes.
 That allows one to create more complex applications;