mirror of
https://gitlab.freedesktop.org/pipewire/pipewire.git
synced 2025-10-29 05:40:27 -04:00
doc: document more properties
Also add examples for customizing properties.
This commit is contained in:
Pauli Virtanen
Wim Taymans
parent
35b3c8c279
commit
a346a7d42e
1 changed files with 94 additions and 12 deletions
|
|
@ -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
|
||||
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)".
|
||||
# CUSTOMIZING PROPERTIES @IDX@ props
|
||||
|
||||
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).
|
||||
|
||||
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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue