From 26099f4c29d294ae7ba0f3d1bbbeb3a8813bace1 Mon Sep 17 00:00:00 2001
From: Wim Taymans <wtaymans@redhat.com>
Date: Wed, 14 May 2025 11:28:16 +0200
Subject: [PATCH] doc: add doc about Tag params

---
 doc/dox/internals/index.dox |  1 +
 doc/dox/internals/tag,dox   | 68 +++++++++++++++++++++++++++++++++++++
 doc/meson.build             |  1 +
 3 files changed, 70 insertions(+)
 create mode 100644 doc/dox/internals/tag,dox

diff --git a/doc/dox/internals/index.dox b/doc/dox/internals/index.dox
index 84e0ce295..64f548ccc 100644
--- a/doc/dox/internals/index.dox
+++ b/doc/dox/internals/index.dox
@@ -12,6 +12,7 @@
 - \subpage page_dma_buf
 - \subpage page_scheduling
 - \subpage page_latency
+- \subpage page_tag
 - \subpage page_native_protocol
 
 
diff --git a/doc/dox/internals/tag,dox b/doc/dox/internals/tag,dox
new file mode 100644
index 000000000..7adf0cdc4
--- /dev/null
+++ b/doc/dox/internals/tag,dox
@@ -0,0 +1,68 @@
+/** \page page_tag Tag support
+
+This document explains how stream specific metadata is transported in
+the PipeWire graph.
+
+The metadata is a dictionary of string key/value pairs with information
+such as the author, track, copyright, album information etc.
+
+# Use Cases
+
+## A stream/node/port has some metadata
+
+Applications need to be able to query the Tag of a port/node/stream.
+
+Linked Nodes need to be informed of the upstream and downstream tags.
+
+## dynamically update tags
+
+It needs to be possible to dynamically update the tags of a port/node/stream
+and this should inform all linked ports/nodes of the updated tags.
+
+## Aggregate tags upstream and downstream
+
+A node might need to know all the upstream and downstream tags. Each node can
+add or remove metadata in the Tag param.
+
+A mixer node might need to combine the Tags of the two input streams and
+generate a combined tag.
+
+# Concepts
+
+## Port Tags
+
+The fundamental object for implementing metadata reporting in PipeWire is the
+Tag object.
+
+It consists of a direction (input/output) and one or more generic dictionaries
+with string key/value pairs.
+
+The direction of the tag object determines how the object propagates in the graph.
+
+- SPA_DIRECTION_OUTPUT Tag objects move from output ports downstream and contain
+  the metadata from all nodes upstream. An output tag received on an input port
+  should instruct the node to update the output tag on its output ports related
+  to this input port.
+
+- SPA_DIRECTION_INPUT Tag objects move from input ports upstream and contain
+  the metadata from all nodes downstream. An input tag received on an output port
+  should instruct the node to update the input tag on its input ports related
+  to this output port.
+
+PipeWire will automatically propagate Tag objects from ports to all linked ports
+in the graph. Output Tag objects on output ports are propagated to linked input
+ports and input Tag objects on input ports are propagated to linked output ports.
+
+If a port has links with multiple other ports, the Tag objects are merged by
+appending the dictionaties to the Tag param. Intermediate nodes or sinks are allowed
+to take the multiple dictionaries in a Tag and combine them into one dictionary if
+they would like to do so.
+
+This way, Output Tag always describes the aggragated total upstream metadata of
+signal up to the port and Input tag describes the aggregated downstream metadata
+of the signal from the port.
+
+# Tag updates
+
+Tag params on the ports can be updated as needed. This can happen because some upstream or
+downstream Tag changed or when the metadata of a node/port/stream changes.
diff --git a/doc/meson.build b/doc/meson.build
index 2e221fb06..dc90e122b 100644
--- a/doc/meson.build
+++ b/doc/meson.build
@@ -59,6 +59,7 @@ extra_docs = [
   'dox/internals/design.dox',
   'dox/internals/access.dox',
   'dox/internals/latency.dox',
+  'dox/internals/tag.dox',
   'dox/internals/midi.dox',
   'dox/internals/portal.dox',
   'dox/internals/daemon.dox',