pipewire-props(7) - Man pages

dwww Home | Manual pages | Find package

pipewire-props(7) Miscellaneous Information Manual pipewire-props(7)

NAME
pipewire-props - PipeWire object property reference.

DESCRIPTION
PipeWire describes and configures audio and video elements with objects
of the following main types:

Node
Audio or video sink/source endpoint

Device
Sound cards, bluetooth devices, cameras, etc. May have multiple
nodes.

Monitor
Finding devices and handling hotplugging

Port
Audio/video endpoint in a node

Link
Connection between ports, that transporting audio/video between
them.

Client
Application connected to PipeWire.

All objects have properties ('props'), most of which can be set in
configuration files or at runtime when the object is created.

Some of the properties are 'common properties' (for example
node.description) and can be set on all objects of the given 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 context.objects in pipewire.conf(5).

See also
WirePlumber configuration

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
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.

device.plugged # integer

when the device was created.

As a uint64 in nanoseconds.

device.nick # string

a short device nickname

device.description # string

localized human readable device one-line description.

Ex. 'Foobar USB Headset'

device.serial # string

Serial number if applicable.

device.vendor.id # integer

vendor ID if applicable

device.vendor.name # string

vendor name if applicable

device.product.id # integer

product name if applicable

device.product.name # string

product ID if applicable

device.class # string

device class

device.form-factor # string

form factor if applicable.

One of 'internal', 'speaker', 'handset', 'tv', 'webcam',
'microphone', 'headset', 'headphone', 'hands-free', 'car', 'hifi',
'computer', 'portable'

device.icon # string

icon for the device.

A base64 blob containing PNG image data

device.icon-name # string

an XDG icon name for the device.

Ex. 'sound-card-speakers-usb'

device.intended-roles # string

intended use.

A space separated list of roles (see media.role) this device is
particularly well suited for, due to latency, quality or form
factor.

device.disabled = false # boolean
Disable the creation of this device in session manager.

There are other common device.* properties for technical purposes and
not usually user-configurable.

See also
Key Names in the API documentation for a full list.

COMMON NODE PROPERTIES
The properties here apply to general audio or video input/output
streams, and other nodes such as sinks or sources corresponding to real
or virtual devices.

Identifying Properties
These contain properties to identify the node or to display the node in
a GUI application.

node.name
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.

node.description
A human readable description of the node or stream.

media.name
A user readable media name, usually the artist and title. These are
usually shown in user facing applications to inform the user about
the current playing media.

media.title
A user readable stream title.

media.artist
A user readable stream artist

media.copyright
User readable stream copyright information

media.software
User readable stream generator software information

media.language
Stream language in POSIX format. Ex: en_GB

media.filename
File name for the stream

media.icon
Icon for the media, a base64 blob with PNG image data

media.icon-name
An XDG icon name for the media. Ex: audio-x-mp3

media.comment
Extra stream comment

media.date
Date of the media

media.format
User readable stream format information

object.linger = false
If the object should outlive its creator.

device.id
ID of the device the node belongs to.

Classifying Properties
The classifying properties of a node are use for routing the signal to
its destination and for configuring the settings.

media.type
The media type contains a broad category of the media that is being
processed by the node. Possible values include 'Audio', 'Video',
'Midi'

media.category
What kind of processing is done with the media. Possible values
include:

• Playback: media playback.

• Capture: media capture.

• Duplex: media capture and playback or media processing in general.

• Monitor: a media monitor application. Does not actively change
media data but monitors activity.

• Manager: Will manage the media graph.

media.role
The Use case of the media. Possible values include:

• Movie: Movie playback with audio and video.

• Music: Music listening.

• Camera: Recording video from a camera.

• Screen: Recording or sharing the desktop screen.

• Communication: VOIP or other video chat application.

• Game: Game.

• Notification: System notification sounds.

• DSP: Audio or Video filters and effect processing.

• Production: Professional audio processing and production.

• Accessibility: Audio and Visual aid for accessibility.

• Test: Test program.

media.class
The media class is to classify the stream function. Possible values
include:

• Video/Source: a producer of video, like a webcam.

• Video/Sink: a consumer of video, like a display window.

• Audio/Source: a source of audio samples like a microphone.

• Audio/Sink: a sink for audio samples, like an audio card.

• Audio/Duplex: a node that is both a sink and a source.

• Stream/Output/Audio: a playback stream.

• Stream/Input/Audio: a capture stream.

The session manager assigns special meaning to the nodes based on
the media.class. Sink or Source classes are used as targets for
Stream classes, etc..

Scheduling Properties
node.latency = 1024/48000
Sets a suggested latency on the node as a fraction. This is just a
suggestion, the graph will try to configure this latency or less for
the graph. It is however possible that the graph is forced to a
higher latency.

