pipewire/doc/dox/overview-for-users.md

\page page_overview_for_users Overview for Users

While the \ref page_overview page describes PipeWire on a technical level for programmers, this page is intended for end users working with (and not programming on) PipeWire.

PipeWire

• docs.pipewire.org: PipeWire docs – that’s this page
• pipewire.pages.freedesktop.org: WirePlumber docs – WirePlumber reference
• gitlab.freedesktop.org Wiki with guides and links to other docs
• wiki.archlinux.org: ArchLinux docs with tool list and examples

PipeWire is a multimedia framework for Linux. The Kernel uses ALSA, and applications can either use ALSA directly (but only one application send sound to an ALSA output at the same time), or use a different backend like JACK, PulseAudio, or (the newest) PipeWire. All those backends do not have the single client limitation and provide additional features.

PipeWire uses a powerful graph based approach for routing application freely between producers and consumers.

PipeWire provides a PulseAudio API (and others like JACK), so clients relying on PulseAudio still work, they just use the PulseAudio API provided by PipeWire. Therefore, PulseAudio tools like pavucontrol still work (see PulseAudio section below).

PipeWire overview

Normally, a system with PipeWire also runs WirePlumber.

PipeWire only provides the functionality for transporting and transforming audio and video. It is used by a session manager.

There is one PipeWire server which is used by a number of PipeWire clients (the processes that produce/consume multimedia). PipeWire, as well as WirePlumber, run in userspace, so interfacing with them with systemd (and journald etc.) happens in user context with the --user flag, for example systemctl --user status pipewire.service or journalctl --user -fu wireplumber.service.

WirePlumber provides Session Management: It enables new devices when they appear on ALSA, creates and configures nodes, create links between nodes to route sound from an application to a consumer, etc.

Terminology

For a more technical description, see \ref page_overview.

• Nodes produce and/or consume data, for example a stereo output to a headset (consumes), an audio player (produces), a reverb effect filter (consumes, then produces modified audio), etc.
• Ports are the connectors on nodes where data enters or exits. A stereo output sound card has two input ports typically labeled FL and FR for front left and front right, which may receive data from vlc which has two output ports FL and FR. (Physically, the sound card can have a stereo jack output, for example, but that is not in the scope of PipeWire.)
• Links connect two ports. Audio/Video data only flows when there is a link between ports. Ports can have multiple incoming/outgoing links, so PipeWire can e.g. send the same vlc audio stream to the stereo headset and a bluetooth headset and an audio recorder.
• Devices represent e.g. ALSA PCM sound cards. They have Profiles, and the active profile defines properties like channel setup. For example, a sound card can have a stereo profile where only two ports are exposed, or a surround7.1 profile with 8 ports available.

Nodes have various properties like name/description, a vendor (if available), an ID (changes between restart, therefore use node.name or device.name), etc. Some specific properties:

• media.class describes the type of the node. A sound card (a device in PipeWire) has media class Audio/Device with corresponding Audio/Source input and Audio/Sink output nodes. A process producing audio is Stream/Output/Audio.

Relationships between different object types (type property):

flowchart LR
    C[PipeWire:Interface:Client]
    D[PipeWire:Interface:Device]
    N[PipeWire:Interface:Node]
    P[PipeWire:Interface:Port]
    L[PipeWire:Interface:Link]
	CO[PipeWire:Interface:Core]
	M[PipeWire:Interface:Module]
	SC[PipeWire:Interface:SecurityContext]
	PR[PipeWire:Interface:Profiler]
	PM[PipeWire:Interface:Metadata]
    N -- target.object --> C
    N -- target.object --> D
    L -- input + output port --> P
    L -- input + output node --> N

PipeWire Tools

• List of PipeWire programs

This is just a short selection of tools.

qpwgraph gives a quick visual overview over the current system configuration with nodes and links between them. It also allows creating and deleting links on the fly.

pw-dump dumps the whole configuration (json dump all, nodes etc)

pw-cli allows to query and configure PipeWire, for example setting a sound card profile with pw-cli s Profile CARD_ID '{index: PROFILE_ID, save: true}', or in interactive mode. Important: In interactive mode, do not use quotes around JSON data.

