diff --git a/doc/dox/config/index.md b/doc/dox/config/index.md index 578199c15..53e3a609f 100644 --- a/doc/dox/config/index.md +++ b/doc/dox/config/index.md @@ -23,45 +23,56 @@ configuration options and files: Configuration of daemons: -- \ref page_man_pipewire_conf_5 -- \ref page_man_pipewire-pulse_conf_5 +- \ref page_man_pipewire_conf_5 "PipeWire daemon configuration reference" +- \ref page_man_pipewire-pulse_conf_5 "PipeWire Pulseaudio daemon configuration reference" - [WirePlumber daemon configuration](https://pipewire.pages.freedesktop.org/wireplumber/) - [Wiki page on PipeWire daemon configuration](https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/Config-PipeWire) - [Wiki page on PipeWire PulseAudio daemon configuration](https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/Config-PulseAudio) Configuration of devices: -- \ref page_man_pipewire-devices_7 - [WirePlumber configuration](https://pipewire.pages.freedesktop.org/wireplumber/daemon/configuration.html) +- \ref page_man_pipewire-devices_7 "Device and node property reference" - [Wiki page on device runtime settings](https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/Config-Devices) Configuration for client applications, either connecting via the native PipeWire interface, or the emulated ALSA, JACK, or PulseAudio interfaces: -- \ref page_man_pipewire-client_conf_5 -- \ref page_man_pipewire-jack_conf_5 -- \ref page_man_pipewire-pulse_conf_5 +- \ref page_man_pipewire-client_conf_5 "PipeWire native and ALSA client configuration reference" +- \ref page_man_pipewire-jack_conf_5 "PipeWire JACK client configuration reference" +- \ref page_man_pipewire-pulse_conf_5 "PipeWire Pulseaudio client configuration reference" - [Wiki page on native clients](https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/Config-client) - [Wiki page on ALSA clients](https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/Config-ALSA) - [Wiki page on JACK clients](https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/Config-JACK) - [Wiki page on PulseAudio clients](https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/Config-PulseAudio) +# Manual Pages + +- \subpage page_man_pipewire_conf_5 +- \subpage page_man_pipewire-client_conf_5 +- \subpage page_man_pipewire-pulse_conf_5 +- \subpage page_man_pipewire-jack_conf_5 +- \subpage page_man_pipewire-filter-chain_conf_5 +- \subpage page_man_pipewire-devices_7 +- \subpage page_man_pipewire-pulse-modules_7 +- \subpage page_man_libpipewire-modules_7 + # Configuration Index \ref page_man_pipewire_conf_5 "pipewire.conf" @SECREF@ pipewire.conf -\ref page_man_pipewire_conf_5 "pipewire-pulse.conf" +\ref page_man_pipewire-pulse_conf_5 "pipewire-pulse.conf" @SECREF@ pipewire-pulse.conf -\ref page_man_pipewire_conf_5 "client.conf, client-rt.conf" +\ref page_man_pipewire-client_conf_5 "client.conf, client-rt.conf" @SECREF@ client.conf -\ref page_man_pipewire_conf_5 "jack.conf" +\ref page_man_pipewire-jack_conf_5 "jack.conf" @SECREF@ jack.conf diff --git a/doc/dox/programs/index.md b/doc/dox/programs/index.md index 6eff77066..0f7a3aa25 100644 --- a/doc/dox/programs/index.md +++ b/doc/dox/programs/index.md @@ -3,13 +3,7 @@ Manual pages: - \subpage page_man_pipewire_1 -- \subpage page_man_pipewire_conf_5 -- \subpage page_man_pipewire-client_conf_5 - \subpage page_man_pipewire-pulse_1 -- \subpage page_man_pipewire-pulse_conf_5 -- \subpage page_man_pipewire-pulse-modules_7 -- \subpage page_man_pipewire-jack_conf_5 -- \subpage page_man_pipewire-devices_7 - \subpage page_man_pw-cat_1 - \subpage page_man_pw-cli_1 - \subpage page_man_pw-config_1 @@ -30,4 +24,3 @@ Manual pages: - \subpage page_man_spa-json-dump_1 - \subpage page_man_spa-monitor_1 - \subpage page_man_spa-resample_1 -- \subpage page_man_libpipewire-modules_7 diff --git a/doc/dox/programs/pipewire-client.conf.5.md b/doc/dox/programs/pipewire-client.conf.5.md index edae946fe..1c3bde9c7 100644 --- a/doc/dox/programs/pipewire-client.conf.5.md +++ b/doc/dox/programs/pipewire-client.conf.5.md @@ -41,15 +41,13 @@ and if nothing is specified, it usually loads `client.conf`. The ALSA plugin uses the `client-rt.conf` file, as do some PipeWire native clients such as \ref page_man_pw-cat_1 "pw-cat(1)". -The configuration file format is the same as for `pipewire.conf(5)`. +The configuration file format and lookup logic is the same as for \ref page_man_pipewire_conf_5 "pipewire.conf(5)". + +Drop-in configuration files `client.conf.d/*.conf` can be used, and are recommended. +See \ref pipewire_conf__drop-in_configuration_files "pipewire.conf(5)". # CONFIGURATION FILE SECTIONS -The same sections as in \ref page_man_pipewire_conf_5 "pipewire.conf(5)" -are available. However, a client usually sets the -`core.daemon` property to false, and has a limited set of -`context.spa-libs` usually only to create audio nodes and a poll loop. - \par stream.properties Configures options for native client streams. @@ -62,6 +60,9 @@ ALSA client configuration. \par alsa.rules ALSA client match rules. +In addition, the PipeWire context configuration sections +may also be specified, see \ref page_man_pipewire_conf_5 "pipewire.conf(5)". + # STREAM PROPERTIES @IDX@ client.conf The client configuration files contain a stream.properties section that configures the options for client streams: @@ -111,12 +112,42 @@ as targets for linking by the session manager. A human readable description of the node or stream. @PAR@ client.conf media.name -@PAR@ client.conf media.title -@PAR@ client.conf media.artist -A user readable media name, usually the artist and title. These are usually shown in user facing applications +A user readable media name, usually the artist and title. +These are usually shown in user facing applications to inform the user about the current playing media. -Other media properties exist such as copyright and icon. +@PAR@ client.conf media.title +A user readable stream title. + +@PAR@ client.conf media.artist +A user readable stream artist + +@PAR@ client.conf media.copyright +User readable stream copyright information + +@PAR@ client.conf media.software +User readable stream generator software information + +@PAR@ client.conf media.language +Stream language in POSIX format. Ex: `en_GB` + +@PAR@ client.conf media.filename +File name for the stream + +@PAR@ client.conf media.icon +Icon for the media, a base64 blob with PNG image data + +@PAR@ client.conf media.icon-name +An XDG icon name for the media. Ex: `audio-x-mp3` + +@PAR@ client.conf media.comment +Extra stream comment + +@PAR@ client.conf media.date +Date of the media + +@PAR@ client.conf media.format +User readable stream format information @PAR@ client.conf object.linger = false If the object should outlive its creator. diff --git a/doc/dox/programs/pipewire-devices.7.md b/doc/dox/programs/pipewire-devices.7.md index c9f286e5e..226ea9a40 100644 --- a/doc/dox/programs/pipewire-devices.7.md +++ b/doc/dox/programs/pipewire-devices.7.md @@ -225,14 +225,18 @@ Use the driver provided channel map. Default is false because many drivers don't @PAR@ device-param api.alsa.multi-rate UNDOCUMENTED -@PAR@ device-param api.alsa.htimestamp -UNDOCUMENTED +@PAR@ device-param api.alsa.htimestamp = false +Use ALSA htimestamps in scheduling, instead of the system clock. +Some ALSA drivers produce bad timestamps, so this is not enabled by default +and will be disabled at runtime if it looks like the ALSA timestamps are bad. -@PAR@ device-param api.alsa.disable-tsched -UNDOCUMENTED +@PAR@ device-param api.alsa.disable-tsched = false +Disable timer-based scheduling, and use IRQ for scheduling instead. +The "Pro Audio" profile will usually enable this setting, if it is expected it works on the hardware. -@PAR@ device-param api.alsa.auto-link -UNDOCUMENTED +@PAR@ device-param api.alsa.auto-link = false +Link follower PCM devices to the driver PCM device when using IRQ-based scheduling. +The "Pro Audio" profile will usually enable this setting, if it is expected it works on the hardware. @PAR@ device-param latency.internal.rate Static set the device systemic latency, in samples at playback rate. @@ -250,7 +254,8 @@ UNDOCUMENTED UNDOCUMENTED @PAR@ device-param iec958.codecs -UNDOCUMENTED +Enable only specific IEC958 codecs. This can be used to disable some codecs the hardware supports. +Available values: PCM, AC3, DTS, MPEG, MPEG2-AAC, EAC3, TRUEHD, DTSHD # BLUETOOTH PARAMETERS @IDX@ device-param diff --git a/doc/dox/programs/pipewire-filter-chain.conf.5.md b/doc/dox/programs/pipewire-filter-chain.conf.5.md new file mode 100644 index 000000000..bde3ffff2 --- /dev/null +++ b/doc/dox/programs/pipewire-filter-chain.conf.5.md @@ -0,0 +1,42 @@ +\page page_man_pipewire-filter-chain_conf_5 filter-chain.conf + +PipeWire example configuration for running audio filters. + +\tableofcontents + +# SYNOPSIS + +*$XDG_CONFIG_HOME/pipewire/filter-chain.conf* + +*$(PIPEWIRE_CONFIG_DIR)/filter-chain.conf* + +*$(PIPEWIRE_CONFDATADIR)/filter-chain.conf* + +*$(PIPEWIRE_CONFDATADIR)/filter-chain.conf.d/* + +*$(PIPEWIRE_CONFIG_DIR)/filter-chain.conf.d/* + +*$XDG_CONFIG_HOME/pipewire/filter-chain.conf.d/* + +# DESCRIPTION + +When \ref page_man_pipewire_1 "pipewire(1)" is run using +this configuration file, `pipewire -c filter-chain.conf`, +it starts a PipeWire client application that publishes +nodes that apply various audio filters to their input. + +It is a normal PipeWire client application in all respects. + +Drop-in configuration files `filter-chain.conf.d/*.conf` can be used +to modify the filter configuration, see \ref pipewire_conf__drop-in_configuration_files "pipewire.conf(5)". +Some examples are in *$(PIPEWIRE_CONFDATADIR)/filter-chain/* + +# AUTHORS + +The PipeWire Developers <$(PACKAGE_BUGREPORT)>; +PipeWire is available from <$(PACKAGE_URL)> + +# SEE ALSO + +\ref page_man_pipewire_1 "pipewire(1)", +\ref page_man_pipewire_conf_5 "pipewire.conf(5)" diff --git a/doc/dox/programs/pipewire-jack.conf.5.md b/doc/dox/programs/pipewire-jack.conf.5.md index cae770fbd..3224d47f8 100644 --- a/doc/dox/programs/pipewire-jack.conf.5.md +++ b/doc/dox/programs/pipewire-jack.conf.5.md @@ -20,30 +20,24 @@ The PipeWire JACK client configuration file. # DESCRIPTION -Configuration for PipeWire native clients, and for PipeWire's ALSA -plugin. +Configuration for PipeWire JACK clients. -A PipeWire native client program selects the default config to load, -and if nothing is specified, it usually loads `client.conf`. +The configuration file format and lookup logic is the same as for \ref page_man_pipewire_conf_5 "pipewire.conf(5)". -The ALSA plugin uses the `client-rt.conf` file, as do some PipeWire -native clients such as \ref page_man_pw-cat_1 "pw-cat(1)". - -The configuration file format is the same as for `pipewire.conf(5)`. +Drop-in configuration files `jack.conf.d/*.conf` can be used, and are recommended. +See \ref pipewire_conf__drop-in_configuration_files "pipewire.conf(5)". # CONFIGURATION FILE SECTIONS -The same sections as in \ref page_man_pipewire_conf_5 "pipewire.conf(5)" -are available. However, a client usually sets the -`core.daemon` property to false, and has a limited set of -`context.spa-libs` usually only to create audio nodes and a poll loop. - \par jack.properties JACK client configuration. \par jack.rules JACK client match rules. +In addition, the PipeWire context configuration sections +may also be specified, see \ref page_man_pipewire_conf_5 "pipewire.conf(5)". + # JACK PROPERTIES @IDX@ jack.conf The configuration file can contain an extra JACK specific section called `jack.properties` like this: @@ -333,7 +327,5 @@ PipeWire is available from <$(PACKAGE_URL)> # SEE ALSO -\ref page_module_protocol_pulse "libpipewire-module-protocol-pulse(7)", -\ref page_man_pipewire_conf_5 "pipewire.conf(5)", -\ref page_man_pipewire-pulse_1 "pipewire-pulse(1)", -\ref page_man_pipewire-pulse-modules_7 "pipewire-pulse-modules(7)" +\ref page_man_pw-jack_1 "pw-jack(1)", +\ref page_man_pipewire_conf_5 "pipewire.conf(5)" diff --git a/doc/dox/programs/pipewire-pulse.1.md b/doc/dox/programs/pipewire-pulse.1.md index d77bd989e..66d2ec887 100644 --- a/doc/dox/programs/pipewire-pulse.1.md +++ b/doc/dox/programs/pipewire-pulse.1.md @@ -35,12 +35,16 @@ are supported. In addition: -@PAR@ pulse-env PULSE_RUNTIME_PATH - -@PAR@ pulse-env XDG_RUNTIME_DIR +@PAR@ pulse-env PULSE_RUNTIME_PATH +@PAR@ pulse-env XDG_RUNTIME_DIR Directory where to create the native protocol pulseaudio socket. +@PAR@ pulse-env PULSE_LATENCY_MSEC +Extra buffering latency in milliseconds. This controls buffering +logic in `libpulse` and may be set for PulseAudio client applications +to adjust their buffering. (Setting it on the `pipewire-pulse` server +has no effect.) # AUTHORS diff --git a/doc/dox/programs/pipewire-pulse.conf.5.md b/doc/dox/programs/pipewire-pulse.conf.5.md index 064a9277c..ce5684891 100644 --- a/doc/dox/programs/pipewire-pulse.conf.5.md +++ b/doc/dox/programs/pipewire-pulse.conf.5.md @@ -22,9 +22,10 @@ The PipeWire Pulseaudio server configuration file Configuration for PipeWire's PulseAudio-compatible daemon. -The configuration file format is the same as for `pipewire.conf(5)`. -There are additional sections for configuring `pipewire-pulse(1)` -settings. +The configuration file format and lookup logic is the same as for \ref page_man_pipewire_conf_5 "pipewire.conf(5)". + +Drop-in configuration files `pipewire-pulse.conf.d/*.conf` can be used, and are recommended. +See \ref pipewire_conf__drop-in_configuration_files "pipewire.conf(5)". # CONFIGURATION FILE SECTIONS @@ -50,8 +51,8 @@ clients. See \ref page_module_protocol_pulse "libpipewire-module-protocol-pulse(7)" for the detailed description. -In addition, the general PipeWire daemon configuration sections apply, -see \ref page_man_pipewire_conf_5 "pipewire.conf(5)". +In addition, the PipeWire context configuration sections +may also be specified, see \ref page_man_pipewire_conf_5 "pipewire.conf(5)". # STREAM PROPERTIES @IDX@ pipewire-pulse.conf diff --git a/doc/dox/programs/pipewire.conf.5.md b/doc/dox/programs/pipewire.conf.5.md index 5edb5b761..9643fcc57 100644 --- a/doc/dox/programs/pipewire.conf.5.md +++ b/doc/dox/programs/pipewire.conf.5.md @@ -26,41 +26,76 @@ 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 +The config file is looked up in the order listed in the [SYNOPSIS](#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](#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. +Other PipeWire configuration files generally follow the same lookup +logic, replacing `pipewire.conf` with the name of the particular +config file. + +# DROP-IN CONFIGURATION FILES @IDX@ pipewire.conf + +All `*.conf` files in the `pipewire.conf.d/` directories are loaded +and merged into the configuration. Dictionary sections are merged, +overriding properties if they already existed, and array sections are +appended to. The drop-in files have same format as the main +configuration file, but only contain the settings to be modified. + +As the `pipewire.conf` configuration file contains various parts +that must be present for correct functioning, using drop-in files +for configuration is recommended. + +## Example + +A configuration file `~/.config/pipewire/pipewire.conf.d/custom.conf` +to change the value of the `default.clock.min-quantum` setting in `pipewire.conf`: + +```css +context.properties = { + default.clock.min-quantum = 128 +} +``` # CONFIGURATION FILE FORMAT @IDX@ pipewire.conf -The configuration file is in (SPA) JSON format. +The configuration file is in "SPA" JSON format. + +The configuration file contains top-level keys, which are the sections. +The value of a section is either a dictionary, `{ }`, or an +array, `[ ]`. Section and dictionary item declarations +have `KEY = VALUE` form, and are separated by whitespace. +For example: -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 +context.properties = { # top-level dictionary section - name = { key1 = value1 key2 = value2 } # a dictionary with two entries + key1 = value # a simple value - name = [ value1 value2 ] # an array with two entries + key2 = { key1 = value1 key2 = value2 } # a dictionary with two entries - name = [ { k = v1 } { k = v2 } ] # an array of dictionaries + key3 = [ value1 value2 ] # an array with two entries + + key4 = [ { k = v1 } { k = v2 } ] # an array of dictionaries + +} + +context.modules = [ # top-level array section + + value1 + + value2 + +] ``` -The configuration files can be expressed in standard JSON syntax but for -ease of use, a relaxed format may be used where: +The configuration files can also be written in standard JSON syntax, +but for easier manual editing, the relaxed "SPA" variant is allowed. +In "SPA" JSON: -- `:` to delimit keys and values can be substuted by `=` or a space. +- `:` to delimit keys and values can be substituted by `=` or a space. - \" around keys and string can be omitted as long as no special characters are used in the strings. - `,` to separate objects can be replaced with a whitespace character. @@ -148,12 +183,16 @@ Default quantum used when no client specifies one. Maximum quantum to reserve space for. @PAR@ pipewire.conf default.video.width +Default video width @PAR@ pipewire.conf default.video.height +Default video height @PAR@ pipewire.conf default.video.rate.num +Default video rate numerator @PAR@ pipewire.conf default.video.rate.denom +Default video rate denominator @PAR@ pipewire.conf library.name.system = support/libspa-support The name of the shared library to use for the system functions for the main thread. @@ -193,10 +232,10 @@ it. Disable this if you want to globally disable DBus support in the process. Any property in the vm.overrides property object will override the property in the context.properties when PipeWire detects it is running in a VM. -\par CONDITION = true / false -The `context.modules` and `context.objects` sections can declare -additional condition variables, which control whether a specific -module or object to be loaded on startup. +The context properties may also contain custom values. For example, +the `context.modules` and `context.objects` sections can declare +additional conditions that control whether a module or object is loaded +depending on what properties are present. # SPA LIBRARIES @IDX@ pipewire.conf @@ -244,15 +283,17 @@ context.modules = [ \par name Name of module to be loaded -\par args = { KEY = VALUE } -Argument to the module +\par args = { } +Arguments passed to the module \par flags = [ ] Loading flags. `ifexists` to only load module if it exists, and `nofail` to not fail PipeWire startup if the module fails to load. -\par condition = [ { KEY = VALUE }, ... ] -Named condition variables, which control whether a module is loaded. +\par condition = [ ] +A \ref pipewire_conf__match_rules "match rule" `matches` condition. +The module is loaded only if one of the expressions in the array matches +to a context property. # CONTEXT OBJECTS @IDX@ pipewire.conf @@ -270,32 +311,35 @@ context.objects = [ ``` This section can be used to make nodes or links between nodes. -\par name -Name of module to be loaded +\par factory +Name of the factory to create the object. -\par args = { KEY = VALUE } -Argument to the module +\par args = { } +Arguments passed to the factory. \par flags = [ ] -Loading flags. `ifexists` to only load module if it exists, -and `nofail` to not fail PipeWire startup if the module fails to load. +Flag `nofail` to not fail PipeWire startup if the object fails to load. -\par condition = [ { KEY = VALUE }, ... ] -Named condition variables, which control whether a module is loaded. +\par condition = [ ] +A \ref pipewire_conf__match_rules "match rule" `matches` condition. +The object is created only if one of the expressions in the array matches +to a context property. ## Example -This fragment creates a new dummy driver node: +This fragment creates a new dummy driver node, but only if +`core.daemon` property is true: ```json context.objects = [ { factory = spa-node-factory - args = { - factory.name = support.node.driver - node.name = Dummy-Driver - node.group = pipewire.dummy - priority.driver = 20000 - } + args = { + factory.name = support.node.driver + node.name = Dummy-Driver + node.group = pipewire.dummy + priority.driver = 20000 + }, + condition = [ { core.daemon = true } ] } ] ``` @@ -321,7 +365,9 @@ Program to execute. Arguments to the program. \par condition -Condition variable definition. +A \ref pipewire_conf__match_rules "match rule" `matches` condition. +The object is created only if one of the expressions in the array matches +to a context property. ## Example @@ -351,6 +397,9 @@ The general rules object follows the following pattern: # all keys must match the value. ! negates. ~ starts regex. #application.process.binary = "teams" #application.name = "~speech-dispatcher.*" + + # Absence of property can be tested by comparing to null + #pipewire.sec.flatpak = null } { # more matches here... diff --git a/doc/meson.build b/doc/meson.build index 05ea7f349..f35a348d7 100644 --- a/doc/meson.build +++ b/doc/meson.build @@ -74,6 +74,7 @@ manpage_docs = [ 'dox/programs/pipewire-client.conf.5.md', 'dox/programs/pipewire-jack.conf.5.md', 'dox/programs/pipewire-devices.7.md', + 'dox/programs/pipewire-filter-chain.conf.5.md', 'dox/programs/pw-cat.1.md', 'dox/programs/pw-cli.1.md', 'dox/programs/pw-config.1.md',