mirror of
https://gitlab.freedesktop.org/pipewire/pipewire.git
synced 2025-10-29 05:40:27 -04:00
doc: add sections to index, clarify discussion of properties
Add some sections to index + fix typos and section levels. Clarify discussion of device properties.
This commit is contained in:
Pauli Virtanen
parent
3c27dcd868
commit
aec9bc5217
6 changed files with 72 additions and 36 deletions
|
|
@ -86,8 +86,4 @@ interfaces:
|
|||
|
||||
**Device properties**
|
||||
|
||||
@SECREF@ device-property
|
||||
|
||||
**Device parameters**
|
||||
|
||||
@SECREF@ device-param
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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 <id>` 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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue