PipeWire
0.3.47
|
Overview | PipeWire is a new low-level multimedia framework designed from scratch that aims to provide |
▼PipeWire Design | Internals |
Design | A short overview of PipeWire's design |
Audio | This document explains how Audio is implemented |
Access Control | This document explains how access control is designed and implemented |
Portal Access Control | This document explains how clients from the portal are handled |
MIDI Support | This document explains how MIDI is implemented |
Objects Design | This 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 Library | There are 2 main components that make up the PipeWire library: |
DMA-BUF sharing | PipeWire supports sharing Direct Memory Access buffers (DMA-BUFs) between clients via the SPA_DATA_DmaBuf data type |
PipeWire Daemon | The PipeWire daemon is the central process that manages data exchange between devices and clients |
▼PipeWire Tools | Manual 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)``, |
PipeWire Session Manager | The 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: Access | The access module performs access checks on clients |
PipeWire Module: Adapter | |
PipeWire Module: Client Device | |
PipeWire Module: Client Node | |
PipeWire Module: Echo Cancel | The echo-cancel module performs echo cancellation |
PipeWire Module: Example Sink | |
PipeWire Module: Example Source | |
PipeWire Module: Fallback Sink | Fallback 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: Portal | The 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 sink | The roc-sink module creates a PipeWire sink that sends samples to a preconfigured receiver address |
PipeWire Module: ROC source | The 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: RT | The 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 Bell | The x11-bell module intercept the X11 bell events and uses libcanberra to play a sound |
PipeWire Module: Zeroconf Discover | |
▼Tutorial | Welcome to the PipeWire tutorial |
Tutorial - Part 1: Getting started | Index | Tutorial - Part 2: Enumerating objects |
Tutorial - Part 2: Enumerating objects | Tutorial - Part 1: Getting started | Index | Tutorial - Part 3: Forcing a roundtrip |
Tutorial - Part 3: Forcing a roundtrip | Tutorial - Part 2: Enumerating objects | Index | Tutorial - Part 4: Playing a tone |
Tutorial - Part 4: Playing a tone | Tutorial - Part 3: Forcing a roundtrip | Index | Tutorial - Part 5: Capturing video frames |
Tutorial - Part 5: Capturing video frames | Tutorial - Part 4: Playing a tone | Index | Tutorial - Part 6: Binding objects |
Tutorial - Part 6: Binding objects | Tutorial - Part 5: Capturing video frames | Index |
List of example programs | |
▼PipeWire API | The 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 Plugins | SPA plugins are dynamically loadable objects that contain objects and interfaces that can be introspected and used at runtime in any application |
SPA POD | POD (plain old data) is a sort of data container |
SPA Buffers |
|