node.lock-quantum = false
When this node is active, the quantum of the graph is locked and not
allowed to change automatically. It can still be changed forcibly
with metadata or when a node forces a quantum.

JACK clients use this property to avoid unexpected quantum changes.

node.force-quantum = INTEGER
While the node is active, force a quantum in the graph. The last
node to be activated with this property wins.

A value of 0 unforces the quantum.

node.rate = RATE
Suggest a rate (samplerate) for the graph. The suggested rate will
only be applied when doing so would not cause interruptions (devices
are idle) and when the rate is in the list of allowed rates in the
server.

node.lock-rate = false
When the node is active, the rate of the graph will not change
automatically. It is still possible to force a rate change with
metadata or with a node property.

node.force-rate = RATE
When the node is active, force a specific sample rate on the graph.
The last node to activate with this property wins.

A RATE of 0 means to force the rate in node.rate denominator.

node.always-process = false
When the node is active, it will always be joined with a driver
node, even when nothing is linked to the node. Setting this property
to true also implies node.want-driver = true.

This is the default for JACK nodes, that always need their process
callback called.

node.want-driver = true
The node wants to be linked to a driver so that it can start
processing. This is the default for streams and filters since
0.3.51. Nodes that are not linked to anything will still be set to
the idle state, unless node.always-process is set to true.

node.pause-on-idle = false

node.suspend-on-idle = false
When the node is not linked anymore, it becomes idle. Normally idle
nodes keep processing and are suspended by the session manager after
some timeout. It is possible to immediately pause a node when idle
with this property.

When the session manager does not suspend nodes (or when there is no
session manager), the node.suspend-on-idle property can be used
instead.

node.loop.name = null

node.loop.class = data.rt
Add the node to a specific loop name or loop class. By default the
node is added to the data.rt loop class. You can make more specific
data loops and then assign the nodes to those.

Other well known names are main-loop.0 and the main node.loop.class
which runs the node data processing in the main loop.

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.

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.

Session Manager Properties
node.autoconnect = true
Instructs the session manager to automatically connect this node to
some other node, usually a sink or source.

node.exclusive = false
If this node wants to be linked exclusively to the sink/source.

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.

target.object = <node.name|object.serial>
Where the node should link to, this can be a node.name or an
object.serial.

node.dont-reconnect = false
When the node has a target configured and the target is destroyed,
destroy the node as well. This property also inhibits that the node
is moved to another sink/source.

Note that if a stream should appear/disappear in sync with the
target, a session manager (WirePlumber) script should be written
instead.

node.passive = false
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).

This is used for filter nodes that sit in front of sinks/sources and
need to suspend together with the sink/source.

node.link-group = ID
Add the node to a certain link group. Nodes from the same link group
are not automatically linked to each other by the session manager.
And example is a coupled stream where you don't want the output to
link to the input streams, making a useless loop.

stream.dont-remix = false
Instruct the session manager to not remix the channels of a stream.
Normally the stream channel configuration is changed to match the
sink/source it is connected to. With this property set to true, the
stream will keep its original channel layout and the session manager
will link matching channels with the sink.

priority.session # integer
The priority for selecting this node as the default source or sink.

Format Properties
Streams and also most device nodes can be configured in a certain format
with properties.

audio.rate = RATE
Forces a samplerate on the node.

audio.channels = INTEGER
The number of audio channels to use. Must be a value between 1 and
64.

audio.format = FORMAT
Forces an audio format on the node. This is the format used
internally in the node because the graph processing format is always
float 32.

Valid formats include: S16, S32, F32, F64, S16LE, S16BE, ...

audio.allowed-rates
An array of allowed samplerates for the node. ex. '[ 44100 48000 ]'

Other Properties
node.param.PARAM = { ... } # 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.

node.disabled = false # boolean
Disable the creation of this node in session manager.

AUDIO ADAPTER PROPERTIES
Most audio nodes (ALSA, Bluetooth, audio streams from applications, ...)
have common properties for the audio adapter. The adapter performs
sample format, sample rate and channel mixing operations.

All properties listed below are node properties.

Merger Parameters
The merger is used as the input for a sink device node or a capture
stream. It takes the various channels and merges them into a single
stream for further processing.

The merger will also provide the monitor ports of the input channels and
can apply a software volume on the monitor signal.

monitor.channel-volumes = false
The volume of the input channels is applied to the volume of the
monitor ports. Normally the monitor ports expose the raw unmodified
signal on the input ports.

Resampler Parameters
Source, sinks, capture and playback streams contain a high quality
adaptive resampler. It uses sinc based resampling with linear
interpolation of filter banks to perform arbitrary resample factors. The
resampler is activated in the following cases:

• The hardware of a device node does not support the graph samplerate.
Resampling will occur from the graph samplerate to the hardware
samplerate.

