pipewire-devices(7)

📦 version 1.0.5, in ubuntu noble

✨ NAME ✨

okay bestie, welcome to pipewire-devices(7) — from the Miscellaneous Information Manual, and it's literally the PipeWire device and node property reference. If your sinks, sources, cameras, Bluetooth thingies, or virtual objects are doing too much, this is the page that explains their properties. 💖

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

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

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.

✨ Node properties ✨

💜 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.acp.auto-port # boolean — Select reasonable port on device startup. Available for ACP devices.
  • api.acp.auto-profile # boolean — Select reasonable profile on device startup. Available for ACP devices.

🎚️ 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 # integer — Some devices require a startup period. The default is 0. Higher values can be set to send silence samples to the device first.
  • api.alsa.disable-mmap # 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 false because many drivers 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 advertize 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

🦋 BLUETOOTH PROPERTIES 🦋

ok so bluetooth is a whole ✨situation✨ and it has its own little universe of settings. buckle up bestie 💖

🎧 Monitor properties

heads up, these are settings for the Bluetooth device monitor itself — not device properties, not node properties. different vibes entirely, don't mix them up 🙈

  • bluez5.roles — JSON array of string. which roles are enabled (default: [ a2dp_sink a2dp_source bap_sink bap_source hfp_hf hfp_ag ])

fr fr, some headsets (looking at you, Sony WH-1000XM3 👀) just do not work when both hsp_ag and hfp_ag are enabled, so by default we only turn on HFP. periodt.

the roles you can pick from:

  • 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)
  • bluez5.codecs — JSON array of string. which A2DP codecs are on (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. the default audio rate.
  • bluez5.default.channels — integer. the 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. registers a dummy AVRCP player. some devices have volume or playback controls that are just lowkey broken unless you turn this on. default: false
  • bluez5.enable-sbc-xq — boolean. overrides the device quirk list and enables SBC-XQ for devices where it's normally disabled.
  • bluez5.enable-msbc — boolean. overrides the device quirk list and enables MSBC for devices where it's normally disabled.
  • bluez5.enable-hw-volume — boolean. overrides the device quirk list and enables hardware volume for devices where it's normally disabled.
  • bluez5.hw-offload-sco — boolean. HFP/HSP hardware offload SCO support (default: false).
⚠️ this one needs a custom config that routes SCO audio to ALSA nodes, and it has to be done in a platform-specific way. there's an example in tests/examples/bt-pinephone.lua in WirePlumber if you're curious. do NOT enable this setting if you don't know what all of that means, because it literally won't work. it's giving "I read the docs and ignored them" 💀
  • 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).

📱 Device properties

these are the ones that live on the actual device, bestie 🫶

  • bluez5.auto-connect — boolean. auto-connects devices on start up. if you don't specify this property, it's disabled by default. no cap.
  • bluez5.hw-volume = [ PROFILE1 PROFILE2... ] — JSON array of string. which profiles get hardware volume control (default: [ hfp_ag hsp_ag a2dp_source ]).
  • bluez5.profile — string. the initial device profile. honestly this usually does nothing because the session manager overrides it 🙈
  • bluez5.a2dp.ldac.quality — 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 — 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

🎀 Node properties

  • bluez5.media-source-role — string. the media source role for Bluetooth clients connecting to this instance. available values:
    • playback: playing stream to speakers
    • input: appear as source node.

🌈 ALSA CARD PROFILES 🌈

ok so the sound card profiles (like 'Analog stereo', 'Analog stereo duplex', …) — literally all of them except 'Pro Audio' — come from two different sources, bestie:

peep those links for how to configure either system 💅

for ACP, PipeWire goes looking 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 live in the paths and profile-sets subdirectories of those directories. and yes you can override individual files locally — just drop a modified copy into the ACP directories under ~/.config or /etc. iconic behavior tbh ✨

👑 AUTHORS

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

🌸 SEE ALSO

pipewire.conf(5)

and that's the whole page, bestie 💖 this was PipeWire 1.0.5, page pipewire-devices(7) — slay, you made it to the end, go take a lil break, you've earned it 🧚🌟

📦 where this page comes from