PipeWire: a graph based media server that keeps the old audio backends working

A graph of nodes passing file descriptors

PipeWire describes itself as a server and user space API for multimedia pipelines, and the first paragraph of the README says what that means concretely: making sources of video available, whether from capture devices or application provided streams, and multiplexing them with clients; accessing video sources for consumption; and generating graphs for audio and video processing.

The mechanism underneath is the interesting part. Nodes in the graph can be implemented as separate processes communicating with sockets and exchanging multimedia content using fd passing. File descriptor passing is what lets media move between processes without copying through userspace buffers, and it is why PipeWire can afford to be a graph of independent nodes rather than a monolithic server with internal function calls. It is also why screen sharing from a Wayland compositor works through the native API without a virtual display device.

The repository reflects that layering. src/ holds the daemon, spa/ is the plugin and stream processing architecture layer, include/ the public headers, doc/ the documentation, po/ the translations, subprojects/ the bundled dependencies, test/ and template.test.in the suite scaffolding. Three sibling directories named pipewire-alsa/, pipewire-jack/ and pipewire-v4l2/ are the backends that make the compatibility story work, and they exist as separate directories because they genuinely are separate protocol implementations.

GitHub reports topics of audio, daemon, framework, multimedia and video, and 2,158 stars with 192 forks. The repository is not archived and the last push was on 2026-09-28.

This GitHub repository is a mirror, and that changes where you look

The repository's own description field reads Mirror of the PipeWire repository, with a pointer to gitlab.freedesktop.org/pipewire/pipewire. That is the single most useful fact for anyone arriving here, and it explains several other things.

No releases are published on this GitHub repository. GitHub reports a license of NOASSERTION, which is what the API says when it cannot classify a license file automatically, and a COPYING file does exist at the root of the tree. So the license is in the file and the metadata field is simply uninformed; read COPYING rather than trusting the field.

The CI configuration tells the same story from another angle. The tree has .gitlab-ci.yml and a .gitlab/ directory rather than a GitHub Actions workflow directory, which is what you would expect if the pipeline runs on GitLab. The README's own documentation links point at gitlab.freedesktop.org and at pipewire.org, and the introspection GUI it recommends, Helvum, is hosted on GitLab too.

So the practical division of labour is: use this repository to read code and file issues if that is your habit, but take the changelog, the release announcements and the issue tracker from the GitLab project. The three AI assistant instruction files at the root, AGENTS.md, CLAUDE.md and GEMINI.md, are unusual for a C project of this age and are worth a look if you plan to work on the code with an assistant, since they describe conventions the README does not.

Replacing PulseAudio without applications noticing

The README frames compatibility as the primary purpose: the most important purpose of PipeWire is to run your favorite apps. Applications using the native API, such as most compositors including gnome-shell and wayland, work automatically. Most audio applications can use ALSA, JACK or PulseAudio as a backend, and PipeWire provides support for all three.

The PulseAudio path is the one most people care about, because it is the server swap on an existing system. PipeWire can run a PulseAudio compatible replacement server, and applications keep using the regular PulseAudio client libraries. The only thing that changes is the server implementation. The README is direct about one constraint: you cannot use both servers at the same time, and normally the package manager makes them conflict so only one can be installed.

The verification step is worth memorizing, because the failure mode people hit is assuming the swap worked:

pactl info

The output should include a Server Name line reading something like `Server Name: PulseAudio (on PipeWire 0.3.x)`. If it says plain PulseAudio, your audio is still going through the old server. Profile and port changes, volume control and stream redirection work through pavucontrol the same way they did before.

The JACK story has two shapes. In dual mode, JACK applications use the JACK server by default, and `pw-jack` redirects a specific application to PipeWire. If PipeWire has replaced JACK entirely, `pw-jack` has no effect and can be omitted. And ALSA applications, if the alsa module is installed, see a `pipewire:` device in `aplay -L`.

Latency and quantum are the two knobs worth learning

The environment variable list is the real configuration surface, and most of it exists to control latency. The README documents `PIPEWIRE_DEBUG` with a level of none, error, warnings, info, debug or trace, `PIPEWIRE_LOG` to redirect the log to a file, `PIPEWIRE_LOG_SYSTEMD=false` to disable journal logging, and `PIPEWIRE_NODE=<id>` to request a link to a specific node by node.name or object.serial.

The two that change behavior rather than diagnostics are worth reading closely:

PIPEWIRE_LATENCY=128/48000 jack_simple_client

