From aec9bc5217aee13ce1c6915f72c4ade43aec19b8 Mon Sep 17 00:00:00 2001 From: Pauli Virtanen Date: Mon, 19 Feb 2024 20:03:01 +0200 Subject: [PATCH] doc: add sections to index, clarify discussion of properties Add some sections to index + fix typos and section levels. Clarify discussion of device properties. --- doc/dox/config/index.md | 4 -- doc/dox/config/pipewire-client.conf.5.md | 2 +- doc/dox/config/pipewire-devices.7.md | 77 +++++++++++++++++------- doc/dox/config/pipewire-jack.conf.5.md | 2 +- doc/dox/config/pipewire-pulse.conf.5.md | 2 +- doc/dox/config/pipewire.conf.5.md | 21 +++++-- 6 files changed, 72 insertions(+), 36 deletions(-) diff --git a/doc/dox/config/index.md b/doc/dox/config/index.md index 53e3a609f..df6981b97 100644 --- a/doc/dox/config/index.md +++ b/doc/dox/config/index.md @@ -86,8 +86,4 @@ interfaces: **Device properties** -@SECREF@ device-property - -**Device parameters** - @SECREF@ device-param diff --git a/doc/dox/config/pipewire-client.conf.5.md b/doc/dox/config/pipewire-client.conf.5.md index 1c3bde9c7..e253c2acd 100644 --- a/doc/dox/config/pipewire-client.conf.5.md +++ b/doc/dox/config/pipewire-client.conf.5.md @@ -46,7 +46,7 @@ The configuration file format and lookup logic is the same as for \ref page_man_ 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 +# CONFIGURATION FILE SECTIONS @IDX@ client.conf \par stream.properties Configures options for native client streams. diff --git a/doc/dox/config/pipewire-devices.7.md b/doc/dox/config/pipewire-devices.7.md index 226ea9a40..937b0cd79 100644 --- a/doc/dox/config/pipewire-devices.7.md +++ b/doc/dox/config/pipewire-devices.7.md @@ -6,25 +6,25 @@ PipeWire device and node property reference. # DESCRIPTION -Devices such as audio sinks and sources, cameras and Bluetooth -endpoints have properties that can be set in configuration files or at +Audio sinks and sources, cameras, Bluetooth endpoints, and other +objects have properties that can be set in configuration files or at runtime. -Technically, nodes and devices have both "properties" and "parameters". -The "properties" appear in \ref page_man_pw-dump_1 "pw-dump(1)" as `"props"`, -and generally control other aspects than hardware features. -The "parameters" are lower-level device settings, and technically -are the configuration of the underlying SPA device/node implementation. +Some of the properties are "common object properties" (e.g. such as +`node.description`) and can be set on all types of devices and +nodes. Other properties control settings of a specific type of a +device (ALSA, Bluetooth, ...). -All device settings are usually configured in the session manager configuration. +All the properties are usually configured in the session manager configuration. For how to configure them, see the session manager documentation. In minimal PipeWire setups without a session manager, they can be configured via \ref pipewire_conf__context_objects "context.objects in pipewire.conf(5)". -# RUNTIME PARAMETERS @IDX@ device-param +# RUNTIME SETTINGS @IDX@ device-param -Most ALSA and virtual device parameters can be configured also at runtime. +The settings of most ALSA and virtual device parameters can be +configured also at runtime. The settings are available in device `Props` in the `params` field. They can be seen e.g. using `pw-dump ` for an ALSA device: @@ -81,19 +81,22 @@ These settings are not saved and need to be reapplied for each session manager r # COMMON NODE PROPERTIES @IDX@ device-param -These are common properties for nodes. +The properties listed in \ref client_conf__stream_properties "Stream properties" +apply also to sink or source nodes corresponding to real or virtual devices. -@PAR@ device-property priority.driver +In addition: + +@PAR@ device-param priority.driver \parblock The priority of choosing this device as the driver in the graph. The driver is selected from all linked devices by selecting the device with the highest priority. Normally, the session manager assigns higher priority to sources so that they become the driver in the graph. The reason for this is that adaptive resampling should be done on the sinks rather than the source to avoid signal distortion when capturing audio. \endparblock -@PAR@ device-property priority.session +@PAR@ device-param priority.session The priority for selecting this device as the default device. -@PAR@ device-property clock.name +@PAR@ device-param clock.name \parblock The name of the clock. This name is auto generated from the card index and stream direction. Devices with the same clock name will not use a resampler to align the clocks. This can be used to link devices together with a shared word clock. @@ -102,9 +105,37 @@ In Pro Audio mode, nodes from the same device are assumed to have the same clock In Non Pro Audio profile, no such assumption is made and adaptive resampling is done in all cases by default. This can also be disabled by setting the same clock.name on the nodes. \endparblock -# AUDIO CONVERTER PARAMETERS @IDX@ device-param +@PAR@ device-param node.param.PARAM = JSON +\parblock +Set value of a node \ref spa_param_type "Param" to a JSON value when the device is loaded. +This works similarly as \ref page_man_pw-cli_1 "pw-cli(1)" `set-param` command. +The `PARAM` should be replaced with the name of the Param to set, +ie. for example `node.param.Props = { ... }` to set `Props`. +\endparblock -Most audio nodes (ALSA, Bluetooth, ...) have common parameters for the audio +@PAR@ device-param device.id +ID of the device the node belongs to. + +# COMMON DEVICE PROPERTIES @IDX@ device-param + +These are common properties for devices. + +@PAR@ device-param device.name +A (unique) name for the device. It can be used by command-line and other tools to identify the device. + +@PAR@ device-param device.param.PARAM = JSON +\parblock +Set value of a device \ref spa_param_type "Param" to a JSON value when the device is loaded. +This works similarly as \ref page_man_pw-cli_1 "pw-cli(1)" `set-param` command. +The `PARAM` should be replaced with the name of the Param to set, +ie. for example `device.Param.Props = { ... }` to set `Props`. +\endparblock + +Other `device.*` properties: UNDOCUMENTED + +# AUDIO CONVERTER PROPERTIES @IDX@ device-param + +Most audio nodes (ALSA, Bluetooth, ...) have common properties for the audio converter. See \ref client_conf__stream_properties "pipewire-client.conf(5) stream.properties" for explanations. @@ -178,9 +209,9 @@ UNDOCUMENTED UNDOCUMENTED -# ALSA PARAMETERS @IDX@ device-param +# ALSA PROPERTIES @IDX@ device-param -ALSA node parameters: +ALSA node properties: @PAR@ device-param audio.channels The number of audio channels to open the device with. Defaults depends on the profile of the device. @@ -257,10 +288,10 @@ 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 +# BLUETOOTH PROPERTIES @IDX@ device-param -The following are global Bluetooth parameters, not specific to a -specific device or node: +The following are settings for the Bluetooth module, not device or +node properties: @PAR@ device-param bluez5.roles \parblock @@ -347,7 +378,7 @@ PipeWire Opus Pro audio profile duplex max bitrate. @PAR@ device-param bluez5.a2dp.opus.pro.bidi.frame-dms = 400 PipeWire Opus Pro audio profile duplex frame duration (1/10 ms). -## Device parameters +## Device properties @PAR@ device-param bluez5.auto-connect Auto-connect devices on start up. Disabled by default if @@ -378,7 +409,7 @@ PipeWire Opus Pro Audio encoding mode: audio, voip, lowdelay @PAR@ device-param bluez5.a2dp.opus.pro.bidi.application = "audio" PipeWire Opus Pro Audio duplex encoding mode: audio, voip, lowdelay -## Node parameters +## Node properties @PAR@ device-param bluez5.media-source-role \parblock diff --git a/doc/dox/config/pipewire-jack.conf.5.md b/doc/dox/config/pipewire-jack.conf.5.md index 3224d47f8..53004f390 100644 --- a/doc/dox/config/pipewire-jack.conf.5.md +++ b/doc/dox/config/pipewire-jack.conf.5.md @@ -27,7 +27,7 @@ The configuration file format and lookup logic is the same as for \ref page_man_ 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 +# CONFIGURATION FILE SECTIONS @IDX@ jack.conf \par jack.properties JACK client configuration. diff --git a/doc/dox/config/pipewire-pulse.conf.5.md b/doc/dox/config/pipewire-pulse.conf.5.md index ce5684891..20f469064 100644 --- a/doc/dox/config/pipewire-pulse.conf.5.md +++ b/doc/dox/config/pipewire-pulse.conf.5.md @@ -27,7 +27,7 @@ The configuration file format and lookup logic is the same as for \ref page_man_ 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 +# CONFIGURATION FILE SECTIONS @IDX@ pipewire-pulse.conf \par stream.properties Dictionary. These properties configure the PipeWire Pulseaudio server diff --git a/doc/dox/config/pipewire.conf.5.md b/doc/dox/config/pipewire.conf.5.md index ecb98f6a5..c2cd7b828 100644 --- a/doc/dox/config/pipewire.conf.5.md +++ b/doc/dox/config/pipewire.conf.5.md @@ -101,7 +101,7 @@ In "SPA" JSON: - `,` to separate objects can be replaced with a whitespace character. - `#` can be used to start a comment until the line end -# CONFIGURATION FILE SECTIONS +# CONFIGURATION FILE SECTIONS @IDX@ pipewire.conf \par context.properties Dictionary. These properties configure the PipeWire instance. @@ -129,6 +129,15 @@ this mode of operation has since been demoted to development aid. Avoid starting a session manager in this way in production environment. \endparblock +\par node.rules +Array of dictionaries. Match rules for modifying node properties +on the server. + +\par device.rules +Array of dictionaries. Match rules for modifying device properties +on the server. + + # CONTEXT PROPERTIES @IDX@ pipewire.conf Available PipeWire properties in `context.properties` and possible @@ -381,7 +390,7 @@ context.exec = [ # MATCH RULES @IDX@ pipewire.conf -Some configuration files can contain match rules. This makes it +Some configuration file sections contain match rules. This makes it possible to perform some action when an object (usually a node or stream) is created/updated that matches certain properties. @@ -421,9 +430,9 @@ The available actions and their values depend on the specific rule that is used. Usually it is possible to update some properties or set some quirks on the object. -## node.rules +# NODE RULES @IDX@ pipewire.conf -The node.rules are evaluated very time the properties on a node are set +The node.rules are evaluated every time the properties on a node are set or updated. This can be used on the server side to override client set properties on arbitrary nodes. @@ -452,9 +461,9 @@ node.rules = [ Will set the `node.force-quantum` property of `jack_simple_client` to 512. -## device.rules +# DEVICE RULES @IDX@ pipewire.conf -The device.rules are evaluated very time the properties on a device are set +The device.rules are evaluated every time the properties on a device are set or updated. This can be used on the server side to override client set properties on arbitrary devices.