doc: add some more coverage

Fix some copypaste mistakes and other errors.

Add explanations for some more properties.  Explain "drop-in" config
files.  Explain filter-chain.conf.

Move configuration man pages under Configuration in TOC.

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_conf_5 "PipeWire daemon configuration reference"
-- \ref page_man_pipewire-pulse_conf_5
+- \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-client_conf_5 "PipeWire native and ALSA client configuration reference"
-- \ref page_man_pipewire-jack_conf_5
+- \ref page_man_pipewire-jack_conf_5 "PipeWire JACK client configuration reference"
-- \ref page_man_pipewire-pulse_conf_5
+- \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
 

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

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
+A user readable media name, usually the artist and title.
-@PAR@ client.conf  media.artist
+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.

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
+@PAR@ device-param  api.alsa.htimestamp = false
-UNDOCUMENTED
+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
+@PAR@ device-param  api.alsa.disable-tsched = false
-UNDOCUMENTED
+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
+@PAR@ device-param  api.alsa.auto-link = false
-UNDOCUMENTED
+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
 

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)"

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
+Configuration for PipeWire JACK clients.
-plugin.
 
-A PipeWire native client program selects the default config to load,
+The configuration file format and lookup logic is the same as for \ref page_man_pipewire_conf_5 "pipewire.conf(5)".
-and if nothing is specified, it usually loads `client.conf`.
 
-The ALSA plugin uses the `client-rt.conf` file, as do some PipeWire
+Drop-in configuration files `jack.conf.d/*.conf` can be used, and are recommended.
-native clients such as \ref page_man_pw-cat_1 "pw-cat(1)".
+See \ref pipewire_conf__drop-in_configuration_files "pipewire.conf(5)".
-
-The configuration file format is the same as for `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_pw-jack_1 "pw-jack(1)",
-\ref page_man_pipewire_conf_5 "pipewire.conf(5)",
+\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)"

doc/dox/programs/pipewire-pulse.1.md

@@ -35,12 +35,16 @@ are supported.
 
 In addition:
 
-@PAR@ pulse-env PULSE_RUNTIME_PATH
+@PAR@ pulse-env  PULSE_RUNTIME_PATH
-
-@PAR@ pulse-env XDG_RUNTIME_DIR
 
+@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
 

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)`.
+The configuration file format and lookup logic is the same as for \ref page_man_pipewire_conf_5 "pipewire.conf(5)".
-There are additional sections for configuring `pipewire-pulse(1)`
+
-settings.
+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,
+In addition, the PipeWire context configuration sections 
-see \ref page_man_pipewire_conf_5 "pipewire.conf(5)".
+may also be specified, see \ref page_man_pipewire_conf_5 "pipewire.conf(5)".
 
 # STREAM PROPERTIES  @IDX@ pipewire-pulse.conf
 

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
+Other PipeWire configuration files generally follow the same lookup
-the file with a `.d/` suffix. All directories in the
+logic, replacing `pipewire.conf` with the name of the particular
-[SYNOPSIS](#synopsis) directory search paths are traversed in the listed
+config file.
-order and the contents of the `*.conf` files inside them are appended to
+
-the main configuration file as overrides. Object sections are merged and
+# DROP-IN CONFIGURATION FILES  @IDX@ pipewire.conf
-array sections are appended.
+
+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
+The configuration files can also be written in standard JSON syntax,
-ease of use, a relaxed format may be used where:
+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.
 - <tt>\"</tt> 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 properties may also contain custom values. For example,
-The `context.modules` and `context.objects` sections can declare
+the `context.modules` and `context.objects` sections can declare
-additional condition variables, which control whether a specific
+additional conditions that control whether a module or object is loaded
-module or object to be loaded on startup.
+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 }
+\par args = { }
-Argument to the module
+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 }, ... ]
+\par condition = [ ]
-Named condition variables, which control whether a module is loaded.
+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
+\par factory
-Name of module to be loaded
+Name of the factory to create the object.
 
-\par args = { KEY = VALUE }
+\par args = { }
-Argument to the module
+Arguments passed to the factory.
 
 \par flags = [ ]
-Loading flags. `ifexists` to only load module if it exists,
+Flag `nofail` to not fail PipeWire startup if the object fails to load.
-and `nofail` to not fail PipeWire startup if the module fails to load.
 
-\par condition = [ { KEY = VALUE }, ... ]
+\par condition = [ ]
-Named condition variables, which control whether a module is loaded.
+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 = {
+      args = {
-            factory.name    = support.node.driver
+          factory.name    = support.node.driver
-            node.name       = Dummy-Driver
+          node.name       = Dummy-Driver
-            node.group      = pipewire.dummy
+          node.group      = pipewire.dummy
-            priority.driver = 20000
+          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...

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',