doc: document more properties

Also add examples for customizing properties.

doc/dox/config/pipewire-props.7.md

@@ -36,11 +36,66 @@ type. Other properties control settings of a specific kinds of device
 or node (ALSA, Bluetooth, ...), and have meaning only for those
 objects.
 
-Usually, all the properties are configured in the session manager
+# CUSTOMIZING PROPERTIES  @IDX@ props
-configuration.  For how to configure them, see the session manager
+
-documentation. In minimal PipeWire setups without a session manager,
+Usually, all device properties are configured in the session manager
-they can be configured via
+configuration, see the session manager documentation.
-\ref pipewire_conf__context_objects "context.objects in pipewire.conf(5)".
+Application properties are configured in
+``client.conf`` (for native PipeWire and ALSA applications), and
+``pipewire-pulse.conf`` (for Pulseaudio applications).
+
+In minimal PipeWire setups without a session manager,
+the device properties can be configured via
+\ref pipewire_conf__context_objects "context.objects in pipewire.conf(5)"
+when creating the devices.
+
+\see [WirePlumber configuration](https://pipewire.pages.freedesktop.org/wireplumber/daemon/configuration.html)
+
+## Examples
+
+Client configuration (requires client application restart to apply)
+```css
+# ~/.config/pipewire/client.conf/custom-props.conf
+
+stream.rules = [
+  {
+    matches = [ { application.name = "pw-play" } ]
+    actions = { update-props = { node.description = "Some pw-cat stream" } }
+  }
+]
+```
+\see \ref client_conf__stream_rules "pipewire-client.conf(5)", \ref client_conf__stream_rules "pipewire-pulse.conf(5)"
+
+Device configuration (using WirePlumber; requires WirePlumber restart to apply):
+```css
+# ~/.config/wireplumber/wireplumber.conf.d/custom-props.conf
+
+monitor.alsa.properties = {
+  alsa.udev.expose-busy = true
+}
+
+monitor.alsa.rules = [
+  {
+    matches = [ { device.name = "~alsa_card.pci-.*" } ],
+    actions = { update-props = { api.alsa.soft-mixer = true } ]
+  },
+  {
+    matches = [ { node.name = "alsa_output.pci-0000_03_00.1.hdmi-stereo-extra3" } ]
+    actions = { update-props = { node.description = "Main Audio" } ]
+  }
+]
+
+monitor.bluez.properties = {
+  bluez5.hfphsp-backend = ofono
+}
+
+monitor.bluez.rules = [
+  {
+    matches = [ { device.name = "~bluez_card.*" } ],
+    actions = { update-props = { bluez5.dummy-avrcp player = true } ]
+  }
+]
+```
 
 \see [WirePlumber configuration](https://pipewire.pages.freedesktop.org/wireplumber/daemon/configuration.html)
 
@@ -51,6 +106,9 @@ These are common properties for devices.
 @PAR@ device-prop  device.name    # string
 A (unique) name for the device. It can be used by command-line and other tools to identify the device.
 
+@PAR@ device-prop  device.nick    # string
+A short name for the device.
+
 @PAR@ device-prop  device.param.PARAM = { ... }   # JSON
 \parblock
 Set value of a device \ref spa_param_type "Param" to a JSON value when the device is loaded.
@@ -143,11 +201,14 @@ real or virtual devices.
 
 These contain properties to identify the node or to display the node in a GUI application.
 
-@PAR@ node-prop  node.name
+@PAR@ node-prop  node.name    # string
 A (unique) name for the node. This is usually set on sink and sources to identify them
 as targets for linking by the session manager.
 
-@PAR@ node-prop  node.description
+@PAR@ node-prop  node.nick    # string
+A short name for the node.
+
+@PAR@ node-prop  node.description    # string
 A human readable description of the node or stream.
 
 @PAR@ node-prop  media.name
@@ -338,14 +399,14 @@ a sink or source.
 @PAR@ node-prop  node.exclusive = false
 If this node wants to be linked exclusively to the sink/source.
 
+@PAR@ node-prop  target.object = <node.name|object.serial>
+Where the node should link to, this can be a node.name or an object.serial.
+
 @PAR@ node-prop  node.target = <node.name|object.id>
 Where this node should be linked to. This can be a node.name or an object.id of a node. This property is
 deprecated, the target.object property should be used instead, which uses the more unique object.serial as
 a possible target.
 
-@PAR@ node-prop  target.object = <node.name|object.serial>
-Where the node should link to, this can be a node.name or an object.serial.
-
 @PAR@ node-prop  node.dont-reconnect = false
 \parblock
 When the node has a target configured and the target is destroyed, destroy the node as well.
@@ -355,6 +416,13 @@ Note that if a stream should appear/disappear in sync with the target, a session
 should be written instead.
 \endparblock
 
+@PAR@ node-prop  node.dont-fallback = false
+If linking this node to its specified target does not succeed, session
+manager should not fall back to linking it to the default target.
+
+@PAR@ node-prop  node.dont-move = false
+Whether the node target may be changed using metadata.
+
 @PAR@ node-prop  node.passive = false
 \parblock
 This is a passive node and so it should not keep sinks/sources busy. This property makes the session manager create passive links to the sink/sources. If the node is not otherwise linked (via a non-passive link), the node and the sink it is linked to are idle (and eventually suspended).
@@ -371,6 +439,13 @@ Instruct the session manager to not remix the channels of a stream. Normally the
 @PAR@ node-prop  priority.session    # integer
 The priority for selecting this node as the default source or sink.
 
+@PAR@ node-prop  session.suspend-timeout-seconds = 3  # float
+Timeout in seconds, after which an idle node is suspended.
+Value ``0`` means the node will not be suspended.
+
+@PAR@ node-prop  state.restore-props = true
+Whether session manager should save state for this node.
+
 ## Format Properties
 
 Streams and also most device nodes can be configured in a certain format with properties.
@@ -640,8 +715,9 @@ See \ref spa_param_port_config for the meaning.
 
 ## Monitor properties
 
-@PAR@ monitor-prop  alsa.use-acp    # boolean
+@PAR@ monitor-prop  alsa.use-acp = true      # boolean
 Use \ref monitor-prop__alsa_card_profiles "ALSA Card Profiles" (ACP) for device configuration.
+This autodetects available ALSA devices and configures port and hardware mixers.
 
 @PAR@ monitor-prop  alsa.udev.expose-busy    # boolean
 Expose the ALSA card even if it is busy/in use. Default false. This can be useful when some
@@ -658,7 +734,7 @@ When ACP is enabled and a UCM configuration is available for a device, by
 default it is used instead of the ACP profiles. This option allows you to
 disable this and use the ACP profiles instead.
 
-This option does nothing if `api.alsa.use-acp` is set to `false`.
+This option does nothing if `alsa.use-acp` is set to `false`.
 \endparblock
 
 @PAR@ device-prop  api.alsa.soft-mixer = false  # boolean
@@ -1058,6 +1134,12 @@ this instance. Available values:
   - input: appear as source node.
 \endparblock
 
+@PAR@ node-prop  node.latency-offset-msec   # string
+Applies only for BLE MIDI nodes.
+Latency adjustment to apply on the node. Larger values add a
+constant latency, but reduces timing jitter caused by Bluetooth
+transport.
+
 # PORT PROPERTIES  @IDX@ props
 
 Port properties are usually not directly configurable via PipeWire