PipeWire  0.3.49
Related Pages
Here is a list of all related documentation pages:
[detail level 123]
 OverviewPipeWire is a new low-level multimedia framework designed from scratch that aims to provide
 PipeWire Design

Internals

 DesignA short overview of PipeWire's design
 AudioThis document explains how Audio is implemented
 Access ControlThis document explains how access control is designed and implemented
 Portal Access ControlThis document explains how clients from the portal are handled
 MIDI SupportThis document explains how MIDI is implemented
 Objects DesignThis document is a design reference on the various objects that exist in the PipeWire media and session management graphs, explaining what these objects are, how they are meant to be used and how they relate to other kinds of objects and concepts that exist in subsystems or other libraries
 PipeWire LibraryThere are 2 main components that make up the PipeWire library:
 DMA-BUF sharingPipeWire supports sharing Direct Memory Access buffers (DMA-BUFs) between clients via the SPA_DATA_DmaBuf data type
 PipeWire DaemonThe PipeWire daemon is the central process that manages data exchange between devices and clients
 PipeWire ToolsManual pages:
 pipewire
pipewire
########

-------------------------
The PipeWire media server
-------------------------

:Manual section: 1
:Manual group: General Commands Manual

SYNOPSIS
========

| **pipewire** [*options*]

DESCRIPTION
===========

PipeWire is a service that facilitates sharing of multimedia content
between devices and applications.

The **pipewire** daemon reads a config file that is further documented in
``pipewire.conf(5)`` manual page.

OPTIONS
=======

-h | --help
  Show help.

-v | --verbose
  Increase the verbosity by one level. This option may be specified multiple
  times.

--version
  Show version information.

-c | --config=FILE
  Load the given config file (Default: pipewire.conf).

AUTHORS
=======

The PipeWire Developers <@PACKAGE_BUGREPORT@>;
PipeWire is available from @PACKAGE_URL@

SEE ALSO
========

``pw-mon(1)``,
``pw-cat(1)``,
``pw-cli(1)``,
 pipewire-pulse
pipewire-pulse
##############

-----------------------------------
The PipeWire PulseAudio replacement
-----------------------------------

:Manual section: 1
:Manual group: General Commands Manual

SYNOPSIS
========

| **pipewire-pulse** [*options*]

DESCRIPTION
===========

**pipewire-pulse** starts a PulseAudio-compatible daemon that integrates with
the PipeWire media server. This daemon is a drop-in replacement for the
PulseAudio daemon.

OPTIONS
=======

-h | --help
  Show help.

-v | --verbose
  Increase the verbosity by one level. This option may be specified multiple
  times.

--version
  Show version information.

-c | --config=FILE
  Load the given config file (Default: pipewire-pulse.conf).

AUTHORS
=======

The PipeWire Developers <@PACKAGE_BUGREPORT@>;
PipeWire is available from @PACKAGE_URL@

SEE ALSO
========

``pipewire(1)``
 pipewire.conf
pipewire.conf
#############

--------------------------------------
The PipeWire server configuration file
--------------------------------------

:Manual section: 5
:Manual group: File Formats Manual

.. _synopsis:

SYNOPSIS
========

*$XDG_CONFIG_HOME/pipewire/pipewire.conf*

*@PIPEWIRE_CONFIG_DIR@/pipewire.conf*

*@PIPEWIRE_CONFDATADIR@/pipewire.conf*