• The hardware clock of a device does not run at the same speed as the
graph clock and adaptive resampling is required to match the clocks.

• A stream does not have the same samplerate as the graph and needs to
be resampled.

• An application wants to activate adaptive resampling in a stream to
make it match some other clock.

PipeWire performs most of the sample conversions and resampling in the
client (Or in the case of the PulseAudio server, in the pipewire-pulse
server that creates the streams). This ensures all the conversions are
offloaded to the clients and the server can deal with one single format
for performance reasons.

Below is an explanation of the options that can be tuned in the sample
converter.

resample.quality = 4
The quality of the resampler. from 0 to 14, the default is 4.

Increasing the quality will result in better cutoff and less
aliasing at the expense of (much) more CPU consumption. The default
quality of 4 has been selected as a good compromise between quality
and performance with no artifacts that are well below the audible
range.

See Infinite Wave for a comparison of the performance.

resample.disable = false
Disable the resampler entirely. The node will only be able to
negotiate with the graph when the samplerates are compatible.

Channel Mixer Parameters
Source, sinks, capture and playback streams can apply channel mixing on
the incoming signal.

Normally the channel mixer is not used for devices, the device channels
are usually exposed as they are. This policy is usually enforced by the
session manager, so we refer to its documentation there.

Playback and capture streams are usually configured to the channel
layout of the sink/source they connect to and will thus perform channel
mixing.

The channel mixer also implements a software volume. This volume
adjustment is performed on the original channel layout. ex: A stereo
playback stream that is up-mixed to 5.1 has 2 a left an right volume
control.

channelmix.disable = false
Disables the channel mixer completely. The stream will only be able
to link to compatible sources/sinks with the exact same channel
layout.

channelmix.min-volume = 0.0

channelmix.max-volume = 10.0
Gives the min and max volume values allowed. Any volume that is set
will be clamped to these values.

channelmix.normalize = false
Makes sure that during such mixing & resampling original 0 dB level
is preserved, so nothing sounds wildly quieter/louder.

While this options prevents clipping, it can in some cases produce
too low volume. Increase the volume in that case or disable
normalization.

channelmix.lock-volumes = false
Completely disable volume or mute changes. Defaults to false.

channelmix.mix-lfe = true
Mixes the low frequency effect channel into the front center or
stereo pair. This might enhance the dynamic range of the signal if
there is no subwoofer and the speakers can reproduce the low
frequency signal.

channelmix.upmix = true
Enables up-mixing of the front center (FC) when the target has a FC
channel. The sum of the stereo channels is used and an optional
lowpass filter can be used (see channelmix.fc-cutoff).

Also enabled up-mixing of LFE when channelmix.lfe-cutoff is set to
something else than 0 and the target has an LFE channel. The LFE
channel is produced by adding the stereo channels.

If channelmix.upmix is true, the up-mixing of the rear channels is
also enabled and controlled with the channelmix-upmix-method
property.

channelmix.upmix-method = psd
3 methods are provided to produce the rear channels in a surround
sound:

1. none. No rear channels are produced.

2. simple. Front channels are copied to the rear. This is fast but
can produce phasing effects.

3. psd. The rear channels as produced from the front left and right
ambient sound (the difference between the channels). A delay and
optional phase shift are added to the rear signal to make the
sound bigger.

channelmix.lfe-cutoff = 150
Apply a lowpass filter to the low frequency effects. The value is
expressed in Hz. Typical subwoofers have a cutoff at around 150 and
200. The default value of 0 disables the feature.

channelmix.fc-cutoff = 12000
Apply a lowpass filter to the front center frequency. The value is
expressed in Hz.

Since the front center contains the dialogs, a typical cutoff
frequency is 12000 Hz.

This option is only active when the up-mix is enabled.

channelmix.rear-delay = 12.0
Apply a delay in milliseconds when up-mixing the rear channels. This
improves specialization of the sound. A typical delay of 12
milliseconds is the default.

This is only active when the psd up-mix method is used.

channelmix.stereo-widen = 0.0
Subtracts some of the front center signal from the stereo channels.
This moves the dialogs more to the center speaker and leaves the
ambient sound in the stereo channels.

This is only active when up-mix is enabled and a Front Center
channel is mixed.

channelmix.hilbert-taps = 0
This option will apply a 90 degree phase shift to the rear channels
to improve specialization. Taps needs to be between 15 and 255 with
more accurate results (and more CPU consumption) for higher values.

This is only active when the psd up-mix method is used.

dither.noise = 0
This option will add N bits of random data to the signal. When no
dither.method is specified, the random data will flip between
[-(1<<(N-1)), 0] every 1024 samples. With a dither.method, the
dither noise is amplified with 1<<(N-1) bits.

