From ab99f4d027e5aa3bceb689144408f6b1372769ee Mon Sep 17 00:00:00 2001
From: Wim Taymans <wtaymans@redhat.com>
Date: Fri, 23 Jul 2021 12:06:53 +0200
Subject: [PATCH] doc: add general audio configuration

---
 doc/pipewire-audio.dox | 129 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 129 insertions(+)
 create mode 100644 doc/pipewire-audio.dox

diff --git a/doc/pipewire-audio.dox b/doc/pipewire-audio.dox
new file mode 100644
index 000000000..54a3d079e
--- /dev/null
+++ b/doc/pipewire-audio.dox
@@ -0,0 +1,129 @@
+/** \page page_audio PipeWire Audio
+
+This document explains how Audio is implemented.
+
+# Use cases
+
+## Audio devices are made available as processing nodes/ports
+
+Applications need to be able to see a port for each stream of an
+Audio device.
+
+## Audio devices can be plugged and unplugged
+
+When devices are plugged and unplugged the associated nodes/ports
+need to be created and removed.
+
+## Audio port in cannonical format
+
+It must be possible to make individual audio channels available
+as a single mono stream with a fixed format and samplerate.
+
+This makes it possible to link any of the audio ports together
+without doing conversions.
+
+## Applications can connect to Audio devices
+
+Applications can create ports that can connect to the Audio ports
+so that data can be provided to or consumed from them.
+
+It should be possible to automatically connect an application to
+a sink/source when it requests this.
+
+## Default Audio sink and sources
+
+It should be possible to mark a source or sink as the default source
+and sink so that applications are routed to them by default.
+
+It should be possible to change the default audio sink/source.
+
+## Application should be able to move between sinks/sources
+
+It should be possible to move an application from one device to
+another dynamically.
+
+## Exclusive access
+
+Application should be able to connect to a device in exclusive mode.
+This allows the application to negotiate a specific format with the
+device such as a compressed format.
+
+Exclusive access means that only one application can access the device
+because mixing is in general not possible when negotiating
+compressed formats.
+
+
+# Design
+
+## SPA
+
+Audio devices are implemented with an SPA Device object.
+\ref spa_device .
+
+This object is then responsable for controlling the SPA Nodes that
+provide the audio ports to interface with the device.
+
+The Nodes operate on the native audio formats supported by the device.
+This incluides the sample rate as well as the number of channels and
+the audio format.
+
+## Audio Adapter
+
+An SPA Node called the adapter is usually used with the SPA device Node
+as the internal node.
+
+The function of the adapter is to convert the device native format to
+the required external format. This can include format or samplerate
+conversion but also channel remixing/remapping.
+
+The audio adapter is also responsable for exposing the audio channels
+as separate mono ports. This is called the DSP setup.
+
+The audio adapter can also be configured in passthrough mode when it
+will not do any conversions but simply pass through the port information
+of the internal Node. This can be used to implement exclusive access.
+
+Setup of the different configurations of the adapter can be done with
+the PortConfig parameter.
+
+## The session manager
+
+The session manager is responsable for creating Nodes and Ports for
+the various audio devices. It will need to wrap them into an audio
+adapter so that the specific configuration of the node can be
+decided by the policy mode.
+
+The session manager should create name and description for the
+devices and nodes.
+
+The session manager is responsable for assigning priorities to the
+Nodes. At least PW_KEY_PRIORITY_SESSION and PW_KEY_PRIORITY_DRIVER
+need to be set.
+
+The session manager might need to work with other services to gain
+exclusive access to the device, like though DBus.
+
+
+# Implementation
+
+## pipewire-media-session (alsa-monitor)
+
+PipeWire media session uses the SPA_NAME_API_ALSA_ENUM_UDEV plugin
+for enumerating the ALSA devices. For each device it does:
+
+- Try to acquire the DBus device reservation object to gain exclusive
+  access to the device.
+- Create an SPA Device instance for the device and monitor this.
+- For each Node created by the device, it creates an adapter with
+  an ALSA PCM node in the context of the PipeWire daemon.
+
+The session manager will also create suitable names and descriptions
+for the Devices and Nodes that it creates as well as assign session
+and driver priorities.
+
+The session manager has the option to add extra properties on the
+Devices and Node that it creates to control their behaviour. This
+is implemented with match rules.
+
+
+*/