mirrors/pipewire
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/pipewire/pipewire.git synced 2025-10-29 05:40:27 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

doc: improve property documentation

Browse source 
Add some more examples, and more xref links to index.
This commit is contained in:
Pauli Virtanen 2025-08-30 15:26:44 +03:00 • committed by Wim Taymans
parent 98b7a34102
commit bde2aa34ef
5 changed files with 91 additions and 43 deletions
Download patch file Download diff file Expand all files Collapse all files

8
doc/dox/config/pipewire-client.conf.5.md
View file

@ -48,7 +48,7 @@ ALSA client match rules.
In addition, the PipeWire context configuration sections In addition, the PipeWire context configuration sections
may also be specified, 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@ client.conf # STREAM PROPERTIES @IDX@ client.conf stream.properties
The client configuration files contain a stream.properties section that configures the options for client streams: The client configuration files contain a stream.properties section that configures the options for client streams:
```css ```css
@ -93,7 +93,7 @@ A list of object properties that can be applied to streams can be found in
and and
\ref props__audio_converter_properties "pipewire-props(7) Audio Adapter Properties" \ref props__audio_converter_properties "pipewire-props(7) Audio Adapter Properties"
# STREAM RULES @IDX@ client.conf # STREAM RULES @IDX@ client.conf stream.rules
You can add \ref pipewire_conf__match_rules "match rules, see pipewire(1)" You can add \ref pipewire_conf__match_rules "match rules, see pipewire(1)"
to set properties for certain streams and filters. to set properties for certain streams and filters.
@ -127,7 +127,7 @@ stream.rules = [
Will set the node.name of Firefox to "My Name". Will set the node.name of Firefox to "My Name".
# ALSA CLIENT PROPERTIES @IDX@ client.conf # ALSA CLIENT PROPERTIES @IDX@ client.conf alsa.properties
An `alsa.properties` section can be added to configure client applications An `alsa.properties` section can be added to configure client applications
that connect via the PipeWire ALSA plugin. that connect via the PipeWire ALSA plugin.
@ -169,7 +169,7 @@ The number of bytes in the alsa buffer. The default is 0, which is to allow any
This controls the volume curve used on the ALSA mixer. Possible values are `cubic` and This controls the volume curve used on the ALSA mixer. Possible values are `cubic` and
`linear`. The default is to use `cubic`. `linear`. The default is to use `cubic`.
# ALSA CLIENT RULES @IDX@ client.conf # ALSA CLIENT RULES @IDX@ client.conf alsa.rules
It is possible to set ALSA client specific properties by using It is possible to set ALSA client specific properties by using
\ref pipewire_conf__match_rules "Match rules, see pipewire(1)". You can \ref pipewire_conf__match_rules "Match rules, see pipewire(1)". You can

4
doc/dox/config/pipewire-jack.conf.5.md
View file

@ -38,7 +38,7 @@ JACK client match rules.
In addition, the PipeWire context configuration sections In addition, the PipeWire context configuration sections
may also be specified, see \ref page_man_pipewire_conf_5 "pipewire.conf(5)". may also be specified, see \ref page_man_pipewire_conf_5 "pipewire.conf(5)".
# JACK PROPERTIES @IDX@ jack.conf # JACK PROPERTIES @IDX@ jack.conf jack.properties
The configuration file can contain an extra JACK specific section called `jack.properties` like this: The configuration file can contain an extra JACK specific section called `jack.properties` like this:
```css ```css
@ -206,7 +206,7 @@ JACK apps don't know about this flag yet and refuse to show the port.
Set this to true for applications that know how to handle MIDI2 ports. Set this to true for applications that know how to handle MIDI2 ports.
\endparblock \endparblock
# MATCH RULES @IDX@ jack.conf # MATCH RULES @IDX@ jack.conf jack.rules
`jack.rules` provides an `update-props` action that takes an object with properties that are updated `jack.rules` provides an `update-props` action that takes an object with properties that are updated
on the client and node object of the jack client. on the client and node object of the jack client.

98
doc/dox/config/pipewire-props.7.md
View file

@ -41,32 +41,19 @@ objects.
Usually, all device properties are configured in the session manager Usually, all device properties are configured in the session manager
configuration, see the session manager documentation. configuration, see the session manager documentation.
Application properties are configured in Application properties are configured in
``client.conf`` (for native PipeWire and ALSA applications), and ``client.conf`` (for native PipeWire and ALSA applications),
``pipewire-pulse.conf`` (for Pulseaudio applications). ``pipewire-pulse.conf`` (for Pulseaudio applications), and
``jack.conf`` (for JACK applications).
In minimal PipeWire setups without a session manager, In minimal PipeWire setups without a session manager,
the device properties can be configured via the device properties can be configured via
\ref pipewire_conf__context_objects "context.objects in pipewire.conf(5)" \ref pipewire_conf__context_objects "context.objects in pipewire.conf(5)"
when creating the devices. when creating the devices.
\see [WirePlumber configuration](https://pipewire.pages.freedesktop.org/wireplumber/daemon/configuration.html)
## Examples ## Examples
Client configuration (requires client application restart to apply) Device configuration using WirePlumber (requires WirePlumber restart to apply).
```css See [WirePlumber configuration](https://pipewire.pages.freedesktop.org/wireplumber/daemon/configuration.html)
# ~/.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 ```css
# ~/.config/wireplumber/wireplumber.conf.d/custom-props.conf # ~/.config/wireplumber/wireplumber.conf.d/custom-props.conf
@ -77,14 +64,18 @@ monitor.alsa.properties = {
monitor.alsa.rules = [ monitor.alsa.rules = [
{ {
matches = [ { device.name = "~alsa_card.pci-.*" } ], matches = [ { device.name = "~alsa_card.pci-.*" } ],
actions = { update-props = { api.alsa.soft-mixer = true } ] actions = { update-props = { api.alsa.soft-mixer = true } }
}, },
{ {
matches = [ { node.name = "alsa_output.pci-0000_03_00.1.hdmi-stereo-extra3" } ] matches = [ { node.name = "alsa_output.pci-0000_03_00.1.hdmi-stereo-extra3" } ]
actions = { update-props = { node.description = "Main Audio" } ] actions = { update-props = { node.description = "Main Audio" } }
} }
] ]
monitor.alsa-midi.properties = {
api.alsa.seq.ump = true
}
monitor.bluez.properties = { monitor.bluez.properties = {
bluez5.hfphsp-backend = ofono bluez5.hfphsp-backend = ofono
} }
@ -92,12 +83,49 @@ monitor.bluez.properties = {
monitor.bluez.rules = [ monitor.bluez.rules = [
{ {
matches = [ { device.name = "~bluez_card.*" } ], matches = [ { device.name = "~bluez_card.*" } ],
actions = { update-props = { bluez5.dummy-avrcp player = true } ] actions = { update-props = { bluez5.dummy-avrcp player = true } }
} }
] ]
``` ```
\see [WirePlumber configuration](https://pipewire.pages.freedesktop.org/wireplumber/daemon/configuration.html) Native client configuration (requires client application restart to apply).
See \ref client_conf__stream_rules "pipewire-client.conf(5)"
```css
# ~/.config/pipewire/client.conf/custom-props.conf
stream.rules = [
{
matches = [ { application.name = "pw-play" } ]
actions = { update-props = { node.description = "Some pw-cat stream" } }
}
]
```
Pulseaudio client configuration (requires \ref page_man_pipewire-pulse_1 "pipewire-pulse(1)" restart to apply).
See \ref pipewire-pulse_conf__stream_rules "pipewire-pulse.conf(5)"
```css
# ~/.config/pipewire/pipewire-pulse.conf/custom-props.conf
stream.rules = [
{
matches = [ { application.name = "paplay" } ]
actions = { update-props = { node.description = "Some paplay stream" } }
}
]
```
JACK client configuration (requires client restart to apply).
See \ref jack_conf__match_rules "pipewire-jack.conf(5)"
```css
# ~/.config/pipewire/jack.conf/custom-props.conf
jack.rules = [
{
matches = [ { client.name = "jack_delay" } ]
actions = { update-props = { node.description = "Some JACK node" } }
}
]
```
# COMMON DEVICE PROPERTIES @IDX@ props # COMMON DEVICE PROPERTIES @IDX@ props
@ -106,9 +134,6 @@ These are common properties for devices.
@PAR@ device-prop device.name # string @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. 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 @PAR@ device-prop device.param.PARAM = { ... } # JSON
\parblock \parblock
Set value of a device \ref spa_param_type "Param" to a JSON value when the device is loaded. Set value of a device \ref spa_param_type "Param" to a JSON value when the device is loaded.
@ -901,6 +926,29 @@ Informative property.
\endparblock \endparblock
# ALSA MIDI PROPERTIES @IDX@ props
## Node properties
For ALSA MIDI in Wireplumber, MIDI bridge node properties are
configured in the monitor properties.
@PAR@ monitor-prop api.alsa.seq.ump = true # boolean
Use MIDI 2.0 if possible.
@PAR@ monitor-prop api.alsa.seq.min-pool = 500 # integer
@PAR@ monitor-prop api.alsa.seq.max-pool = 2000 # integer
@PAR@ monitor-prop clock.name = "clock.system.monotonic" # string
Clock to follow.
@PAR@ monitor-prop api.alsa.path = "default" # string
Sequencer device to use.
@PAR@ monitor-prop api.alsa.disable-longname = true # boolean
If card long name should not be passed to MIDI port.
# BLUETOOTH PROPERTIES @IDX@ props # BLUETOOTH PROPERTIES @IDX@ props
## Monitor properties ## Monitor properties

8
doc/dox/config/pipewire-pulse.conf.5.md
View file

@ -54,7 +54,7 @@ for the detailed description.
In addition, the PipeWire context configuration sections In addition, the PipeWire context configuration sections
may also be specified, 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 # STREAM PROPERTIES @IDX@ pipewire-pulse.conf stream.properties
The `stream.properties` section contains properties for streams created The `stream.properties` section contains properties for streams created
by the pipewire-pulse server. by the pipewire-pulse server.
@ -100,18 +100,18 @@ stream.properties = {
} }
``` ```
# STREAM RULES @IDX@ pipewire-pulse.conf # STREAM RULES @IDX@ pipewire-pulse.conf stream.rules
The `stream.rules` section works the same as The `stream.rules` section works the same as
\ref client_conf__stream_rules "pipewire-client.conf(5) stream.rules". \ref client_conf__stream_rules "pipewire-client.conf(5) stream.rules".
# PULSEAUDIO PROPERTIES @IDX@ pipewire-pulse.conf # PULSEAUDIO PROPERTIES @IDX@ pipewire-pulse.conf pulse.properties
For `pulse.properties` section, For `pulse.properties` section,
see \ref page_module_protocol_pulse "libpipewire-module-protocol-pulse(7)" see \ref page_module_protocol_pulse "libpipewire-module-protocol-pulse(7)"
for available options. for available options.
# PULSEAUDIO RULES @IDX@ pipewire-pulse.conf # PULSEAUDIO RULES @IDX@ pipewire-pulse.conf pulse.rules
For each client, a set of rules can be written in `pulse.rules` For each client, a set of rules can be written in `pulse.rules`
section to configure quirks of the client or to force some pulse section to configure quirks of the client or to force some pulse

16
doc/dox/config/pipewire.conf.5.md
View file

@ -140,7 +140,7 @@ Array of dictionaries. Match rules for modifying device properties
on the server. on the server.
# CONTEXT PROPERTIES @IDX@ pipewire.conf # CONTEXT PROPERTIES @IDX@ pipewire.conf context.properties
Available PipeWire properties in `context.properties` and possible Available PipeWire properties in `context.properties` and possible
default values. default values.
@ -302,7 +302,7 @@ the `context.modules` and `context.objects` sections can declare
additional conditions that control whether a module or object is loaded additional conditions that control whether a module or object is loaded
depending on what properties are present. depending on what properties are present.
# SPA LIBRARIES @IDX@ pipewire.conf # SPA LIBRARIES @IDX@ pipewire.conf context.spa-libs
SPA plugins are loaded based on their factory-name. This is a well SPA plugins are loaded based on their factory-name. This is a well
known name that uniquely describes the features that the plugin should known name that uniquely describes the features that the plugin should
@ -331,7 +331,7 @@ context.spa-libs = {
} }
``` ```
# MODULES @IDX@ pipewire.conf # MODULES @IDX@ pipewire.conf context.modules
PipeWire modules to be loaded. See PipeWire modules to be loaded. See
\ref page_man_libpipewire-modules_7 "libpipewire-modules(7)". \ref page_man_libpipewire-modules_7 "libpipewire-modules(7)".
@ -364,7 +364,7 @@ A \ref pipewire_conf__match_rules "match rule" `matches` condition.
The module is loaded only if one of the expressions in the array matches The module is loaded only if one of the expressions in the array matches
to a context property. to a context property.
# CONTEXT OBJECTS @IDX@ pipewire.conf # CONTEXT OBJECTS @IDX@ pipewire.conf context.objects
The `context.objects` section allows you to make some objects from factories (usually created The `context.objects` section allows you to make some objects from factories (usually created
by loading modules in `context.modules`). by loading modules in `context.modules`).
@ -417,7 +417,7 @@ context.objects = [
] ]
``` ```
# COMMAND EXECUTION @IDX@ pipewire.conf # COMMAND EXECUTION @IDX@ pipewire.conf context.exec
The `context.exec` section can be used to start arbitrary commands as The `context.exec` section can be used to start arbitrary commands as
part of the initialization of the PipeWire program. part of the initialization of the PipeWire program.
@ -590,7 +590,7 @@ matches = [
``` ```
# CONTEXT PROPERTIES RULES @IDX@ pipewire.conf # CONTEXT PROPERTIES RULES @IDX@ pipewire.conf context.properties.rules
`context.properties.rules` can be used to dynamically update the properties `context.properties.rules` can be used to dynamically update the properties
based on other properties. based on other properties.
@ -614,7 +614,7 @@ context.properties.rules = [
} }
``` ```
# NODE RULES @IDX@ pipewire.conf # NODE RULES @IDX@ pipewire.conf node.rules
The node.rules are evaluated every 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 or updated. This can be used on the server side to override client set
@ -647,7 +647,7 @@ node.rules = [
Will set the `node.force-quantum` property of `jack_simple_client` to 512. Will set the `node.force-quantum` property of `jack_simple_client` to 512.
# DEVICE RULES @IDX@ pipewire.conf # DEVICE RULES @IDX@ pipewire.conf device.rules
The device.rules are evaluated every 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 or updated. This can be used on the server side to override client set