wpctl interfaces with WirePlumber, for example wpctl status shows an ASCII representation of the nodes, sources, sinks, and routing.

WirePlumber

WirePlumber creates links based on defaults and priorities as described in Linking Policy. For example, when an application starts audio playback, it links to the default sound output like the Bluetooth headset. If that output disappears, it dynamically chooses the next suitable output device.

Configuration files and rules

• PipeWire docs: configuration overview

Both PipeWire and WirePlumber have a set of config files for configuring different parts. They use the same format.

Rules in config file can define default outputs for specific nodes (e.g. VLC sound always goes to the 7.1 sound card). ArchLinux: WirePlumber gives a short introduction to using them.

PipeWire server configuration configures the PipeWire instance, defines which modules PipeWire should load, adds device rules, etc.

• Location: pipewire/pipewire.conf
• Docs: pipewire.conf
• Configures: context.exec, context.modules, context.properties, context.spa-libs, device.rules, node.rules

PipeWire client configuration contains configuration for PipeWire and ALSA clients, e.g. if VLC uses the PipeWire or ALSA backend, its runtime behaviour can be modified with this configuration. Example: A stream rule defines to always route vlc sound output to Bluetooth earbuds and pw-play to a stereo headset.

• Location: pipewire/client.conf, for example ~/.config/pipewire/client.conf.d/
• Docs: client.conf and PipeWire object property reference (also contains WirePlumber related options!)
• Configures: alsa.properties, alsa.rules, stream.properties, stream.rules

PulseAudio/JACK configuration contains configuration for PipeWire’s PulseAudio and JACK servers.

• Docs: pipewire-pulse.conf, jack.conf

WirePlumber configuration configures general WirePlumber aspects (should it even bring up ALSA devices or save/restore user settings configured with e.g. pavucontrol) and also ALSA/Bluetooth monitor aspects (choosing a default profile like Stereo or 7.1, setting device priorities that affect default routing, setting device properties, etc.).

• Location: wireplumber.conf, e.g. ~/.config/wireplumber/wireplumber.conf.d/

• Docs: WirePlumber daemon configuration and more like ALSA configuration

• Configures: context, device, linking, wireplumber, monitor (like monitor.alsa.properties, monitor.alsa.rules), node (like node.software-dsp),support, policy

Writing Rules and Examples

Rules can use regular expression when strings start with ~, as explained in PipeWire: Working with rules.

# Goes to ~/.config/wireplumber/wireplumber.conf.d/wireplumber-default-device.conf
# Restart wireplumber.service so it loads the rules
# This sample rule increases the priority of the stereo output on a Raspberry Pi,
# so it is used by default.
monitor.alsa.rules = [
  {
    matches = [
      {
        node.name = "alsa_output.platform-fe00b840.mailbox.stereo-fallback"
      }
    ]
    actions = {
      update-props = {
        priority.driver = 3000
        priority.session = 3000
      }
    }
  }
]

# Goes to ~/.config/pipewire/client.conf.d/default-pw-play-output.conf
# Restart wireplumber.service so it loads the rules
# This sample rule uses a specific sound card for playback with pw-play.
# If it does not exist, WirePlumber takes the next suitable one.
stream.rules = [
  {
    matches = [
      {
        application.name = "pw-play"
      }
    ]
    actions = {
      update-props = {
        target.object = "alsa_output.usb-PreSonus_Audio_AudioBox_USB-01.pro-output-0"
      }
    }
  }
]

Debugging

• Setting WirePlumber log level: https://pipewire.pages.freedesktop.org/wireplumber/daemon/logging.html
• pw-play --target [ID|node.name] myfile.mp3 plays a sound file and tries to use the given target; useful for trying to find out the correct target
• Automatically Link Pipewire Nodes with Wireplumber

PulseAudio API

• Migrating from PulseAudio to PipeWire
• PulseAudio clients and usage for PipeWire

Many PulseAudio tools also work for PipeWire, like:

• pavucontrol (GUI to configure sound cards, select profiles, etc.)
• pactl (CLI configuration tool, e.g. for setting the default audio sink)
• paplay and parecord for playing and recording audio