That line requests the JACK client run with a buffer of 128 samples or less. `PIPEWIRE_LATENCY=<num/denom>` configures latency as a fraction, so 10/1000 is 10ms, and it is usually expressed as a fraction of the samplerate, like 256/48000, which the README explains as 256 samples at 48KHz for a latency of 5.33ms. The README also notes this variable does not attempt to configure the samplerate. `PIPEWIRE_QUANTUM=<num/denom>` is the stronger version: it forces the graph samplerate to the denominator and forces the given buffer size, and `PIPEWIRE_RATE=<num/denom>` sets a rate for the graph without touching buffer size.

The distinction between latency and quantum is the kind of thing that matters when a client refuses to start or audio crackles. If a JACK application demands a buffer size the graph cannot provide, setting latency alone may not be enough, since quantum is what actually fixes the graph's rate and size together.

Six tools for looking at a graph that is hard to see

Because the system is a graph spread across processes, the tooling is the practical entry point. The README names them in order of complexity.

`pw-dump` dumps daemon state as JSON, which is the one to reach for when you need the properties and parameters of individual objects, because it is machine readable and diffable. `pw-mon` dumps and monitors state in a human readable form. `pw-top` monitors real-time status and answers the two questions you have when audio misbehaves: which clients are running and how much DSP they use. `pw-dot` can dump a graph of the pipeline, so you can render the actual topology rather than infer it.

`pw-cli` is the more complicated one, used interactively or to run single commands, and the README's example asks the server for its information:

$ pw-cli info 0

For a graphical view the README points at Helvum, and it also mentions the JACK tools such as Carla, catia and qjackctl, with an important caveat: through the JACK tools you will not see all features like the video ports. If you are debugging video, use Helvum or pw-dot rather than catia.

For playing and recording audio and midi, `pw-cat` is the tool, with `pw-play` and `pw-record` as convenience aliases:

$ pw-play /home/wim/data/01. Firepower.wav

Video has its own path through GStreamer, where PipeWire provides two elements named `pipewiresrc` and `pipewiresink`, used like `$ gst-launch-1.0 pipewiresrc ! videoconvert ! autovideosink`. A `gst-device-monitor-1.0` run shows PipeWire devices, which is how applications such as cheese end up using the PipeWire video source automatically.

Installation advice that amounts to use your package manager

The README is unusually firm about this: the preferred way to install PipeWire is with your distribution package system, because that ensures it is integrated into the rest of your system for the best experience. If you want to build and install it yourself, the README sends you to INSTALL.md.

That is not a brush-off. PipeWire's compatibility depends on ALSA configuration, on PulseAudio client library versions, on GStreamer plugins and on modules being present in the right places, and most of that is distribution packaging decisions rather than upstream code. The three backend directories in the tree and the separate INSTALL.md file are the visible cost of a project whose real integration surface is wider than its own source tree.

The build system is Meson, with meson.build and meson_options.txt at the root alongside a Makefile.in and autogen.sh for compatibility. There is a Dockerfile, a .codespell-ignore file, which tells you the project runs a spell checker and keeps an exception list, and CODE_OF_CONDUCT.md plus a NEWS file. The homepage GitHub reports is pipewire.org.

For anyone evaluating this project, the honest summary is that you are not choosing a library, you are choosing a Linux audio stack. If you build a distribution or an appliance and need a different outcome from what your distribution ships, that is the case this project is written for. Otherwise the package manager has already made the decision for you, and the tools above are what you need when it is wrong.

Editorial conclusion

PipeWire's design bet is that compatibility is cheaper than migration, and the README backs that bet by shipping ALSA, JACK and PulseAudio front ends alongside its native API instead of asking applications to change. For most desktop Linux audio that means the swap is invisible, verified by the Server Name line pactl info prints. The parts worth understanding before you touch it are the latency and quantum environment variables, because they are what actually change the graph's behavior, and pw-cli and pw-top for when something is wrong, since a graph-based server is hard to debug without introspection. Note that this repository is a mirror: the project's own description points at gitlab.freedesktop.org as the home, no releases are published here, and the license field GitHub reports is NOASSERTION even though a COPYING file sits at the root, so read the license from the file and follow the changelog on the GitLab side. If you are troubleshooting rather than deploying, pactl info and pw-dump tell you which server is actually in front of you, which resolves most of the confusion people have with this project.

Frequently asked questions

Official sources

1. Issues
2. PipeWire/pipewire on GitHub
3. Project website
4. README