Miscellaneous Information Manual

NAME¶

pipewire-devices - pipewire-devices
PipeWire device and node property reference.

DESCRIPTION¶

Audio sinks and sources, cameras, Bluetooth endpoints, and other objects have properties that can be set in configuration files or at runtime.

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 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 context.objects in pipewire.conf(5).

RUNTIME SETTINGS¶

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:

{
...


      "Props": [


        {


          ...


          "params": [


              "audio.channels",


              2,


              "audio.rate",


              0,


              "audio.format",


              "UNKNOWN",


              "audio.position",


              "[ FL, FR ]",


              "audio.allowed-rates",


              "[  ]",


              "api.alsa.period-size",


              0,


              "api.alsa.period-num",


              0,


              "api.alsa.headroom",


              0,


              "api.alsa.start-delay",


              0,


              "api.alsa.disable-mmap",


              false,


              "api.alsa.disable-batch",


              false,


              "api.alsa.use-chmap",


              false,


              "api.alsa.multi-rate",


              true,


              "latency.internal.rate",


              0,


              "latency.internal.ns",


              0,


              "clock.name",


              "api.alsa.c-1"


            ]


          }
...

One or more params can be changed using pw-cli(1):

pw-cli s <id> Props '{ params = [ "api.alsa.headroom" 1024 ] }'

These settings are not saved and need to be reapplied for each session manager restart.

COMMON NODE PROPERTIES¶

The properties listed in Stream properties apply also to sink or source nodes corresponding to real or virtual devices.

In addition:

priority.driver # integer

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.

priority.session # integer

The priority for selecting this device as the default device.

clock.name # string

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.

In Pro Audio mode, nodes from the same device are assumed to have the same clock and no resampling will happen when linked together. So, linking a capture port to a playback port will not use any adaptive resampling in Pro Audio mode.

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.

node.param.PARAM = JSON # JSON

Set value of a node Param to a JSON value when the device is loaded. This works similarly as 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.

device.id

ID of the device the node belongs to.

COMMON DEVICE PROPERTIES¶

These are common properties for devices.

device.name # string

A (unique) name for the device. It can be used by command-line and other tools to identify the device.

device.param.PARAM = JSON # JSON

Set value of a device Param to a JSON value when the device is loaded. This works similarly as 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.

Other device.* properties: UNDOCUMENTED

AUDIO CONVERTER PROPERTIES¶

Most audio nodes (ALSA, Bluetooth, ...) have common properties for the audio converter. See pipewire-client.conf(5) stream.properties for explanations.