*@PIPEWIRE_CONFDATADIR@/pipewire.conf.d/*

*@PIPEWIRE_CONFIG_DIR@/pipewire.conf.d/*

*$XDG_CONFIG_HOME/pipewire/pipewire.conf.d/*

DESCRIPTION
===========

PipeWire is a service that facilitates sharing of multimedia content
between devices and applications.

On startup, the daemon reads a main configuration file to configure
itself. It executes a series of commands listed in the config
file.

The config files are loaded in the order listed in the SYNOPSIS_.
The environment variables ``PIPEWIRE_CONFIG_DIR``, ``PIPEWIRE_CONFIG_PREFIX``
and ``PIPEWIRE_CONFIG_NAME`` can be used to specify an alternative config
directory, subdirectory and file respectively.

Next to the configuration file can be a directory with the same name as
the file with a ``.d/`` suffix. All directories in the SYNOPSIS_ directory
search paths are traversed in the listed order and the contents of the
``*.conf`` files inside them are appended to the main configuration file
as overrides. Object sections are merged and array sections are appended.


CONFIGURATION FILE FORMAT
=========================

The configuration file format is grouped into sections. A section
is either a dictionary, {}, or an array, []. Dictionary and array
entries are separated by whitespace and may be simple value
assignment, an array or a dictionary. For example:

name = value # simple assignment

name = { key1 = value1 key2 = value2 } # a dictionary with two
entries

name = [ value1 value2 ] # an array with two entries

name = [ { k = v1 } { k = v2 } ] # an array of dictionaries


The configuration files can be expressed in full JSON syntax but for ease
of use, a relaxed format may be used where:

 * ``:`` to delimit keys and values can be substuted by ``=`` or a space.
 * ``"`` around keys and string can be omited as long as no special characters
         are used in the strings.
 * ``,`` to separate objects can be replaced with a whitespace character.
 * ``#`` can be used to start a comment until the line end


CONFIGURATION FILE SECTIONS
===========================

context.properties
  Dictionary. These properties configure the PipeWire instance.

context.spa-libs
  Dictionary. Maps plugin features with globs to a spa library.

context.modules
  Array of dictionaries. Each entry in the array is a dictionary with the *name* of the module to load,
  including optional *args* and *flags*. Most modules support being loaded
  multiple times.

context.objects
  Array of dictionaries. Each entry in the array is a dictionary containing the *factory* to create an
  object from and optional extra arguments specific to that factory.

context.exec
  Array of dictionaries. Each entry in the array is dictionary containing the *path* of a program to
  execute on startup and optional *args*.

  This array used to contain an entry to start the session manager but this mode
  of operation has since been demoted to development aid. Avoid starting a
  session manager in this way in production environment.

AUTHORS
=======

The PipeWire Developers <@PACKAGE_BUGREPORT@>; PipeWire is available from @PACKAGE_URL@

SEE ALSO
========

``pipewire(1)``,
``pw-mon(1)``,
 pw-cat
pw-cat
######

-----------------------------------
Play and record media with PipeWire
-----------------------------------

:Manual section: 1
:Manual group: General Commands Manual

SYNOPSIS
========

| **pw-cat** [*options*] [*FILE*]
| **pw-play** [*options*] [*FILE*]
| **pw-record** [*options*] [*FILE*]
| **pw-midiplay** [*options*] [*FILE*]
| **pw-midirecord** [*options*] [*FILE*]

DESCRIPTION
===========

**pw-cat** is a simple tool for playing back or
capturing raw or encoded media files on a PipeWire
server. It understands all audio file formats supported by
``libsndfile``.

OPTIONS
=======

-h | --help
  Show help.

--version
  Show version information.

-v | --verbose
  Verbose operation.

-R | --remote=NAME
  The name the *remote* instance to connect to. If left unspecified,
  a connection is made to the default PipeWire instance.

-p | --playback
  Playback mode. Read data from the specified file, and play it back. If the tool
  is called under the name **pw-play** or **pw-midiplay** this is the default.

-r | --record
  Recording mode. Capture data and write it to the specified file. If the tool is
  called under the name **pw-record** or **pw-midirecord** this is the default.

-m | --midi
  MIDI mode. *FILE* is a MIDI file. If the tool is called under the name
  **pw-midiplay** or **pw-midirecord** this is the default.

--media-type=VALUE
  Set the media type property (default Audio/Midi depending on mode).
  The media type is used by the session manager to select a suitable target
  to link to.

--media-category=VALUE
  Set the media category property (default Playback/Capture depending on mode).
  The media type is used by the session manager to select a suitable target
  to link to.

--media-role=VALUE
  Set the media role property (default Music).
  The media type is used by the session manager to select a suitable target
  to link to.

--target=VALUE
  Set a node target (default auto). The value can be:

  auto
    Automatically select (Default)

  0
    Don't try to link this node

  <id>
    The id of a target node

--latency=VALUE[*units*]
  Set the node latency (default 100ms)

  The latency determines the minimum amount of time it takes
  for a sample to travel from application to device (playback) and
  from device to application (capture).

  The latency determines the size of the buffers that the
  application will be able to fill. Lower latency means smaller
  buffers but higher overhead. Higher latency means larger buffers
  and lower overhead.

  Units can be **s** for seconds, **ms** for milliseconds,
  **us** for microseconds, **ns** for nanoseconds.
  If no units are given, the latency value is samples with the samplerate
  of the file.

--list-targets
  List the available targets for **--target**

-q | --quality=VALUE
  Resampler quality. When the samplerate of the source or
  destination file does not match the samplerate of the server, the
  data will be resampled. Higher quality uses more CPU. Values between 0 and 15 are
  allowed, the default quality is 4.

--rate=VALUE
  The sample rate, default 48000.

--channels=VALUE
  The number of channels, default 2.

--channel-map=VALUE
  The channelmap. Possible values include:
  **mono**, **stereo**, **surround-21**,
  **quad**, **surround-22**, **surround-40**,
  **surround-31**, **surround-41**,
  **surround-50**, **surround-51**,
  **surround-51r**, **surround-70**,
  **surround-71** or a comma separated list of channel names:
  **FL**, **FR**, **FC**, **LFE**,
  **SL**, **SR**, **FLC**, **FRC**,
  **RC**, **RL**, **RR**, **TC**,
  **TFL**, **TFC**, **TFR**, **TRL**,
  **TRC**, **TRR**, **RLC**, **RRC**,
  **FLW**, **FRW**, **LFE2**, **FLH**,
  **FCH**, **FRH**, **TFLC**, **TFRC**,
  **TSL**, **TSR**, **LLFR**, **RLFE**,
  **BC**, **BLC**, **BRC**

--format=VALUE
  The sample format to use. One of:
  **s8**, **s16** (default), **s24**, **s32**,
  **f32**, **f64**.

--volume=VALUE
  The stream volume, default 1.000.

AUTHORS
=======

The PipeWire Developers <@PACKAGE_BUGREPORT@>; PipeWire is available from @PACKAGE_URL@

SEE ALSO
========

``PipeWire(1)``,
``pw-mon(1)``,
 pw-cli
pw-cli
######

-----------------------------------
The PipeWire Command Line Interface
-----------------------------------

:Manual section: 1
:Manual group: General Commands Manual

SYNOPSIS
========

| **pw-cli** [*command*]

DESCRIPTION
===========

Interact with a PipeWire instance.

When a command is given, **pw-cli**
will execute the command and exit

When no command is given, **pw-cli**
starts an interactive session with the default PipeWire instance
*pipewire-0*.

Connections to other, remote instances can be made. The current instance
name is displayed at the prompt. Some commands operate on the current
instance and some on the local instance.

Use the 'help' command to list the available commands.

GENERAL COMMANDS
================

help
  Show a quick help on the commands available.

quit
  Exit from **pw-cli**

MODULE MANAGEMENT
=================

| Modules are loaded and unloaded in the local instance and can add
| functionality or objects to the local instance.

load-module *name* [*arguments...*]
  Load a module specified by its name and arguments. For most
  modules it is OK to be loaded more than once.

  This command returns a module variable that can be used
  to unload the module.

unload-module *module-var*
  Unload a module, specified either by its variable.

OBJECT INTROSPECTION
====================

list-objects
  List the objects of the current instance.

  Objects are listed with their *id*, *type* and *version*.

info *id* | *all*
  Get information about a specific object or *all* objects.

  Requesting info about an object will also notify you of changes.

WORKING WITH REMOTES
====================

connect [*remote-name*]
  Connect to a remote instance and make this the new current
  instance.

  If no remote name is specified, a connection is made to
  the default remote instance, usually *pipewire-0*.

  This command returns a remote var that can be used to disconnect or
  switch remotes.

disconnect [*remote-var*]
  Disconnect from a *remote instance*.

  If no remote name is specified, the current instance is disconnected.

list-remotes
  List all *remote instances*.

switch-remote [*remote-var*]
  Make the specified *remote* the current instance.

  If no remote name is specified, the local instance is made current.

NODE MANAGEMENT
===============

create-node *factory-name* [*properties...*]
  Create a node from a factory in the current instance.

  Properties are key=value pairs separated by whitespace.

  This command returns a *node variable*.

destroy-node *node-var*
  Destroy a node.

export-node *node-id* [*remote-var*]
  Export a node from the local instance to the specified instance.
  When no instance is specified, the node will be exported to the current
  instance.

LINK MANAGEMENT
===============

create-link *node-id* *port-id* *node-id* *port-id* [*properties...*]
  Create a link between 2 nodes and ports.

  Port *ids* can be *-1* to automatically select an available port.

  Properties are key=value pairs separated by whitespace.

  This command returns a *link variable*.

destroy-link *link-var*
  Destroy a link.

EXAMPLES
========

AUTHORS
=======

The PipeWire Developers <@PACKAGE_BUGREPORT@>; PipeWire is available from @PACKAGE_URL@

SEE ALSO
========

``pipewire(1)``,
``pw-mon(1)``,
 pw-dot
pw-dot
######

---------------------------
The PipeWire dot graph dump
---------------------------

:Manual section: 1
:Manual group: General Commands Manual

SYNOPSIS
========

| **pw-dot** [*options*]

DESCRIPTION
===========

Create a .dot file of the PipeWire graph.

The .dot file can then be visualized with a tool like **dotty**
or rendered to a PNG file with ``dot -Tpng pw.dot -o pw.png``.

OPTIONS
=======

-r | --remote=NAME
  The name the remote instance to connect to. If left unspecified,
  a connection is made to the default PipeWire instance.

-h | --help
  Show help.

--version
  Show version information.

-a | --all
  Show all object types.

-s | --smart
  Show linked objects only.

-d | --detail
  Show all object properties.

-o FILE | --output=FILE
  Output file name (Default pw.dot). Use - for stdout.

-L | --lr
  Lay the graph from left to right, instead of dot's default top to bottom.

-9 | --90
  Lay the graph using 90-degree angles in edges.

AUTHORS
=======

The PipeWire Developers <@PACKAGE_BUGREPORT@>; PipeWire is available from @PACKAGE_URL@

SEE ALSO
========

``pipewire(1)``,
``pw-cli(1)``,
``pw-mon(1)``,
 pw-metadata
pw-metadata
###########

---------------------
The PipeWire metadata
---------------------

:Manual section: 1
:Manual group: General Commands Manual

SYNOPSIS
========

| **pw-metadata** [*options*] [*id* [*key* [*value* [*type* ] ] ] ]

DESCRIPTION
===========

Monitor, set and delete metadata on PipeWire objects.

Metadata are key/type/value triplets attached to objects identified
by *id*. The metadata is shared between all applications
binding to the same metadata object. When an object is destroyed, all its
metadata is automatically removed.

When no *value* is given, **pw-metadata** will query and
log the metadata matching the optional arguments *id*
and *key*. Without any arguments, all metadata is displayed.

When *value* is given, **pw-metadata** will set the
metadata for *id* and *key* to *value* and
an optional *type*.

OPTIONS
=======

-r | --remote=NAME
  The name the remote instance to use. If left unspecified,
  a connection is made to the default PipeWire instance.

-h | --help
  Show help.

--version
  Show version information.

-m | --monitor
  Keeps running and log the changes to the metadata.

-d | --delete

  Delete all metadata for *id* or for the
  specified *key* of object *id*

  Without any option, all metadata is removed

AUTHORS
=======

The PipeWire Developers <@PACKAGE_BUGREPORT@>; PipeWire is available from @PACKAGE_URL@

SEE ALSO
========

``pipewire(1)``,
``pw-mon(1)``,
``pw-cli(1)``,
 pw-mididump
pw-mididump
###########

----------------------
The PipeWire MIDI dump
----------------------

:Manual section: 1
:Manual group: General Commands Manual

SYNOPSIS
========

| **pw-mididump** [*options*] [*FILE*]

DESCRIPTION
===========

Dump MIDI messages to stdout.

When a MIDI file is given, the events inside the file are printed.

When no file is given, **pw-mididump** creates a PipeWire
MIDI input stream and will print all MIDI events received on the port to
stdout.

OPTIONS
=======

-r | --remote=NAME
  The name the remote instance to monitor. If left unspecified,
  a connection is made to the default PipeWire instance.

-h | --help
  Show help.

--version
  Show version information.

AUTHORS
=======

The PipeWire Developers <@PACKAGE_BUGREPORT@>; PipeWire is available from @PACKAGE_URL@

SEE ALSO
========

``pipewire(1)``,
``pw-cat(1)``,
 pw-mon
pw-mon
######

--------------------
The PipeWire monitor
--------------------

:Manual section: 1
:Manual group: General Commands Manual

SYNOPSIS
========

| **pw-mon** [*options*]

DESCRIPTION
===========

Monitor objects on the PipeWire instance.

OPTIONS
=======

-r | --remote=NAME
  The name the *remote* instance to monitor. If left unspecified,
  a connection is made to the default PipeWire instance.

-h | --help
  Show help.

--version
  Show version information.

-N | --color=WHEN
  Whether to use color, one of 'never', 'always', or 'auto'. The
  default is 'auto'. **-N** is equivalent to **--color=never**.

AUTHORS
=======

The PipeWire Developers <@PACKAGE_BUGREPORT@>; PipeWire is available from @PACKAGE_URL@

SEE ALSO
========

``pipewire(1)``,
 pw-profiler
pw-profiler
###########

---------------------
The PipeWire profiler
---------------------

:Manual section: 1
:Manual group: General Commands Manual

SYNOPSIS
========

| **pw-profiler** [*options*]

DESCRIPTION
===========

Start profiling a PipeWire instance.

If the server has the profiler module loaded, this program will
connect to it and log the profiler data. Profiler data contains
times and durations when processing nodes and devices started and
completed.

When this program is stopped, a set of **gnuplot** files and a script to generate
SVG files from the .plot files is generated, along with a .html file to
visualize the profiling results in a browser.

OPTIONS
=======

-r | --remote=NAME
  The name the remote instance to monitor. If left unspecified,
  a connection is made to the default PipeWire instance.

-h | --help
  Show help.

--version
  Show version information.

-o | --output=FILE
  Profiler output name (default "profiler.log").

AUTHORS
=======

The PipeWire Developers <@PACKAGE_BUGREPORT@>; PipeWire is available from @PACKAGE_URL@

SEE ALSO
========

``pipewire(1)``,
 pw-top
pw-top
######

---------------------------
The PipeWire process viewer
---------------------------

:Manual section: 1
:Manual group: General Commands Manual

SYNOPSIS
========

| **pw-top** [*options*]

DESCRIPTION
===========

The *pw-top* program provides a dynamic real-time view of the pipewire
node and device statistics.

The columns presented are as follows:

S
  Measurement status.
  ! representing inactive - no connections

  Blank representing active

ID
  The ID of the pipewire node/device, as found in *pw-dump*

QUANT
  Current quantum at which the device/node is polled.
  See https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/FAQ#pipewire-buffering-explained

RATE
  Sample rate used for communicating with this device/node.

WAIT

BUSY

W/Q
  Ratio of WAIT / QUANT.

B/Q
  Ratio of BUSY / QUANT

ERR
  Total of Xruns and Errors

NAME
  Name assigned to the device/node, as found in *pw-dump* node.name

  Names are prefixed by *+* when they are linked to a driver (entry above with no +)


OPTIONS
=======

-h | --help
  Show help.

-r | --remote=NAME
  The name the *remote* instance to monitor. If left unspecified,
  a connection is made to the default PipeWire instance.

--version
  Show version information.


AUTHORS
=======

The PipeWire Developers <@PACKAGE_BUGREPORT@>; PipeWire is available from @PACKAGE_URL@

SEE ALSO
========

``pipewire(1)``,

 pw-jack
pw-jack
#######

----------------------------
Use PipeWire instead of JACK
----------------------------

:Manual section: 1
:Manual group: General Commands Manual

SYNOPSIS
========

| **pw-jack** [*options*] *COMMAND* [*FILE*]

DESCRIPTION
===========

**pw-jack** modifies the ``LD_LIBRARY_PATH`` environment
variable so that applications will load PipeWire's reimplementation
of the JACK client libraries instead of JACK's own
libraries. This results in JACK clients being redirected to
PipeWire.

If PipeWire's reimplementation of the JACK client libraries
has been installed as a system-wide replacement for JACK's
own libraries, then the whole system already behaves in that way,
in which case **pw-jack** has no practical effect.

OPTIONS
=======

-h
  Show help.

-r NAME
  The name of the remote instance to connect to. If left
  unspecified, a connection is made to the default PipeWire
  instance.

-v
  Verbose operation.

EXAMPLES
========

| **pw-jack** sndfile-jackplay /usr/share/sounds/freedesktop/stereo/bell.oga

NOTES
=====

Using PipeWire for audio is currently considered to be
experimental.

AUTHORS
=======

The PipeWire Developers <@PACKAGE_BUGREPORT@>;
PipeWire is available from @PACKAGE_URL@

SEE ALSO
========

``pipewire(1)``,
``jackd(1)``,
 PipeWire Session ManagerThe PipeWire Daemon is primarily a framework that allows devices and applications to exchange data
 PulseAudio compatibility

Internals - Mapping between ALSA and streams

 PipeWire Modules
A PipeWire module is effectively a PipeWire client in an .so file that shares the Context with the loading entity
 PipeWire Module: AccessThe access module performs access checks on clients
 PipeWire Module: Adapter
 PipeWire Module: Client Device
 PipeWire Module: Client Node
 PipeWire Module: Echo CancelThe echo-cancel module performs echo cancellation
 PipeWire Module: Example Sink
 PipeWire Module: Example Source
 PipeWire Module: Fallback SinkFallback sink, which appear dynamically when no other sinks are present
 PipeWire Module: Filter-Chain
 PipeWire Module: Link Factory
 PipeWire Module: Loopback
 PipeWire Module: Metadata
 PipeWire Module: PortalThe portal module performs access control management for clients started inside an XDG portal
 PipeWire Module: Profiler
 PipeWire Module: Protocol Native
 PipeWire Module: Protocol Pulse
 PipeWire Module: Protocol Simple
 PipeWire Module: Pulse Tunnel
 PipeWire Module: RAOP Discover
 PipeWire Module: ROC sinkThe roc-sink module creates a PipeWire sink that sends samples to a preconfigured receiver address
 PipeWire Module: ROC sourceThe roc-source module creates a PipeWire source that receives samples from ROC sender and passes them to the sink it is connected to
 PipeWire Module: RTThe rt module uses the operating system's scheduler to enable realtime scheduling for certain threads to assist with low latency audio processing
 PipeWire Module: Session Manager
 PipeWire Module: X11 BellThe x11-bell module intercept the X11 bell events and uses libcanberra to play a sound
 PipeWire Module: Zeroconf Discover
 TutorialWelcome to the PipeWire tutorial
 Tutorial - Part 1: Getting startedIndex | Tutorial - Part 2: Enumerating objects
 Tutorial - Part 2: Enumerating objectsTutorial - Part 1: Getting started | Index | Tutorial - Part 3: Forcing a roundtrip
 Tutorial - Part 3: Forcing a roundtripTutorial - Part 2: Enumerating objects | Index | Tutorial - Part 4: Playing a tone
 Tutorial - Part 4: Playing a toneTutorial - Part 3: Forcing a roundtrip | Index | Tutorial - Part 5: Capturing video frames
 Tutorial - Part 5: Capturing video framesTutorial - Part 4: Playing a tone | Index | Tutorial - Part 6: Binding objects
 Tutorial - Part 6: Binding objectsTutorial - Part 5: Capturing video frames | Index
 List of example programs
 PipeWire APIThe PipeWire API consists of several parts:
 Client Implementation
 Proxy
 Streams
 Thread Loop
 SPA (Simple Plugin API)SPA (Simple Plugin API) is an extensible API to implement all kinds of plugins
 SPA Design

Conventions

 SPA PluginsSPA plugins are dynamically loadable objects that contain objects and interfaces that can be introspected and used at runtime in any application
 SPA PODPOD (plain old data) is a sort of data container
 SPA Buffers

What is the array of spa_data in spa_buffer?