This can be used to keep some amplifiers alive during silent
periods. One or two bits of noise is usually enough, otherwise the
noise will become audible. This is usually used together with
session.suspend-timeout-seconds to disable suspend in the session
manager.

Note that PipeWire uses floating point operations with 24 bits
precission for all of the audio processing. Conversion to 24 bits
integer sample formats is lossless and conversion to 32 bits integer
sample formats are simply padded with 0 bits at the end. This means
that the dither noise is always only in the 24 most significant
bits.

dither.method = none
Optional dithering can be done on the quantized output signal.

There are 6 modes available:

1. none No dithering is done.

2. rectangular Dithering with a rectangular noise distribution.
This adds random bits in the [-0.5, 0.5] range to the signal
with even distribution.

3. triangular Dithering with a triangular noise distribution. This
add random bits in the [-1.0, 1.0] range to the signal with
triangular distribution around 0.0.

4. triangular-hf Dithering with a sloped triangular noise
distribution.

5. wannamaker3 Additional noise shaping is performed on the sloped
triangular dithering to move the noise to the more inaudible
range. This is using the 'F-Weighted' noise filter described by
Wannamaker.

6. shaped5 Additional noise shaping is performed on the triangular
dithering to move the noise to the more inaudible range. This is
using the Lipshitz filter.

Dithering is only useful for conversion to a format with less than
24 bits and will be disabled otherwise.

Debug Parameters
debug.wav-path = ''
Make the stream to also write the raw samples to a WAV file for
debugging purposes.

Other Parameters
These control low-level technical features:

clock.quantum-limit
See pipewire.conf(5)

resample.peaks = false # boolean
Instead of actually resampling, produce peak amplitude values as
output. This is used for volume monitoring, where it is set as a
property of the 'recording' stream.

resample.prefill = false # boolean
Prefill resampler buffers with silence. This affects the initial
samples produced by the resampler.

adapter.auto-port-config = null # JSON
If specified, configure the ports of the node when it is created,
instead of leaving that to the session manager to do. This is useful
(only) for minimal configurations without a session manager.

Value is SPA JSON of the form:

{
mode = "none", # "none", "passthrough", "convert", "dsp"
monitor = false, # boolean
control = false, # boolean
position = "preserve" # "unknown", "aux", "preserve"
}

See spa_param_port_config for the meaning.

ALSA PROPERTIES
Monitor properties
alsa.use-acp # boolean
Use ALSA Card Profiles (ACP) for device configuration.

alsa.udev.expose-busy # boolean
Expose the ALSA card even if it is busy/in use. Default false. This
can be useful when some of the PCMs are in use by other applications
but the other free PCMs should still be exposed.

Device properties
api.alsa.path # string
ALSA device path as can be used in snd_pcm_open() and
snd_ctl_open().

api.alsa.use-ucm = true # boolean
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.

api.alsa.soft-mixer = false # boolean
Setting this option to true will disable the hardware mixer for
volume control and mute. All volume handling will then use software
volume and mute, leaving the hardware mixer untouched. This can be
interesting to work around bugs in the mixer detection or decibel
reporting. The hardware mixer will still be used to mute unused
audio paths in the device. Use api.alsa.disable-mixer-path to also
disable mixer path selection.

api.alsa.disable-mixer-path = false # boolean
Setting this option to true will disable the hardware mixer path
selection. The hardware mixer path is the configuration of the mixer
depending on the jacks that are inserted in the card. If this is
disabled, you will have to manually enable and disable mixer
controls but it can be used to work around bugs in the mixer. The
hardware mixer will still be used for volume and mute. Use
api.alsa.soft-mixer to also disable hardware volume and mute.

api.alsa.ignore-dB = false # boolean
Setting this option to true will ignore the decibel setting
configured by the driver. Use this when the driver reports wrong
settings.

device.profile-set # string
This option can be used to select a custom ACP profile-set name for
the device. This can be configured in UDev rules, but it can also be
specified here. The default is to use 'default.conf' unless there is
a matching udev rule.

device.profile # string
The initial active profile name. The default is to start from the
'Off' profile and then let session manager select the best profile
based on its policy.

api.acp.auto-profile = true # boolean
Automatically select the best profile for the device. The session
manager usually disables this, as it handles this task instead. This
can be enabled in custom configurations without the session manager
handling this.

api.acp.auto-port = true # boolean
Automatically select the highest priority port that is available
('port' is a PulseAudio/ACP term, the equivalent of a 'Route' in
PipeWire). The session manager usually disables this, as it handles
this task instead. This can be enabled in custom configurations
without the session manager handling this.

api.acp.probe-rate # integer
Sets the samplerate used for probing the ALSA devices and collecting
the profiles and ports.

