PipeWire Library

There are two main components that make up the PipeWire library:

1. An implementation of a graph based media processing engine.
2. An asynchronous IPC mechanism to manipulate and introspect a graph in another process.

There is usually a daemon that implements the global graph and clients that operate on this graph.

The IPC mechanism in PipeWire is inspired by Wayland in that it follows the same design principles of objects and methods/events along with how this API is presented to the user.

PipeWire has a plugin architecture that allows new features to be added (or removed) by the user. Plugins can hook into many aspects of PipeWire and change the behaviour or number of features dynamically.

Principles

The PipeWire API is an object oriented asynchronous protocol. All requests and replies are method invocations on some object.

Objects are identified with a unique ID. Each object implements an interface and requests result in invocations of methods on the interface.

The protocol is message based. A message sent by a client to the server is called a method. A message from the server to the client is called an event. Unlike Wayland, these messages are not (yet) described in an external protocol file but implemented directly in a protocol plugin. Protocol plugins can be added to add new objects or even protocols when required.

Messages are encoded with SPA POD, which make it possible to encode complex objects with right types.

Events from the server can be a reply to a method or can be emitted when the server state changes.

Upon connecting to a server, it will broadcast its state. Clients should listen for these state changes and cache them. There is no need (or mechanism) to query the state of the server.

The server also has a registry object that, when listening to, will broadcast the presence of global objects and any changes in their state.

State about objects can be obtained by binding to them and listening for state changes.

Versioning

All interfaces have a version number. The maximum supported version number of an interface is advertized in the registry global event.

A client asks for a specific version of an interface when it binds to them. It is the task of the server to adapt to the version of the client.

Interfaces increase their version number when new methods or events are added. Methods or events should never be removed or changed for simplicity.

Proxies and Resources

When a client connects to a PipeWire daemon, a new struct pw_proxy object is created with ID 0. The struct pw_core interface is assigned to the proxy.

On the server side there is an equivalent struct pw_resource with ID 0. Whenever the client sends a message on the proxy (by calling a method on the interface of the proxy) it will transparently result in a callback on the resource with the same ID.

Likewise if the server sends a message (an event) on a resource, it will result in an event on the client proxy with the same ID.

PipeWire will notify a client when a resource ID (and thus also proxy ID) becomes unused. The client is responsible for destroying the proxy when it no longer wants to use it.

Interfaces

struct pw_loop

An abstraction for a poll(2) loop. It is usually part of one of:

• struct pw_main_loop: A helper that can run and stop a pw_loop.
• struct pw_thread_loop: A helper that can run and stop a pw_loop in a different thread. It also has some helper functions for various thread related synchronization issues.
• struct pw_data_loop: A helper that can run and stop a pw_loop in a real-time thread along with some useful helper functions.

struct pw_context

The main context for PipeWire resources. It keeps track of the mainloop, loaded modules, the processing graph and proxies to remote PipeWire instances.

An application has to select an implementation of a struct pw_loop when creating a context.

The context has methods to create the various objects you can use to build a server or client application.

struct pw_core

A proxy to a remote PipeWire instance. This is used to send messages to a remote PipeWire daemon and to receive events from it.

A core proxy can be used to receive errors from the remote daemon or to perform a roundtrip message to flush out pending requests.

Other core methods and events are used internally for the object life cycle management.

struct pw_registry

A proxy to a PipeWire registry object. It emits events about the available objects on the server and can be used to bind to those objects in order to call methods or receive events from them.

struct pw_module

A proxy to a loadable module. Modules implement functionality such as provide new objects or policy.

struct pw_factory

A proxy to an object that can create other objects.

struct pw_device

A proxy to a device object. Device objects model a physical hardware or software device in the system and can create other objects such as nodes or other devices.

struct pw_node

A Proxy to a processing node in the graph. Nodes can have input and output ports and the ports can be linked together to form a graph.

struct pw_port

A Proxy to an input or output port of a node. They can be linked together to form a processing graph.

struct pw_link

A proxy to a link between in output and input port. A link negotiates a format and buffers between ports. A port can be linked to many other ports and PipeWire will manage mixing and duplicating the buffers.

High Level Helper Objects

Some high level objects are implemented to make it easier to interface with a PipeWire graph.

struct pw_filter

A struct pw_filter allows you implement a processing filter that can be added to a PipeWire graph. It is comparable to a JACK client.

struct pw_stream

A struct pw_stream makes it easy to implement a playback or capture client for the graph. It takes care of format conversion and buffer sizes. It is comparable to Core Audio AudioQueue or a PulseAudio stream.

Security

With the default native protocol, clients connect to PipeWire using a named socket. This results in a client socket that is used to send messages.

For sandboxed clients, it is possible to get the client socket via other ways, like using the portal. In that case, a portal will do the connection for the client and then hands the connection socket to the client.

All objects in PipeWire have per client permission bits, currently READ, WRITE, EXECUTE and METADATA. A client can not see an object unless it has READ permissions. Similarly, a client can only execute methods on an object when the EXECUTE bit is set and to modify the state of an object, the client needs WRITE permissions.

A client (the portal after it makes a connection) can drop permissions on an object. Once dropped, it can never reacquire the permission.

Clients with WRITE/EXECUTE permissions on another client can add and remove permissions for the client at will.

Clients with MODIFY permissions on another object can set or remove metadata on that object.

Clients that need permissions assigned to them can be started in blocked mode and resume when permissions are assigned to them by a session manager or portal, for example.

PipeWire uses memfd (memfd_create(2)) or DMA-BUF for sharing media and data between clients. Clients can thus not look at other clients data unless they can see the objects and connect to them.

Implementation

PipeWire also exposes an API to implement the server side objects in a graph.

Error Reporting

Functions return either NULL with errno set or a negative int error code when an error occurs. Error codes are used from the SPA plugin library on which PipeWire is built.

Some functions might return asynchronously. The error code for such functions is positive and SPA_RESULT_IS_ASYNC() will return true. SPA_RESULT_ASYNC_SEQ() can be used to get the unique sequence number associated with the async operation.

The object returning the async result code will have some way to signal the completion of the async operation (with, for example, a callback). The sequence number can be used to see which operation completed.