1 files changed, 69 insertions, 0 deletions
diff --git a/doc/pulseaudio.dox b/doc/pulseaudio.dox
new file mode 100644
index 0000000..2ac19a9
--- /dev/null
+++ b/doc/pulseaudio.dox
@@ -0,0 +1,69 @@
+/** \page page_pulseaudio PulseAudio Compatibility
+
+# Internals - Mapping Between ALSA and Streams
+
+This explains the mapping between alsa cards and streams and session manager
+objects.
+
+## ALSA Cards
+
+An ALSA card is exposed as a PipeWire device.
+
+## Streams
+
+Each ALSA PCM is opened and a node is created for each PCM stream.
+
+
+# Session Manager
+
+## ALSA UCM
+
+The mapping of the PipeWire object hierarchy to the ALSA object hierarchy is the following:
+
+One PipeWire device is created for every ALSA card.
+
+- For each UCM verb, a node is created for the associated PCM devices.
+- For each UCM verb, an endpoint is created.
+
+In a first step: For each available combination of UCM device and modifier,
+a stream is created. Streams are marked with compatible other streams.
+
+Streams with the same modifier and mutually exclusive devices are grouped
+into one stream and the UCM devices are exposed on the endpoint as destinations.
+
+## ALSA Fallback
+
+Each PCM stream (node) becomes an endpoint. The endpoint references the
+ALSA device ID.
+
+Each endpoint has one stream (for now) called HiFi Playback / HiFi Capture.
+
+More streams can be created depending on the format of the node.
+
+## ALSA Pulse UCM
+
+Using the ALSA backend of PulseAudio we can create the following streams.
+
+## ALSA Pulse Fallback
+
+The pulse ALSA backend will use the mixer controls and some probing to
+create the following nodes and endpoints.
+
+
+# PulseAudio
+
+PulseAudio uses the session manager API to construct cards with profiles
+and sink/source with ports.
+
+If an endpoint references a device, a card object is created for the device.
+
+Each endpoint becomes a sink/source.
+
+Each Stream in the endpoint becomes a profile on the PulseAudio card. Because
+only one profile is selected on the device, only one stream is visible on
+the endpoint. This clashes with the notion that multiple streams can be
+active at the same time but is a PulseAudio limitation.
+
+Each Endpoint destination becomes a port on the sink/source.
+
+*/