api.acp.pro-channels # integer
Sets the number of channels to use when probing the 'Pro Audio'
profile. Normally, the maximum amount of channels will be used but
with this setting this can be reduced, which can make it possible to
use other samplerates on some devices.

api.alsa.split-enable # boolean

For UCM devices with split PCMs, don't split to multiple PCMs using
alsa-lib plugins, but instead add api.alsa.split properties to
emitted nodes with PCM splitting information.

Node properties
audio.channels # integer
The number of audio channels to open the device with. Defaults
depends on the profile of the device.

audio.rate # integer
The audio rate to open the device with. Default is 0, which means to
open the device with a rate as close to the graph rate as possible.

audio.format # string
The audio format to open the device in. By default this is
'UNKNOWN', which will open the device in the best possible bits
(32/24/16/8..). You can force a format like S16_LE or S32_LE.

audio.position # JSON array of strings
The audio position of the channels in the device. This is auto
detected based on the profile. You can configure an array of channel
positions, like '[ FL, FR ]'.

audio.allowed-rates # JSON array of integers
The allowed audio rates to open the device with. Default is '[ ]',
which means the device can be opened in any supported rate.

Only rates from the array will be used to open the device. When the
graph is running with a rate not listed in the allowed-rates, the
resampler will be used to resample to the nearest allowed rate.

api.alsa.period-size # integer
The period size to open the device in. By default this is 0, which
will open the device in the default period size to minimize latency.

api.alsa.period-num # integer
The amount of periods to use in the device. By default this is 0,
which means to use as many as possible.

api.alsa.headroom # integer
The amount of extra space to keep in the ringbuffer. The default is
0. Higher values can be configured when the device read and write
pointers are not accurately reported.

api.alsa.start-delay = 0 # integer
Some devices need some time before they can report accurate hardware
pointer positions. In those cases, an extra start delay can be added
to compensate for this startup delay. This sets the startup delay in
samples.

api.alsa.disable-mmap = false # boolean
Disable mmap operation of the device and use the ALSA read/write API
instead. Default is false, mmap is preferred.

api.alsa.disable-batch # boolean
Ignore the ALSA batch flag. If the batch flag is set, ALSA will need
an extra period to update the read/write pointers. Ignore this flag
from ALSA can reduce the latency. Default is false.

api.alsa.use-chmap # boolean
Use the driver provided channel map. Default is true when using UCM,
false otherwise because many driver don't report this correctly.

api.alsa.multi-rate # boolean
Allow devices from the same card to be opened in multiple sample
rates. Default is true. Some older drivers did not properly
advertise the capabilities of the device and only really supported
opening the device in one rate.

api.alsa.htimestamp = false # boolean
Use ALSA htimestamps in scheduling, instead of the system clock.
Some ALSA drivers produce bad timestamps, so this is not enabled by
default and will be disabled at runtime if it looks like the ALSA
timestamps are bad.

api.alsa.htimestamp.max-errors # integer
Specify the number of consecutive errors before htimestamp is
disabled. Setting this to 0 makes htimestamp never get disabled.

api.alsa.disable-tsched = false # boolean
Disable timer-based scheduling, and use IRQ for scheduling instead.
The 'Pro Audio' profile will usually enable this setting, if it is
expected it works on the hardware.

api.alsa.auto-link = false # boolean
Link follower PCM devices to the driver PCM device when using IRQ-
based scheduling. The 'Pro Audio' profile will usually enable this
setting, if it is expected it works on the hardware.

latency.internal.rate # integer
Static set the device systemic latency, in samples at playback rate.

latency.internal.ns # integer
Static set the device systemic latency, in nanoseconds.

api.alsa.path # string
UNDOCUMENTED

api.alsa.open.ucm # boolean
Open device using UCM.

api.alsa.bind-ctls # boolean
UNDOCUMENTED

iec958.codecs # JSON array of string
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

api.alsa.split.parent # boolean

PCM is UCM SplitPCM parent PCM, to be opened with SplitPCM set.

api.alsa.split.position # JSON

(SPA JSON list) If present, this is a virtual device corresponding
to a subset of channels in an underlying PCM, listed in this
property. Informative property.

api.alsa.split.hw-position # JSON

(SPA JSON list) Channel map of the underlying split PCM.
Informative property.

BLUETOOTH PROPERTIES
Monitor properties
The following are settings for the Bluetooth device monitor, not device
or node properties:

bluez5.roles = [ a2dp_sink a2dp_source bap_sink bap_source
bap_bcast_sink bap_bcast_source hfp_hf hfp_ag ] # JSON array of string
Enabled roles.

Currently some headsets (Sony WH-1000XM3) are not working with both
hsp_ag and hfp_ag enabled, so by default we enable only HFP.

Supported roles:

• hsp_hs (HSP Headset),

• hsp_ag (HSP Audio Gateway),

• hfp_hf (HFP Hands-Free),

• hfp_ag (HFP Audio Gateway)

• a2dp_sink (A2DP Audio Sink)

• a2dp_source (A2DP Audio Source)

• bap_sink (LE Audio Basic Audio Profile Sink)

• bap_source (LE Audio Basic Audio Profile Source)

• bap_bcast_sink (LE Audio Basic Audio Profile Broadcast Sink)

• bap_bcast_source (LE Audio Basic Audio Profile Broadcast Source)

bluez5.codecs # JSON array of string
Enabled A2DP codecs (default: all). Possible values: sbc, sbc_xq,
aac, aac_eld, aptx, aptx_hd, aptx_ll, aptx_ll_duplex, faststream,
faststream_duplex, lc3plus_h3, ldac, opus_05, opus_05_51,
opus_05_71, opus_05_duplex, opus_05_pro, opus_g, lc3.

bluez5.default.rate # integer
Default audio rate.

bluez5.default.channels # integer
Default audio channels.

bluez5.hfphsp-backend # integer
HFP/HSP backend (default: native). Available values: any, none,
hsphfpd, ofono, native

bluez5.hfphsp-backend-native-modem # string

bluez5.dummy-avrcp player # boolean
Register dummy AVRCP player. Some devices have wrongly functioning
volume or playback controls if this is not enabled. Default: false

bluez5.enable-sbc-xq # boolean
Override device quirk list and enable SBC-XQ for devices for which
it is disabled.

bluez5.enable-msbc # boolean
Override device quirk list and enable MSBC for devices for which it
is disabled.

bluez5.enable-hw-volume # boolean
Override device quirk list and enable hardware volume fo devices for
which it is disabled.

bluez5.hw-offload-sco # boolean
HFP/HSP hardware offload SCO support (default: false).

This feature requires a custom configuration that routes SCO audio
to ALSA nodes, in a platform-specific way. See tests/examples/bt-
pinephone.lua in WirePlumber for an example. Do not enable this
setting if you don't know what all this means, as it won't work.

bluez5.a2dp.opus.pro.channels = 3 # integer
PipeWire Opus Pro audio profile channel count.

bluez5.a2dp.opus.pro.coupled-streams = 1 # integer
PipeWire Opus Pro audio profile coupled stream count.

bluez5.a2dp.opus.pro.locations = 'FL,FR,LFE' # string
PipeWire Opus Pro audio profile audio channel locations.

bluez5.a2dp.opus.pro.max-bitrate = 600000 # integer
PipeWire Opus Pro audio profile max bitrate.

bluez5.a2dp.opus.pro.frame-dms = 50 # integer
PipeWire Opus Pro audio profile frame duration (1/10 ms).

bluez5.a2dp.opus.pro.bidi.channels = 1 # integer
PipeWire Opus Pro audio profile duplex channels.

bluez5.a2dp.opus.pro.bidi.coupled-streams = 0 # integer
PipeWire Opus Pro audio profile duplex coupled stream count.

bluez5.a2dp.opus.pro.bidi.locations = 'FC' # string
PipeWire Opus Pro audio profile duplex coupled channel locations.

bluez5.a2dp.opus.pro.bidi.max-bitrate = 160000 # integer
PipeWire Opus Pro audio profile duplex max bitrate.

bluez5.a2dp.opus.pro.bidi.frame-dms = 400 # integer
PipeWire Opus Pro audio profile duplex frame duration (1/10 ms).

bluez5.bcast_source.config = [] # JSON
Example:

bluez5.bcast_source.config = [
{
"broadcast_code": "Børne House",
"encryption: false,
"sync_factor": 2,
"bis": [
{ # BIS configuration
"qos_preset": "16_2_1", # QOS preset name from table Table 6.4 from BAP_v1.0.1.
"audio_channel_allocation": 1, # audio channel allocation configuration for the BIS
"metadata": [ # metadata configurations for the BIS
{ "type": 1, "value": [ 1, 1 ] }
]
}
]
}
]

bluez5.bap-server-capabilities.rates # Array of integers
Supported sampling frequencies for the LC3 codec (default: all).
Possible values: 8000, 16000, 24000, 32000, 44100, 48000

bluez5.bap-server-capabilities.durations # Array of doubles
Supported frame durations for the LC3 codec (default: all). Possible
values: 7.5, 10

bluez5.bap-server-capabilities.channels # Array of integers
Supported audio channel counts for the LC3 codec (default: [1, 2]).
Possible values: 1, 2, 3, 4, 5, 6, 7, 8

bluez5.bap-server-capabilities.framelen_min # integer
Minimum number of octets supported per codec frame for the LC3 codec
(default: 20).

bluez5.bap-server-capabilities.framelen_max # integer
Maximum number of octets supported per codec frame for the LC3 codec
(default: 400).

