mirror of
https://gitlab.freedesktop.org/pipewire/pipewire.git
synced 2025-10-29 05:40:27 -04:00
doc: improve property documentation
Add some more examples, and more xref links to index.
This commit is contained in:
Pauli Virtanen
Wim Taymans
parent
98b7a34102
commit
bde2aa34ef
5 changed files with 91 additions and 43 deletions
|
|
@ -48,7 +48,7 @@ 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
|
||||
# STREAM PROPERTIES @IDX@ client.conf stream.properties
|
||||
|
||||
The client configuration files contain a stream.properties section that configures the options for client streams:
|
||||
```css
|
||||
|
|
@ -93,7 +93,7 @@ A list of object properties that can be applied to streams can be found in
|
|||
and
|
||||
\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)"
|
||||
to set properties for certain streams and filters.
|
||||
|
|
@ -127,7 +127,7 @@ stream.rules = [
|
|||
|
||||
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
|
||||
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
|
||||
`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
|
||||
\ref pipewire_conf__match_rules "Match rules, see pipewire(1)". You can
|
||||
|
|
|
|||
|
|
@ -38,7 +38,7 @@ 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
|
||||
# JACK PROPERTIES @IDX@ jack.conf jack.properties
|
||||
|
||||
The configuration file can contain an extra JACK specific section called `jack.properties` like this:
|
||||
```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.
|
||||
\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
|
||||
on the client and node object of the jack client.
|
||||
|
|
|
|||
|
|
@ -41,32 +41,19 @@ objects.
|
|||
Usually, all device properties are configured in the session manager
|
||||
configuration, see the session manager documentation.
|
||||
Application properties are configured in
|
||||
``client.conf`` (for native PipeWire and ALSA applications), and
|
||||
``pipewire-pulse.conf`` (for Pulseaudio applications).
|
||||
``client.conf`` (for native PipeWire and ALSA applications),
|
||||
``pipewire-pulse.conf`` (for Pulseaudio applications), and
|
||||
``jack.conf`` (for JACK 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):
|
||||
Device configuration using WirePlumber (requires WirePlumber restart to apply).
|
||||
See [WirePlumber configuration](https://pipewire.pages.freedesktop.org/wireplumber/daemon/configuration.html)
|
||||
```css
|
||||
# ~/.config/wireplumber/wireplumber.conf.d/custom-props.conf
|
||||
|
||||
|
|
@ -77,14 +64,18 @@ monitor.alsa.properties = {
|
|||
monitor.alsa.rules = [
|
||||
{
|
||||
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" } ]
|
||||
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 = {
|
||||
bluez5.hfphsp-backend = ofono
|
||||
}
|
||||
|
|
@ -92,12 +83,49 @@ monitor.bluez.properties = {
|
|||
monitor.bluez.rules = [
|
||||
{
|
||||
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
|
||||
|
||||
|
|
@ -106,9 +134,6 @@ 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.
|
||||
|
|
@ -901,6 +926,29 @@ Informative property.
|
|||
\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
|
||||
|
||||
## Monitor properties
|
||||
|
|
|
|||
|
|
@ -54,7 +54,7 @@ for the detailed description.
|
|||
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
|
||||
# STREAM PROPERTIES @IDX@ pipewire-pulse.conf stream.properties
|
||||
|
||||
The `stream.properties` section contains properties for streams created
|
||||
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
|
||||
\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,
|
||||
see \ref page_module_protocol_pulse "libpipewire-module-protocol-pulse(7)"
|
||||
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`
|
||||
section to configure quirks of the client or to force some pulse
|
||||
|
|
|
|||
|
|
@ -140,7 +140,7 @@ Array of dictionaries. Match rules for modifying device properties
|
|||
on the server.
|
||||
|
||||
|
||||
# CONTEXT PROPERTIES @IDX@ pipewire.conf
|
||||
# CONTEXT PROPERTIES @IDX@ pipewire.conf context.properties
|
||||
|
||||
Available PipeWire properties in `context.properties` and possible
|
||||
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
|
||||
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
|
||||
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
|
||||
\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
|
||||
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
|
||||
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
|
||||
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
|
||||
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
|
||||
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.
|
||||
|
||||
# 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
|
||||
or updated. This can be used on the server side to override client set
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue