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.