bluez5.bap-server-capabilities.max_frames # integer
Maximum number of codec frames supported per SDU for the LC3 codec
(default: 2).

Device properties
bluez5.auto-connect # boolean
Auto-connect devices on start up. Disabled by default if the
property is not specified.

bluez5.hw-volume = [ hfp_ag hsp_ag a2dp_source ] # JSON array of string
Profiles for which to enable hardware volume control.

bluez5.profile # string
Initial device profile. This usually has no effect as the session
manager overrides it.

bluez5.a2dp.ldac.quality = 'auto' # string
LDAC encoding quality Available values:

• auto (Adaptive Bitrate, default)

• hq (High Quality, 990/909kbps)

• sq (Standard Quality, 660/606kbps)

• mq (Mobile use Quality, 330/303kbps)

bluez5.a2dp.aac.bitratemode = 0 # integer
AAC variable bitrate mode. Available values: 0 (cbr, default), 1-5
(quality level)

bluez5.a2dp.opus.pro.application = 'audio' # string
PipeWire Opus Pro Audio encoding mode: audio, voip, lowdelay

bluez5.a2dp.opus.pro.bidi.application = 'audio' # string
PipeWire Opus Pro Audio duplex encoding mode: audio, voip, lowdelay

bluez5.bap.cig = 'auto' # integer, or 'auto'
Set CIG ID for BAP unicast streams of the device.

Node properties
bluez5.media-source-role # string
Media source role for Bluetooth clients connecting to this instance.
Available values:

• playback: playing stream to speakers

• input: appear as source node.

PORT PROPERTIES
Port properties are usually not directly configurable via PipeWire
configuration files, as they are determined by applications creating
them. Below are some port properties may interesting for users:

port.name # string

port name

port.alias # string

port alias

See also
Key Names in the API documentation for a full list.

LINK PROPERTIES
Link properties are usually not directly configurable via PipeWire
configuration files, as they are determined by applications creating
them.

See also
Key Names in the API documentation for a full list.

CLIENT PROPERTIES
Client properties are usually not directly configurable via PipeWire
configuration files, as they are determined by the application
connecting to PipeWire. Clients are however affected by the settings in
pipewire.conf(5) and session manager settings.

Note
Only the properties pipewire.* are safe to use for security purposes
such as identifying applications and their capabilities, as clients
can set and change other properties freely.

Below are some client properties may interesting for users.

application.name # string

application keys

application name. Ex: 'Totem Music Player'

application.process.id # integer

process id (pid)

pipewire.sec.pid # integer
Client pid, set by protocol.

Note that for PulseAudio applications, this is the PID of the
pipewire-pulse process.

See also
Key Names in the API documentation for a full list.

RUNTIME SETTINGS
Objects such as devices and nodes also have parameters that can be
modified after the object has been created. For example, the active
device profile, channel volumes, and so on.

For some objects, the parameters also allow changing some of the
properties. The settings of most ALSA and virtual device parameters can
be configured also at runtime.

These settings are available in device parameter called Props in its
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"
]
}
...

They generally have the same names and meaning as the corresponding
properties.

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.

ALSA CARD PROFILES
The sound card profiles ('Analog stereo', 'Analog stereo duplex', ...)
except 'Pro Audio' come from two sources:

• UCM: ALSA Use Case Manager: the profile configuration system from
ALSA. See https://github.com/alsa-project/alsa-ucm-conf/

• ACP ('Alsa Card Profiles'): Pulseaudio's profile system ported to
PipeWire. See
https://www.freedesktop.org/wiki/Software/PulseAudio/Backends/ALSA/Profiles/

See the above links on how to configure these systems.

For ACP, PipeWire looks for the profile configuration files under

• ~/.config/alsa-card-profile

• /etc/alsa-card-profile

• /usr/share/alsa-card-profile/mixer`.

The path and profile-set files are in subdirectories paths and profile-
sets of these directories. It is possible to override individual files
locally by putting a modified copy into the ACP directories under
~/.config or /etc.

OTHER OBJECT TYPES
Technically, PipeWire objects is what are manipulated by applications
using the PipeWire API.

The list of object types that are usually 'exported' (i.e. appear in pw-
dump(1) output) is larger than considered above:

• Node

• Device

• Port

• Link

• Client

• Metadata

• Module

• Profiler

• SecurityContext

Monitors do not appear in this list; they are not usually exported, and
technically also Device objects. They are considered above as a separate
object type because they have configurable properties.

Metadata objects are what is manipulated with pw-metadata(1)

Modules can be loaded in configuration files, or by PipeWire
applications.

The Profiler and SecurityContext objects only provide corresponding
PipeWire APIs.

INDEX
Monitor properties
• alsa.udev.expose-busy

• alsa.use-acp

• bluez5.a2dp.opus.pro.bidi.channels

• bluez5.a2dp.opus.pro.bidi.coupled-streams

• bluez5.a2dp.opus.pro.bidi.frame-dms

• bluez5.a2dp.opus.pro.bidi.locations

• bluez5.a2dp.opus.pro.bidi.max-bitrate

• bluez5.a2dp.opus.pro.channels

• bluez5.a2dp.opus.pro.coupled-streams

• bluez5.a2dp.opus.pro.frame-dms

• bluez5.a2dp.opus.pro.locations

• bluez5.a2dp.opus.pro.max-bitrate

• bluez5.bap-server-capabilities.channels

• bluez5.bap-server-capabilities.durations

• bluez5.bap-server-capabilities.framelen_max

• bluez5.bap-server-capabilities.framelen_min

• bluez5.bap-server-capabilities.max_frames

• bluez5.bap-server-capabilities.rates

• bluez5.bcast_source.config

• bluez5.codecs

• bluez5.default.channels

• bluez5.default.rate

• bluez5.dummy-avrcp

• bluez5.enable-hw-volume

• bluez5.enable-msbc

• bluez5.enable-sbc-xq

• bluez5.hfphsp-backend

• bluez5.hfphsp-backend-native-modem

• bluez5.hw-offload-sco

• bluez5.roles

Device properties
• api.acp.auto-port

• api.acp.auto-profile

• api.acp.pro-channels

• api.acp.probe-rate

• api.alsa.disable-mixer-path

• api.alsa.ignore-dB

• api.alsa.path

• api.alsa.soft-mixer

• api.alsa.split-enable

• api.alsa.split.parent

• api.alsa.use-ucm

• bluez5.a2dp.aac.bitratemode

• bluez5.a2dp.ldac.quality

• bluez5.a2dp.opus.pro.application

• bluez5.a2dp.opus.pro.bidi.application

• bluez5.auto-connect

• bluez5.bap.cig

• bluez5.hw-volume

• bluez5.profile

• device.class

• device.description

• device.disabled

• device.form-factor

• device.icon

• device.icon-name

• device.intended-roles

• device.name

• device.nick

• device.param.PARAM

• device.plugged

• device.product.id

• device.product.name

• device.profile

• device.profile-set

• device.serial

• device.vendor.id

• device.vendor.name

Node properties
• adapter.auto-port-config

• api.alsa.auto-link

• api.alsa.bind-ctls

• api.alsa.disable-batch

• api.alsa.disable-mmap

• api.alsa.disable-tsched

• api.alsa.headroom

• api.alsa.htimestamp

• api.alsa.htimestamp.max-errors

• api.alsa.multi-rate

• api.alsa.open.ucm

• api.alsa.path

• api.alsa.period-num

• api.alsa.period-size

• api.alsa.split.hw-position

• api.alsa.split.position

• api.alsa.start-delay

• api.alsa.use-chmap

• audio.allowed-rates

• audio.channels

• audio.format

• audio.position

• audio.rate

• bluez5.media-source-role

• channelmix.disable

• channelmix.fc-cutoff

• channelmix.hilbert-taps

• channelmix.lfe-cutoff

• channelmix.lock-volumes

• channelmix.max-volume

• channelmix.min-volume

• channelmix.mix-lfe

• channelmix.normalize

• channelmix.rear-delay

• channelmix.stereo-widen

• channelmix.upmix

• channelmix.upmix-method

• clock.name

• clock.quantum-limit

• debug.wav-path

• device.id

• dither.method

• dither.noise

• iec958.codecs

• latency.internal.ns

• latency.internal.rate

• media.artist

• media.category

• media.class

• media.comment

• media.copyright

• media.date

• media.filename

• media.format

• media.icon

• media.icon-name

• media.language

• media.name

• media.role

• media.software

• media.title

• media.type

• monitor.channel-volumes

• node.always-process

• node.autoconnect

• node.description

• node.disabled

• node.dont-reconnect

• node.exclusive

• node.force-quantum

• node.force-rate

• node.latency

• node.link-group

• node.lock-quantum

• node.lock-rate

• node.loop.class

• node.loop.name

• node.name

• node.param.PARAM

• node.passive

• node.pause-on-idle

• node.rate

• node.suspend-on-idle

• node.target

• node.want-driver

• object.linger

• priority.driver

• priority.session

• resample.disable

• resample.peaks

• resample.prefill

• resample.quality

• stream.dont-remix

• target.object

Port properties
• port.alias

• port.name

Client properties
• application.name

• application.process.id

• pipewire.sec.pid

AUTHORS
The PipeWire Developers
<https://gitlab.freedesktop.org/pipewire/pipewire/issues>; PipeWire is
available from <https://pipewire.org>