update zh_CN.po

Fixes #944

.gitlab-ci.yml

@@ -1,6 +1,15 @@
+# Create merge request pipelines for open merge requests, branch pipelines
+# otherwise. This allows MRs for new users to run CI, and prevents duplicate
+# pipelines for branches with open MRs.
+workflow:
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+    - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS
+      when: never
+    - if: $CI_COMMIT_BRANCH
+
 stages:
   - container
-  - container_coverity
   - build
   - analysis
   - pages
@@ -10,8 +19,8 @@ variables:
   # change to build against a different tag or branch of pipewire
   PIPEWIRE_HEAD: 'master'
 
-# ci-templates as of Mar 24th 2023
+# ci-templates as of Feb 14th 2025
-.templates_sha: &templates_sha dd90ac0d7a03b574eb4f18d7358083f0c97825f3
+.templates_sha: &templates_sha ef5e4669b7500834a17ffe9277e15fbb6d977fff
 
 include:
   - project: 'freedesktop/ci-templates'
@@ -27,8 +36,8 @@ include:
 .fedora:
   variables:
     # Update this tag when you want to trigger a rebuild
-    FDO_DISTRIBUTION_TAG: '2023-03-24.1'
+    FDO_DISTRIBUTION_TAG: '2025-03-05.1'
-    FDO_DISTRIBUTION_VERSION: '37'
+    FDO_DISTRIBUTION_VERSION: '41'
     # findutils: used by the .build script below
     # dbus-devel: required by pipewire
     # dbus-daemon: required by GDBus unit tests
@@ -59,12 +68,13 @@ include:
 .ubuntu:
   variables:
     # Update this tag when you want to trigger a rebuild
-    FDO_DISTRIBUTION_TAG: '2023-03-24.1'
+    FDO_DISTRIBUTION_TAG: '2023-06-16.1'
-    FDO_DISTRIBUTION_VERSION: '20.04'
+    FDO_DISTRIBUTION_VERSION: '22.04'
     FDO_DISTRIBUTION_PACKAGES: >-
       debhelper-compat
       findutils
       git
+      meson
       ninja-build
       pkg-config
       python3-pip
@@ -75,14 +85,12 @@ include:
       libgirepository1.0-dev
       doxygen
       python3-lxml
-    FDO_DISTRIBUTION_EXEC: >-
-      pip3 install meson
 
 .alpine:
   variables:
     # Update this tag when you want to trigger a rebuild
-    FDO_DISTRIBUTION_TAG: '2023-03-24.1'
+    FDO_DISTRIBUTION_TAG: '2025-03-05.1'
-    FDO_DISTRIBUTION_VERSION: '3.15'
+    FDO_DISTRIBUTION_VERSION: '3.21'
     FDO_DISTRIBUTION_PACKAGES: >-
       dbus
       dbus-dev
@@ -113,14 +121,23 @@ include:
       tar xf /tmp/cov-analysis-linux64.tgz ;
       mv cov-analysis-linux64-* coverity ;
       rm /tmp/cov-analysis-linux64.tgz
-  only:
-    variables:
-      - $COVERITY
 
-.not_coverity:
+.rules_on_success_except_coverity:
-  except:
+  rules:
-    variables:
+    - if: $COVERITY
-      - $COVERITY
+      when: never
+    - when: on_success
+
+.rules_only_on_coverity:
+  rules:
+    - if: $COVERITY
+
+.rules_only_on_mr_and_branch:
+  rules:
+    - if: $COVERITY
+      when: never
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+    - if: $CI_COMMIT_BRANCH != "master"
 
 .build:
   before_script:
@@ -137,13 +154,22 @@ include:
     # Fedora also ships that, but without the test plugins that we need...
     - git clone --depth=1 --branch="$PIPEWIRE_HEAD"
         https://gitlab.freedesktop.org/pipewire/pipewire.git
-    - meson "$PW_BUILD_DIR" pipewire --prefix="$PREFIX"
+    # Set build options based on PipeWire version
-        -Dpipewire-alsa=disabled -Dpipewire-jack=disabled
+    - |
-        -Dalsa=disabled -Dv4l2=disabled -Djack=disabled -Dbluez5=disabled
+      case "$PIPEWIRE_HEAD" in
-        -Dvulkan=disabled -Dgstreamer=disabled -Dsystemd=disabled
+        1.0|1.2|1.4)
-        -Ddocs=disabled -Dman=disabled -Dexamples=disabled -Dpw-cat=disabled
+          export PIPEWIRE_BUILD_OPTIONS="-Dsystemd=disabled"
-        -Dsdl2=disabled -Dsndfile=disabled -Dlibpulse=disabled -Davahi=disabled
+          ;;
-        -Decho-cancel-webrtc=disabled -Dsession-managers=[]
+        *)
+          export PIPEWIRE_BUILD_OPTIONS="-Dlibsystemd=disabled"
+          ;;
+      esac
+    - meson "$PW_BUILD_DIR" pipewire --prefix="$PREFIX" $PIPEWIRE_BUILD_OPTIONS
+        -Dpipewire-alsa=disabled -Dpipewire-jack=disabled -Dalsa=disabled
+        -Dv4l2=disabled -Djack=disabled -Dbluez5=disabled -Dvulkan=disabled
+        -Dgstreamer=disabled -Ddocs=disabled -Dman=disabled -Dexamples=disabled
+        -Dpw-cat=disabled -Dsdl2=disabled -Dsndfile=disabled -Dlibpulse=disabled
+        -Davahi=disabled -Decho-cancel-webrtc=disabled -Dsession-managers=[]
         -Dvideotestsrc=enabled -Daudiotestsrc=enabled -Dtest=enabled
     - ninja $NINJA_ARGS -C "$PW_BUILD_DIR" install
     # misc environment only for wireplumber
@@ -165,6 +191,7 @@ include:
 
 container_fedora:
   extends:
+    - .rules_on_success_except_coverity
     - .fedora
     - .fdo.container-build@fedora
   stage: container
@@ -173,6 +200,7 @@ container_fedora:
 
 container_ubuntu:
   extends:
+    - .rules_only_on_mr_and_branch
     - .ubuntu
     - .fdo.container-build@ubuntu
   stage: container
@@ -181,6 +209,7 @@ container_ubuntu:
 
 container_alpine:
   extends:
+    - .rules_only_on_mr_and_branch
     - .alpine
     - .fdo.container-build@alpine
   stage: container
@@ -189,17 +218,18 @@ container_alpine:
 
 container_coverity:
   extends:
+    - .rules_only_on_coverity
     - .fedora
     - .coverity
     - .fdo.container-build@fedora
-  stage: container_coverity
+  stage: container
   variables:
     GIT_STRATEGY: none
 
 build_on_fedora_with_docs:
   extends:
+    - .rules_on_success_except_coverity
     - .fedora
-    - .not_coverity
     - .fdo.distribution-image@fedora
     - .build
   stage: build
@@ -208,18 +238,21 @@ build_on_fedora_with_docs:
 
 build_on_fedora_no_docs:
   extends:
+    - .rules_only_on_mr_and_branch
     - .fedora
-    - .not_coverity
     - .fdo.distribution-image@fedora
     - .build
   stage: build
   variables:
     BUILD_OPTIONS: -Dintrospection=enabled -Ddoc=disabled -Dsystem-lua=false
+  parallel:
+    matrix:
+      - PIPEWIRE_HEAD: ['master', '1.4', '1.2', '1.0']
 
 build_on_ubuntu_with_gir:
   extends:
+    - .rules_only_on_mr_and_branch
     - .ubuntu
-    - .not_coverity
     - .fdo.distribution-image@ubuntu
     - .build
   stage: build
@@ -228,8 +261,8 @@ build_on_ubuntu_with_gir:
 
 build_on_ubuntu_no_gir:
   extends:
+    - .rules_only_on_mr_and_branch
     - .ubuntu
-    - .not_coverity
     - .fdo.distribution-image@ubuntu
     - .build
   stage: build
@@ -238,8 +271,8 @@ build_on_ubuntu_no_gir:
 
 build_on_alpine:
   extends:
+    - .rules_only_on_mr_and_branch
     - .alpine
-    - .not_coverity
     - .fdo.distribution-image@alpine
     - .build
   stage: build
@@ -248,6 +281,7 @@ build_on_alpine:
 
 build_with_coverity:
   extends:
+    - .rules_only_on_coverity
     - .fedora
     - .coverity
     - .fdo.suffixed-image@fedora
@@ -277,16 +311,23 @@ build_with_coverity:
 shellcheck:
   extends:
     - .fedora
-    - .not_coverity
     - .fdo.distribution-image@fedora
   stage: analysis
   script:
     - shellcheck $(git grep -l "#\!/.*bin/.*sh")
+  rules:
+    - if: $COVERITY
+      when: never
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+      changes:
+        - "**/*.sh"
+    - if: $CI_COMMIT_BRANCH != "master"
+      changes:
+        - "**/*.sh"
 
 linguas_check:
   extends:
     - .fedora
-    - .not_coverity
     - .fdo.distribution-image@fedora
   stage: analysis
   script:
@@ -295,10 +336,17 @@ linguas_check:
     - ls *.po | sed s/.po//g | sort > LINGUAS.new
     - diff -u LINGUAS.sorted LINGUAS.new
     - rm -f LINGUAS.*
+  rules:
+    - if: $COVERITY
+      when: never
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+      changes:
+        - po/*
+    - if: $CI_COMMIT_BRANCH != "master"
+      changes:
+        - po/*
 
 pages:
-  extends:
-    - .not_coverity
   stage: pages
   dependencies:
     - build_on_fedora_with_docs
@@ -308,5 +356,7 @@ pages:
   artifacts:
     paths:
       - public
-  only:
+  rules:
-    - master
+    - if: $COVERITY
+      when: never
+    - if: $CI_COMMIT_BRANCH == "master"

AGENTS.md

@@ -0,0 +1,37 @@
+## Building and Testing
+
+- To compile the project: `meson compile -C build` (compiles everything, no target needed)
+- To run tests: `meson test -C build`
+- The build artifacts always live in a directory called `build` or `builddir`.
+  If `build` doesn't exist, use `-C builddir` in the meson commands.
+
+## Git Workflow
+
+- Main branch: `master`
+- Always create feature branches for new work
+- Use descriptive commit messages following project conventions
+- Reference GitLab MR/issue numbers in commits where applicable
+- Never commit build artifacts or temporary files
+- Use `glab` CLI tool for GitLab interactions (MRs, issues, etc.)
+
+## Making a release
+
+- Each release always consists of an entry in NEWS.rst, at the top of the file, which describes
+  the changes between the previous release and the current one. In addition, each release is given
+  a unique version number, which is present:
+    1. on the section header of that NEWS.rst entry
+    2. in the project() command in meson.build
+    3. on the commit message of the commit that introduces the above 2 changes
+    4. on the git tag that marks the above commit
+- In order to make a release:
+    - Begin by analyzing the git history and the merged MRs from GitLab between the previous release
+      and today. GitLab MRs that are relevant always have the new release's version number set as a
+      "milestone"
+    - Create a new entry in NEWS.rst describing the changes, in a similar style and format as the
+      previous entries. Consolidate the changes to larger work items and also reference the relevant
+      gitlab MR that corresponds to each change and/or the gitlab issues that were addressed by each
+      change.
+    - Make sure to move the "Past releases" section header up, so that the only 2 top-level sections
+      are the new release section and the "Past releases" section.
+    - Edit meson.build to change the project version to the new release number
+    - Do not commit anything to git. Let the user review the changes and commit manually.

NEWS.rst

@@ -1,6 +1,779 @@
-WirePlumber 0.4.15
+WirePlumber 0.5.14
 ~~~~~~~~~~~~~~~~~~
 
+Additions & Enhancements:
+
+  - Added per-device default volume configuration via the
+    ``device.routes.default-{source,sink}-volume`` property, allowing device-specific volume
+    defaults (e.g. a comfortable default for internal speakers or no attenuation for HDMI) (!772)
+
+  - Added Lua 5.5 support; the bundled Lua subproject wrap has also been updated to 5.5.0
+    (!775, !788)
+
+  - Enhanced libcamera monitor to load camera nodes locally within the WirePlumber
+    process instead of the PipeWire daemon, eliminating race conditions that could occur
+    during initial enumeration and hotplug events (!790)
+
+  - Enhanced Bluetooth loopback nodes to always be created when a device supports both
+    A2DP and HSP/HFP profiles, simplifying the logic and making the BT profile autoswitch
+    setting take effect immediately without requiring device reconnection (!782)
+
+  - Enhanced Bluetooth loopback nodes to use ``target.object`` property instead of smart
+    filters, fixing issues that prevented users from setting them as default nodes and
+    also allowing smart filters to be used with them (#898; !792)
+
+  - Enhanced Bluetooth profile autoswitch logic with further robustness improvements,
+    including better headset profile detection using profile name patterns and resolving
+    race conditions by running profile switching after ``device/apply-profile`` in a
+    dedicated event hook (#926, #923; !776, !777, !808)
+
+  - Enhanced wpctl ``set-default`` command to accept virtual nodes (e.g.
+    ``Audio/Source/Virtual``) in addition to regular device nodes (#896; !787)
+
+  - Improved stream linking to make the full graph rescan optional when linkable items
+    change, saving CPU on low-end systems and reducing audio startup latency when
+    connecting multiple streams in quick succession (!800)
+
+  - Allowed installation of systemd service units without libsystemd being present,
+    useful for distributions like Alpine Linux that allow systemd service subpackages
+    (!793)
+
+  - Allowed the ``mincore`` syscall in the WirePlumber systemd sandbox, required for
+    Mesa/EGL (e.g. for the libcamera GPUISP pipeline)
+
+  - Allowed passing ``WIREPLUMBER_CONFIG_DIR`` via the ``wp-uninstalled`` script,
+    useful for passing additional configuration paths in an uninstalled environment (!801)
+
+Fixes:
+
+  - Removed Bluetooth sink loopback node, which was causing issues with KDE and GNOME (!794)
+
+  - Fixed default audio source selection to never automatically use ``Audio/Sink`` nodes
+    as the default source unless explicitly selected by the user (#886; !781)
+
+  - Fixed crash in ``state-stream`` when the Format parameter has a Choice for the
+    number of channels (#903; !795)
+
+  - Fixed BAP Bluetooth device set channel properties, where ``audio.position`` was
+    incorrectly serialized as a pointer address instead of the channel array (!786)
+
+  - Fixed memory leaks in ``wp_interest_event_hook_get_matching_event_types`` and in
+    the Lua ``LocalModule()`` implementation (!784, !810)
+
+  - Fixed HFP HF stream media class being incorrectly assigned due to
+    ``api.bluez5.internal=true`` being set on HFP HF streams (!809)
+
+  - Fixed Lua 5.4 compatibility in ``state-stream`` script
+
+  - Updated translations: Bulgarian, Georgian, Kazakh, Swedish
+
+Past releases
+~~~~~~~~~~~~~
+
+WirePlumber 0.5.13
+..................
+
+Additions & Enhancements:
+
+  - Added internal filter graph support for audio nodes, allowing users to
+    create audio preprocessing and postprocessing chains without exposing
+    filters to applications, useful for software DSP (!743)
+
+  - Added new Lua Properties API that significantly improves performance by
+    avoiding constant serialization between WpProperties and Lua tables,
+    resulting in approximately 40% faster node linking (!757)
+
+  - Added WpIterator Lua API for more efficient parameter enumeration (!746)
+
+  - Added bash completions for wpctl command (!762)
+
+  - Added script to find suitable volume control when using role-based policy,
+    allowing volume sliders to automatically adjust the volume of the currently
+    active role (e.g., ringing, call, media) (!711)
+
+  - Added experimental HDMI channel detection setting to use HDMI ELD
+    information for channel configuration (!749)
+
+  - Enhanced role-based policy to allow setting preferred target sinks for
+    media role loopbacks via ``policy.role-based.preferred-target`` (!754)
+
+  - Enhanced Bluetooth profile autoswitch logic to be more robust and handle
+    saved profiles correctly, including support for loopback sink nodes (!739)
+
+  - Enhanced ALSA monitor to include ``alsa.*`` device properties on nodes for
+    rule matching (!761)
+
+  - Optimized stream node linking for common cases to reduce latency when new
+    audio/video streams are added (!760)
+
+  - Improved event dispatcher performance by using hash table registration for
+    event hooks, eliminating performance degradation as more hooks are
+    registered (!765)
+
+  - Increased audio headroom for VMware and VirtualBox virtual machines (!756)
+
+  - Added setting to prevent restoring "Off" profiles via
+    ``session.dont-restore-off-profile`` property (!753)
+
+  - Added support for 128 audio channels when compiled with a recent version of
+    PipeWire (pipewire#4995; CI checks in !768)
+
+Fixes:
+
+  - Fixed memory leaks and issues in the modem manager module (!770, !764)
+
+  - Fixed MPRIS module incorrectly treating GHashTable as GObject (!759)
+
+  - Fixed warning messages when process files in ``/proc/<pid>/*`` don't exist,
+    particularly when processes are removed quickly (#816, !717)
+
+  - Fixed MONO audio configuration to only apply to device sink nodes, allowing
+    multi-channel mixing in the graph (!769)
+
+  - Fixed event dispatcher hook registration and removal to avoid spurious
+    errors (!747)
+
+  - Improved logging for standard-link activation failures (!744)
+
+  - Simplified event-hook interest matching for better performance (!758)
+
+WirePlumber 0.5.12
+..................
+
+Additions & Enhancements:
+
+  - Added mono audio configuration support via ``node.features.audio.mono``
+    setting that can be changed at runtime with wpctl (!721)
+
+  - Added automatic muting of ALSA devices when a running node is removed,
+    helping prevent loud audio on speakers when headsets are unplugged (!734)
+
+  - Added notifications API module for sending system notifications (!734)
+
+  - Added comprehensive wpctl man page and documentation (!735, #825)
+
+  - Enhanced object interest handling for PipeWire properties on session items (!738)
+
+Fixes:
+
+  - Fixed race condition during shutdown in the permissions portal module that
+    could cause crashes in GDBus signal handling (!748)
+
+  - Added device validity check in state-routes handling to prevent issues
+    when devices are removed during async operations (!737, #844)
+
+  - Fixed Log.critical undefined function error in device-info-cache (!733)
+
+  - Improved device hook documentation and configuration (!736)
+
+WirePlumber 0.5.11
+..................
+
+Additions & Enhancements:
+
+  - Added modem manager module for tracking voice call status and voice call
+    device profile selection hooks to improve phone call audio routing on
+    mobile devices (!722, !729, #819)
+
+  - Added MPRIS media player pause functionality that automatically pauses
+    media playback when the audio target (e.g. headphones) is removed (!699, #764)
+
+  - Added support for human-readable names and localization of settings in
+    ``wireplumber.conf`` with ``wpctl`` displaying localized setting descriptions (!712)
+
+  - Improved default node selection logic to use both session and route
+    priorities when nodes have equal session priorities (!720)
+
+  - Increased USB device priority in the ALSA monitor (!719)
+
+Fixes:
+
+  - Fixed multiple Lua runtime issues including type confusion bugs, stack
+    overflow prevention, and SPA POD array/choice builders (!723, !728)
+
+  - Fixed proxy object lifecycle management by properly clearing the
+    OWNED_BY_PROXY flag when proxies are destroyed to prevent dangling
+    pointers (!732)
+
+  - Fixed state-routes handling to prevent saving unavailable routes and
+    eliminate race conditions during profile switching (!730, #762)
+
+  - Fixed some memory leaks in the script tester and the settings iterator (!727, !726)
+
+  - Fixed a potential crash caused by module-loopback destroying itself when the
+    pipewire connection is closed (#812)
+
+  - Fixed profile saving behavior in ``wpctl set-profile`` command (#808)
+
+  - Fixed GObject introspection closure annotation
+
+WirePlumber 0.5.10
+..................
+
+Fixed a critical crash in ``linking-utils.haveAvailableRoutes`` that was
+introduced accidentally in 0.5.9 and caused loss of audio output on affected
+systems (#797, #799, #800, !713)
+
+WirePlumber 0.5.9
+.................
+
+Additions & Enhancements:
+
+  - Added a new audio node grouping functionality using an external command line
+    tool (!646)
+
+  - The libcamera monitor now supports devices that are not associated with
+    device ids (!701)
+
+  - The wireplumber user systemd service is now associated with dbus.service to
+    avoid strange warnings when dbus exits (!702)
+
+  - Added "SYSLOG_IDENTIFIER", "SYSLOG_FACILITY", "SYSLOG_PID" and "TID" to log
+    messages that are sent to the journal (!709)
+
+Fixes:
+
+  - Fixed a crash of ``wpctl set-default`` on 32-bit architectures (#773)
+
+  - Fixed a crash when a configuration component had no 'provides' field (#771)
+
+  - Reduced the log level of some messages that didn't need to be as high (!695)
+
+  - Fixed another nil reference issue in the alsa.lua monitor script (!704)
+
+  - Fixed name deduplication of v4l2 and libcamera devices (!705)
+
+  - Fixed an issue with wpctl not being able to save settings sometimes (!708, #749)
+
+WirePlumber 0.5.8
+.................
+
+Additions & Enhancements:
+
+  - Added support for handling UCM SplitPCM nodes in the ALSA monitor, which
+    allows native PipeWire channel remapping using loopbacks for devices that
+    use this feature (!685)
+
+  - Introduced new functions to mark WpSpaDevice child objects as pending.
+    This allows properly associating asynchronously created loopback nodes with
+    their parent WpSpaDevice without losing ObjectConfig events (!687, !689)
+
+  - Improved the node name deduplication logic in the ALSA monitor to prevent
+    node names with .2, .3, etc appended to them in some more cases (!688)
+
+  - Added a new script to populate ``session.services``. This is a step towards
+    implementing detection of features that PipeWire can service (!686)
+
+Fixes:
+
+  - Fixed an issue that was causing duplicate Bluetooth SCO (HSP/HFP) source
+    nodes to be shown in UIs (#701, !683)
+
+  - In the BlueZ monitor, marked the source loopback node as non-virtual,
+    addressing how it appears on UIs (#729)
+
+  - Disabled stream-restore for device loopback nodes to prevent unwanted
+    property changes (!691)
+
+  - Fixed ``wp_lua_log_topic_copy()`` to correctly copy topic names (#757)
+
+  - Updated script tests to handle differences in object identifiers
+    (``object.serial`` vs ``node.id``), ensuring proper test behavior (#761)
+
+WirePlumber 0.5.7
+.................
+
+Highlights:
+
+  - Fixed an issue that would cause random profile switching when an application
+    was trying to capture from non-Bluetooth devices (#715, #634, !669)
+
+  - Fixed an issue that would cause strange profile selection issues [choices
+    not being remembered or unavailable routes being selected] (#734)
+
+  - Added a timer that delays switching Bluetooth headsets to the HSP/HFP
+    profile, avoiding needless rapid switching when an application is trying to
+    probe device capabilities instead of actually capturing audio (!664)
+
+  - Improved libcamera/v4l2 device deduplication logic to work with more complex
+    devices (!674, !675, #689, #708)
+
+Fixes:
+
+  - Fixed two memory leaks in module-mixer-api and module-dbus-connection
+    (!672, !673)
+
+  - Fixed a crash that could occur in module-reserve-device (!680, #742)
+
+  - Fixed an issue that would cause the warning "[string "alsa.lua"]:182:
+    attempt to concatenate a nil value (local 'node_name')" to appear in the
+    logs when an ALSA device was busy, breaking node name deduplication (!681)
+
+  - Fixed an issue that could make find-preferred-profile.lua crash instead of
+    properly applying profile priority rules (#751)
+
+WirePlumber 0.5.6
+.................
+
+Additions:
+
+  - Implemented before/after dependencies for components, to ensure correct
+    load order in custom configurations (#600)
+
+  - Implemented profile inheritance in the configuration file. This allows
+    profiles to inherit all the feature specifications of other profiles, which
+    is useful to avoid copying long lists of features just to make small changes
+
+  - Added multi-instance configuration profiles, tested and documented them
+
+  - Added a ``main-systemwide`` profile, which is now the default for instances
+    started via the system-wide systemd service and disables features that
+    depend on the user session (#608)
+
+  - Added a ``wp_core_connect_fd`` method, which allows making a connection to
+    PipeWire via an existing open socket (useful for portal-based connections)
+
+Fixes:
+
+  - The Bluetooth auto-switch script now uses the common event source object
+    managers, which should improve its stability (!663)
+
+  - Fix an issue where switching between Bluetooth profiles would temporarily
+    link active audio streams to the internal speakers (!655)
+
+WirePlumber 0.5.5
+.................
+
+Highlights:
+
+  - Hotfix release to address crashes in the Bluetooth HSP/HFP autoswitch
+    functionality that were side-effects of some changes that were part
+    of the role-based linking policy (#682)
+
+Improvements:
+
+  - wpctl will now properly show a '*' in front of sink filters when they are
+    selected as the default sink (!660)
+
+WirePlumber 0.5.4
+.................
+
+Highlights:
+
+  - Refactored the role-based linking policy (previously known also as
+    "endpoints" or "virtual items" policy) to blend in with the standard desktop
+    policy. It is now possible use role-based sinks alongside standard desktop
+    audio operations and they will only be used for streams that have a
+    "media.role" defined. It is also possible to force streams to have a
+    media.role, using a setting. Other features include: blending with smart
+    filters in the graph and allowing hardware DSP nodes to be also used easily
+    instead of requiring software loopbacks for all roles. (#610, !649)
+
+Improvements:
+
+  - Filters that are not declared as smart will now behave again as normal
+    application streams, instead of being treated sometimes differently (!657)
+
+Fixes:
+
+  - Fixed an issue that would cause WirePlumber to crash at startup if an
+    empty configuration file was present in one of the search paths (#671)
+
+  - Fixed Bluetooth profile auto-switching when a filter is permanently linked
+    to the Bluetooth source (!650)
+
+  - Fixed an issue in the software-dsp script that would cause DSP filters to
+    stay around and cause issues after their device node was destroyed (!651)
+
+  - Fixed an issue in the autoswitch-bluetooth-profile script that could cause
+    an infinite loop of switching between profiles (!652, #617)
+
+  - Fixed a rare issue that could cause WirePlumber to crash when dealing with
+    a device object that didn't have the "device.name" property set (#674)
+
+WirePlumber 0.5.3
+.................
+
+Fixes:
+
+  - Fixed a long standing issue that would cause many device nodes to have
+    inconsistent naming, with a '.N' suffix (where N is a number >= 2) being
+    appended at seemingly random times (#500)
+
+  - Fixed an issue that would cause unavailable device profiles to be selected
+    if they were previously stored in the state file, sometimes requiring users
+    to manually remove the state file to get things working again (#613)
+
+  - Fixed an occasional crash that could sometimes be triggered by hovering
+    the volume icon on the KDE taskbar, and possibly other similar actions
+    (#628, !644)
+
+  - Fixed camera device deduplication logic when the same device is available
+    through both V4L2 and libcamera, and the libcamera one groups multiple V4L2
+    devices together (#623, !636)
+
+  - Fixed applying the default volume on streams that have no volume previously
+    stored in the state file (#655)
+
+  - Fixed an issue that would prevent some camera nodes - in some cases -
+    from being destroyed when the camera device is removed (#640)
+
+  - Fixed an issue that would cause video stream nodes to be linked with audio
+    smart filters, if smart audio filters were configured (!647)
+
+  - Fixed an issue that would cause WP to re-activate device profiles even
+    though they were already active (!639)
+
+  - Configuration files in standard JSON format (starting with a '{', among
+    other things) are now correctly parsed (#633)
+
+  - Fixed overriding non-container values when merging JSON objects (#653)
+
+  - Functions marked with WP_PRIVATE_API are now also marked as
+    non-introspectable in the gobject-introspection metadata (#599)
+
+Improvements:
+
+  - Logging on the systemd journal now includes the log topic and also the log
+    level and location directly on the message string when the log level is
+    high enough, which is useful for gathering additional context in logs
+    submitted by users (!640)
+
+  - Added a video-only profile in wireplumber.conf, for systems where only
+    camera & screensharing are to be used (#652)
+
+  - Improved seat state monitoring so that Bluetooth devices are only enabled
+    when the user is active on a local seat, instead of allowing remote users
+    as well (!641)
+
+  - Improved how main filter nodes are detected for the smart filters (!642)
+
+  - Added Lua method to merge JSON containers (!637)
+
+WirePlumber 0.5.2
+.................
+
+Highlights:
+
+  - Added support for loading configuration files other than the default
+    wireplumber.conf within Lua scripts (!629)
+
+  - Added support for loading single-section configuration files, without
+    fragments (!629)
+
+  - Updated the node.software-dsp script to be able to load filter-chain graphs
+    from external configuration files, which is needed for Asahi Linux audio
+    DSP configuration (!629)
+
+Fixes:
+
+  - Fixed destroying camera nodes when the camera device is removed (#627, !631)
+
+  - Fixed an issue with Bluetooth BAP device set naming (!632)
+
+  - Fixed an issue caused by the pipewire event loop not being "entered" as
+    expected (!634, #638)
+
+  - A false positive warning about no modules being loaded is now suppressed
+    when using libpipewire >= 1.0.5 (#620)
+
+  - Default nodes can now be selected using priority.driver when
+    priority.session is not set (#642)
+
+Changes:
+
+  - The library version is now generated following pipewire's versioning scheme:
+    libwireplumber-0.5.so.0.5.2 becomes libwireplumber-0.5.so.0.0502.0 (!633)
+
+WirePlumber 0.5.1
+.................
+
+Highlights:
+
+  - Added a guide documenting how to migrate configuration from 0.4 to 0.5,
+    also available online at:
+    https://pipewire.pages.freedesktop.org/wireplumber/daemon/configuration/migration.html
+    If you are packaging WirePlumber for a distribution, please consider
+    informing users about this.
+
+Fixes:
+
+  - Fixed an odd issue where microphones would stop being usable when a
+    Bluetooth headset was connected in the HSP/HFP profile (#598, !620)
+
+  - Fixed an issue where it was not possible to store the volume/mute state of
+    system notifications (#604)
+
+  - Fixed a rare crash that could occur when a node was destroyed while the
+    'select-target' event was still being processed (!621)
+
+  - Fixed deleting all the persistent settings via ``wpctl --delete`` (!622)
+
+  - Fixed using Bluetooth autoswitch with A2DP profiles that have an input route
+    (!624)
+
+  - Fixed sending an error to clients when linking fails due to a format
+    mismatch (!625)
+
+Additions:
+
+  - Added a check that prints a verbose warning when old-style 0.4.x Lua
+    configuration files are found in the system. (#611)
+
+  - The "policy-dsp" script, used in Asahi Linux to provide a software DSP
+    for Apple Sillicon devices, has now been ported to 0.5 properly and
+    documented (#619, !627)
+
+WirePlumber 0.5.0
+.................
+
+Changes:
+
+  - Bumped the minimum required version of PipeWire to 1.0.2, because we
+    make use of the 'api.bluez5.internal' property of the BlueZ monitor (!613)
+
+  - Improved the naming of Bluetooth nodes when the auto-switching loopback
+    node is present (!614)
+
+  - Updated the documentation on "settings", the Bluetooth monitor, the Access
+    configuration, the file search locations and added a document on how to
+    modify the configuration file (#595, !616)
+
+Fixes:
+
+  - Fixed checking for available routes when selecting the default node (!609)
+
+  - Fixed an issue that was causing an infinite loop storing routes in the
+    state file (!610)
+
+  - Fixed the interpretation of boolean values in the alsa monitor rules (#586, !611)
+
+  - Fixes a Lua crash when we have 2 smart filters, one with a target and one
+    without (!612)
+
+  - Fixed an issue where the default nodes would not be updated when the
+    currently selected default node became unavailable (#588, !615)
+
+  - Fixed an issue that would cause the Props (volume, mute, etc) of loopbacks
+    and other filter nodes to not be restored at startup (#577, !617)
+
+  - Fixed how some constants were represented in the gobject-introspection file,
+    mostly by converting them from defines to enums (#540, #591)
+
+  - Fixed an issue using WirePlumber headers in other projects due to
+    redefinition of G_LOG_DOMAIN (#571)
+
+WirePlumber 0.4.90
+..................
+
+This is the first release candidate (RC1) of WirePlumber 0.5.0.
+
+Highlights:
+
+  - The configuration system has been changed back to load files from the
+    WirePlumber configuration directories, such as ``/etc/wireplumber`` and
+    ``$XDG_CONFIG_HOME/wireplumber``, unlike in the pre-releases. This was done
+    because issues were observed with installations that use a different prefix
+    for pipewire and wireplumber. If you had a ``wireplumber.conf`` file in
+    ``/etc/pipewire`` or ``$XDG_CONFIG_HOME/pipewire``, you should move it to
+    ``/etc/wireplumber`` or ``$XDG_CONFIG_HOME/wireplumber`` respectively (!601)
+
+  - The internal base directories lookup system now also respects the
+    ``XDG_CONFIG_DIRS`` and ``XDG_DATA_DIRS`` environment variables, and their
+    default values as per the XDG spec, so it is possible to install
+    configuration files also in places like ``/etc/xdg/wireplumber`` and
+    override system-wide data paths (!601)
+
+  - ``wpctl`` now has a ``settings`` subcommand to show, change and delete
+    settings at runtime. This comes with changes in the ``WpSettings`` system to
+    validate settings using a schema that is defined in the configuration file.
+    The schema is also exported on a metadata object, so it is available to any
+    client that wants to expose WirePlumber settings (!599, !600)
+
+  - The ``WpConf`` API has changed to not be a singleton and support opening
+    arbitrary config files. The main config file now needs to be opened prior to
+    creating a ``WpCore`` and passed to the core using a property. The core uses
+    that without letting the underlying ``pw_context`` open and read the default
+    ``client.conf``. The core also closes the ``WpConf`` after all components
+    are loaded, which means all the config loading is done early at startup.
+    Finally, ``WpConf`` loads all sections lazily, keeping the underlying files
+    memory mapped until it is closed and merging them on demand (!601, !606)
+
+WirePlumber 0.4.82
+..................
+
+This is a second pre-release of WirePlumber 0.5.0, made available for testing
+purposes. This is not API/ABI stable yet and there is still pending work to do
+before the final 0.5.0 release, both in the codebase and the documentation.
+
+Highlights:
+
+  - Bluetooth auto-switching is now implemented with a virtual source node. When
+    an application links to it, the actual device switches to the HSP/HFP
+    profile to provide the real audio stream. This is a more robust solution
+    that works with more applications and is more user-friendly than the
+    previous application whitelist approach
+
+  - Added support for dynamic log level changes via the PipeWire ``settings``
+    metadata. Also added support for log level patterns in the configuration
+    file
+
+  - The "persistent" (i.e. stored) settings approach has changed to use two
+    different metadata objects: ``sm-settings`` and ``persistent-sm-settings``.
+    Changes in the former are applied in the current session but not stored,
+    while changes in the latter are stored and restored at startup. Some work
+    was also done to expose a ``wpctl`` interface to read and change these
+    settings, but more is underway
+
+  - Several WirePlumber-specific node properties that used to be called
+    ``target.*`` have been renamed to ``node.*`` to match the PipeWire
+    convention of ``node.dont-reconnect``. These are also now fully documented
+
+Other changes:
+
+  - Many documentation updates
+
+  - Added support for SNAP container permissions
+
+  - Fixed multiple issues related to restoring the Route parameter of devices,
+    which includes volume state (#551)
+
+  - Smart filters can now be targetted by specific streams directly when
+    the ``filter.smart.targetable`` property is set (#554)
+
+  - Ported the mechanism to override device profile priorities in the
+    configuration, which is used to re-prioritize Bluetooth codecs
+
+  - WpSettings is no longer a singleton class and there is a built-in component
+    to preload an instance of it
+
+WirePlumber 0.4.81
+..................
+
+This is a preliminary release of WirePlumber 0.5.0, which is made available
+for testing purposes. Please test it and report feedback (merge requests are
+also welcome ;) ). This is not API/ABI stable yet and there is still pending
+work to do before the final 0.5.0 release, both in the codebase and the
+documentation.
+
+Highlights:
+
+  - Lua scripts have been refactored to use the new event dispatcher API, which
+    allows them to be split into multiple small fragments that react to
+    events in a specified order. This allows scripts to be more modular and
+    easier to maintain, as well as more predictable in terms of execution
+    order.
+
+  - The configuration system has been refactored to use a single SPA-JSON file,
+    like PipeWire does, with support for fragments that can override options.
+    This file is also now loaded using PipeWire's configuration API, which
+    effectively means that the file is now loaded from the PipeWire configuration
+    directories, such as ``/etc/pipewire`` and ``$XDG_CONFIG_HOME/pipewire``.
+
+  - The configuration system now has the concept of profiles, which are groups
+    of components that can be loaded together, with the ability to mark certain
+    components as optional. This allows having multiple configurations that
+    can be loaded using the same configuration file. Optional components also
+    allow loading the same profile gracefully on different setups, where some
+    components may not be available (ex, loading of the session D-Bus plugin on
+    a system-wide PipeWire setup now does not fail).
+
+  - Many configuration options are now exposed in the ``sm-settings`` metadata,
+    which allows changing them at runtime. This can be leveraged in the future
+    to implement configuration tools that can modify WirePlumber's behaviour
+    dynamically, without restarting.
+
+  - A new "filters" system has been implemented, which allows specifying chains
+    of "filter" nodes to be dynamically linked in-between streams and devices.
+    This is achieved with certain properties and metadata that can be set on
+    the filter nodes themselves.
+
+  - The default linking policy now reads some more ``target.*`` properties from
+    nodes, which allows fine-tuning some aspects of their linking behaviour,
+    such as whether they are allowed to be re-linked or whether an error should
+    be sent to the client if they cannot be linked.
+
+  - Some state files have been renamed and some have changed format to use JSON
+    for storing complex values, such as arrays. This may cause some of the old
+    state to be lost on upgrade, as there is no transition path implemented.
+
+  - The libcamera and V4L2 monitors have a "device deduplication" logic built-in,
+    which means that for each physical camera device, only one node will be
+    created, either from libcamera or V4L2, depending on which one is considered
+    better for the device. This is mainly to avoid having multiple nodes for
+    the same camera device, which can cause confusion when looking at the list
+    of available cameras in applications.
+
+WirePlumber 0.4.17
+..................
+
+Fixes:
+
+  - Fixed a reference counting issue in the object managers that could cause
+    crashes due to memory corruption (#534)
+
+  - Fixed an issue with filters linking to wrong targets, often with two sets
+    of links (#536)
+
+  - Fixed a crash in the endpoints policy that would show up when log messages
+    were enabled at level 3 or higher
+
+WirePlumber 0.4.16
+..................
+
+Additions:
+
+  - Added a new "sm-objects" script that allows loading objects on demand
+    via metadata entries that describe the object to load; this can be used to
+    load pipewire modules, such as filters or network sources/sinks, on demand
+
+  - Added a mechanism to override device profile priorities in the configuration,
+    mainly as a way to re-prioritize Bluetooth codecs, but this also can be used
+    for other devices
+
+  - Added a mechanism in the endpoints policy to allow connecting filters
+    between a certain endpoint's virtual sink and the device sink; this is
+    specifically intended to allow plugging a filter-chain to act as equalizer
+    on the Multimedia endpoint
+
+  - Added wp_core_get_own_bound_id() method in WpCore
+
+Changes:
+
+  - PipeWire 0.3.68 is now required
+
+  - policy-dsp now has the ability to hide hardware nodes behind the DSP sink
+    to prevent hardware misuse or damage
+
+  - JSON parsing in Lua now allows keys inside objects to be without quotes
+
+  - Added optional argument in the Lua JSON parse() method to limit recursions,
+    making it possible to partially parse a JSON object
+
+  - It is now possible to pass ``nil`` in Lua object constructors that expect an
+    optional properties object; previously, omitting the argument was the only
+    way to skip the properties
+
+  - The endpoints policy now marks the endpoint nodes as "passive" instead of
+    marking their links, adjusting for the behavior change in PipeWire 0.3.68
+
+  - Removed the "passive" property from si-standard-link, since only nodes are
+    marked as passive now
+
+Fixes:
+
+  - Fixed the ``wpctl clear-default`` command to completely clear all the
+    default nodes state instead of only the last set default
+
+  - Reduced the amount of globals that initially match the interest in the
+    object manager
+
+  - Used an idle callback instead of pw_core_sync() in the object manager to
+    expose tmp globals
+
+WirePlumber 0.4.15
+..................
+
 Additions:
 
   - A new "DSP policy" module has been added; its purpose is to automatically
@@ -51,9 +824,6 @@ Changes/Fixes:
   - Added some missing `\since` annotations and made them show up in the
     generated gobject-introspection file, to help bindings generators
 
-Past releases
-~~~~~~~~~~~~~
-
 WirePlumber 0.4.14
 ..................
 

README.rst

@@ -7,9 +7,6 @@ WirePlumber
 .. image:: https://scan.coverity.com/projects/21488/badge.svg
    :alt: Coverity Scan Build Status
 
-.. image:: https://img.shields.io/tokei/lines/gitlab.freedesktop.org/pipewire/wireplumber
-   :alt: Lines of code
-
 .. image:: https://img.shields.io/badge/license-MIT-green
    :alt: License
 

docs/Doxyfile.in

@@ -1240,15 +1240,6 @@ HTML_COLORSTYLE_SAT    = 100
 
 HTML_COLORSTYLE_GAMMA  = 80
 
-# If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML
-# page will contain the date and time when the page was generated. Setting this
-# to YES can help to show when doxygen was last run and thus if the
-# documentation is up to date.
-# The default value is: NO.
-# This tag requires that the tag GENERATE_HTML is set to YES.
-
-HTML_TIMESTAMP         = NO
-
 # If the HTML_DYNAMIC_MENUS tag is set to YES then the generated HTML
 # documentation will contain a main index with vertical navigation menus that
 # are dynamically created via JavaScript. If disabled, the navigation index will
@@ -1543,17 +1534,6 @@ HTML_FORMULA_FORMAT    = png
 
 FORMULA_FONTSIZE       = 10
 
-# Use the FORMULA_TRANSPARENT tag to determine whether or not the images
-# generated for formulas are transparent PNGs. Transparent PNGs are not
-# supported properly for IE 6.0, but are supported on all modern browsers.
-#
-# Note that when changing this option you need to delete any form_*.png files in
-# the HTML output directory before the changes have effect.
-# The default value is: YES.
-# This tag requires that the tag GENERATE_HTML is set to YES.
-
-FORMULA_TRANSPARENT    = YES
-
 # The FORMULA_MACROFILE can contain LaTeX \newcommand and \renewcommand commands
 # to create new LaTeX commands to be used in formulas as building blocks. See
 # the section "Including formulas" for details.
@@ -1865,14 +1845,6 @@ LATEX_HIDE_INDICES     = NO
 
 LATEX_BIB_STYLE        = plain
 
-# If the LATEX_TIMESTAMP tag is set to YES then the footer of each generated
-# page will contain the date and time when the page was generated. Setting this
-# to NO can help when comparing the output of multiple runs.
-# The default value is: NO.
-# This tag requires that the tag GENERATE_LATEX is set to YES.
-
-LATEX_TIMESTAMP        = NO
-
 # The LATEX_EMOJI_DIRECTORY tag is used to specify the (relative or absolute)
 # path from which the emoji images will be read. If a relative path is entered,
 # it will be relative to the LATEX_OUTPUT directory. If left blank the
@@ -2265,23 +2237,6 @@ HAVE_DOT               = YES
 
 DOT_NUM_THREADS        = 0
 
-# When you want a differently looking font in the dot files that doxygen
-# generates you can specify the font name using DOT_FONTNAME. You need to make
-# sure dot is able to find the font, which can be done by putting it in a
-# standard location or by setting the DOTFONTPATH environment variable or by
-# setting DOT_FONTPATH to the directory containing the font.
-# The default value is: Helvetica.
-# This tag requires that the tag HAVE_DOT is set to YES.
-
-DOT_FONTNAME           = Helvetica
-
-# The DOT_FONTSIZE tag can be used to set the size (in points) of the font of
-# dot graphs.
-# Minimum value: 4, maximum value: 24, default value: 10.
-# This tag requires that the tag HAVE_DOT is set to YES.
-
-DOT_FONTSIZE           = 10
-
 # By default doxygen will tell dot to use the default font as specified with
 # DOT_FONTNAME. If you specify a different font using DOT_FONTNAME you can set
 # the path where dot can find it using this tag.
@@ -2518,18 +2473,6 @@ DOT_GRAPH_MAX_NODES    = 50
 
 MAX_DOT_GRAPH_DEPTH    = 0
 
-# Set the DOT_TRANSPARENT tag to YES to generate images with a transparent
-# background. This is disabled by default, because dot on Windows does not seem
-# to support this out of the box.
-#
-# Warning: Depending on the platform used, enabling this option may lead to
-# badly anti-aliased labels on the edges of a graph (i.e. they become hard to
-# read).
-# The default value is: NO.
-# This tag requires that the tag HAVE_DOT is set to YES.
-
-DOT_TRANSPARENT        = NO
-
 # Set the DOT_MULTI_TARGETS tag to YES to allow dot to generate multiple output
 # files in one run (i.e. multiple -o and -T options on the command line). This
 # makes dot run faster, but since only newer versions of dot (>1.8.10) support

docs/conf.py.in

@@ -1,11 +1,15 @@
 # -- Project information -----------------------------------------------------
 
 project = 'WirePlumber'
-copyright = '2021, Collabora'
+copyright = '2020-2025, Collabora & contributors'
-author = 'Collabora'
+author = 'The WirePlumber Developers'
 release = '@VERSION@'
 version = '@VERSION@'
 
+# -- General configuration ---------------------------------------------------
+
+smartquotes = False
+
 # -- Breathe configuration ---------------------------------------------------
 
 extensions = [
@@ -43,3 +47,9 @@ html_css_files = ['custom.css']
 graphviz_output_format = "svg"
 
 pygments_style = "friendly"
+
+# -- Options for manual page output -----------------------------------------
+
+man_pages = [
+    ('tools/wpctl', 'wpctl', 'WirePlumber Control CLI', ['The WirePlumber Developers'], 1)
+]

docs/gen-api-gtkdoc.py

@@ -130,7 +130,7 @@ class DoxygenProcess(object):
     def __process_element(self, xml):
         s = ""
 
-        if xml.text and re.search('\S', xml.text):
+        if xml.text and re.search(r'\S', xml.text):
             s += xml.text
         for n in xml.getchildren():
             if n.tag == "emphasis":
@@ -143,7 +143,7 @@ class DoxygenProcess(object):
                 s += " - " + self.__process_element(n)
             if n.tag == "para":
                 p = self.__process_element(n)
-                if re.search('\S', p):
+                if re.search(r'\S', p):
                     s += p + "\n"
             if n.tag == "ref":
                 s += n.text if n.text else ""
@@ -168,7 +168,7 @@ class DoxygenProcess(object):
             if n.tag == "htmlonly":
                 s += ""
             if n.tail:
-                if re.search('\S', n.tail):
+                if re.search(r'\S', n.tail):
                   s += n.tail
             if n.tag.startswith("param"):
                 pass  # parameters are handled separately in DoxyFunction::from_memberdef()
@@ -319,6 +319,8 @@ class DoxyFunction(DoxyElement):
             d = normalize_text(d)
 
         e = DoxyFunction(name, d)
+        if (xml.get("prot") == "private"):
+            e.extra = "(skip)"
         e.add_brief(xml.find("briefdescription"))
         e.add_detail(xml.find("detaileddescription"))
         for p in xml.xpath(".//detaileddescription/*/parameterlist[@kind='param']/parameteritem"):

docs/meson.build

@@ -69,6 +69,7 @@ if build_doc
     meson.current_source_dir()/'..'/'README.rst',
     meson.current_source_dir()/'..'/'NEWS.rst',
   )
+  sphinx_files += scripts_doc_files
   subdir('rst')
 
   sphinx_conf_data = configuration_data()
@@ -98,7 +99,27 @@ if build_doc
     depends: [doxyxml_wp],
     output: 'html',
     install: true,
-    install_dir: get_option('datadir') / 'doc' / 'wireplumber',
+    install_dir: wireplumber_doc_dir,
+    build_by_default: true,
+  )
+
+  # Generate man pages directory with sphinx
+  custom_target('manpages',
+    command: [sphinx_p,
+      '-q',                       # quiet
+      '-E',                       # rebuild from scratch
+      '-b', 'man',                # man page builder
+      '-d', '@PRIVATE_DIR@',      # doctrees dir
+      '-c', '@OUTDIR@',           # conf.py dir
+      '@CURRENT_SOURCE_DIR@/rst', # source dir
+      '@OUTDIR@',                 # output directory
+    ],
+    depend_files: [
+      sphinx_conf, sphinx_files,
+    ],
+    output: ['wpctl.1'],
+    install: true,
+    install_dir: get_option('mandir') / 'man1',
     build_by_default: true,
   )
 endif
@@ -140,7 +161,7 @@ if build_gir
     dependencies: [wp_dep, dummy_dep],
     namespace: 'Wp',
     nsversion: wireplumber_api_version,
-    export_packages: 'wireplumber-0.4',
+    export_packages: 'wireplumber-' + wireplumber_api_version,
     header: 'wp/wp.h',
     sources: [wpenums_h, wp_gtkdoc_h, wp_lib_headers],
     include_directories: [wpenums_include_dir],

docs/rst/c_api/endpoint_api.rst

@@ -1,24 +0,0 @@
-.. _endpoint_api:
-
-PipeWire Endpoint
-=================
-.. graphviz::
-  :align: center
-
-   digraph inheritance {
-      rankdir=LR;
-      GObject -> WpObject;
-      WpObject -> WpProxy;
-      WpProxy -> WpGlobalProxy;
-      WpGlobalProxy -> WpEndpoint;
-      GInterface -> WpPipewireObject;
-      WpPipewireObject -> WpEndpoint;
-      WpEndpoint -> WpImplEndpoint;
-   }
-
-.. doxygenstruct:: WpEndpoint
-
-.. doxygenstruct:: WpImplEndpoint
-
-.. doxygengroup:: wpendpoint
-   :content-only:

docs/rst/configuration.rst

@@ -1,34 +0,0 @@
- .. _configuration:
-
-Configuration
-=============
-
-WirePlumber is a heavily modular daemon. By itself, it doesn't do anything
-except load the configured modules. All the rest of the logic is implemented
-inside those modules.
-
-Modular design ensures that it is possible to swap the implementation of
-specific functionality without having to re-implement the rest of it, allowing
-flexibility on target-sensitive parts, such as policy management and
-making use of non-standard hardware.
-
-At startup, WirePlumber first reads its **main** configuration file.
-This file configures the operation context (properties of the daemon,
-modules to be loaded, etc). This file may also specify additional, secondary
-configuration files which will be loaded as well at the time of parsing the
-main file.
-
-All files and modules are specified relative to their standard search locations,
-which are documented later in this chapter.
-
-.. toctree::
-   :maxdepth: 1
-
-   configuration/locations.rst
-   configuration/main.rst
-   configuration/config_lua.rst
-   configuration/multi_instance.rst
-   configuration/alsa.rst
-   configuration/bluetooth.rst
-   configuration/policy.rst
-   configuration/access.rst

docs/rst/configuration/access.rst

@@ -1,63 +0,0 @@
-.. _config_access:
-
-Access configuration
-====================
-
-main.lua.d/50-default-access-config.lua
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Using a similar format as the :ref:`ALSA monitor <config_alsa>`, this
-configuration file is charged to configure the client objects created by
-PipeWire.
-
-* *default_access.properties*
-
-  A Lua object that contains generic client configuration properties in the
-  for of key pairs.
-
-  Example:
-
-  .. code-block:: lua
-
-    default_access.properties = {
-      ["enable-flatpak-portal"] = true,
-    }
-
-  The above example sets to ``true`` the ``enable-flatpak-portal`` property.
-
-  The list of valid properties are:
-
-  .. code-block:: lua
-
-    ["enable-flatpak-portal"] = true,
-
-  Whether to enable the flatpak portal or not.
-
-* *default_access.rules*
-
-  This is a Lua array that can contain objects with rules for a client object.
-  Those Lua objects have 2 properties. Similar to the
-  :ref:`ALSA configuration <config_alsa>`, the first property is ``matches``,
-  which allow users to define rules to match a client object.
-  The second property is ``default_permissions``, and it is used to set
-  permissions on the matched client object.
-
-  Example:
-
-  .. code-block:: lua
-
-    {
-      matches = {
-        {
-          { "pipewire.access", "=", "flatpak" },
-        },
-      },
-      default_permissions = "rx",
-    }
-
-  This grants read and execute permissions to all clients that have the
-  ``pipewire.access`` property set to ``flatpak``.
-
-  Possible permissions are any combination of ``r``, ``w`` and ``x`` for read,
-  write and execute; or ``all`` for all kind of permissions.
-

docs/rst/configuration/alsa.rst

@@ -1,478 +0,0 @@
-.. _config_alsa:
-
-ALSA configuration
-==================
-
-Modifying the default configuration
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-ALSA devices are created and managed by the session manager with the *alsa.lua*
-monitor script. In the default configuration, this script is loaded by
-``main.lua.d/30-alsa-monitor.lua``, which also specifies an ``alsa_monitor``
-global table that can be filled in with properties and rules in subsequent
-config files. By default, these are filled in ``main.lua.d/50-alsa-config.lua``.
-
-The ``alsa_monitor`` global table has 2 sub-tables:
-
-* *alsa_monitor.properties*
-
-  This is a simple Lua table that has key value pairs used as properties.
-
-  Example:
-
-  .. code-block:: lua
-
-    alsa_monitor.properties = {
-      ["alsa.jack-device"] = false,
-      ["alsa.reserve"] = true,
-    }
-
-  The above example will configure the ALSA monitor to not enable the JACK
-  device, and do ALSA device reservation using the mentioned DBus interface.
-
-  A list of valid properties are:
-
-  .. code-block:: lua
-
-    ["alsa.jack-device"] = false
-
-  Creates a JACK device if set to ``true``. This is not enabled by default because
-  it requires that the PipeWire JACK replacement libraries are not used by the
-  session manager, in order to be able to connect to the real JACK server.
-
-  .. code-block:: lua
-
-    ["alsa.reserve"] = true
-
-  Reserve ALSA devices via *org.freedesktop.ReserveDevice1* on D-Bus.
-
-  .. code-block:: lua
-
-    ["alsa.reserve.priority"] = -20
-
-  The used ALSA device reservation priority.
-
-  .. code-block:: lua
-
-    ["alsa.reserve.application-name"] = "WirePlumber"
-
-  The used ALSA device reservation application name.
-
-
-* *alsa_monitor.rules*
-
-  This is a Lua array that can contain objects with rules for a device or node.
-  Those objects have 2 properties. The first one is ``matches``, which allow
-  users to define rules to match a device or node. The second property is
-  ``apply_properties``, and it is used to apply properties on the matched object.
-
-  Example:
-
-  .. code-block:: lua
-
-    alsa_monitor.rules = {
-        matches = {
-          {
-            { "device.name", "matches", "alsa_card.*" },
-          },
-        },
-        apply_properties = {
-          ["api.alsa.use-acp"] = true,
-        }
-    }
-
-  This sets the API ALSA use ACP property to all devices with a name that
-  matches the ``alsa_card.*`` pattern.
-
-  The ``matches`` section is an array of arrays. On the first level, the rules
-  are ORed together, so any rule match is going to apply the properties. On
-  the second level, the rules are merged with AND, so they must all match.
-
-  Example:
-
-  .. code-block:: lua
-
-    matches = {
-      {
-        { "node.name", "matches", "alsa_input.*" },
-        { "alsa.driver_name", "equals", "snd_hda_intel" },
-      },
-      {
-        { "node.name", "matches", "alsa_output.*" },
-      },
-    },
-
-  This is equivalent to the following logic, in pseudocode:
-
-  .. code-block::
-
-    if ("node.name" MATCHES "alsa_input.*" AND "alsa.driver_name" EQUALS "snd_hda_intel" )
-       OR
-       ("node.name" MATCHES "alsa_output.*")
-    then
-       ... apply the properties ...
-    end
-
-  As you can notice, the individual rules are themselves also lua arrays. The
-  first element is a property name (ex "node.name"), the second element is a
-  verb and the third element is an expected value, which depends on the verb.
-  Internally, this uses the ``Constraint`` API, which is documented in the
-  :ref:`Object Interet API <lua_object_interest_api>` section. All the verbs
-  that you can use on ``Constraint`` are also allowed here.
-
-  .. note::
-
-    When using the "matches" verb, the values are not complete regular expressions.
-    They are wildcard patterns, which means that '*' matches an arbitrary,
-    possibly empty, string and '?' matches an arbitrary character.
-
-  All the possible properties that you can apply to devices and nodes of the
-  ALSA monitor are described in the sections below.
-
-Device properties
-^^^^^^^^^^^^^^^^^
-
-PipeWire devices correspond to the ALSA cards.
-The following properties can be configured on devices created by the monitor:
-
-.. code-block:: lua
-
-  ["api.alsa.use-acp"] = true
-
-Use the ACP (alsa card profile) code to manage the device. This will probe the
-device and configure the available profiles, ports and mixer settings. The
-code to do this is taken directly from PulseAudio and provides devices that
-look and feel exactly like the PulseAudio devices.
-
-.. code-block:: lua
-
-  ["api.alsa.use-ucm"] = true
-
-By default, the UCM configuration is used when it is available for your device.
-With this option you can disable this and use the ACP profiles instead.
-
-.. code-block:: lua
-
-  ["api.alsa.soft-mixer"] = false
-
-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. The hardware mixer will still be used to mute
-unused audio paths in the device.
-
-.. code-block:: lua
-
-  ["api.alsa.ignore-dB"] = false
-
-Setting this option to true will ignore the decibel setting configured by the
-driver. Use this when the driver reports wrong settings.
-
-.. code-block:: lua
-
-  ["device.profile-set"] = "profileset-name"
-
-This option can be used to select a custom profile set name for the device.
-Usually this is configured in Udev rules but it can also be specified here.
-
-.. code-block:: lua
-
-  ["device.profile"] = "default profile name"
-
-The default active profile name.
-
-.. code-block:: lua
-
-  ["api.acp.auto-profile"] = false
-
-Automatically select the best profile for the device. Normally this option is
-disabled because the session manager will manage the profile of the device.
-The session manager can save and load previously selected profiles. Enable
-this if your session manager does not handle this feature.
-
-.. code-block:: lua
-
-  ["api.acp.auto-port"] = false
-
-Automatically select the highest priority port that is available. This is by
-default disabled because the session manager handles the task of selecting and
-restoring ports. It can, for example, restore previously saved volumes. Enable
-this here when the session manager does not handle port restore.
-
-.. code-block:: lua
-
-  ["api.acp.probe-rate"] = 48000
-
-Sets the samplerate used for probing the ALSA devices and collecting the profiles
-and ports.
-
-.. code-block:: lua
-
-  ["api.acp.pro-channels"] = 64
-
-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.
-
-Some of the other properties that might be configured on devices:
-
-.. code-block:: lua
-
-  ["device.nick"] = "My Device",
-  ["device.description"] = "My Device"
-
-``device.description`` will show up in most apps when a device name is shown.
-
-Node Properties
-^^^^^^^^^^^^^^^
-
-Nodes are sinks or sources in the PipeWire graph. They correspond to the ALSA
-devices. In addition to the generic stream node configuration options, there are
-some alsa specific options as well:
-
-.. code-block:: lua
-
-    ["priority.driver"] = 2000
-
-This configures the node driver priority. Nodes with higher priority will be
-used as a driver in the graph. Other nodes with lower priority will have to
-resample to the driver node when they are joined in the same graph. The default
-value is set based on some heuristics.
-
-.. code-block:: lua
-
-    ["priority.session"] = 1200
-
-This configures the priority of the node when selecting a default node.
-Higher priority nodes will be more likely candidates as a default node.
-
-.. note::
-
-  By default, sources have a ``priority.session`` value around 1600-2000 and
-  sinks have a value around 600-1000. If you are increasing the priority of a
-  sink, it is **not advised** to use a value higher than 1500, as it may cause
-  a sink's monitor to be selected as a default source.
-
-.. code-block:: lua
-
-    ["node.pause-on-idle"] = false
-
-Pause-on-idle will stop the node when nothing is linked to it anymore.
-This is by default false because some devices cause a pop when they are
-opened/closed. The node will, normally, pause and suspend after a timeout
-(see suspend-node.lua).
-
-.. code-block:: lua
-
-    ["session.suspend-timeout-seconds"] = 5  -- 0 disables suspend
-
-This option configures a different suspend timeout on the node.
-By default this is 5 seconds. For some devices (HiFi amplifiers, for example)
-it might make sense to set a higher timeout because they might require some
-time to restart after being idle.
-
-A value of 0 disables suspend for a node and will leave the ALSA device busy.
-The device can then manually be suspended with ``pactl suspend-sink|source``.
-
-**The following properties can be used to configure the format used by the
-ALSA device:**
-
-.. code-block:: lua
-
-    ["audio.format"] = "S16LE"
-
-By default, PipeWire will use a 32 bits sample format but a different format
-can be set here.
-
-The Audio rate of a device can be set here:
-
-.. code-block:: lua
-
-    ["audio.rate"] = 44100
-
-By default, the ALSA device will be configured with the same samplerate as the
-global graph. If this is not supported, or a custom values is set here,
-resampling will be used to match the graph rate.
-
-.. code-block:: lua
-
-    ["audio.channels"] = 2
-    ["audio.position"] = "FL,FR"
-
-By default the channels and their position are determined by the selected
-Device profile. You can override this setting here and optionally swap or
-reconfigure the channel positions.
-
-.. code-block:: lua
-
-    ["api.alsa.use-chmap"] = false
-
-Use the channel map as reported by the driver. This is disabled by default
-because it is often wrong and the ACP code handles this better.
-
-.. code-block:: lua
-
-    ["api.alsa.disable-mmap"]  = true
-
-PipeWire will by default access the memory of the device using mmap.
-This can be disabled and force the usage of the slower read and write access
-modes in case the mmap support of the device is not working properly.
-
-.. code-block:: lua
-
-    ["channelmix.normalize"] = true
-
-Makes sure that during such mixing & resampling original 0 dB level is
-preserved, so nothing sounds wildly quieter/louder.
-
-.. code-block:: lua
-
-    ["channelmix.mix-lfe"] = true
-
-Creates "center" channel for X.0 recordings from front stereo on X.1 setups and
-pushes some low-frequency/bass from "center" from X.1 recordings into front
-stereo on X.0 setups.
-
-.. code-block:: lua
-
-    ["monitor.channel-volumes"] = false
-
-By default, the volume of the sink/source does not influence the volume on the
-monitor ports. Set this option to true to change this. PulseAudio has
-inconsistent behaviour regarding this option, it applies channel-volumes only
-when the sink/source is using software volumes.
-
-ALSA buffer properties
-^^^^^^^^^^^^^^^^^^^^^^
-
-PipeWire uses a timer to consume and produce samples to/from ALSA devices.
-After every timeout, it queries the device hardware pointers of the device and
-uses this information to set a new timeout. See also this example program.
-
-By default, PipeWire handles ALSA batch devices differently from non-batch
-devices. Batch devices only get their hardware pointers updated after each
-hardware interrupt. Non-batch devices get updates independent of the interrupt.
-This means that for batch devices we need to set the interrupt at a sufficiently
-high frequency (at the cost of CPU usage) while for non-batch devices we want to
-set the interrupt frequency as low as possible (to save CPU).
-
-For batch devices we also need to take the extra buffering into account caused
-by the delayed updates of the hardware pointers.
-
-Most USB devices are batch devices and will be handled as such by PipeWire by
-default.
-
-There are 2 tunable parameters to control the buffering and timeouts in a
-device
-
-.. code-block:: lua
-
-    ["api.alsa.period-size"] = 1024
-
-This sets the device interrupt to every period-size samples for non-batch
-devices and to half of this for batch devices. For batch devices, the other
-half of the period-size is used as extra buffering to compensate for the delayed
-update. So, for batch devices, there is an additional period-size/2 delay.
-It makes sense to lower the period-size for batch devices to reduce this delay.
-
-.. code-block:: lua
-
-    ["api.alsa.headroom"] = 0
-
-This adds extra delay between the hardware pointers and software pointers.
-In most cases this can be set to 0. For very bad devices or emulated devices
-(like in a VM) it might be necessary to increase the headroom value.
-In summary, this is the overview of buffering and timings:
-
-
-  ============== ========================================== =========
-  Property       Batch                                      Non-Batch
-  ============== ========================================== =========
-  IRQ Frequency  api.alsa.period-size/2                     api.alsa.period-size
-  Extra Delay    api.alsa.headroom + api.alsa.period-size/2 api.alsa.headroom
-  ============== ========================================== =========
-
-It is possible to disable the batch device tweaks with:
-
-.. code-block:: lua
-
-    ["api.alsa.disable-batch"] = true
-
-It removes the extra delay added of period-size/2 if the device can support this.
-For batch devices it is also a good idea to lower the period-size
-(and increase the IRQ frequency) to get smaller batch updates and lower latency.
-
-ALSA extra latency properties
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Extra internal delay in the DAC and ADC converters of the device itself can be
-set with the ``latency.internal.*`` properties:
-
-.. code-block:: lua
-
-    ["latency.internal.rate"] = 256
-    ["latency.internal.ns"] = 0
-
-You can configure a latency in samples (relative to rate with
-``latency.internal.rate``) or in nanoseconds (``latency.internal.ns``).
-This value will be added to the total reported latency by the node of the device.
-
-You can use a tool like ``jack_iodelay`` to get the number of samples of
-internal latency of your device.
-
-This property is also adjustable at runtime with the ``ProcessLatency`` param.
-You will need to find the id of the Node you want to change. For example:
-Query the current internal latency of an ALSA node with id 58:
-
-.. code-block:: console
-
-    $ pw-cli e 58 ProcessLatency
-    Object: size 80, type Spa:Pod:Object:Param:ProcessLatency (262156), id Spa:Enum:ParamId:ProcessLatency (16)
-      Prop: key Spa:Pod:Object:Param:ProcessLatency:quantum (1), flags 00000000
-        Float 0.000000
-      Prop: key Spa:Pod:Object:Param:ProcessLatency:rate (2), flags 00000000
-        Int 0
-      Prop: key Spa:Pod:Object:Param:ProcessLatency:ns (3), flags 00000000
-        Long 0
-
-Set the internal latency to 256 samples:
-
-.. code-block:: console
-
-    $ pw-cli s 58 ProcessLatency '{ rate = 256 }'
-    Object: size 32, type Spa:Pod:Object:Param:ProcessLatency (262156), id Spa:Enum:ParamId:ProcessLatency (16)
-      Prop: key Spa:Pod:Object:Param:ProcessLatency:rate (2), flags 00000000
-        Int 256
-    remote 0 node 58 changed
-    remote 0 port 70 changed
-    remote 0 port 72 changed
-    remote 0 port 74 changed
-    remote 0 port 76 changed
-
-Startup tweaks
-^^^^^^^^^^^^^^
-
-Some devices need some time before they can report accurate hardware pointer
-positions. In those cases, an extra start delay can be added that is used to
-compensate for this startup delay:
-
-.. code-block:: lua
-
-    ["api.alsa.start-delay"] = 0
-
-It is unsure when this tunable should be used.
-
-IEC958 (S/PDIF) passthrough
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-S/PDIF passthrough will only be enabled when the accepted codecs are configured
-on the ALSA device.
-
-This can be done in 3 different ways:
-
-  1. Use pavucontrol and toggle the codecs in the output advanced section
-
-  2. Modify the ``["iec958.codecs"] = "[ PCM DTS AC3 MPEG MPEG2-AAC EAC3 TrueHD DTS-HD ]"``
-     node property to something.
-
-  3. Use ``pw-cli s <node-id> Props '{ iec958Codecs : [ PCM ] }'`` to modify
-     the codecs at runtime.

docs/rst/configuration/bluetooth.rst

@@ -1,160 +0,0 @@
-.. _config_bluetooth:
-
-Bluetooth configuration
-=======================
-
-Using the same format as the :ref:`ALSA monitor <config_alsa>`, the
-configuration file ``bluetooth.lua.d/50-bluez-config.lua`` is charged
-to configure the Bluetooth devices and nodes created by WirePlumber.
-
-* *bluez_monitor.properties*
-
-  A Lua object that contains generic client configuration properties in the
-  for of key pairs.
-
-  Example:
-
-  .. code-block:: lua
-
-    bluez_monitor.properties = {
-      ["bluez5.enable-msbc"] = true,
-    }
-
-  This example will enable the MSBC codec in connected Bluetooth devices that
-  support it.
-
-  The list of valid properties are:
-
-  .. code-block:: lua
-
-    ["bluez5.enable-sbc-xq"] = true
-
-  Enables the SBC-XQ codec in connected Blueooth devices that support it
-
-  .. code-block:: lua
-
-    ["bluez5.enable-msbc"] = true
-
-  Enables the MSBC codec in connected Blueooth devices that support it
-
-  .. code-block:: lua
-
-    ["bluez5.enable-hw-volume"] = true
-
-  Enables hardware volume controls in Bluetooth devices that support it
-
-  .. code-block:: lua
-
-    ["bluez5.headset-roles"] = "[ hsp_hs hsp_ag hfp_hf hfp_ag ]"
-
-  Enabled headset roles (default: [ hsp_hs hfp_ag ]), this property only applies
-  to native backend. Currently some headsets (Sony WH-1000XM3) are not working
-  with both hsp_ag and hfp_ag enabled, disable either hsp_ag or hfp_ag to work
-  around it.
-
-  Supported headset roles: ``hsp_hs`` (HSP Headset), ``hsp_ag`` (HSP Audio Gateway),
-  ``hfp_hf`` (HFP Hands-Free) and ``hfp_ag`` (HFP Audio Gateway)
-
-  .. code-block:: lua
-
-    ["bluez5.codecs"] = "[ sbc sbc_xq aac ]"
-
-  Enables ``sbc``, ``sbc_zq`` and ``aac`` A2DP codecs.
-
-  Supported codecs: ``sbc``, ``sbc_xq``, ``aac``, ``ldac``, ``aptx``,
-  ``aptx_hd``, ``aptx_ll``, ``aptx_ll_duplex``, ``faststream``, ``faststream_duplex``.
-
-  All codecs are supported by default.
-
-  .. code-block:: lua
-
-    ["bluez5.hfphsp-backend"] = "native"
-
-  HFP/HSP backend (default: native). Available values: ``any``, ``none``,
-  ``hsphfpd``, ``ofono`` or ``native``.
-
-  .. code-block:: lua
-
-    ["bluez5.default.rate"] = 48000
-
-  The bluetooth default audio rate.
-
-  .. code-block:: lua
-
-    ["bluez5.default.channels"] = 2
-
-  The bluetooth default number of channels.
-
-* *bluez_monitor.rules*
-
-  Like in the :ref:`ALSA configuration <config_alsa>`, this is a Lua array that
-  can contain objects with rules for a Bluetooth device or node.
-  Those objects have 2 properties. The first one is ``matches``, which allows
-  users to define rules to match a Bluetooth device or node.
-  The second property is ``apply_properties``, and it is used to apply
-  properties on the matched Bluetooth device or node.
-
-  Example:
-
-  .. code-block:: lua
-
-    {
-      matches = {
-        {
-          { "device.name", "matches", "bluez_card.*" },
-        },
-      },
-      apply_properties = {
-         ["bluez5.auto-connect"]  = "[ hfp_hf hsp_hs a2dp_sink ]"
-      }
-    }
-
-  This will set the auto-connect property to ``hfp_hf``, ``hsp_hs`` and ``a2dp_sink``
-  on bluetooth devices whose name matches the ``bluez_card.*`` pattern.
-
-  A list of valid properties are:
-
-  .. code-block:: lua
-
-    ["bluez5.auto-connect"] = "[ hfp_hf hsp_hs a2dp_sink ]"
-
-  Auto-connect device profiles on start up or when only partial profiles have
-  connected. Disabled by default if the property is not specified.
-
-  Supported values are: ``hfp_hf``, ``hsp_hs``, ``a2dp_sink``, ``hfp_ag``,
-  ``hsp_ag`` and ``a2dp_source``.
-
-  .. code-block:: lua
-
-    ["bluez5.hw-volume"] = "[ hfp_ag hsp_ag a2dp_source ]"
-
-  Hardware volume controls (default: ``hfp_ag``, ``hsp_ag``, and ``a2dp_source``)
-
-  Supported values are: ``hfp_hf``, ``hsp_hs``, ``a2dp_sink``, ``hfp_ag``,
-  ``hsp_ag`` and ``a2dp_source``.
-
-  .. code-block:: lua
-
-    ["bluez5.a2dp.ldac.quality"] = "auto"
-
-  LDAC encoding quality.
-
-  Available values: ``auto`` (Adaptive Bitrate, default),
-  ``hq`` (High Quality, 990/909kbps), ``sq`` (Standard Quality, 660/606kbps) and
-  ``mq`` (Mobile use Quality, 330/303kbps).
-
-  .. code-block:: lua
-
-    ["bluez5.a2dp.aac.bitratemode"] = 0
-
-  AAC variable bitrate mode.
-
-  Available values: 0 (cbr, default), 1-5 (quality level).
-
-  .. code-block:: lua
-
-    ["device.profile"] = "a2dp-sink"
-
-  Profile connected first.
-
-  Available values: ``a2dp-sink`` (default) or ``headset-head-unit``.

docs/rst/configuration/config_lua.rst

@@ -1,185 +0,0 @@
-.. _config_lua:
-
-Lua Configuration Files
-=======================
-
-Lua configuration files are similar to the main configuration file, but they
-leverage the Lua language to enable advanced configuration of module arguments
-and allow split-file configuration.
-
-There is only one global section that WirePlumber reads from these files: the
-**components** table. This table is equivalent to the **context.components**
-object on the main configuration file. Its purpose is to list components that
-WirePlumber should load on startup.
-
-Every line on the **components** table should be another table that contains
-information about the loaded component::
-
-  {
-    "component-name",
-    type = "component-type",
-    args = { additional arguments },
-    optional = true/false,
-  }
-
-* **component-name**: Should be the name of the component to load
-  (ex. *"libwireplumber-module-mixer-api"*).
-
-* **component-type**: Should be the type of the component.
-  Valid component types include:
-
-  * ``module``: A WirePlumber shared object module.
-  * ``script/lua``: A WirePlumber Lua script.
-  * ``pw_module``: A PipeWire shared object module (loaded on WirePlumber,
-    not on the PipeWire daemon).
-
-* **args**: Is an optional table that can contain additional arguments to be
-  passed down to the module or script. Scripts can retrieve these arguments
-  by declaring a line that reads ``local config = ...`` at the top of the script.
-  Modules receive these arguments as a GVariant ``a{sv}`` table.
-
-* **optional**: Is a boolean value that specifies whether loading of this
-  component is optional. The default value is ``false``. If set to ``true``,
-  then WirePlumber will not fail loading if the component is not found.
-
-Split-File Configuration
-------------------------
-
-When a Lua configuration file is loaded, the engine also looks for additional
-files in a directory that has the same name as the configuration file and a
-``.d`` suffix.
-
-A Lua directory can contain a list of Lua configuration files. Those files are
-loaded alphabetically by filename so that user can control the order in which
-Lua configuration files are executed.
-
-Lua files in the directory are always loaded *after* the configuration file
-that is out of the directory. However, it is perfectly valid to not have any
-configuration file out of the directory.
-
-Example hierarchy with files both in and out of the directory
-(in the order of loading)::
-
-  config.lua
-  config.lua.d/00-functions.lua
-  config.lua.d/01-alsa.lua
-  config.lua.d/10-policy.lua
-  config.lua.d/99-misc.lua
-
-Example hierarchy with files only in the directory
-(in the order of loading)::
-
-  config.lua.d/00-functions.lua
-  config.lua.d/01-alsa.lua
-  config.lua.d/10-policy.lua
-  config.lua.d/99-misc.lua
-
-Example of a file using alsa_monitor.rules in a split-file configuration:
-
-.. code-block:: lua
-
-  table.insert (alsa_monitor.rules, {
-    matches = {
-      {
-        { "device.name", "matches", "alsa_card.*" },
-      },
-    },
-    apply_properties = {
-      ["api.alsa.use-acp"] = true,
-    }
-  })
-
-Multi-Path Merging
-------------------
-
-WirePlumber looks for configuration files in 3 different places, as described
-in the :ref:`Locations of files <config_locations>` section. When a split-file
-configuration scheme is used, files will be merged from these different locations.
-
-For example, consider these files exist on the filesystem::
-
-  /usr/share/wireplumber/config.lua.d/00-functions.lua
-  /usr/share/wireplumber/config.lua.d/01-alsa.lua
-  /usr/share/wireplumber/config.lua.d/10-policy.lua
-  /usr/share/wireplumber/config.lua.d/99-misc.lua
-  ...
-  /etc/wireplumber/config.lua.d/01-alsa.lua
-  ...
-  /home/user/.config/wireplumber/config.lua.d/11-policy-extras.lua
-
-In this case, loading ``config.lua`` will result in loading these files
-(in this order)::
-
-  /usr/share/wireplumber/config.lua.d/00-functions.lua
-  /etc/wireplumber/config.lua.d/01-alsa.lua
-  /usr/share/wireplumber/config.lua.d/10-policy.lua
-  /home/user/.config/wireplumber/config.lua.d/11-policy-extras.lua
-  /usr/share/wireplumber/config.lua.d/99-misc.lua
-
-This is useful to keep the default configuration in /usr and override it
-with host-specific and user-specific parts in /etc and /home respectively.
-
-As an exception to this rule, if the configuration path is overridden with
-the ``WIREPLUMBER_CONFIG_DIR`` environment variable, then configuration files
-will only be loaded from this path and no merging will happen.
-
-Functions
----------
-
-Because of the nature of these files (they are scripts!), it is more convenient
-to manage the **components** table through functions. In the default
-configuration files shipped with WirePlumber, there is a file called
-``00-functions.lua`` that defines some helper functions to load components.
-
-When loading components through these functions, *duplicate calls are ignored*,
-so it is possible to call a function to load a specific component multiple times
-and it will only be loaded once.
-
-.. function:: load_module(module, args)
-
-   Loads a WirePlumber shared object module.
-
-   :param string module: the module name, without the "libwireplumber-module-"
-      prefix (ex specify "mixer-api" to load "libwireplumber-module-mixer-api")
-   :param table args: optional module arguments table
-
-.. function:: load_optional_module(module, args)
-
-   Loads an optional WirePlumber shared object module. Optional in this case
-   means that if the module is not present on the filesystem, it will be ignored.
-
-   :param string module: the module name, without the "libwireplumber-module-"
-      prefix (ex specify "mixer-api" to load "libwireplumber-module-mixer-api")
-   :param table args: optional module arguments table
-
-.. function:: load_pw_module(module)
-
-   Loads a PipeWire shared object module
-
-   :param string module: the module name, without the "libpipewire-module-"
-      prefix (ex specify "adapter" to load "libpipewire-module-adapter")
-
-.. function:: load_script(script, args)
-
-   Loads a Lua script (a functionality script, not a lua configuration file)
-
-   :param string script: the script's filename (ex. "policy-node.lua")
-   :param table args: optional script arguments table
-
-.. function:: load_monitor(monitor, args)
-
-   Loads a Lua monitor script. Monitors are scripts found in the ``monitors/``
-   directory and their purpose is to monitor and load devices.
-
-   :param string monitor: the scripts's name without the directory or the .lua
-      extension (ex. "alsa" will load "monitors/alsa.lua")
-   :param table args: optional script arguments table
-
-.. function:: load_access(access, args)
-
-   Loads a Lua access script. Access scripts are ones found in the ``access/``
-   directory and their purpose is to manage application permissions.
-
-   :param string access: the scripts's name without the directory or the .lua
-      extension (ex. "flatpak" will load "access/access-flatpak.lua")
-   :param table args: optional script arguments table

docs/rst/configuration/locations.rst

@@ -1,94 +0,0 @@
-.. _config_locations:
-
-Locations of files
-==================
-
-Location of configuration files
--------------------------------
-
-WirePlumber's default locations of its configuration files are determined at
-compile time by the build system. Typically, those end up being
-``$XDG_CONFIG_DIR/wireplumber``, ``/etc/wireplumber``, and
-``/usr/share/wireplumber``, in that order of priority.
-
-In more detail, the latter two are controlled by the ``--sysconfdir`` and ``--datadir``
-meson options. When those are set to an absolute path, such as ``/etc``, the
-location of the configuration files is set to be ``$sysconfdir/wireplumber``.
-When set to a relative path, such as ``etc``, then the installation prefix (``--prefix``)
-is prepended to the path: ``$prefix/$sysconfdir/wireplumber``
-
-The three locations are intended for custom user configuration,
-host-specific configuration and distribution-provided configuration,
-respectively. At runtime, WirePlumber will search the directories
-for the highest-priority directory to contain the needed configuration file.
-This allows a user or system administrator to easily override the distribution
-provided configuration files by placing an equally named file in the respective
-directory.
-
-It is also possible to override the configuration directory by setting the
-``WIREPLUMBER_CONFIG_DIR`` environment variable::
-
-  WIREPLUMBER_CONFIG_DIR=src/config wireplumber
-
-If ``WIREPLUMBER_CONFIG_DIR`` is set, the default locations are ignored and
-configuration files are *only* looked up in this directory.
-
-
-Location of scripts
--------------------
-
-WirePlumber's default locations of its scripts are the same ones as for the
-configuration files, but with the ``scripts`` directory appended.
-Typically, these end up being ``$XDG_CONFIG_DIR/wireplumber/scripts``,
-``/etc/wireplumber/scripts``, and ``/usr/share/wireplumber/scripts``,
-in that order of priority.
-
-The three locations are intended for custom user scripts,
-host-specific scripts and distribution-provided scripts, respectively.
-At runtime, WirePlumber will search the directories for the highest-priority
-directory to contain the needed script.
-
-It is also possible to override the scripts directory by setting the
-``WIREPLUMBER_DATA_DIR`` environment variable::
-
-  WIREPLUMBER_DATA_DIR=src wireplumber
-
-The "data" directory is a somewhat more generic path that may be used for
-other kinds of data files in the future. For scripts, WirePlumber still expects
-to find a ``scripts`` subdirectory in this "data" directory, so in the above
-example the scripts would be in ``src/scripts``.
-
-If ``WIREPLUMBER_DATA_DIR`` is set, the default locations are ignored and
-scripts are *only* looked up in this directory.
-
-Location of modules
--------------------
-
-WirePlumber modules
-^^^^^^^^^^^^^^^^^^^
-
-Like with configuration files, WirePlumber's default location of its modules is
-determined at compile time by the build system. Typically, it ends up being
-``/usr/lib/wireplumber-0.4`` (or ``/usr/lib/<arch-triplet>/wireplumber-0.4`` on
-multiarch systems)
-
-In more detail, this is controlled by the ``--libdir`` meson option. When
-this is set to an absolute path, such as ``/lib``, the location of the
-modules is set to be ``$libdir/wireplumber-$abi_version``. When this is set
-to a relative path, such as ``lib``, then the installation prefix (``--prefix``)
-is prepended to the path: ``$prefix/$libdir/wireplumber-$abi_version``.
-
-It is possible to override this directory at runtime by setting the
-``WIREPLUMBER_MODULE_DIR`` environment variable::
-
-  WIREPLUMBER_MODULE_DIR=build/modules wireplumber
-
-PipeWire and SPA modules
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-PipeWire and SPA modules are not loaded from the same location as WirePlumber's
-modules. They are loaded from the location that PipeWire loads them.
-
-It is also possible to override these locations by using environment variables:
-``SPA_PLUGIN_DIR`` and ``PIPEWIRE_MODULE_DIR``. For more details, refer to
-PipeWire's documentation.

docs/rst/configuration/main.rst

@@ -1,126 +0,0 @@
-.. _config_main:
-
-Main configuration file
-=======================
-
-The main configuration file is by default called ``wireplumber.conf``. This can
-be changed on the command line by passing the ``--config-file`` or ``-c`` option::
-
-  wireplumber --config-file=bluetooth.conf
-
-The ``--config-file`` option is useful to run multiple instances of wireplumber
-that do separate tasks each. For more information on this subject, see the
-:ref:`Multiple Instances <config_multi_instance>` section.
-
-The format of this configuration file is the variant of JSON that is also
-used in PipeWire configuration files. Note that this is subject to change
-in the future.
-
-All sections are essentially JSON objects. Lines starting with *#* are treated
-as comments and ignored. The list of all possible section JSON objects are:
-
-* *context.properties*
-
-  Used to define properties to configure the PipeWire context and some modules.
-
-  Example::
-
-    context.properties = {
-      application.name = WirePlumber
-      log.level = 2
-    }
-
-  This sets the daemon's name to *WirePlumber* and the log level to *2*, which
-  only displays errors and warnings. See the
-  :ref:`Debug Logging <logging>` section for more details.
-
-* *context.spa-libs*
-
-  Used to find spa factory names. It maps a spa factory name regular expression
-  to a library name that should contain that factory. The object property names
-  are the regular expression, and the object property values are the actual
-  library name::
-
-    <factory-name regex> = <library-name>
-
-  Example::
-
-    context.spa-libs = {
-      api.alsa.*      = alsa/libspa-alsa
-      audio.convert.* = audioconvert/libspa-audioconvert
-    }
-
-  In this example, we instruct wireplumber to only any *api.alsa.** factory name
-  from the *libspa-alsa* library, and also any *audio.convert.** factory name
-  from the *libspa-audioconvert* library.
-
-* *context.modules*
-
-  Used to load PipeWire modules. This does not affect the PipeWire daemon by any
-  means. It exists simply to allow loading *libpipewire* modules in the PipeWire
-  core that runs inside WirePlumber. This is usually useful to load PipeWire
-  protocol extensions, so that you can export custom objects to PipeWire and
-  other clients.
-
-  Users can also pass key-value pairs if the specific module has arguments, and
-  a combination of 2 flags: ``ifexists`` flag is given, the module is ignored when
-  not found; if ``nofail`` is given, module initialization failures are ignored::
-
-    {
-      name = <module-name>
-      [ args = { <key> = <value> ... } ]
-      [ flags = [ [ ifexists ] [ nofail ] ]
-    }
-
-  Example::
-
-    context.modules = [
-      { name = libpipewire-module-adapter }
-      {
-        name = libpipewire-module-metadata,
-        flags = [ ifexists ]
-      }
-    ]
-
-  The above example loads both PipeWire adapter and metadata modules. The
-  metadata module will be ignored if not found because of its ``ifexists`` flag.
-
-* *context.components*
-
-  Used to load WirePlumber components. Components can be either WirePlumber
-  modules written in C, WirePlumber scripts or other configuration
-  files::
-
-    { name = <component-name>, type = <component-type> }
-
-  Valid component types include:
-
-  * ``module``: A WirePlumber shared object module
-  * ``script/lua``: A WirePlumber Lua script
-    (requires ``libwireplumber-module-lua-scripting``)
-  * ``config/lua``: A WirePlumber Lua configuration file
-    (requires ``libwireplumber-module-lua-scripting``)
-
-  Example::
-
-    context.components = [
-      { name = libwireplumber-module-lua-scripting, type = module }
-      { name = main.lua, type = config/lua }
-    ]
-
-  This will load the WirePlumber lua-scripting module, dynamically, and then
-  it will also load any components specified in the ``main.lua`` file.
-
-  .. note::
-
-    When loading lua configuration files, WirePlumber will also look for
-    additional files in the directory suffixed with ``.d`` and will load
-    all of them as well. For example, loading ``example.lua`` will also load
-    any ``.lua`` files under ``example.lua.d/``. In addition, the presence of the
-    main file is optional, so it is valid to specify ``example.lua`` in the
-    component name, while ``example.lua`` doesn't exist, but ``example.lua.d/``
-    exists instead and has ``.lua`` files to load.
-
-    For more information about lua configuration files, see the
-    :ref:`Lua configuration files <config_lua>` section.
-

docs/rst/configuration/meson.build

@@ -1,11 +0,0 @@
-# you need to add here any files you add to the toc directory as well
-sphinx_files += files(
-  'locations.rst',
-  'main.rst',
-  'config_lua.rst',
-  'multi_instance.rst',
-  'alsa.rst',
-  'bluetooth.rst',
-  'policy.rst',
-  'access.rst',
-)

docs/rst/configuration/multi_instance.rst

@@ -1,45 +0,0 @@
-.. _config_multi_instance:
-
-Running multiple instances
-==========================
-
-WirePlumber has the ability to run either as a single instance daemon or as
-multiple instances, meaning that there can be multiple processes, each one
-doing a different task.
-
-In the default configuration, both setups are supported. The default is to run
-in single-instance mode.
-
-In single-instance mode, WirePlumber reads ``wireplumber.conf``, which is the
-default configuration file, and from there it loads ``main.lua``, ``policy.lua``
-and ``bluetooth.lua``, which are lua configuration files (deployed as directories)
-that enable all the relevant functionality.
-
-In multi-instance mode, WirePlumber is meant to be started with the
-``--config-file`` command line option 3 times:
-
-.. code-block:: console
-
-  $ wireplumber --config-file=main.conf
-  $ wireplumber --config-file=policy.conf
-  $ wireplumber --config-file=bluetooth.conf
-
-That loads one process which reads ``main.conf``, which then loads ``main.lua``
-and enables core functionality. Then another process that reads ``policy.conf``,
-which then loads ``policy.lua`` and enables policy functionality... and so on.
-
-To make this easier to work with, a template systemd unit is provided, which is
-meant to be started with the name of the main configuration file as a
-template argument:
-
-.. code-block:: console
-
-  $ systemctl --user disable wireplumber # disable the single instance
-
-  $ systemctl --user enable wireplumber@main
-  $ systemctl --user enable wireplumber@policy
-  $ systemctl --user enable wireplumber@bluetooth
-
-It is obviously possible to start as many instances as desired, with manually
-crafted configuration files, as long as it is ensured that these instances
-serve a different purpose and they do not conflict with each other.

docs/rst/configuration/policy.rst

@@ -1,116 +0,0 @@
-.. _config_policy:
-
-Policy Configuration
-====================
-
-policy.lua.d/10-default-policy.lua
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This file contains generic default policy properties that can be configured.
-
-* *default_policy.policy*
-
-  This is a Lua object that contains several properties that change the
-  behavior of the default WirePlumber policy.
-
-  Example:
-
-  .. code-block:: lua
-
-    default_policy.policy = {
-      ["move"] = true,
-    }
-
-  The above example will set the ``move`` policy property to ``true``.
-
-  The list of supported properties are:
-
-  .. code-block:: lua
-
-    ["move"] = true
-
-  Moves session items when metadata ``target.node`` changes.
-
-  .. code-block:: lua
-
-    ["follow"] = true
-
-  Moves session items to the default device when it has changed.
-
-  .. code-block:: lua
-
-    ["audio.no-dsp"] = false
-
-  Set to ``true`` to disable channel splitting & merging on nodes and enable
-  passthrough of audio in the same format as the format of the device. Note that
-  this breaks JACK support; it is generally not recommended.
-
-  .. code-block:: lua
-
-    ["duck.level"] = 0.3
-
-  How much to lower the volume of lower priority streams when ducking. Note that
-  this is a linear volume modifier (not cubic as in PulseAudio).
-
-policy.lua.d/50-endpoints-config.lua
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-  Endpoints are objects that can group multiple clients into different groups or
-  roles. This is useful if a user wants to apply specific actions when a client
-  is connected to a particular role/endpoint. This configuration file allows
-  users to configure those endpoints and their actions.
-
-* *default_policy.policy.roles*
-
-  This is a Lua array with objects defining the actions of each role.
-
-  Example:
-
-  .. code-block:: lua
-
-    default_policy.policy.roles = {
-      ["Multimedia"] = {
-        ["alias"] = { "Movie", "Music", "Game" },
-        ["priority"] = 10,
-        ["action.default"] = "mix",
-      }
-      ["Notification"] = {
-        ["priority"] = 20,
-        ["action.default"] = "duck",
-        ["action.Notification"] = "mix",
-      }
-    }
-
-  The above example defines actions for both ``Multimedia`` and ``Notification``
-  roles. Since the Notification role has more priority than the Multimedia
-  role, when a client connects to the Notification endpoint, it will ``duck``
-  the volume of all Multimedia clients. If Multiple Notification clients want
-  to play audio, only the Notifications audio will be mixed.
-
-  Possible values of actions are: ``mix`` (Mixes audio),
-  ``duck`` (Mixes and lowers the audio volume) or ``cork`` (Pauses audio).
-
-* *default_policy.policy.endpoints*
-
-  This is a Lua array with objects defining the endpoints that the user wants
-  to create.
-
-  Example:
-
-  .. code-block:: lua
-
-    default_policy.endpoints = {
-      ["endpoint.multimedia"] = {
-        ["media.class"] = "Audio/Sink",
-        ["role"] = "Multimedia",
-      }
-    },
-    ["endpoint.notifications"] = {
-      ["media.class"] = "Audio/Sink",
-      ["role"] = "Notification",
-    }
-
-  This example creates 2 endpoints, with names ``endpoint.multimedia`` and
-  ``endpoint.notifications``; and assigned roles ``Multimedia`` and ``Notification``
-  respectively. Both endpoints have ``Audio/Sink`` media class, and so are only
-  used for playback.

docs/rst/daemon-logging.rst

@@ -1,139 +0,0 @@
- .. _logging:
-
-Debug Logging
-=============
-
-Getting debug messages on the command line is a matter of setting the
-``WIREPLUMBER_DEBUG`` environment variable. The generic syntax is:
-
-.. code::
-
-   WIREPLUMBER_DEBUG=level:category1,category2,...
-
-``level`` can be one of ``CEWMIDT`` or a numerical log level as listed below.
-In either case it defines the minimum debug level to show:
-
-  0. critical warnings and fatal errors (``C`` & ``E`` in the log)
-  1. warnings (``W``)
-  2. normal messages (``M``)
-  3. informational messages (``I``)
-  4. debug messages (``D``)
-  5. trace messages (``T``)
-
-``category1,category2,...`` is an *optional* comma-separated list of debug
-categories to show. Any categories not listed here will *not* appear in the log.
-If no categories are specified, then all messages are printed.
-
-Categories support
-`glob style patterns <https://developer.gnome.org/glib/stable/glib-Glob-style-pattern-matching.html>`_
-containing ``*`` and ``?``, for convenience.
-
-Well known categories include:
-
-  - **wireplumber**: messages from the wireplumber daemon
-  - **pw**: messages from libpipewire & spa plugins
-  - **wp-***: messages from libwireplumber
-  - **wp-core**: messages from *WpCore*
-  - **wp-proxy**: messages from *WpProxy*
-  - ... and so on ...
-  - **m-***: messages from wireplumber modules
-  - **m-default-profile**: messages from *libwireplumber-module-default-profile*
-  - **m-default-routes**: messages from *libwireplumber-module-default-routes*
-  - ... and so on ...
-  - **script/***: messages from scripts
-  - **script/policy-node**: messages from the *policy-node.lua* script
-  - ... and so on ...
-
-Examples
---------
-
-Show all messages:
-
-.. code::
-
-   WIREPLUMBER_DEBUG=T
-
-Show all messages up to the *debug* level (E, C, W, M, I & D), excluding *trace*:
-
-.. code::
-
-   WIREPLUMBER_DEBUG=D
-
-Show all messages up to the *message* level (E, C, W & M),
-excluding *info*, *debug* & *trace*
-(this is also the default when ``WIREPLUMBER_DEBUG`` is omitted):
-
-.. code::
-
-   WIREPLUMBER_DEBUG=2
-
-Show all messages from the wireplumber library:
-
-.. code::
-
-   WIREPLUMBER_DEBUG=T:wp-*
-
-Show all messages from ``wp-registry``, libpipewire and all modules:
-
-.. code::
-
-   WIREPLUMBER_DEBUG=T:wp-registry,pw,m-*
-
-Relationship with the GLib log handler & G_MESSAGES_DEBUG
----------------------------------------------------------
-
-Older versions of WirePlumber used to use ``G_MESSAGES_DEBUG`` to control their
-log output, which is the environment variable that affects GLib's default
-log handler.
-
-As of WirePlumber 0.3, ``G_MESSAGES_DEBUG`` is no longer used, since
-libwireplumber replaces the default log handler.
-
-If you are writing your own application based on libwireplumber, you can choose
-if you want to replace this log handler using the flags passed to
-:c:func:`wp_init`.
-
-Relationship with the PipeWire log handler & PIPEWIRE_DEBUG
------------------------------------------------------------
-
-libpipewire uses the ``PIPEWIRE_DEBUG`` environment variable, with a similar syntax.
-WirePlumber replaces the log handler of libpipewire with its own, rendering
-``PIPEWIRE_DEBUG`` useless. Instead, you should use ``WIREPLUMBER_DEBUG`` and the
-``pw`` category to control log messages from libpipewire & its plugins.
-
-If you are writing your own application based on libwireplumber, you can choose
-if you want to replace this log handler using the flags passed to
-:c:func:`wp_init`.
-
-Mapping of PipeWire debug levels to WirePlumber
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Both WirePlumber and PipeWire support 6 levels of debug logging, from 0 to 5
-
-PipeWire uses a slightly different semantic for the first 3 levels:
-
-=====  ========  ===========
-Level  PipeWire  WirePlumber
-=====  ========  ===========
-0      no log    Critical / fatal Errors
-1      Errors    Warnings
-2      Warnings  Messages
-=====  ========  ===========
-
-When PipeWire log messages are printed by the WirePlumber log handler, the
-level number stays the same and the semantic changes. PipeWire's errors are
-printed in the ``W`` category and PipeWire's warnings are printed in the
-``M`` category.
-
-In WirePlumber's (actually GLib's) semantics, this feels more appropriate
-because:
-
-  - GLib's errors are fatal (``abort()`` is called)
-  - GLib's critical warnings are assertion failures (i.e. programming mistakes,
-    not runtime errors)
-  - PipeWire's errors are neither fatal, nor programming mistakes; they are
-    just bad situations that are not meant to happen
-  - GLib's warnings are exactly that: bad runtime situations that are not meant
-    to happen, so mapping PipeWire errors to GLib warnings makes sense
-  - The **Messages** log level does not exist in PipeWire, so it can be used to
-    fill the gap for PipeWire warnings

docs/rst/daemon/configuration.rst

@@ -0,0 +1,30 @@
+.. _daemon_configuration:
+
+Configuration
+=============
+
+WirePlumber is a heavily modular daemon. By itself, it doesn't do anything
+except load its configured components. The actual management logic is
+implemented inside those components.
+
+At startup, WirePlumber reads its configuration file (combined with all the
+fragments it may have) and loads the components specified in the selected
+profile. This configures the operation context. Then, the components take over
+and drive the entirety of the daemon's operation.
+
+The sections below describe in more detail the configuration file format and
+the various options available.
+
+.. toctree::
+   :maxdepth: 1
+
+   configuration/conf_file.rst
+   configuration/components_and_profiles.rst
+   configuration/configuration_option_types.rst
+   configuration/modifying_configuration.rst
+   configuration/migration.rst
+   configuration/features.rst
+   configuration/settings.rst
+   configuration/alsa.rst
+   configuration/bluetooth.rst
+   configuration/access.rst

docs/rst/daemon/configuration/access.rst

@@ -0,0 +1,125 @@
+.. _config_access:
+
+Access configuration
+====================
+
+WirePlumber includes a "client access" policy which defines access control
+rules for PipeWire clients.
+
+Rules
+-----
+
+This policy can be configured with rules that can be used to match clients and
+apply default permissions to them.
+
+Example:
+
+.. code-block::
+
+   access.rules = [
+     {
+       matches = [
+         {
+           access = "flatpak"
+           media.category = "Manager"
+         }
+       ]
+       actions = {
+         update-props = {
+           access = "flatpak-manager"
+           default_permissions = "all",
+         }
+       }
+     }
+     {
+       matches = [
+         {
+           access = "flatpak"
+         }
+       ]
+       actions = {
+         update-props = {
+           default_permissions = "rx"
+         }
+       }
+     }
+   ]
+
+Possible permissions are any combination of:
+
+ * ``r``: client is allowed to **read** objects, i.e. "see" them on the registry
+   and list their properties
+ * ``w``: client is allowed to **write** objects, i.e. call methods that modify
+   their state
+ * ``x``: client is allowed to **execute** methods on objects; the ``w`` flag
+   must also be present to call methods that modify the object
+ * ``m``: client is allowed to set **metadata** on objects
+ * ``l``: nodes of this client are allowed to **link** to other nodes that the
+   client can't "see" (i.e. the client doesn't have ``r`` permission on them)
+
+The special value ``all`` is also supported and it is synonym for ``rwxm``
+
+Permission Managers
+-------------------
+
+For more advanced use cases, WirePlumber supports *permission managers* that can
+apply per-object permissions dynamically based on rules and object interests.
+Permission managers are defined in the ``access.permission-managers`` section
+and then referenced by name in ``access.rules``.
+
+Example:
+
+.. code-block::
+
+   access.permission-managers = [
+     {
+       name = "custom"
+       default_permissions = "all"
+       core_permissions = "rx"
+       rules = [
+         {
+           matches = [
+             {
+               media.class = "Audio/Source"
+             }
+           ]
+           actions = {
+             set-permissions = "-"
+           }
+         }
+       ]
+     }
+   ]
+
+   access.rules = [
+     {
+       matches = [
+         {
+           application.name = "paplay"
+         }
+       ]
+       actions = {
+         update-props = {
+           permission_manager_name = "custom"
+         }
+       }
+     }
+   ]
+
+Each permission manager supports the following properties:
+
+ * ``name``: (required) a unique name used to reference the manager from
+   ``access.rules``
+ * ``default_permissions``: the fallback permissions applied to all objects
+   that don't match any rule (applied as ``PW_ID_ANY``)
+ * ``core_permissions``: permissions applied specifically to the PipeWire core
+   object (``PW_ID_CORE``, ID 0). This is useful when you want to allow a
+   client to interact with the core (e.g. enumerate objects, subscribe to
+   events) while restricting access to individual objects. If not set, the
+   ``default_permissions`` value is used for the core as well.
+ * ``rules``: a list of match rules with ``set-permissions`` actions that
+   grant specific permissions to objects matching the given constraints
+
+When both ``default_permissions`` and ``permission_manager_name`` are set in
+a rule's ``update-props`` action, ``default_permissions`` takes precedence and
+the permission manager is ignored.

docs/rst/daemon/configuration/alsa.rst

@@ -0,0 +1,485 @@
+.. _config_alsa:
+
+ALSA configuration
+==================
+
+One of the components of WirePlumber is the ALSA monitor. This monitor is
+responsible for creating PipeWire devices and nodes for all the ALSA cards that
+are available on the system. It also manages the configuration of these devices.
+
+The ALSA monitor is enabled by default and can be disabled using the
+``monitor.alsa`` :ref:`feature <config_features>` in the configuration file.
+
+The monitor, as with all device monitors, is implemented as a SPA plugin and is
+part of PipeWire. WirePlumber merely loads the plugin and lets it do its work.
+The plugin then monitors UDev and creates device and node objects for all the
+ALSA cards that are available on the system.
+
+.. note::
+
+   One thing worth remembering here is that in ALSA, a "card" represents a
+   physical sound controller device, and a "device" is a logical access point
+   that represents a set of inputs and/or outputs that are part of the card. In
+   PipeWire, a "device" is the direct equivalent of an ALSA "card" and a "node"
+   is almost equivalent (close, but not quite) of an ALSA "device".
+
+Properties
+----------
+
+The ALSA monitor SPA plugin (``api.alsa.enum.udev``) supports properties that
+can be used to configure it when it is loaded. These properties can be set in
+the ``monitor.alsa.properties`` section of the WirePlumber configuration file.
+
+Example:
+
+.. code-block::
+
+   monitor.alsa.properties = {
+     alsa.use-acp = true
+   }
+
+.. describe:: alsa.use-acp
+
+   A boolean that controls whether the ACP (alsa card profile) code is to be
+   the default manager of the device. This will probe the device and configure
+   the available profiles, ports and mixer settings. The code to do this is
+   taken directly from PulseAudio and provides devices that look and feel
+   exactly like the PulseAudio devices.
+
+Rules
+-----
+
+When device and node objects are created by the ALSA monitor, they can be
+configured using rules. These rules allow matching the existing properties of
+these objects and updating them with new values. This is the main way of
+configuring ALSA device settings.
+
+These rules can be set in the ``monitor.alsa.rules`` section of the WirePlumber
+configuration file.
+
+Example:
+
+.. code-block::
+
+   monitor.alsa.rules = [
+     {
+       matches = [
+         {
+           # This matches the value of the 'device.name' property of the device.
+           device.name = "~alsa_card.*"
+         }
+       ]
+       actions = {
+         update-props = {
+           # Apply all the desired device settings here.
+           api.alsa.use-acp = true
+         }
+       }
+     }
+     {
+       matches = [
+         # This matches the value of the 'node.name' property of the node.
+         {
+           node.name = "~alsa_output.*"
+         }
+       ]
+       actions = {
+         # Apply all the desired node specific settings here.
+         update-props = {
+           node.nick              = "My Node"
+           priority.driver        = 100
+           session.suspend-timeout-seconds = 5
+         }
+       }
+     }
+   ]
+
+Device properties
+^^^^^^^^^^^^^^^^^
+
+The following properties can be configured on devices created by the monitor:
+
+.. describe:: api.alsa.use-acp
+
+   Use the ACP (alsa card profile) code to manage this device. This will probe
+   the device and configure the available profiles, ports and mixer settings.
+   The code to do this is taken directly from PulseAudio and provides devices
+   that look and feel exactly like the PulseAudio devices.
+
+   :Default value: ``true``
+   :Type: boolean
+
+.. describe:: api.alsa.use-ucm
+
+   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``.
+
+   :Default value: ``true``
+   :Type: boolean
+
+.. describe:: api.alsa.soft-mixer
+
+   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. The hardware mixer will still be used
+   to mute unused audio paths in the device.
+
+   :Type: boolean
+
+.. describe:: api.alsa.ignore-dB
+
+   Setting this option to ``true`` will ignore the decibel setting configured by
+   the driver. Use this when the driver reports wrong settings.
+
+   :Type: boolean
+
+.. describe:: device.profile-set
+
+   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".
+
+   :Type: string
+
+.. describe:: device.profile
+
+   The initial active profile name. The default is to start from the "Off"
+   profile and then let WirePlumber select the best profile based on its
+   policy.
+
+   :Type: string
+
+.. describe:: api.acp.auto-profile
+
+   Automatically select the best profile for the device. Normally this option is
+   disabled because WirePlumber will manage the profile of the device.
+   WirePlumber can save and load previously selected profiles. Enable this in
+   custom configurations where the relevant WirePlumber components are disabled.
+
+   :Type: boolean
+
+.. describe:: api.acp.auto-port
+
+   Automatically select the highest priority port that is available ("port" is a
+   PulseAudio/ACP term, the equivalent of a "Route" in PipeWire). This is by
+   default disabled because WirePlumber handles the task of selecting and
+   restoring Routes. Enable this in custom configurations where the relevant
+   WirePlumber components are disabled.
+
+   :Type: boolean
+
+.. describe:: api.acp.probe-rate
+
+   Sets the samplerate used for probing the ALSA devices and collecting the
+   profiles and ports.
+
+   :Type: integer
+
+.. describe:: api.acp.pro-channels
+
+   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.
+
+   :Type: integer
+
+Some of the other properties that can be configured on devices:
+
+.. describe:: device.nick
+
+   A short name for the device.
+
+.. describe:: device.description
+
+   A longer, user-friendly name of the device. This will show up in most
+   user interfaces as the device's name.
+
+.. describe:: device.disabled
+
+   Disables the device. PipeWire will remove it from the list of cards or
+   devices.
+
+   :Type: boolean
+
+Node properties
+^^^^^^^^^^^^^^^
+
+The following properties can be configured on nodes created by the monitor:
+
+.. describe:: priority.driver
+
+   This configures the node driver priority. Nodes with higher priority will be
+   used as a driver in the graph. Other nodes with lower priority will have to
+   resample to the driver node when they are joined in the same graph. The
+   default value is set based on some heuristics.
+
+   :Type: integer
+
+.. describe:: priority.session
+
+   This configures the priority of the node when selecting a default node
+   (default sink/source as a link target for streams). Higher priority nodes
+   will be more likely candidates for becoming the default node.
+
+   :Type: integer
+
+   .. note::
+
+      By default, sources have a ``priority.session`` value around 1600-2000 and
+      sinks have a value around 600-1000. If you are increasing the priority of
+      a sink, it is **not advised** to use a value higher than 1500, as it may
+      cause a sink's monitor to be selected as the default source.
+
+.. describe:: node.pause-on-idle
+
+   Pause the node when nothing is linked to it anymore. This is by default false
+   because some devices make a "pop" sound when they are opened/closed.
+   The node will normally pause and suspend after a timeout (see below).
+
+   :Type: boolean
+
+.. describe:: session.suspend-timeout-seconds
+
+   This option configures a different suspend timeout on the node. By default
+   this is ``5`` seconds. For some devices (HiFi amplifiers, for example) it
+   might make sense to set a higher timeout because they might require some time
+   to restart after being idle.
+
+   A value of ``0`` disables suspend for a node and will leave the ALSA device
+   busy. The device can then be manually suspended with
+   ``pactl suspend-sink|source``.
+
+   :Type: integer
+
+.. describe:: audio.format
+
+   The sample format of the device. By default, PipeWire will use a 32 bits
+   sample format but a different format can be set here.
+
+   :Type: string (``"S16LE"``, ``"S32LE"``, ``"F32LE"``, ...)
+
+.. describe:: audio.rate
+
+   The sample rate of the device. By default, the ALSA device will be configured
+   with the same samplerate as the global graph. If this is not supported, or a
+   custom value is set here, resampling will be used to match the graph rate.
+
+   :Type: integer
+
+.. describe:: audio.channels
+
+   The number of channels of the device. By default the channels and their
+   position are determined by the selected device profile. You can override
+   this setting here.
+
+   :Type: integer
+
+.. describe:: audio.position
+
+   The position of the channels. By default the number of channels and their
+   position are determined by the selected device profile. You can override
+   this setting here and optionally swap or reconfigure the channel positions.
+
+   :Type: array of strings (example: ``["FL", "FR", "LFE", "FC", "RL", "RR"]``)
+
+.. describe:: api.alsa.use-chmap
+
+    Use the channel map as reported by the driver. This is disabled by default
+    because it is often wrong and the ACP code handles this better.
+
+    :Type: boolean
+
+.. describe:: api.alsa.disable-mmap
+
+   Disable the use of mmap for the ALSA device. By default, PipeWire will access
+   the memory of the device using mmap. This can be disabled and force the usage
+   of the slower read and write access modes, in case the mmap support of the
+   device is not working properly.
+
+   :Type: boolean
+
+.. describe:: channelmix.normalize
+
+   Normalize the channel volumes when mixing & resampling, making sure that the
+   original 0 dB level is preserved so that nothing sounds wildly
+   quieter/louder. This is disabled by default.
+
+   :Type: boolean
+
+.. describe:: channelmix.mix-lfe
+
+   Creates a "center" channel for X.0 recordings from the front stereo on X.1
+   setups and pushes some low-frequency/bass from the "center" of X.1 recordings
+   into the front stereo on X.0 setups. This is disabled by default.
+
+   :Type: boolean
+
+.. describe:: monitor.channel-volumes
+
+   By default, the volume of the sink/source does not influence the volume on
+   the monitor ports. Set this option to true to change this. PulseAudio has
+   inconsistent behaviour regarding this option, it applies channel-volumes only
+   when the sink/source is using software volumes.
+
+   :Type: boolean
+
+.. describe:: node.disabled
+
+   Disables the node. Pipewire will remove it from the list of the nodes.
+
+   :Type: boolean
+
+ALSA buffer properties
+......................
+
+PipeWire by default uses a timer to consume and produce samples to/from ALSA
+devices. After every timeout, it queries the hardware pointers of the device and
+uses this information to set a new timeout. This works well for most devices,
+but there is a class of devices, so called "batch" devices, that need extra
+buffering and timing tweaks to work properly. This is because batch devices only
+get their hardware pointers updated after each hardware interrupt. When the
+hardware interrupt frequency and the timer frequency are aligned, it is possible
+for the hardware pointers to be updated just after the timer has expired,
+resulting in sometimes wrong timing information being returned by the query. In
+contrast, non-batch devices get pointer updates independent of the interrupt.
+
+This means that for batch devices we need to set the interrupt at a sufficiently
+high frequency, at the cost of CPU usage, while for non-batch devices we want to
+set the interrupt frequency as low as possible to save CPU. For batch devices
+we also need to take the extra buffering into account caused by the delayed
+updates of the hardware pointers.
+
+.. note::
+
+   Most USB devices are batch devices and will be handled as such by PipeWire by
+   default.
+
+There are 2 tunable parameters to control the buffering and timeouts in a
+device:
+
+.. describe:: api.alsa.period-size
+
+   This sets the device interrupt to every period-size samples for non-batch
+   devices and to half of this for batch devices. For batch devices, the other
+   half of the period-size is used as extra buffering to compensate for the
+   delayed update. So, for batch devices, there is an additional period-size/2
+   delay. It makes sense to lower the period-size for batch devices to reduce
+   this delay.
+
+   :Type: integer (samples)
+
+.. describe:: api.alsa.headroom
+
+   This adds extra delay between the hardware pointers and software pointers.
+   In most cases this can be set to 0. For very bad devices or emulated devices
+   (like in a VM) it might be necessary to increase the headroom value.
+
+   :Type: integer (samples)
+
+.. describe:: api.alsa.period-num
+
+   This configures the number of periods in the hardware buffer, which controls
+   its size. Note that this is multiplied by the period of the device to
+   determine the size, so for batch devices, the total buffer size is
+   effectively period-num * period-size/2.
+
+   :Type: integer
+
+In summary, this is the overview of buffering and timings:
+
+============== ============================================ ==========================================
+Property       Batch                                        Non-Batch
+============== ============================================ ==========================================
+IRQ Frequency  api.alsa.period-size/2                       api.alsa.period-size
+Extra Delay    api.alsa.headroom + api.alsa.period-size/2   api.alsa.headroom
+Buffer Size    api.alsa.period-num * api.alsa.period-size/2 api.alsa.period-num * api.alsa.period-size
+============== ============================================ ==========================================
+
+Finally, it is possible to disable the batch device tweaks with:
+
+.. describe:: api.alsa.disable-batch
+
+   This disables the batch device tweaks. It removes the extra delay added of
+   period-size/2 if the device can support this. For batch devices it is also a
+   good idea to lower the period-size (and increase the IRQ frequency) to get
+   smaller batch updates and lower latency.
+
+   :Type: boolean
+
+ALSA extra latency properties
+.............................
+
+Extra internal delay in the DAC and ADC converters of the device itself can be
+set with the ``latency.internal.*`` properties:
+
+.. code-block::
+
+    latency.internal.rate = 256
+    latency.internal.ns = 0
+
+You can configure a latency in samples (relative to rate with
+``latency.internal.rate``) or in nanoseconds (``latency.internal.ns``).
+This value will be added to the total reported latency by the node of the device.
+
+You can use a tool like ``jack_iodelay`` to get the number of samples of
+internal latency of your device.
+
+This property is also adjustable at runtime with the ``ProcessLatency`` param.
+You will need to find the id of the Node you want to change. For example:
+Query the current internal latency of an ALSA node with id 58:
+
+.. code-block:: console
+
+    $ pw-cli e 58 ProcessLatency
+    Object: size 80, type Spa:Pod:Object:Param:ProcessLatency (262156), id Spa:Enum:ParamId:ProcessLatency (16)
+      Prop: key Spa:Pod:Object:Param:ProcessLatency:quantum (1), flags 00000000
+        Float 0.000000
+      Prop: key Spa:Pod:Object:Param:ProcessLatency:rate (2), flags 00000000
+        Int 0
+      Prop: key Spa:Pod:Object:Param:ProcessLatency:ns (3), flags 00000000
+        Long 0
+
+Set the internal latency to 256 samples:
+
+.. code-block:: console
+
+    $ pw-cli s 58 ProcessLatency '{ rate = 256 }'
+    Object: size 32, type Spa:Pod:Object:Param:ProcessLatency (262156), id Spa:Enum:ParamId:ProcessLatency (16)
+      Prop: key Spa:Pod:Object:Param:ProcessLatency:rate (2), flags 00000000
+        Int 256
+    remote 0 node 58 changed
+    remote 0 port 70 changed
+    remote 0 port 72 changed
+    remote 0 port 74 changed
+    remote 0 port 76 changed
+
+Startup tweaks
+..............
+
+.. describe:: api.alsa.start-delay
+
+   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. The default
+   is 0.
+
+   :Type: integer (samples)
+
+IEC958 (S/PDIF) passthrough
+...........................
+
+.. describe:: iec958.codecs
+
+   S/PDIF passthrough will only be enabled when the accepted codecs are configured
+   on the ALSA device. This can be done by setting the list of supported codecs
+   on this property.
+
+   Note that it is possible to also configure this property at runtime, either
+   with tools like pavucontrol or with the ``pw-cli`` tool, like this:
+   ``pw-cli s <node-id> Props '{ iec958Codecs : [ PCM ] }'``
+
+   :Type: array of strings (example: ``[ "PCM", "DTS", "AC3", "EAC3", "TrueHD", "DTS-HD" ]``)

docs/rst/daemon/configuration/bluetooth.rst

@@ -0,0 +1,440 @@
+.. _config_bluetooth:
+
+Bluetooth configuration
+=======================
+
+Bluetooth audio and MIDI devices are managed by the BlueZ and BlueZ-MIDI
+monitors, respectively.
+
+Both monitors are enabled by default and can be disabled using the
+``monitor.bluez`` and ``monitor.bluez-midi`` :ref:`features <config_features>`
+in the configuration file.
+
+As with all device monitors, both of these monitors are implemented as SPA
+plugins and are part of PipeWire. WirePlumber merely loads the plugins and lets
+them do their work. These plugins then monitor the BlueZ system-wide D-Bus
+service and create device and node objects for all the connected Bluetooth audio
+and MIDI devices.
+
+Logind integration
+------------------
+
+The BlueZ monitors are integrated with logind to ensure that only one user at a
+time can use the Bluetooth audio devices. This is because on most Linux desktop
+systems, the graphical login manager (GDM, SDDM, etc.) is running as a separate
+user and runs its own instance of PipeWire and Wireplumber. This means that if a
+user logs in graphically, the Bluetooth audio devices will be automatically
+grabbed by the PipeWire/WirePlumber instance of the graphical login manager,
+and the user that logs in will not get access to them.
+
+To overcome this, the BlueZ monitors are integrated with logind and are only
+allowed to create device and node objects for Bluetooth audio devices if the
+user is currently on the "active" logind session.
+
+In some cases, however, this behavior is not desired. For example, if you
+manually switch to a TTY and log in there, you may want to keep the Bluetooth
+audio devices connected to the now inactive graphical session. Or you may want
+to have a dedicated user that is always allowed to use the Bluetooth audio
+devices, regardless of the active logind session, for example for a (possibly
+headless) music player daemon.
+
+To disable this behavior, you can set the ``monitor.bluez.seat-monitoring``
+:ref:`feature <config_features>` to ``disabled``.
+
+Example configuration :ref:`fragment <config_conf_file_fragments>` file:
+
+.. code-block::
+
+   wireplumber.profiles = {
+     main = {
+       monitor.bluez.seat-monitoring = disabled
+     }
+   }
+
+.. note::
+
+   If logind is not installed on the system, this functionality is disabled
+   automatically.
+
+Monitor Properties
+------------------
+
+The BlueZ monitor SPA plugin (``api.bluez5.enum.dbus``) supports properties that
+can be used to configure it when it is loaded. These properties can be set in
+the ``monitor.bluez.properties`` section of the WirePlumber configuration file.
+
+Example:
+
+.. code-block::
+
+  monitor.bluez.properties = {
+    bluez5.roles = [ a2dp_sink a2dp_source bap_sink bap_source hsp_hs hsp_ag hfp_hf hfp_ag ]
+    bluez5.codecs = [ sbc sbc_xq aac ]
+    bluez5.enable-sbc-xq = true
+    bluez5.hfphsp-backend = "native"
+  }
+
+.. describe:: bluez5.roles
+
+   Enabled roles.
+
+   Currently some headsets (e.g. Sony WH-1000XM3) do not work 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)
+
+   :Default value: ``[ a2dp_sink a2dp_source bap_sink bap_source hfp_hf hfp_ag ]``
+   :Type: array of strings
+
+.. describe:: bluez5.codecs
+
+   Enabled A2DP codecs.
+
+   Supported codecs: ``sbc``, ``sbc_xq``, ``aac``, ``ldac``, ``aptx``,
+   ``aptx_hd``, ``aptx_ll``, ``aptx_ll_duplex``, ``faststream``,
+   ``faststream_duplex``, ``lc3plus_h3``, ``opus_05``, ``opus_05_51``,
+   ``opus_05_71``, ``opus_05_duplex``, ``opus_05_pro``, ``lc3``.
+
+   :Default value: all available codecs
+   :Type: array of strings
+
+.. describe:: bluez5.enable-msbc
+
+   Enable mSBC codec (wideband speech codec for HFP/HSP).
+
+   This does not work on all headsets, so it is enabled based on the hardware
+   quirks database. By explicitly setting this option you can force it to be
+   enabled or disabled regardless.
+
+   :Default value: ``true``
+   :Type: boolean
+
+.. describe:: bluez5.enable-sbc-xq
+
+   Enable SBC-XQ codec (high quality SBC codec for A2DP).
+
+   This does not work on all headsets, so it is enabled based on the hardware
+   quirks database. By explicitly setting this option you can force it to be
+   enabled or disabled regardless.
+
+   :Default value: ``true``
+   :Type: boolean
+
+.. describe:: bluez5.enable-hw-volume
+
+   Enable hardware volume controls.
+
+   This does not work on all headsets, so it is enabled based on the hardware
+   quirks database. By explicitly setting this option you can force it to be
+   enabled or disabled regardless.
+
+   :Default value: ``true``
+   :Type: boolean
+
+.. describe:: bluez5.hfphsp-backend
+
+   HFP/HSP backend.
+
+   Available values: ``any``, ``none``, ``hsphfpd``, ``ofono`` or ``native``.
+
+   :Default value: ``native``
+   :Type: string
+
+.. describe:: bluez5.hfphsp-backend-native-modem
+
+   Modem to use for native HFP/HSP backend ModemManager support. When enabled,
+   PipeWire will forward HFP commands to the specified ModemManager device.
+   This corresponds to the 'Device' property of the
+   ``org.freedesktop.ModemManager1.Modem`` interface. May also be ``any`` to
+   use any available modem device.
+
+   :Default value: ``none``
+   :Type: string
+
+.. describe:: bluez5.hw-offload-sco
+
+   HFP/HSP hardware offload SCO support.
+
+   Using this feature requires a custom WirePlumber script that handles audio
+   routing in a platform-specific way. See ``tests/examples/bt-pinephone.lua``
+   for an example.
+
+   :Default value: ``false``
+   :Type: boolean
+
+.. describe:: bluez5.default.rate
+
+   The default audio rate for the A2DP codec configuration.
+
+   :Default value: ``48000``
+   :Type: integer
+
+.. describe:: bluez5.default.channels
+
+   The default number of channels for the A2DP codec configuration.
+
+   :Default value: ``2``
+   :Type: integer
+
+.. describe:: bluez5.dummy-avrcp-player
+
+   Register dummy AVRCP player. Some devices have wrongly functioning volume or
+   playback controls if this is not enabled. Disabled by default.
+
+   :Default value: ``false``
+   :Type: boolean
+
+.. describe:: Opus Pro Audio mode settings
+
+   .. code-block::
+
+      bluez5.a2dp.opus.pro.channels = 3
+      bluez5.a2dp.opus.pro.coupled-streams = 1
+      bluez5.a2dp.opus.pro.locations = [ FL,FR,LFE ]
+      bluez5.a2dp.opus.pro.max-bitrate = 600000
+      bluez5.a2dp.opus.pro.frame-dms = 50
+      bluez5.a2dp.opus.pro.bidi.channels = 1
+      bluez5.a2dp.opus.pro.bidi.coupled-streams = 0
+      bluez5.a2dp.opus.pro.bidi.locations = [ FC ]
+      bluez5.a2dp.opus.pro.bidi.max-bitrate = 160000
+      bluez5.a2dp.opus.pro.bidi.frame-dms = 400
+
+   Options for the PipeWire-specific multichannel Opus codec, which can be used
+   to transport audio over Bluetooth between devices running PipeWire.
+
+MIDI Monitor Properties
+-----------------------
+
+The BlueZ MIDI monitor SPA plugin (``api.bluez5.midi.enum``) may, in the future,
+support properties that can be used to configure it when it is loaded. These
+properties can be set in the ``monitor.bluez-midi.properties`` section of the
+WirePlumber configuration file. At the moment of writing, there are no
+properties that can be set there.
+
+In addition, the BlueZ MIDI monitor supports a list of MIDI server node names
+that can be used to create Bluetooth LE MIDI service instances. These
+server node names can be set in the ``monitor.bluez-midi.servers`` section of
+the WirePlumber configuration file.
+
+Example:
+
+.. code-block::
+
+   monitor.bluez-midi.servers = [ "bluez_midi.server" ]
+
+.. note::
+
+   Typical BLE MIDI instruments have one service instance, so adding more than
+   one here may confuse some clients.
+
+Rules
+-----
+
+When device and node objects are created by the BlueZ monitor, they can be
+configured using rules. These rules allow matching the existing properties of
+these objects and updating them with new values. This is the main way of
+configuring Bluetooth device settings.
+
+These rules can be set in the ``monitor.bluez.rules`` section of the WirePlumber
+configuration file.
+
+Example:
+
+.. code-block::
+
+   monitor.bluez.rules = [
+     {
+       matches = [
+         {
+           ## This matches all bluetooth devices.
+           device.name = "~bluez_card.*"
+         }
+       ]
+       actions = {
+         update-props = {
+           bluez5.auto-connect = [ hfp_hf hsp_hs a2dp_sink hfp_ag hsp_ag a2dp_source ]
+           bluez5.hw-volume = [ hfp_hf hsp_hs a2dp_sink hfp_ag hsp_ag a2dp_source ]
+           bluez5.a2dp.ldac.quality = "auto"
+           bluez5.a2dp.aac.bitratemode = 0
+           bluez5.a2dp.opus.pro.application = "audio"
+           bluez5.a2dp.opus.pro.bidi.application = "audio"
+         }
+       }
+     }
+     {
+       matches = [
+         {
+           ## Matches all sources.
+           node.name = "~bluez_input.*"
+         }
+         {
+           ## Matches all sinks.
+           node.name = "~bluez_output.*"
+         }
+       ]
+       actions = {
+         update-props = {
+           bluez5.media-source-role = "input"
+
+           # Common node & audio adapter properties may also be set here
+           node.nick              = "My Node"
+           priority.driver        = 100
+           priority.session       = 100
+           node.pause-on-idle     = false
+           resample.quality       = 4
+           channelmix.normalize   = false
+           channelmix.mix-lfe     = false
+           session.suspend-timeout-seconds = 5
+           monitor.channel-volumes = false
+         }
+       }
+     }
+   ]
+
+Device properties
+^^^^^^^^^^^^^^^^^
+
+The following properties can be set on device objects:
+
+.. describe:: bluez5.auto-connect
+
+   Auto-connect device profiles on start up or when only partial profiles have
+   connected. Disabled by default if the property is not specified.
+
+   Supported values are: ``hfp_hf``, ``hsp_hs``, ``a2dp_sink``, ``hfp_ag``,
+   ``hsp_ag`` and ``a2dp_source``.
+
+   :Default value: ``[]``
+   :Type: array of strings
+
+.. describe:: bluez5.hw-volume
+
+   Enable hardware volume controls on these profiles.
+
+   Supported values are: ``hfp_hf``, ``hsp_hs``, ``a2dp_sink``, ``hfp_ag``,
+   ``hsp_ag`` and ``a2dp_source``.
+
+   :Default value: ``[ hfp_ag hsp_ag a2dp_source ]``
+   :Type: array of strings
+
+.. describe:: bluez5.a2dp.ldac.quality
+
+   LDAC encoding quality.
+
+   Available values: ``auto`` (Adaptive Bitrate, default), ``hq`` (High
+   Quality, 990/909kbps), ``sq`` (Standard Quality, 660/606kbps) and ``mq``
+   (Mobile use Quality, 330/303kbps).
+
+   :Default value: ``auto``
+   :Type: string
+
+.. describe:: bluez5.a2dp.aac.bitratemode
+
+   AAC variable bitrate mode.
+
+   Available values: 0 (cbr, default), 1-5 (quality level).
+
+   :Default value: ``0``
+   :Type: integer
+
+.. describe:: bluez5.a2dp.opus.pro.application
+
+   Opus Pro Audio encoding mode.
+
+   Available values: ``audio``, ``voip``, ``lowdelay``.
+
+   :Default value: ``audio``
+   :Type: string
+
+.. describe:: bluez5.a2dp.opus.pro.bidi.application
+
+   Opus Pro Audio encoding mode for bidirectional audio.
+
+   Available values: ``audio``, ``voip``, ``lowdelay``.
+
+   :Default value: ``audio``
+   :Type: string
+
+.. describe:: device.profile
+
+   The profile that is activated initially when the device is connected.
+
+   Available values: ``a2dp-sink`` (default) or ``headset-head-unit``.
+
+   :Default value: ``a2dp-sink``
+   :Type: string
+
+Node properties
+^^^^^^^^^^^^^^^
+
+The following properties can be set on node objects:
+
+.. describe:: bluez5.media-source-role
+
+   Media source role, ``input`` or ``playback``. This controls how a media
+   source device, such as a smartphone, is used by the system. Defaults to
+   ``playback``, playing the incoming stream out to speakers. Set to ``input``
+   to use the smartphone as an input for apps (like a microphone).
+
+   :Default value: ``playback``
+   :Type: string
+
+MIDI Rules
+----------
+
+Similarly to the above rules, the BlueZ MIDI monitor also supports rules that
+can be used to configure MIDI nodes when they are created.
+
+These rules can be set in the ``monitor.bluez-midi.rules`` section of the
+WirePlumber configuration file.
+
+Example:
+
+.. code-block::
+
+   monitor.bluez-midi.rules = [
+     {
+       matches = [
+         {
+           node.name = "~bluez_midi.*"
+         }
+       ]
+       actions = {
+         update-props = {
+           node.nick = "My Node"
+           priority.driver = 100
+           priority.session = 100
+           node.pause-on-idle = false
+           session.suspend-timeout-seconds = 5
+           node.latency-offset-msec = 0
+         }
+       }
+     }
+   ]
+
+.. note::
+
+   It is possible to also match MIDI server nodes by testing the ``node.name``
+   property against the server node names that were set in the
+   ``monitor.bluez-midi.servers`` section of the WirePlumber configuration file.
+
+MIDI-specific properties
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. describe:: node.latency-offset-msec
+
+   Latency adjustment to apply on the node. Larger values add a
+   constant latency, but reduces timing jitter caused by Bluetooth
+   transport.
+
+   :Default value: ``0``
+   :Type: integer (milliseconds)

docs/rst/daemon/configuration/components_and_profiles.rst

@@ -0,0 +1,218 @@
+.. _config_components_and_profiles:
+
+Components & Profiles
+=====================
+
+WirePlumber is organized in components and profiles. Components are
+functional parts that provide a specific feature, while profiles are
+collections of components that are loaded together to offer a certain
+overall experience.
+
+Components
+----------
+
+Components are functional parts that provide a specific feature. They can be
+described by a name, a type, a feature that they provide and a set of
+dependencies, required and optional.
+
+In the configuration file, a component is described as a SPA-JSON object,
+in the ``wireplumber.components`` array section, like this:
+
+  .. code-block::
+
+     {
+        name = <component-name>
+        type = <component-type>
+        arguments = { <json object> }
+
+        # Feature that this component provides
+        provides = <feature>
+
+        # List of features that must be provided before this component is loaded
+        requires = [ <features> ]
+
+        # List of features that would offer additional functionality if provided
+        # but are not strictly required
+        wants = [ <features> ]
+     }
+
+Name & arguments
+~~~~~~~~~~~~~~~~
+
+The name identifies the resource that this component loads. For example,
+it can be a file or a shared library. Depending on the type, the component
+may also accept arguments, which are passed on to the resource when it is
+loaded.
+
+Types
+~~~~~
+
+The main types of components are:
+
+  * **script/lua**
+
+    A Lua script, which usually contains one or more event hooks and/or
+    other custom logic. This is the main type of component as WirePlumber's
+    business logic is mostly written in Lua.
+
+  * **module**
+
+    A WirePlumber module, which is a shared library that can be loaded
+    dynamically. Modules usually provide some bundled logic to be consumed by
+    scripts or some integration between WirePlumber and an external service.
+
+  * **pw-module**
+
+    A PipeWire module, which is also a shared library that can be loaded
+    dynamically, but extends the functionality of the underlying *libpipewire*
+    library. Loading PipeWire modules in the WirePlumber context can be useful
+    to load custom protocol extensions or to offload some functionality from
+    the PipeWire daemon.
+
+  * **virtual**
+
+    Virtual components are just load targets that can be used to pull in
+    other components by defining dependencies. They do not provide any
+    functionality by themselves. Note that such components do not have a "name".
+
+  * **built-in**
+
+    These components are functional parts that are already built into the
+    WirePlumber library. They provide mostly internal support elements and checks.
+
+Features
+~~~~~~~~
+
+A "feature" is a name that we can use to refer to what is being provided
+by a component. For example, the ``monitors/alsa.lua`` script provides the
+``monitor.alsa`` feature. The feature name is used to refer to the component
+when defining dependencies between components and also when defining profiles.
+
+When a component loads successfully, its feature is marked as provided,
+otherwise it is not. Whether a feature is provided or not can be checked at
+runtime in Lua scripts using the :func:`Core.test_feature` function and in C code
+using the :c:func:`wp_core_test_feature` function.
+
+For a list of well-known features, see :ref:`config_features`.
+
+Dependencies
+~~~~~~~~~~~~
+
+Each component can "provide" a feature. When the component is loaded, the
+feature is marked as provided. Other components can either "require"
+or "want" a feature.
+
+If a component "requires" a feature, that means that this feature **must** be
+provided before this component is loaded and WirePlumber will try to load the
+relevant component that provides that feature if it is not already loaded
+(i.e. it will pull in the component). If that other component fails to load,
+hence the feature is not provided, the component that requires it will fail
+to load as well.
+
+If a component "wants" a feature, that means that this feature would be nice
+to have, in the sense that it would offer additional functionality if it
+was provided, but it's not strictly needed. WirePlumber will also try to load
+the relevant component that provides that feature if it is not already loaded,
+meaning that it will also pull in the component. However, if that other
+component fails to load, the component that wants it will still be loaded
+without error.
+
+Profiles
+--------
+
+A profile is a collection of components that are loaded together to offer
+a certain overall experience.
+
+Profiles are defined in the configuration file as a SPA-JSON object,
+in the ``wireplumber.profiles`` section, like this:
+
+  .. code-block::
+
+     <profile> = {
+       <feature name> = [ required | optional | disabled ]
+       ...
+     }
+
+Each feature can be marked as *required*, *optional* or *disabled*.
+
+  * **required**: Loading this profile will pull in the component that can
+    provide this feature in and if it fails to load, the profile will fail to
+    load as well.
+  * **optional**: Loading this profile does not pull in the component that
+    can provide this feature. If any of the required components either
+    *requires* or *wants* this feature, then WirePlumber will try to load it.
+    If it fails to load, the error condition depends on whether this feature was
+    required or wanted by the component that pulled it in.
+  * **disabled**: This feature will **not** be loaded, even if it is *wanted*
+    by some component. If any required component *requires* this feature, then
+    the profile will fail to load.
+
+By default, all the features provided by all the components in the
+``wireplumber.components`` section are considered to be *optional*.
+That means that no component will be loaded on an empty profile, since optional
+components are not pulled in automatically.
+
+If a feature is marked as *required* in a profile, then the component that
+provides that feature will be pulled in, together with all its dependencies,
+both required and optional.
+
+  .. note::
+
+     In essence, all optional features are opt-in by default. To opt out,
+     you need to mark the feature as *disabled*.
+
+Dependency chain example
+------------------------
+
+Consider the following configuration file:
+
+  .. code-block::
+
+      wireplumber.components = [
+        {
+          name = libwireplumber-module-dbus-connection, type = module
+          provides = support.dbus
+        }
+        {
+          name = libwireplumber-module-reserve-device, type = module
+          provides = support.reserve-device
+          requires = [ support.dbus ]
+        }
+        {
+          name = monitors/alsa.lua, type = script/lua
+          provides = monitor.alsa
+          wants = [ support.reserve-device ]
+        }
+      ]
+
+      wireplumber.profiles = {
+        main = {
+          monitor.alsa = required
+        }
+      }
+
+In this example, the ``main`` profile requires the ``monitor.alsa`` feature.
+This will cause the ``monitors/alsa.lua`` script to be loaded. Now, since the
+``monitors/alsa.lua`` script *wants* the ``support.reserve-device`` feature,
+the ``libwireplumber-module-reserve-device`` module will also be pulled in.
+And since that one *requires* the ``support.dbus`` feature, the
+``libwireplumber-module-dbus-connection`` module will also be pulled in.
+
+However, on a system without D-Bus, a user may want to opt out of the
+``libwireplumber-module-dbus-connection`` module. This can be done by marking
+the ``support.dbus`` feature as disabled in the profile:
+
+  .. code-block::
+
+     wireplumber.profiles = {
+        main = {
+          monitor.alsa = required
+          support.dbus = disabled
+        }
+      }
+
+Upon doing that, the ``libwireplumber-module-dbus-connection`` module will
+not be loaded, causing the ``libwireplumber-module-reserve-device`` module
+to not be loaded as well, since it requires the ``support.dbus`` feature.
+The ``monitors/alsa.lua`` script will still be loaded, since it only *wants*
+the ``support.reserve-device`` feature.

docs/rst/daemon/configuration/conf_file.rst

@@ -0,0 +1,244 @@
+.. _config_conf_file:
+
+The configuration file
+======================
+
+WirePlumber's configuration file is by default ``wireplumber.conf`` and resides
+in one of the WirePlumber specific
+:ref:`configuration file search locations <config_locations>`.
+
+The default configuration file can be changed on the command line by passing
+the ``--config-file`` or ``-c`` option:
+
+.. code-block:: bash
+
+   $ wireplumber --config-file=custom.conf
+
+.. important::
+
+   Starting with WirePlumber 0.5, this is the only file that WirePlumber reads
+   to load configuration (together with its fragments - see below). In the past,
+   WirePlumber also used to read Lua configuration files that were referenced
+   from ``wireplumber.conf`` and all the heavy lifting was done in Lua. This is
+   no longer the case, and the **Lua configuration files are no longer supported.**
+   See :ref:`config_migration`.
+
+   Note that Lua is still the scripting language for WirePlumber, but it is only
+   used for actual scripting and not for configuration.
+
+The SPA-JSON Format
+-------------------
+
+The format of this configuration file is a variant of JSON that is also
+used in PipeWire configuration files (also known as SPA-JSON). The file consists
+of a global JSON object that is not explicitly typed, and a list of sections
+which are essentially key-value pairs of that global JSON object. Each section
+is usually a JSON object, but it can also be a JSON array.
+
+SPA-JSON is a superset of standard JSON, so any valid JSON file is also a valid
+SPA-JSON file. However, it is more permissive than standard JSON. First of all,
+it allows strings to be typed without quotes (``"``), and it also allows the
+character ``=`` as a separator between keys and values in addition to the
+standard ``:``. This can make it look similar to INI files or other custom
+configuration formats that people are familiar with, which makes it easier for
+users to read and edit.
+
+Other deviations from standard JSON include allowing comments (lines starting
+with ``#`` are treated as comments) and allowing the separator characters
+(``:``, ``=``, ``,``) to appear in excess or abundance. That means that you can
+write ``key = value`` or ``key: value`` or ``key value`` and it will be
+interpreted the same way. You may also write ``[val1, val2, val3]`` or
+``[val1, val2, val3, ]`` or ``[val1 val2 val3]`` and it will be interpreted
+the same way. This is allowed because the SPA-JSON parser in fact ignores all
+the separator characters (the real separator is the space character).
+
+Examples of valid SPA-JSON files:
+
+.. code-block::
+
+    # This is the most common syntax
+    section1 = {
+      string-key = value1
+      number-key = 123
+      boolean-key = true
+    }
+    section2 = [
+      val1, val2, val3
+    ]
+
+.. code-block::
+
+    # Mixed syntax
+    section1 {
+      "string-key" = "value1"
+      number-key: 123
+      boolean-key true
+    }
+    section2 = [
+      val1, val2 val3,
+    ]
+
+.. code-block::
+
+   # Standard JSON (albeit this comment line)
+   "section1": {
+     "string-key": "value1",
+     "number-key": 123,
+     "boolean-key": true
+   }
+   "section2": [
+     "val1", "val2", "val3"
+   ]
+
+.. _config_conf_file_fragments:
+
+Fragments
+---------
+
+Just like PipeWire, WirePlumber supports configuration fragments. This means
+that the main configuration file can be split into multiple files, and all of
+them will be loaded and merged together. This is mostly useful to allow users
+to customize their configuration without having to modify the main file.
+
+When loading the configuration file, WirePlumber will also look for
+additional files in the directory that has the same name as the configuration
+file suffixed with ``.d`` and will load all of them as well. For example,
+loading ``wireplumber.conf`` will also load any ``.conf`` files under
+``wireplumber.conf.d/``. This directory is searched in all the configuration
+search locations and the fragments are loaded from *all* of them, starting
+from the most system-wide locations and moving towards the most user-specific
+locations, in alphanumerical order within each location (see also
+:ref:`config_locations_fragments`).
+
+When a JSON object appears in multiple files, the properties of the objects are
+merged together. When a JSON array appears in multiple files, the arrays are
+concatenated together. When merging objects, if specific properties appear in
+many of those objects, the last one to be parsed always overwrites previous
+ones, unless the value is also an object or array; if it is, then the value is
+recursively merged using the same rules.
+
+Sections
+--------
+
+WirePlumber reads the following standard sections from the configuration
+file:
+
+* *wireplumber.components*
+
+  This section is an array that lists components that can be loaded by
+  WirePlumber. For more information, see :ref:`config_components_and_profiles`.
+
+* *wireplumber.components.rules*
+
+  This section is an array containing rules that can be used to modify entries
+  of the *wireplumber.components* array. This is useful to inject changes
+  to the components list without having to modify the main configuration file.
+
+* *wireplumber.profiles*
+
+  This section is an object that defines profiles that can be loaded by
+  WirePlumber. For more information, see :ref:`config_components_and_profiles`.
+
+* *wireplumber.settings*
+
+  This section is an object that defines settings that can be used to
+  alter WirePlumber's behavior. For more information, see :ref:`config_settings`.
+
+* *wireplumber.settings.schema*
+
+  This section is an object that defines the schema for the settings that
+  can be listed in *wireplumber.settings*. This is used to validate the
+  settings when they are modified at runtime. For more information, see
+  :ref:`config_configuration_option_types`.
+
+In addition, there are many sections that are specific to certain components,
+mostly hardware monitors, such as *monitor.alsa.properties*,
+*monitor.alsa.rules*, etc. These are documented further on, in the respective
+sections of this documentation that describe the configuration options of
+these components.
+
+Finally, WirePlumber also reads the following sections, which are parsed
+by libpipewire to configure the PipeWire context:
+
+* *context.properties*
+
+  Used to define properties to configure the PipeWire context and some modules.
+
+* *context.spa-libs*
+
+  Used to find SPA factory names. It maps a SPA factory name regular expression
+  to a library name that should contain that factory. The object property names
+  are the regular expressions, and the object property values are the actual
+  library names:
+
+  .. code-block::
+
+    <factory-name regex> = <library-name>
+
+  For example:
+
+  .. code-block::
+
+    context.spa-libs = {
+      api.alsa.*      = alsa/libspa-alsa
+      audio.convert.* = audioconvert/libspa-audioconvert
+    }
+
+  In this example, we instruct wireplumber to lookup any *api.alsa.** factory
+  in the *libspa-alsa* library, and any *audio.convert.** factory
+  in the *libspa-audioconvert* library.
+
+  .. note::
+
+     The default configuration file already contains a list of well-known
+     factory names and their corresponding libraries. You should only
+     need to add entries to this section if you are using custom SPA plugins.
+
+* *context.modules*
+
+  Used to load PipeWire modules. This does not affect the PipeWire daemon by any
+  means. It exists simply to allow loading *libpipewire* modules inside
+  WirePlumber. This is usually useful to load PipeWire protocol extensions,
+  so that you can export custom objects to PipeWire and other clients.
+
+  .. note::
+
+     PipeWire modules can also be loaded as :ref:`components <config_components_and_profiles>`,
+     which may be preferable since it allows you to load them conditionally
+     based on the profile and component dependencies.
+
+  .. admonition:: Remember
+
+     Modules listed in *context.modules* are always loaded before attempting a
+     connection to the PipeWire daemon, while modules listed in
+     *wireplumber.components* are always loaded after the connection is
+     established. It is important to load the PipeWire protocol-native module
+     and any extensions (such as module-metadata) in the *context.modules*
+     section, so that the connection can be done properly.
+
+  Each module is described by a JSON object containing the module's *name*,
+  its arguments (*args*) and a combination of *flags*, which can be ``ifexists``
+  and ``nofail``.
+
+  .. code-block::
+
+    {
+      name = <module-name>
+      [ args = { <key> = <value> ... } ]
+      [ flags = [ [ ifexists ] [ nofail ] ]
+    }
+
+  For example:
+
+  .. code-block::
+
+    context.modules = [
+      { name = libpipewire-module-adapter }
+      {
+        name = libpipewire-module-metadata,
+        flags = [ ifexists ]
+      }
+    ]
+
+  The above example loads both PipeWire adapter and metadata modules. The
+  metadata module will be ignored if not found because of its ``ifexists`` flag.

docs/rst/daemon/configuration/configuration_option_types.rst

@@ -0,0 +1,125 @@
+.. _config_configuration_option_types:
+
+Configuration option types
+==========================
+
+As seen in the previous sections, WirePlumber can be partly configured by
+enabling or disabling features, which affect which components are getting
+loaded. These components, however, can be further configured to fine-tune their
+behavior. This section describes the different types of configuration options
+that can be used to configure WirePlumber components.
+
+Dynamic options ("Settings")
+----------------------------
+
+Dynamic options (also simply referred to as "settings") are configuration
+options that can be changed at runtime. They are typically simple values like
+booleans, integers, strings, etc. and are all located under the
+``wireplumber.settings`` section in the configuration file. Their purpose is to
+allow the user to change simple behavioral aspects of WirePlumber.
+
+As the name suggests, these options are dynamic and can be changed at runtime
+using ``wpctl`` or the :ref:`settings_api` API. For example, setting the
+``device.routes.default-sink-volume`` setting to ``0.5`` can be done like this:
+
+.. code-block:: bash
+
+   $ wpctl settings device.routes.default-sink-volume 0.5
+
+Under the hood, when WirePlumber starts, the ``metadata.sm-settings`` component
+(provided by ``libwireplumber-module-settings``) reads this section from the
+configuration file and populates the ``sm-settings`` metadata object, which is
+exported to PipeWire. In addition, it reads the ``wireplumber.settings.schema``
+section and populates the ``schema-sm-settings`` metadata object, which is used
+by the API to validate the settings. Any options that are missing from
+``wireplumber.settings`` are also populated in ``sm-settings`` from their
+default values in the schema. Then the rest of the components read their
+configuration options from this metadata object via the :ref:`settings_api` API.
+
+Most of the components that use such dynamic options make sure to listen
+to changes in the metadata object so that they can immediately adapt their
+behavior. Other components, however, do not react immediately and the changes
+only take effect the next time the option is needed. For instance, some options
+affect created objects in a way that cannot be changed after the object has been
+created, so when the option is changed it applies only to new objects and not
+existing ones.
+
+Changing the settings at runtime in the ``sm-settings`` metadata object is
+a non-persistent change. The changes will be lost when WirePlumber is
+restarted. However, the :ref:`settings_api` API also supports saving settings
+to a state file, which will be loaded again when WirePlumber starts and
+override the settings from the configuration file. This is done by using yet
+another metadata object called ``persistent-sm-settings``. When a setting is
+changed in the ``persistent-sm-settings`` metadata object, WirePlumber
+automatically saves the change to the state file and also changes the value in
+the ``sm-settings`` metadata object immediately.
+
+To make such a persistent change using ``wpctl``, the ``--save`` option can be
+used. For example, to set the ``device.routes.default-sink-volume`` setting to
+``0.5`` and save it to the state file:
+
+.. code-block:: bash
+
+   $ wpctl settings --save device.routes.default-sink-volume 0.5
+
+With ``wpctl``, it is also possible to restore a setting to its default value
+(taken from the schema), by using the ``--reset`` option. For example, to reset
+the ``device.routes.default-sink-volume`` setting, the following command can be
+used:
+
+.. code-block:: bash
+
+   $ wpctl settings --reset device.routes.default-sink-volume
+
+In addition, the ``--delete`` option can be used to delete a setting from the
+``persistent-sm-settings`` metadata object, which will also remove it from the
+state file. After deleting, the value from the ``wireplumber.settings`` section
+of the configuration file will be used again. For example, to delete the
+``device.routes.default-sink-volume`` setting, the following command can be
+used:
+
+.. code-block:: bash
+
+   $ wpctl settings --delete device.routes.default-sink-volume
+
+A list of all the available settings can be found in the :ref:`config_settings`
+section.
+
+Static options
+--------------
+
+Static options are more complex configuration structures that reside only in the
+configuration file and cannot be changed at runtime. They are typically used to
+configure device monitors and provide rules that match objects and perform
+actions such as update their properties.
+
+While these options could also in theory be stored in the metadata object and
+be made dynamic, this is not supported because these options are both complex
+and therefore hard to change on the command line, but also because they are
+typically used to configure objects that are created at startup and cannot be
+changed later.
+
+Static options are located in their own top-level sections. Examples of such
+sections are ``monitor.alsa.properties`` and ``monitor.alsa.rules`` that are
+used to configure the ``monitor.alsa`` component. The next sections of this
+documentation describe in detail all the available static options.
+
+Component arguments
+~~~~~~~~~~~~~~~~~~~
+
+Components can also be configured statically by passing arguments to them when
+they are loaded. This is done by adding an ``arguments`` key to the component
+description in the ``wireplumber.components`` section (see
+:ref:`config_components_and_profiles`).
+
+The arguments are mostly meant as a way to instantiate multiple instances of the
+same module or script with slightly different configuration to create a new
+unique component. For example, the ``metadata.lua`` script can be instantiated
+multiple times to create multiple metadata objects, each with a different name.
+The name of the metadata object is passed as an argument to the script.
+
+While many more static options could be passed as arguments, this is not
+recommended because it is not possible to override the arguments by adding
+:ref:`fragment<config_conf_file_fragments>` configuration files. Therefore, it
+is recommended to use component-specific top-level sections, unless the option
+is not meant to be changed by the user.

docs/rst/daemon/configuration/features.rst

@@ -0,0 +1,157 @@
+.. _config_features:
+
+Well-known features
+===================
+
+This is a list of some well-known features that can be enabled or
+disabled accordingly.
+
+There are many more features actually defined in the configuration file, and it
+can be confusing to go through them. This list here is meant to be a quick
+reference for the most common ones that actually make sense to be toggled in
+a configuration file in order to customize WirePlumber's behavior.
+
+For more information on what features are and how they work, refer to the
+previous section: :ref:`config_components_and_profiles`.
+
+Hardware monitors
+-----------------
+
+Audio
+~~~~~
+
+.. describe:: hardware.audio
+
+   Enables bringing up audio hardware.
+
+   :wants: ``monitor.alsa``, ``monitor.alsa-midi``
+
+.. describe:: monitor.alsa
+
+   Enables the ALSA device monitor.
+
+   :wants: ``monitor.alsa.reserve-device``
+
+.. describe:: monitor.alsa.reserve-device
+
+   Enables D-Bus device reservation API for ALSA devices.
+
+   :requires: ``support.reserve-device``
+
+.. describe:: monitor.alsa-midi
+
+   Enables the ALSA MIDI device monitor.
+
+.. describe:: node.software-dsp
+
+   Enables software DSP based on pre-configured hardware rules.
+
+   See :ref:`policies_software_dsp` for more information.
+
+Bluetooth
+~~~~~~~~~
+
+.. describe:: hardware.bluetooth
+
+   Enables bringing up bluetooth hardware.
+
+   :wants: ``monitor.bluez``, ``monitor.bluez-midi``
+
+.. describe:: monitor.bluez
+
+   Enables the BlueZ device monitor.
+
+   :wants: ``monitor.bluez.seat-monitoring``
+
+.. describe:: monitor.bluez.seat-monitoring
+
+   Enables seat monitoring on the bluetooth monitor.
+
+   When enabled, this will make sure that the bluetooth devices are only
+   enabled on the active seat.
+
+   :requires: ``support.logind``
+
+.. describe:: monitor.bluez-midi
+
+   Enables the BlueZ MIDI device monitor.
+
+   :wants: ``monitor.bluez.seat-monitoring``
+
+Video
+~~~~~
+
+.. describe:: hardware.video-capture
+
+   Enables bringing up video capture hardware (cameras, hdmi capture devices,
+   etc.)
+
+   :wants: ``monitor.v4l2``, ``monitor.libcamera``
+
+.. describe:: monitor.v4l2
+
+   Enables the V4L2 device monitor.
+
+.. describe:: monitor.libcamera
+
+   Enables the libcamera device monitor.
+
+Support components
+------------------
+
+.. describe:: support.dbus
+
+   Provides a D-Bus connection to the session bus. This is needed by some other
+   support features (see below) but it is generally optional. WirePlumber does
+   not require a D-Bus connection to work.
+
+   On a system where WirePlumber is configured to run system-wide (headless,
+   embedded, etc), this will most likely fail to load and thus disable all the
+   other support features that require it. On such systems it makes sense to
+   disable this feature explicitly, to avoid the overhead of trying to connect
+   to the session bus.
+
+.. describe:: support.reserve-device
+
+   Provides support for the
+   `D-Bus device reservation API <http://git.0pointer.net/reserve.git/tree/reserve.txt>`_,
+   allowing the device monitors to reserve devices for exclusive access.
+
+   :requires: ``support.dbus``
+
+.. describe:: support.portal-permissionstore
+
+   Integrates with the flatpak portal permission store to give appropriate
+   access permissions to flatpak applications.
+
+   :requires: ``support.dbus``
+
+.. describe:: support.logind
+
+   Integrates with systemd-logind to enable specific functionality only on the
+   active seat.
+
+Policies
+--------
+
+.. describe:: policy.standard
+
+   Enables the standard WirePlumber policy. This includes all the logic
+   for enabling devices, linking streams, granting permissions to clients,
+   etc, as appropriate for a desktop system.
+
+.. describe:: policy.role-based
+
+   Enables the role based priority system policy. This system creates virtual sinks
+   that group streams based on their ``media.role`` property, and assigns a
+   priority to each role. Depending on the priority configuration, lower
+   priority roles may be corked or ducked when a higher priority role stream
+   is active.
+
+   This policy was designed for automotive and mobile systems and may not work
+   as expected on desktop systems.
+
+   Note that this policy is implemented as a superset of ``policy.standard``,
+   so ``policy.standard`` should not be disabled when enabling this policy.
+
+   :requires: ``policy.standard``

docs/rst/daemon/configuration/meson.build

@@ -0,0 +1,13 @@
+# you need to add here any files you add to the toc directory as well
+sphinx_files += files(
+  'conf_file.rst',
+  'components_and_profiles.rst',
+  'configuration_option_types.rst',
+  'modifying_configuration.rst',
+  'migration.rst',
+  'features.rst',
+  'settings.rst',
+  'alsa.rst',
+  'bluetooth.rst',
+  'access.rst',
+)

docs/rst/daemon/configuration/migration.rst

@@ -0,0 +1,305 @@
+.. _config_migration:
+
+Migrating configuration from 0.4
+================================
+
+The configuration file format has changed in version 0.5. No automatic migration
+of old configuration files is performed, so you will have to manually update
+them. This document describes the changes and how to update your configuration.
+
+wireplumber.conf
+----------------
+
+In WirePlumber 0.4, there used to be a ``.conf`` file, typically
+``wireplumber.conf``, using the SPA-JSON format, that would list some Lua
+scripts in the ``wireplumber.components`` section. These scripts were of type
+``config/lua`` and they were called by default ``main.lua``, ``policy.lua`` and
+``bluetooth.lua``.
+
+Typical ``wireplumber.components`` section of a ``wireplumber.conf`` file in 0.4
+would look like this:
+
+.. code-block::
+
+   wireplumber.components = [
+     #{ name = <component-name>, type = <component-type> }
+     #
+     # WirePlumber components to load
+     #
+
+     # The lua scripting engine
+     { name = libwireplumber-module-lua-scripting, type = module }
+
+     # The lua configuration file(s)
+     # Other components are loaded from there
+     { name = main.lua, type = config/lua }
+     { name = policy.lua, type = config/lua }
+     { name = bluetooth.lua, type = config/lua }
+   ]
+
+These Lua "configuration" scripts were then looked up in the standard
+configuration directories (``/usr/share/wireplumber``, ``/etc/wireplumber`` and
+``~/.config/wireplumber``). The system also supported fragments of these scripts
+to be placed in directories called ``main.lua.d``, ``policy.lua.d`` and
+``bluetooth.lua.d`` respectively, in the same locations.
+
+.. attention::
+
+   Starting with WirePlumber 0.5, Lua "configuration" files are **no longer
+   supported**.
+
+If you attempt to start it with a ``wireplumber.conf`` that still
+lists ``config/lua`` components in its ``wireplumber.components`` section, you
+will see the following error message on the output:
+
+   Failed to load configuration: The configuration file at '...' is likely an
+   old WirePlumber 0.4 config and is not supported anymore. Try removing it.
+
+As the message says, to resolve this you should remove the old
+``wireplumber.conf`` file from the designated location. This should allow the
+new WirePlumber to start using the default configuration that it ships with.
+
+Lua configuration scripts
+-------------------------
+
+If you had custom Lua configuration scripts in the standard configuration
+directories, such as *"main.lua.d"*, *"policy.lua.d"* or *"bluetooth.lua.d"*,
+**you need to port them**.
+
+Locations of files
+~~~~~~~~~~~~~~~~~~
+
+The first thing you need to know is that the new files should be placed in the
+``~/.config/wireplumber/wireplumber.conf.d/`` directory instead of
+``~/.config/wireplumber/main.lua.d/`` and such ...
+
+In addition, since the new files are in the SPA-JSON format, they should have
+the ``.conf`` extension instead of ``.lua``.
+
+See also :ref:`config_locations`.
+
+Porting device/node rules
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+One of the most common use-cases for these scripts was to set up properties
+for devices and nodes using rules. Here is an example of an old rules script:
+
+.. code-block:: lua
+   :caption: ~/.config/wireplumber/main.lua.d/51-alsa-pro-audio.lua
+
+    local rule = {
+      matches = {
+        {
+          { "device.name", "matches", "alsa_card.*" },
+        },
+      },
+      apply_properties = {
+        ["api.alsa.use-acp"] = false,
+        ["device.profile"] = "pro-audio",
+        ["api.acp.auto-profile"] = false,
+        ["api.acp.auto-port"] = false,
+      },
+    }
+
+    table.insert(alsa_monitor.rules, rule)
+
+This equivalent of this script in the new configuration format would look like
+this:
+
+.. code-block::
+   :caption: ~/.config/wireplumber/wireplumber.conf.d/51-alsa-pro-audio.conf
+
+   monitor.alsa.rules = [
+     {
+       matches = [
+         {
+           device.name = "~alsa_card.*"
+         }
+       ]
+       actions = {
+         update-props = {
+           api.alsa.use-acp = false,
+           device.profile = "pro-audio"
+           api.acp.auto-profile = false
+           api.acp.auto-port = false
+         }
+       }
+     }
+   ]
+
+Another example of Bluetooth node rules:
+
+.. code-block:: lua
+   :caption: ~/.config/wireplumber/bluetooth.lua.d/51-headphones.lua
+
+    local rule = {
+      matches = {
+        {
+          { "node.name", "equals", "bluez_output.02_11_45_A0_B3_27.a2dp-sink" },
+        },
+      },
+      apply_properties = {
+        ["node.nick"] = "Headphones",
+      },
+    }
+
+    table.insert(bluez_monitor.rules, rule)
+
+This equivalent of this script in the new configuration format would look like:
+
+.. code-block::
+   :caption: ~/.config/wireplumber/wireplumber.conf.d/51-headphones.conf
+
+   monitor.bluez.rules = [
+     {
+       matches = [
+         {
+           node.name = "bluez_output.02_11_45_A0_B3_27.a2dp-sink"
+         }
+       ]
+       actions = {
+         update-props = {
+           node.nick = "Headphones"
+         }
+       }
+     }
+   ]
+
+See also :ref:`config_modifying_configuration_rules`.
+
+Porting properties configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you had configuration scripts that were setting properties in tables such
+as ``alsa_monitor.properties`` or ``bluez_monitor.properties``, then in many
+cases porting to the new format can be done as follows:
+
+.. code-block:: lua
+   :caption: ~/.config/wireplumber/bluetooth.lua.d/80-bluez-properties.lua
+
+    bluez_monitor.properties["bluez5.roles"] = "[ a2dp_sink a2dp_source bap_sink bap_source hsp_hs hsp_ag hfp_hf hfp_ag ]"
+    bluez_monitor.properties["bluez5.hfphsp-backend"] = "native"
+
+.. code-block::
+   :caption: ~/.config/wireplumber/wireplumber.conf.d/80-bluez-properties.conf
+
+    monitor.bluez.properties = {
+      bluez5.roles = [ a2dp_sink a2dp_source bap_sink bap_source hsp_hs hsp_ag hfp_hf hfp_ag ]
+      bluez5.hfphsp-backend = "native"
+    }
+
+See also :ref:`config_modifying_configuration_static`.
+
+In a lot of cases, however, these properties have been promoted to become either
+:ref:`Settings <config_modifying_configuration_settings>` or
+:ref:`Features <config_modifying_configuration_features>`.
+Here are some common examples:
+
+Disabling the D-Bus device reservation API in the ALSA monitor:
+
+* Old format:
+
+  .. code-block:: lua
+     :caption: ~/.config/wireplumber/main.lua.d/80-disable-alsa-reserve.lua
+
+      alsa_monitor.properties["alsa.reserve"] = false
+
+* New format:
+
+  .. code-block::
+     :caption: ~/.config/wireplumber/wireplumber.conf.d/80-disable-alsa-reserve.conf
+
+      wireplumber.profiles = {
+        main = {
+          monitor.alsa.reserve-device = disabled
+        }
+      }
+
+Disabling seat monitoring via logind in the BlueZ monitor:
+
+* Old format:
+
+  .. code-block:: lua
+     :caption: ~/.config/wireplumber/bluetooth.lua.d/80-disable-logind.lua
+
+      bluez_monitor.properties["with-logind"] = false
+
+* New format:
+
+  .. code-block::
+     :caption: ~/.config/wireplumber/wireplumber.conf.d/80-disable-logind.conf
+
+      wireplumber.profiles = {
+        main = {
+          monitor.bluez.seat-monitoring = disabled
+        }
+      }
+
+See also :ref:`config_modifying_configuration_features`.
+
+Linking policy configuration (moved to settings and renamed):
+
+* Old format:
+
+  .. code-block:: lua
+     :caption: ~/.config/wireplumber/policy.lua.d/80-policy.lua
+
+      default_policy.policy = {
+        ["move"] = false,
+        ["follow"] = false,
+      }
+
+* New format:
+
+  .. code-block::
+     :caption: ~/.config/wireplumber/wireplumber.conf.d/80-policy.conf
+
+      wireplumber.settings = {
+        linking.allow-moving-streams = false
+        linking.follow-default-target = false
+      }
+
+See also :ref:`config_modifying_configuration_settings` and remember that
+settings can also be changed at runtime via :command:`wpctl`.
+
+Loading custom scripts
+~~~~~~~~~~~~~~~~~~~~~~
+
+If you had custom Lua scripts that were loaded by the old configuration file,
+you need to port the old ``load_script()`` commands into component descriptions.
+
+For example, if you had a script that was loaded like this:
+
+.. code-block:: lua
+   :caption: ~/.config/wireplumber/main.lua.d/99-my-script.lua
+
+    load_script("my-script.lua")
+
+You should now create a new component description in the configuration file
+and also make sure to require it in the profile:
+
+.. code-block::
+   :caption: ~/.config/wireplumber/wireplumber.conf.d/99-my-script.conf
+
+   wireplumber.components = [
+     {
+       name = my-script.lua, type = script/lua
+       provides = custom.my-script
+     }
+   ]
+
+   wireplumber.profiles = {
+     main = {
+       custom.my-script = required
+     }
+   }
+
+.. attention::
+
+   Another important thing to mention here is the location of custom scripts. In
+   0.4, scripts could be loaded in configuration locations such as
+   ``~/.config/wireplumber/scripts/`` and ``/etc/wireplumber/scripts/``. In 0.5,
+   the XDG base directory specification for data files is honored, so the new
+   location for custom scripts is ``~/.local/share/wireplumber/scripts/`` and
+   anything else specified in ``$XDG_DATA_HOME`` and ``$XDG_DATA_DIRS``. See
+   :ref:`daemon_file_locations` for more information.

docs/rst/daemon/configuration/modifying_configuration.rst

@@ -0,0 +1,365 @@
+.. _config_modifying_configuration:
+
+Modifying configuration
+=======================
+
+WirePlumber is a heavily modular daemon that depends on its configuration
+file to operate. If you were to start WirePlumber with an empty configuration
+file, it would fail to start. This is why the default configuration file is
+installed in the system-wide application data directory, which prevents it from
+being modified by the user.
+
+It is technically possible, if you wish, to copy the default configuration
+file in one of the other :ref:`configuration search locations <config_locations>`
+and modify it. However, this is **not recommended**, as it may lead to issues
+when upgrading WirePlumber.
+
+In the :ref:`Configuration file <config_conf_file>` section, we saw that
+configuration files support fragments, which allow you to override or extend the
+default configuration. This is the recommended way to modify the configuration.
+
+Working with fragments
+----------------------
+
+The easiest way to add :ref:`fragments <config_conf_file_fragments>` to
+modify the default configuration is to create a directory called
+``~/.config/wireplumber/wireplumber.conf.d`` and place your fragments there.
+
+All fragment files need to have the ``.conf`` extension and must be valid
+SPA-JSON files. The fragments are loaded in alphanumerical order, so you can
+control the order in which they are loaded by naming them accordingly. It is
+recommended to use a numeric prefix for the file names, e.g.
+``10-my-fragment.conf``, ``20-my-other-fragment.conf``, etc., so that you can
+easily control the order in which they are loaded.
+
+.. _config_modifying_configuration_features:
+
+Customizing the loaded features
+-------------------------------
+
+As seen in the :ref:`Components & Profiles <config_components_and_profiles>`
+section, the list of components that are loaded can be customized by enabling or
+disabling :ref:`well-known features <config_features>` in the profile that is
+in use by WirePlumber.
+
+The default profile of WirePlumber is called ``main``, so a fragment that
+enables or disables a specific feature in the default configuration should look
+like this:
+
+.. code-block::
+
+   wireplumber.profiles = {
+     main = {
+       some.feature.name = disabled
+       some.other.feature.name = required
+     }
+   }
+
+Remember that features can be ``required``, ``optional`` or ``disabled``. See
+the :ref:`Components & Profiles <config_components_and_profiles>` for details.
+
+.. _config_modifying_configuration_settings:
+
+Modifying dynamic options ("settings")
+--------------------------------------
+
+As seen in the :ref:`Configuration option types <config_configuration_option_types>`
+section, WirePlumber components can be partly configured with dynamic options
+(referred to as "settings"). These settings can either be modified permanently
+in the configuration file, or they can be modified at runtime using the
+``wpctl`` command-line tool.
+
+To modify a setting in the configuration file, you can use a fragment like this:
+
+.. code-block::
+
+   wireplumber.settings = {
+     some.setting.name = value
+   }
+
+For example, setting the ``device.routes.default-sink-volume`` setting to
+``0.5`` can be done like this:
+
+.. code-block::
+
+   wireplumber.settings = {
+     device.routes.default-sink-volume = 0.5
+   }
+
+.. note::
+
+   Since the configuration file is only read at startup, this will only take
+   effect after restarting WirePlumber.
+
+If you would prefer to change the setting at runtime, you can use ``wpctl`` as
+follows:
+
+.. code-block:: bash
+
+   $ wpctl settings device.routes.default-sink-volume 0.5
+   Updated setting 'device.routes.default-sink-volume' to: 0.5
+
+The above command changes the setting immediately, but for the current
+WirePlumber instance only. If you want the setting to be applied every time
+WirePlumber is started, you may also use the ``--save`` option:
+
+.. code-block:: bash
+
+   $ wpctl settings --save device.routes.default-sink-volume 0.5
+   Updated and saved setting 'device.routes.default-sink-volume' to: 0.5
+
+This will save the setting persistently in WirePlumber's state storage.
+Even though it is not in the configuration file, this saved value will be
+applied automatically when WirePlumber is started.
+
+.. attention::
+
+   When a setting's value is saved, it will override the value from the
+   configuration file. Changing the value in the configuration file will
+   have no effect until the saved value is removed. Use the ``--delete``
+   switch in ``wpctl`` to remove a saved value (see below).
+
+With ``wpctl``, it is also possible to restore a setting to its default value
+(taken from the schema), by using the ``--reset`` option. For example, to reset
+the ``device.routes.default-sink-volume`` setting, the following command can be
+used:
+
+.. code-block:: bash
+
+   $ wpctl settings --reset device.routes.default-sink-volume
+   Reset setting 'device.routes.default-sink-volume' successfully
+   $ wpctl settings device.routes.default-sink-volume
+   Value: 0.064 (Saved: 0.5)
+
+Note that the ``--reset`` option will only reset the setting to its default
+value, but it will not remove the saved value from the state file. If you want
+to remove the saved value, you can use the ``--delete`` option:
+
+.. code-block:: bash
+
+   $ wpctl settings --delete device.routes.default-sink-volume
+   Deleted setting 'device.routes.default-sink-volume' successfully
+   $ wpctl settings device.routes.default-sink-volume
+   Value: 0.064
+
+A list of all the available settings can be found in the :ref:`config_settings`
+section.
+
+.. _config_modifying_configuration_static:
+
+Modifying static options
+------------------------
+
+Static options always live in their own section of the configuration file.
+Sections can be of two types: either a JSON object or a JSON array.
+
+When dealing with a **JSON object**, you can add or modify a key-value pair by
+creating a fragment like this:
+
+.. code-block::
+
+   wireplumber.some-section = {
+     some.option = new_value
+   }
+
+This is similar to what we have seen also above for modifying profile features
+and settings (because both are JSON objects).
+
+When dealing with a **JSON array**, any values that you define in a fragment
+will be appended to the array. For example, to add a new rule to the
+``monitor.alsa.rules`` array, you can create a fragment like this:
+
+.. code-block::
+
+   monitor.alsa.rules = [
+     {
+       matches = [
+         {
+           device.name = "~alsa_card.*"
+         }
+       ]
+       actions = {
+         update-props = {
+           api.alsa.use-ucm  = false
+         }
+       }
+     }
+   ]
+
+This will add a new rule to the ``monitor.alsa.rules`` array, which will
+be evaluated **after** all other rules that were parsed before. This is where
+the order in which fragments are loaded actually matters.
+
+If you don't want to append a new rule, but rather override the entire array
+with a new one, you can do so by using the ``override.`` prefix on the array
+name:
+
+.. code-block::
+
+   override.monitor.alsa.rules = [
+     {
+       matches = [
+         {
+           device.name = "~alsa_card.*"
+         }
+       ]
+       actions = {
+         update-props = {
+           api.alsa.use-ucm  = false
+         }
+       }
+     }
+   ]
+
+This will now replace the entire ``monitor.alsa.rules`` array with this new one.
+
+.. attention::
+
+   If you want to remove a rule from the array, you will need to override the
+   whole array with a new one that does not contain the rule you want to remove.
+   There is no way to remove a specific element from an array using fragments.
+
+Another thing worth remembering here is that this behavior of appending values
+to arrays also works in arrays that are nested inside other arrays or objects.
+For example, consider this fragment:
+
+.. code-block::
+
+   monitor.bluez.properties = {
+     bluez5.codecs = [ sbc_xq aac ldac ]
+   }
+
+If this is the first time that the ``bluez5.codecs`` array is being defined, it
+will be created with the given values. If it already exists, the given values
+will be appended to the existing array. If you want to make sure that this
+fragment will override the existing array, you need to use the ``override.``
+prefix on the array name:
+
+.. code-block::
+
+   monitor.bluez.properties = {
+     override.bluez5.codecs = [ sbc_xq aac ldac ]
+   }
+
+The ``override.`` prefix may also be used in JSON object keys, to override the
+entire object with a new one. For example, to override the entire
+``monitor.bluez.properties`` object, you can use a fragment like this:
+
+.. code-block::
+
+   override.monitor.bluez.properties = {
+     bluez5.codecs = [ sbc_xq aac ldac ]
+   }
+
+Here, the entire ``monitor.bluez.properties`` object will be replaced with the
+new one, and all previous key-value pairs configured will be discarded. This
+also means that the ``bluez5.codecs`` array will be replaced with the new one
+and does not require the ``override.`` prefix.
+
+.. note::
+
+   Even though WirePlumber uses PipeWire's syntax for configuration files, the
+   ``override.`` prefix is a WirePlumber extension and does not work in
+   PipeWire.
+
+.. _config_modifying_configuration_rules:
+
+Working with rules
+------------------
+
+Some of the static option sections in the configuration file are used to define
+rules that are evaluated by WirePlumber at runtime. These rules are typically
+used to match objects and perform actions on them. For example, the
+``monitor.alsa.rules`` section is used to define rules that are evaluated by
+the ALSA monitor to match ALSA devices and update their properties.
+
+The syntax of these rules is the same as the syntax of
+`PipeWire's rules <https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/Config-PipeWire#rules>`_.
+
+A rule is always a JSON object with two keys: ``matches`` and ``actions``. The
+``matches`` key is used to define the conditions that need to be met for the
+rule to be evaluated as true, and the ``actions`` key is used to define the
+actions that are performed when the rule is evaluated as true.
+
+The ``matches`` key is always a JSON array of objects, where each object
+defines a condition that needs to be met. Each condition is a list of key-value
+pairs, where the key is the name of the property that is being matched, and the
+value is the value that the property needs to have. Within a condition, all
+the key-value pairs are combined with a logical AND, and all the conditions in
+the ``matches`` array are combined with a logical OR.
+
+The ``actions`` key is always a JSON object, where each key-value pair defines
+an action that is performed when the rule is evaluated as true. The action
+name is specific to the rule and is defined by the rule's documentation, but
+most frequently you will see the ``update-props`` action, which is used to
+update the properties of the matched object.
+
+For example:
+
+.. code-block::
+
+   some.theoretical.rules = [
+     {
+       matches = [
+         {
+           object.name = "my_object"
+           object.profile.name = "my_profile"
+         }
+         {
+           object.name = "other_object"
+         }
+       ]
+       actions = {
+         update-props = {
+           object.tag = "matched_by_my_rule"
+         }
+       }
+     }
+   ]
+
+This rule is equivalent to the following expression:
+
+.. code-block:: python
+
+   if (properties["object.name"] == "my_object" and properties["object.profile.name"] == "my_profile") or (properties["object.name"] == "other_object"):
+        properties["object.tag"] = "matched_by_my_rule"
+
+In the ``matches`` array, it is also possible to use regular expressions to match
+property values. For example, to match all nodes with a name that starts with
+``my_``, you can use the following condition:
+
+.. code-block::
+
+   matches = [
+     {
+       node.name = "~my_.*"
+     }
+   ]
+
+The ``~`` character signifies that the value is a regular expression. The exact
+syntax of the regular expressions is the POSIX extended regex syntax, as
+described in the `regex (7)` man page.
+
+In addition to regular expressions, you may also use the ``!`` character to
+negate a condition. For example, to match all nodes with a name that does not
+start with ``my_``, you can use the following condition:
+
+.. code-block::
+
+   matches = [
+     {
+       node.name = "!~my_.*"
+     }
+   ]
+
+The ``!`` character can be used with or without a regular expression. For
+example, to match all nodes with a name that is not equal to ``my_node``,
+you can use the following condition:
+
+.. code-block::
+
+   matches = [
+     {
+       node.name = "!my_node"
+     }
+   ]

docs/rst/daemon/configuration/settings.rst

@@ -0,0 +1,228 @@
+.. _config_settings:
+
+Well-known settings
+===================
+
+This section describes the settings that can be configured on WirePlumber.
+
+Settings can be either configured statically in the configuration file
+by setting them under the ``wireplumber.settings`` section, or they can be
+configured dynamically at runtime by using metadata.
+
+For more information on what "settings" are and how they work, refer to the
+previous section: :ref:`config_configuration_option_types`.
+
+.. describe:: device.restore-profile
+
+   When a device profile is changed manually (e.g. via pavucontrol), WirePlumber
+   stores the selected profile and restores it when the device appears again
+   (e.g. after a reboot). If this setting is disabled, WirePlumber will always
+   pick the best profile for the device based on profile priorities and
+   availability (or custom rules, if any).
+
+   :Default value: ``true``
+
+.. describe:: device.restore-routes
+
+   When a device route is changed manually (e.g. via pavucontrol), WirePlumber
+   stores the selected route and restores it when the same profile is
+   selected for this device. If this setting is disabled, WirePlumber will
+   always pick the best route for this device profile based on route priorities
+   and availability (or custom rules, if any).
+
+   This setting also enables WirePlumber to restore properties of the device
+   route when the route is restored. This includes the volume levels of sources
+   and sinks, as well as the IEC958 codecs selected (for routes that support
+   encoded streams, such as HDMI).
+
+   :Default value: ``true``
+
+.. describe:: device.routes.default-sink-volume
+
+   This option allows to set the default volume for sinks that are part of a
+   device route (e.g. ALSA PCM sinks). This is used when the route is restored
+   and the sink does not have a previously stored volume.
+
+   It is possible to override the value on a per-device basis with a property
+   (*not* a setting, so this would go into a configuration file) on the device
+   named ``device.routes.default-sink-volume``.
+
+   :Default value: ``0.4 ^ 3`` (40% on the cubic scale)
+
+.. describe:: device.routes.default-source-volume
+
+   This option allows to set the default volume for sources that are part of a
+   device route (e.g. ALSA PCM sources). This is used when the route is restored
+   and the source does not have a previously stored volume.
+
+   It is possible to override the value on a per-device basis with a property
+   (*not* a setting, so this would go into a configuration file) on the device
+   named ``device.routes.default-source-volume``.
+
+   :Default value: ``1.0`` (100%)
+
+.. describe:: linking.allow-moving-streams
+
+   This option allows moving streams by overriding their target via metadata.
+   When enabled, WirePlumber monitors the "default" metadata for changes in the
+   ``target.object`` key of streams and if this key is set to a valid node name
+   (``node.name``) or serial (``object.serial``), the stream is moved to that
+   target node.
+
+   This is used by applications such as pavucontrol and is recommended for
+   compatibility with PulseAudio.
+
+    .. note::
+
+       On the metadata, the ``target.node`` key is also supported for
+       compatibility with older versions of PipeWire, but it is deprecated.
+       Please use the ``target.object`` key instead.
+
+   :Default value: ``true``
+   :See also: ``node.stream.restore-target``
+
+.. describe:: linking.follow-default-target
+
+   When a stream was started with the ``target.object`` property, WirePlumber
+   normally links that stream to that target node and ignores the "default"
+   target for that direction. However, if this option is enabled, WirePlumber
+   will check if the designated target node *is* the "default" target and if so,
+   it will act as if the stream did not have that property.
+
+   In practice, this means that if the "default" target changes at runtime,
+   the stream will be moved to the new "default" target.
+
+   This is what Pulseaudio does and is implemented here for compatibility
+   with some applications that do start with a ``target.object`` property
+   set to the "default" target and expect the stream to be moved when the
+   "default" target changes.
+
+   Note that this logic is only applied on client (i.e. application) streams
+   and *not* on filters.
+
+   :Default value: ``true``
+
+.. describe:: linking.pause-playback
+
+   When an audio sink is removed, pause media players that have streams
+   playing to it. Pausing is done via MPRIS interface.
+
+   :Default value: ``true``
+
+.. describe:: node.features.audio.no-dsp
+
+   When this option is set to ``true``, audio nodes will not be configured
+   in dsp mode, meaning that their channels will *not* be split into separate
+   ports and that the audio data will *not* be converted to the float 32 format
+   (F32P). Instead, devices will be configured in passthrough mode and streams
+   will be configured in convert mode, so that their audio data is converted
+   directly to the format that the device is expecting.
+
+   This may be useful if you are trying to minimize audio processing for an
+   embedded system, but it is not recommended for general use.
+
+   .. warning::
+
+      This option **will break** compatibility with JACK applications
+      and may also break certain patchbay applications. Do not enable, unless
+      you understand what you are doing.
+
+   :Default value: ``false``
+
+.. describe:: node.features.audio.monitor-ports
+
+   This enables the creation of "monitor" ports for audio nodes. Monitor ports
+   are created on nodes that have input ports (i.e. sinks and capture streams)
+   and allow monitoring of the audio data that is being sent to the node.
+
+   This is mostly used by monitoring applications, such as pavucontrol.
+
+   :Default value: ``true``
+
+.. describe:: node.features.audio.control-port
+
+   This enables the creation of a "control" port for audio nodes. Control ports
+   allow sending MIDI data to the node, allowing for control of certain node's
+   parameters (such as volume) via external controllers.
+
+   :Default value: ``false``
+
+.. describe:: node.stream.restore-props
+
+   WirePlumber stores stream parameters such as volume and mute status for each
+   client (i.e. application) stream. If this setting is enabled, WirePlumber
+   will restore the previously stored stream parameters when the stream is
+   activated. If it is disabled, stream parameters will be initialized to their
+   default values.
+
+   :Default value: ``true``
+
+.. describe:: node.stream.restore-target
+
+   When a client (i.e. application) stream is manually moved to a different
+   target node (e.g. via pavucontrol), the target node is stored by WirePlumber.
+   If this setting is enabled, WirePlumber will restore the previously stored
+   target node when the stream is activated.
+
+   .. note::
+
+      This does not restore manual links made by patchbay applications. This
+      is only meant to restore the ``target.object`` property in the "default"
+      metadata, which is manipulated by applications such as pavucontrol when
+      a stream is moved to a different target.
+
+   :Default value: ``true``
+   :See also: ``linking.allow-moving-streams``
+
+.. describe:: node.stream.default-playback-volume
+
+   The default volume for playback streams to be applied when the stream is
+   activated. This is only applied when ``node.stream.restore-props`` is
+   ``true`` and the stream does not have a previously stored volume.
+
+   :Default value: ``1.0``
+   :Range: ``0.0`` to ``1.0``
+
+.. describe:: node.stream.default-capture-volume
+
+   The default volume for capture streams to be applied when the stream is
+   activated. This is only applied when ``node.stream.restore-props`` is
+   ``true`` and the stream does not have a previously stored volume.
+
+   :Default value: ``1.0``
+   :Range: ``0.0`` to ``1.0``
+
+.. describe:: node.filter.forward-format
+
+   When a "filter" pair of nodes (such as echo-cancel or filter-chain) is
+   linked to a device node that has a different channel map than the filter
+   nodes, this option allows the channel map of the filter nodes to be changed
+   to match the channel map of the device node. The change is applied to both
+   ends of the "filter", so that any streams linked to the filter are also
+   reconfigured to match the target channel map.
+
+   This is useful, for instance, to make sure that an application will be
+   properly configured to output surround audio to a surround device, even
+   when going through a filter that was not explicitly configured to have
+   a surround channel map.
+
+   :Default value: ``false``
+
+.. describe:: node.restore-default-targets
+
+   This setting enables WirePlumber to store and restore the "default" source
+   and sink targets of the graph. In PulseAudio terminology, this is also known
+   as the "fallback" source and sink.
+
+   When this setting is enabled, WirePlumber will store the "default" source
+   and sink targets when they are changed manually (e.g. via pavucontrol) and
+   restore them when the available nodes change or after a reload/restart.
+   It will also store a history of past selected "default" targets and restore
+   previously selected ones if the currently selected are not available.
+
+   If this is disabled, WirePlumber will pick the best available source
+   and sink targets based on their priorities, but it will also respect
+   manual user selections that are done at runtime - it will just not remember
+   them so that it can restore them at a later time.
+
+   :Default value: ``true``

docs/rst/daemon/installing.rst

@@ -1,4 +1,4 @@
- .. _installing-wireplumber:
+.. _daemon_installing:
 
 Installing WirePlumber
 ======================
@@ -8,8 +8,8 @@ Dependencies
 
 In order to compile WirePlumber you will need:
 
-* GLib >= 2.62
+* GLib >= 2.68
-* PipeWire 0.3 (>= 0.3.43)
+* PipeWire >= 1.0
 * Lua 5.3 or 5.4
 
 Lua is optional in the sense that if it is not found in the system, a bundled

docs/rst/daemon/locations.rst

@@ -0,0 +1,175 @@
+.. _daemon_file_locations:
+
+Locations of WirePlumber's files
+================================
+
+.. _config_locations:
+
+Location of configuration files
+-------------------------------
+
+WirePlumber's default locations of its configuration files are the following,
+in order of priority:
+
+ 1. ``$XDG_CONFIG_HOME/wireplumber``
+ 2. ``$XDG_CONFIG_DIRS/wireplumber``
+ 3. ``$sysconfdir/wireplumber``
+ 4. ``$XDG_DATA_DIRS/wireplumber``
+ 5. ``$datadir/wireplumber``
+
+Notes:
+
+ * ``$syscondir`` and ``$datadir`` refer to
+   `meson's directory options <https://mesonbuild.com/Builtin-options.html#directories>`_
+   and are hardcoded at build time
+ * ``$XDG_`` variables refer to the
+   `XDG Base Directory Specification <https://specifications.freedesktop.org/basedir-spec/latest/index.html>`_
+
+It is recommended that user specific overrides are placed in
+``$XDG_CONFIG_HOME/wireplumber``, while host-specific configuration is placed in
+``$XDG_CONFIG_DIRS/wireplumber`` or ``$sysconfdir/wireplumber`` and
+distribution-provided configuration is placed in ``$XDG_DATA_DIRS/wireplumber``
+or ``$datadir/wireplumber``.
+
+At runtime, WirePlumber will seek out the directory with the highest priority
+that contains the required configuration file. This setup allows a user or
+system administrator to effortlessly override the configuration files provided
+by the distribution. They can achieve this by placing a file with an identical
+name in a higher priority directory.
+
+It is also possible to override the configuration directory by setting the
+``WIREPLUMBER_CONFIG_DIR`` environment variable:
+
+.. code-block:: bash
+
+   WIREPLUMBER_CONFIG_DIR=src/config wireplumber
+
+``WIREPLUMBER_CONFIG_DIR`` supports listing multiple directories, using the
+standard path list separator ``:``. If multiple directories are specified,
+the first one has the highest priority and the last one has the lowest.
+
+.. note::
+
+   When the configuration directory is overridden with
+   ``WIREPLUMBER_CONFIG_DIR``, the default locations are ignored and
+   configuration files are *only* looked up in the directories specified by this
+   variable.
+
+.. _config_locations_fragments:
+
+Configuration fragments
+^^^^^^^^^^^^^^^^^^^^^^^
+
+WirePlumber also supports configuration fragments. These are configuration files
+that are loaded in addition to the main configuration file, allowing to
+override or extend the configuration without having to copy the whole file.
+See also the :ref:`config_conf_file_fragments` section for semantics.
+
+Configuration fragments are always loaded from subdirectories of the main search
+directories that have the same name as the configuration file, with the ``.d``
+suffix appended. For example, if WirePlumber loads ``wireplumber.conf``, it will
+also load ``wireplumber.conf.d/*.conf``. Note also that the fragment files need
+to have the ``.conf`` suffix.
+
+When WirePlumber loads a configuration file from the default locations, it will
+also load all configuration fragments that are present in all of the default
+locations, but following the reverse order of priority. This allows
+configuration fragments that are installed in more system-wide locations to be
+overridden by the system administrator or the users.
+
+For example, assuming WirePlumber loads ``wireplumber.conf``, from any of the
+search locations, it will also locate and load the following fragments, in this
+order:
+
+ 1. ``$datadir/wireplumber/wireplumber.conf.d/*.conf``
+ 2. ``$XDG_DATA_DIRS/wireplumber/wireplumber.conf.d/*.conf``
+ 3. ``$sysconfdir/wireplumber/wireplumber.conf.d/*.conf``
+ 4. ``$XDG_CONFIG_DIRS/wireplumber/wireplumber.conf.d/*.conf``
+ 5. ``$XDG_CONFIG_HOME/wireplumber/wireplumber.conf.d/*.conf``
+
+Within each search location that contains fragments, the individual fragment
+files are opened in alphanumerical order. This can be important to know, because
+the parsing order matters in merging. See :ref:`config_conf_file_fragments`
+
+.. note::
+
+   When ``WIREPLUMBER_CONFIG_DIR`` is set, the default locations are ignored and
+   fragment files are *only* looked up in the directories specified by this
+   variable.
+
+.. _config_locations_scripts:
+
+Location of scripts
+-------------------
+
+WirePlumber's default locations of its data files are the following,
+in order of priority:
+
+ 1. ``$XDG_DATA_HOME/wireplumber``
+ 2. ``$XDG_DATA_DIRS/wireplumber``
+ 3. ``$datadir/wireplumber``
+
+At runtime, WirePlumber will search the directories for the highest-priority
+directory to contain the needed data file.
+
+Scripts are a specific kind of "data" files and are expected to be located
+within a ``scripts`` subdirectory in the above data search locations. The "data"
+directory is a somewhat more generic path that may be used for other kinds of
+data files in the future.
+
+It is also possible to override the data directory by setting the
+``WIREPLUMBER_DATA_DIR`` environment variable:
+
+.. code-block:: bash
+
+   WIREPLUMBER_DATA_DIR=src wireplumber
+
+As with the default data directories, script files in particular are expected
+to be located within a ``scripts`` subdirectory, so in the above example the
+scripts would actually reside in ``src/scripts``.
+
+``WIREPLUMBER_DATA_DIR`` supports listing multiple directories, using the
+standard path list separator ``:``. If multiple directories are specified,
+the first one has the highest priority and the last one has the lowest.
+
+.. note::
+
+   When ``WIREPLUMBER_DATA_DIR`` is set, the default locations are ignored and
+   scripts are *only* looked up in the directories specified by this variable.
+
+Location of modules
+-------------------
+
+WirePlumber modules
+^^^^^^^^^^^^^^^^^^^
+
+WirePlumber's default location of its modules is
+``$libdir/wireplumber-$api_version``, where ``$libdir`` is set at compile time
+by the build system. Typically, it ends up being ``/usr/lib/wireplumber-0.5``
+(or ``/usr/lib/<arch-triplet>/wireplumber-0.5`` on multiarch systems)
+
+It is possible to override this directory at runtime by setting the
+``WIREPLUMBER_MODULE_DIR`` environment variable:
+
+.. code-block:: bash
+
+   WIREPLUMBER_MODULE_DIR=build/modules wireplumber
+
+``WIREPLUMBER_MODULE_DIR`` supports listing multiple directories, using the
+standard path list separator ``:``. If multiple directories are specified, the
+first one has the highest priority and the last one has the lowest.
+
+.. note::
+
+   When ``WIREPLUMBER_MODULE_DIR`` is set, the default locations are ignored and
+   scripts are *only* looked up in the directories specified by this variable.
+
+PipeWire and SPA modules
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+PipeWire and SPA modules are not loaded from the same location as WirePlumber's
+modules. They are loaded from the location that PipeWire loads them.
+
+It is also possible to override these locations by using environment variables:
+``SPA_PLUGIN_DIR`` and ``PIPEWIRE_MODULE_DIR``. For more details, refer to
+PipeWire's documentation.

docs/rst/daemon/logging.rst

@@ -0,0 +1,248 @@
+.. _daemon_logging:
+
+Debug Logging
+=============
+
+WirePlumber is instrumented with log messages in its entire codebase. These
+messages are categorized based on two heuristics: the log topic and the log
+level.
+
+The log topic is a string that identifies which component of the code this
+message is coming from. Well-known topics include:
+
+  - **wireplumber**: messages from the wireplumber daemon
+  - **wp-***: messages from libwireplumber
+
+   - **wp-core**: messages from *WpCore*
+   - **wp-proxy**: messages from *WpProxy*
+   - ... and so on ...
+
+  - **m-***: messages from wireplumber modules
+
+   - **m-default-profile**: messages from *libwireplumber-module-default-profile*
+   - **m-default-routes**: messages from *libwireplumber-module-default-routes*
+   - ... and so on ...
+
+  - **s-***: messages from scripts
+
+   - **s-linking**: messages from the *linking/\*.lua* scripts
+   - **s-default-nodes**: messages from the *default-nodes/\*.lua* scripts
+   - ... and so on ...
+
+  - **pw.***: messages from libpipewire
+  - **spa.***: messages from spa plugins
+  - **mod.***: messages from libpipewire modules
+  - **conn.***: messages to debug the pipewire socket connection
+
+The log level is a value that designates the importance of the message.
+The levels that exist in WirePlumber are the following:
+
+  - ``F``: *Fatal errors*. These messages represent situations where execution
+    of the program cannot continue. In the extremely unlikely case that
+    they appear, these messages also cause the process to be terminated.
+  - ``E``: *Critical warnings* (or "errors" in the PipeWire terminology).
+    These messages represent situations where something unexpected has happened
+    and someone with understanding of the code should probably take a look at it.
+    These situations are usually programming mistakes or omissions.
+    This does not necessarily mean that the program is not functioning correctly.
+    It may mean, though, that the specific part of the program that logged the
+    message (the plugin, subsystem, ...) may not work optimally.
+  - ``W``: *Warnings*. These messages represent situations where something has
+    gone unintentionally wrong, but it was not totally unexpected. The situation
+    is recovered and the program can continue. In many cases, this warning may
+    mean that there is something wrong with the configuration or the environment
+    and may need attention from the user.
+  - ``N``: *Notices*. These are important messages that the user should notice,
+    like warnings, but they do not necessarily mean a bad situation.
+  - ``I``: *Informational messages*. These messages provide information about
+    the internal operations of the program.
+  - ``D``: *Debug messages*. These messages provide details about the
+    internal operations of the program, which can be useful for debugging.
+  - ``T``: *Traces*. These messages provide very verbose printouts of internal
+    operations and data that affects these operations. These can be useful for
+    debugging as well, but it may be best to be enabled only for the topic(s)
+    that are intended to be debugged, as they can be very big in volume.
+
+By default, WirePlumber logs only messages from levels ``F``, ``E``, ``W``
+and ``N``. These messages are printed on the standard error (``stderr``) stream,
+or they are logged to the systemd journal, if WirePlumber was started as a
+systemd service.
+
+The ``WIREPLUMBER_DEBUG`` environment variable can be used to change which
+topics and levels are enabled. The generic syntax is:
+
+.. code::
+
+   WIREPLUMBER_DEBUG=[<topic pattern>:]<level>,...,
+
+This is a comma-separated list of topics to enable, paired with a level for
+each topic.
+
+``<level>`` can be one of ``FEWNIDT`` or a numerical log level as listed below.
+
+  0. fatal errors (``F``)
+  1. critical warnings (``E``)
+  2. warnings and notices (``W`` & ``N``)
+  3. informational messages (``I``)
+  4. debug messages (``D``)
+  5. trace messages (``T``)
+
+Each level always includes messages from the previous levels, so for instance
+enabling level ``3`` (or ``I``) will also enable messages from levels ``2``
+and ``1`` (``N``, ``W``, ``E`` and ``F``)
+
+``<topic pattern>`` is an *optional* description of one or more topics.
+This supports
+`glob style patterns <https://developer-old.gnome.org/glib/stable/glib-Glob-style-pattern-matching.html>`_
+containing ``*`` and ``?``.
+
+If a ``<topic pattern>`` is not specified, then the given ``<level>`` is
+considered to be the global log level, which applies to all topics that have
+no explicit level specified.
+
+Changing log level at runtime
+-----------------------------
+
+The debug log level can be changed at runtime using ``wpctl``:
+
+.. code::
+
+   wpctl set-log-level D     # enable debug logging for Wireplumber
+   wpctl set-log-level -     # restore default logging for Wireplumber
+
+   wpctl set-log-level 0 4   # enable debug logging for Pipewire daemon
+   wpctl set-log-level 0 -   # restore default logging for Pipewire daemon
+
+Equivalently, it is also possible to adjust the logging by setting
+``log.level`` in the ``settings`` metadata:
+
+.. code::
+
+   pw-metadata -n settings <ID> log.level "D"   # WirePlumber logging
+
+   pw-metadata -n settings 0 log.level 4        # PipeWire daemon logging
+
+Above, ``<ID>`` should be replaced by the WirePlumber daemon client ID.
+
+Note that PipeWire daemon log levels must be specified by numbers, not
+letter codes.
+
+Changing log level via static configuration
+-------------------------------------------
+
+If you need to capture logs from WirePlumber at startup or in other circumstances
+where changing the level at runtime or setting an environment variable is not
+feasible, then you may also set the log level in the configuration file.
+
+The log level changes via the ``log.level`` key in the ``context.properties``
+section:
+
+.. code::
+
+   context.properties = {
+     log.level = "D"
+   }
+
+You may use the same syntax as in ``WIREPLUMBER_DEBUG`` to describe the exact
+logging you want to achieve. For instance, to log debug messages from all
+scripts and informational messages from everywhere else:
+
+.. code::
+
+   context.properties = {
+     log.level = "I,s-*:D"
+   }
+
+The easiest way to configure this is to drop a
+:ref:`fragment file <config_conf_file_fragments>` that contains just this.
+
+.. code-block:: bash
+
+   $ mkdir -p ~/.config/wireplumber/wireplumber.conf.d
+   $ echo 'context.properties = { log.level = "D" }' > ~/.config/wireplumber/wireplumber.conf.d/log.conf
+
+See also :ref:`config_modifying_configuration`
+
+Examples
+--------
+
+Show *all* messages:
+
+.. code::
+
+   WIREPLUMBER_DEBUG=T
+
+Show all messages up to the *debug* level (F, E, W, N, I & D), excluding *trace*:
+
+.. code::
+
+   WIREPLUMBER_DEBUG=D
+
+Show all messages up to the *notice* level (F, E, W & N),
+excluding *info*, *debug* & *trace*
+(this is also the default when ``WIREPLUMBER_DEBUG`` is omitted):
+
+.. code::
+
+   WIREPLUMBER_DEBUG=2
+
+Show all messages from the wireplumber library (including traces), but only
+up to informational messages from other topics:
+
+.. code::
+
+   WIREPLUMBER_DEBUG=I,wp-*:T
+
+Show debug messages from ``wp-registry``, libpipewire and all modules, keeping
+all other topics up to the *notice* level.
+
+.. code::
+
+   WIREPLUMBER_DEBUG=2,wp-registry:4,pw.*:4,m-*:4
+
+Relationship with the GLib log handler & G_MESSAGES_DEBUG
+---------------------------------------------------------
+
+Older versions of WirePlumber used to use ``G_MESSAGES_DEBUG`` to control their
+log output, which is the environment variable that affects GLib's default
+log handler.
+
+As of WirePlumber 0.3, ``G_MESSAGES_DEBUG`` is no longer used, since
+libwireplumber replaces the default log handler.
+
+If you are writing your own application based on libwireplumber, you can choose
+if you want to replace this log handler using the flags passed to
+:c:func:`wp_init`.
+
+Relationship with the PipeWire log handler & PIPEWIRE_DEBUG
+-----------------------------------------------------------
+
+libpipewire uses the ``PIPEWIRE_DEBUG`` environment variable, with a similar syntax.
+WirePlumber replaces the log handler of libpipewire with its own, rendering
+``PIPEWIRE_DEBUG`` useless. Instead, you should use ``WIREPLUMBER_DEBUG``.
+All the log topics that apply to libpipewire and its modules / plugins work
+the same in ``WIREPLUMBER_DEBUG``.
+
+If you are writing your own application based on libwireplumber, you can choose
+if you want to replace this log handler using the flags passed to
+:c:func:`wp_init`.
+
+Mapping of PipeWire debug levels to WirePlumber
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+PipeWire supports 5 levels of debug logging. WirePlumber, on the other hand,
+supports 7 levels. Some levels seem common, but the terminology and the
+semantics are slightly different. The following table shows how the various
+levels are mapped:
+
+=============  ===============  ========================
+Numeric Level  PipeWire         WirePlumber
+=============  ===============  ========================
+0              no log           ``F`` - Fatal Error
+1              ``E`` - Error    ``E`` - Critical Warning
+2              ``W`` - Warning  ``W`` - Warning,
+                                ``N`` - Notice
+3              ``I`` - Info     ``I`` - Info
+4              ``D`` - Debug    ``D`` - Debug
+5              ``T`` - Trace    ``T`` - Trace
+=============  ===============  ========================

docs/rst/daemon/meson.build

@@ -0,0 +1,11 @@
+# you need to add here any files you add to the toc directory as well
+sphinx_files += files(
+   'installing.rst',
+   'running.rst',
+   'configuration.rst',
+   'locations.rst',
+   'logging.rst',
+   'multi_instance.rst',
+)
+
+subdir('configuration')

docs/rst/daemon/multi_instance.rst

@@ -0,0 +1,88 @@
+.. _daemon_multi_instance:
+
+Running multiple instances
+==========================
+
+WirePlumber has the ability to run either as a single instance daemon or as
+multiple instances, meaning that there can be multiple processes, each one
+doing a different task.
+
+The most common use case for such a setup is to separate the graph orchestration
+tasks from the device monitoring and object creation ones. This can be useful
+for robustness and security reasons, as it allows restarting the device monitors
+or running them in different security contexts without affecting the rest of the
+session management functionality.
+
+To achieve a multi-instance setup, WirePlumber can be started multiple times
+with a different :ref:`profile<config_components_and_profiles>` loaded in each
+instance. This can be achieved using the ``--profile`` command line option to
+select the profile to load:
+
+.. code-block:: console
+
+  $ wireplumber --profile=custom
+
+When no particular profile is specified, the ``main`` profile is loaded.
+
+For multi-instance configuration, the default ``wireplumber.conf`` specifies 4
+profiles:
+
+.. describe:: policy
+
+  This profile runs all the policy scripts, i.e. ones that monitor changes
+  in the graph and execute actions to link nodes, select default devices,
+  create new nodes or configure existing ones differently.
+
+.. describe:: audio
+
+  The audio profile runs the ALSA and ALSA MIDI monitors, which make audio &
+  MIDI devices available to PipeWire.
+
+.. describe:: bluetooth
+
+  The bluetooth profile runs the BlueZ and BlueZ MIDI monitors, which enable
+  Bluetooth audio & MIDI devices and other Bluetooth functionality tied to the
+  A2DP, HSP, HFP and BAP profiles, using BlueZ.
+
+.. describe:: video-capture
+
+  The video-capture profile runs the V4L2 and libcamera monitors, which make
+  video capture devices, such as cameras and HDMI capture cards, available
+  to PipeWire.
+
+.. note::
+
+  The ``main`` profile includes all the functionality of the ``policy``,
+  ``audio``, ``video-capture`` and ``bluetooth`` profiles combined (i.e. it is
+  the default for a standard single instance configuration). You should never
+  load the ``main`` profile alongside these other 4 profiles, as their
+  functionality will conflict.
+
+.. warning::
+
+  Always ensure that the instances you load serve a different purpose and they
+  do not conflict with each other. Conflicting components executed in parallel
+  will have undefined behavior.
+
+Systemd integration
+-------------------
+
+To make this easier to work with, a template systemd unit is provided, which is
+meant to be started with the name of the profile as a template argument:
+
+.. code-block:: console
+
+  $ systemctl --user disable wireplumber # disable the "main" profile instance
+  $ systemctl --user enable wireplumber@policy
+  $ systemctl --user enable wireplumber@audio
+  $ systemctl --user enable wireplumber@video-capture
+  $ systemctl --user enable wireplumber@bluetooth
+
+.. note::
+
+   In WirePlumber 0.4, the template argument was the name of the configuration
+   file to load, since profiles did not exist. In WirePlumber 0.5, the template
+   argument is the name of the profile and the configuration file is always
+   ``wireplumber.conf``. To change the name of the configuration file you need
+   to craft custom systemd unit files and use the ``--config-file`` command line
+   option as needed.

docs/rst/daemon/running.rst

@@ -1,4 +1,4 @@
- .. _running-wireplumber-daemon:
+.. _daemon_running:
 
 Running the WirePlumber daemon
 ==============================
@@ -40,7 +40,7 @@ Synopsis:
 
    $ meson -Dsession-managers="[ 'wireplumber' ]" build
    $ ninja -C build
-   $ make run
+   $ make -C build run
 
 Run independently or without installing
 ---------------------------------------

docs/rst/design/events_and_hooks.rst

@@ -0,0 +1,139 @@
+.. _design_events_and_hooks:
+
+Events and Hooks
+================
+
+Session management is all about reacting to events and taking necessary
+actions. This is why WirePlumber's logic is all built on events and hooks.
+
+Events
+------
+
+Events are objects that represent a change that has just happened on a PipeWire
+object, or just a trigger for making a decision and potentially taking some
+action.
+
+Every event has a source, a subject and some properties, which include the
+event type.
+
+* The ``source`` is a reference to the GObject that created this event.
+  Typically, this is the ``WpStandardEventSource`` plugin.
+* The ``subject`` is an *optional* reference to the object that this event
+  is about. For example, in a ``node-added`` event, the ``subject`` would be
+  a reference to the ``WpNode`` object that was just added. Some events,
+  especially those which are used only to trigger actions, do not have a
+  subject.
+* The ``properties`` is a dictionary that contains information about the event,
+  including the event type, and also includes all the PipeWire properties of the
+  ``subject``, if there is one.
+* The ``event.type`` property describes the nature of the event, for example
+  ``node-added`` or ``metadata-changed`` are some valid event types.
+
+Every event also has a priority. Events with a higher priority are processed
+before events with a lower priority. When two or more events have the same
+priority, they are processed in a first-in-first-out manner. This logic
+is defined in the *event dispatcher*.
+
+Events are short-lived objects. They are created at the time that something is
+happening and they are destroyed after they get processed. Processing an event
+means executing all the hooks that are associated with it. The next section
+explains what hooks are and how they are associated with events.
+
+Hooks
+-----
+
+Hooks are objects that represent a runnable action that needs to be executed
+when a certain event is processed. Every hook, therefore, consists of a
+function - synchronous or asynchronous - that can be executed. Additionally,
+every hook has a means to associate itself with specific events. This is
+normally done by declaring *interest* to specific event properties or
+combinations of them.
+
+There are two main types of hooks: ``SimpleEventHook`` and ``AsyncEventHook``.
+
+* ``SimpleEventHook`` contains a single, synchronous function. As soon as this
+  function is executed, the hook is completed.
+* ``AsyncEventHook`` contains multiple functions, combined together in a state
+  machine using ``WpTransition`` underneath. The hook is completed only after
+  the state machine reaches its final state and this can take any amount of time
+  necessary.
+
+Every hook also has a name, which can be an arbitrary string of characters.
+Additionally, it has two arrays of names, which declare dependencies between
+this hook and others. One array is called ``before`` and the other is called
+``after``. The hook names in the ``before`` array specify that this hook must
+be executed *before* those other hooks. Similarly, the hook names in the
+``after`` array specify that this hook must be executed *after* those other
+hooks. Using this mechanism, it is possible to define the order in which
+hooks will be executed, for a specific event.
+
+Hooks are long-lived objects. They are created once, registered in the
+*event dispatcher*, they are attached on events and detached after their
+execution. They don't maintain any internal state, so the actions of the hook
+depend solely on the event itself.
+
+The Event Dispatcher
+--------------------
+
+The event dispatcher is a (per core) singleton object that processes all events
+and also maintains a list of all the registered hooks. It has a method to
+*push* events on it, which causes them to be scheduled for processing.
+
+Scheduling of events and hooks
+------------------------------
+
+The main idea and reasoning behind this architecture is to have everything
+execute in a predefined order and always wait for an action to finish before
+executing the next one.
+
+Every event has a *priority* and every hook also has an order of execution that
+derives from the inter-dependencies between hooks, which are defined with
+``before`` and ``after`` (see above). When an event is pushed on the dispatcher,
+the dispatcher goes through all the registered hooks and checks which hooks are
+configured to run on this event (their event interest matches the event).
+It then makes a list of them, sorted by their order of execution, and stores it
+on the event. The event is then added on the dispatcher's list of events, which
+is sorted by priority.
+
+For example::
+
+  List of events
+   |  event1 (prio 99) -> hook1, hook2, hook3
+   |  event2 (prio 50) -> hook5, hook2, hook4
+   v
+
+The dispatcher has an internal ``GSource`` that is registered with
+``G_PRIORITY_HIGH_IDLE`` priority. When there is at least one event in the
+list of events, the source is dispatched. Every time it gets dispatched,
+it takes the top-most event (the highest priority one) and executes the highest
+priority hook in that event. If the hook executes synchronously, it then takes
+the next hook and continues until there are no more hooks on this event;
+then it goes to the next event, and so on. If the hook, however, executes
+asynchronously, processing stops until the hook finishes; after finishing,
+processing resumes like before.
+
+It is important to notice here that the list of events may be modified while
+events are getting processed. For example, a device is added; that's a
+``device-added`` event. Then a hook is executed to set the profile. That creates
+nodes, so a couple of ``node-added`` events... But there is also another hook to
+set the route, which was attached on the ``device-added`` event for the device.
+Suppose that we give the ``node-added`` events lower priority than the
+``device-added`` events, then the ``set-route`` hook will execute right after
+the ``set-profile`` and before any ``node-added`` events are processed.
+
+Visually, with sample priorities::
+
+  List of events
+   |  "device-added" (prio 20) -> set-profile, set-route
+   |  "node-added" (prio 10) -> restore-stream, create-session-item
+   v
+
+Obviously, there can also be a case where a newly added event has higher
+priority than the event that was being processed before. In that case,
+processing the hooks of the original event is stopped until all the hooks from
+the higher priority event have been processed. For example, a capture stream
+node being added may trigger the "bluetooth autoswitch" hook, which will then
+change the profile of a device. Changing the profile also has to trigger setting
+a new route and also handling the new device nodes, creating session items for
+them... After all this is done, processing the original capture stream
+``node-added`` event can continue.

docs/rst/design/meson.build

@@ -0,0 +1,6 @@
+# you need to add here any files you add to the toc directory as well
+sphinx_files += files(
+  'understanding_session_management.rst',
+  'understanding_wireplumber.rst',
+  'events_and_hooks.rst',
+)

docs/rst/design/understanding_session_management.rst

@@ -0,0 +1,105 @@
+.. _design_understanding_session_management:
+
+Understanding Session Management
+================================
+
+The PipeWire session manager is a tool that is tasked to do a lot of things.
+Many people understand the term "session manager" as a tool that is responsible
+for managing links between nodes, but that is only one of many tasks. To
+understand the entirety of its operation, we need to discuss how PipeWire works,
+first.
+
+When PipeWire starts, it loads a set of modules that are defined in its
+configuration file. These modules provide functionality to PipeWire, otherwise
+it is just an empty process that does nothing. Under normal circumstances,
+the modules that are loaded on PipeWire's startup contain object *factories*,
+plus the native protocol module that allows inter-process communication.
+Other than that, PipeWire does not really load or do anything else. This is
+where session management begins.
+
+Session management is basically about setting up PipeWire to do something
+useful. This is achieved by utilizing PipeWire's exposed object factories to
+create some useful objects, then work with their methods to modify and later
+destroy them. Such objects include devices, nodes, ports, links and others.
+This is a task that requires continuous monitoring and action taking, reacting
+on a large number of different events that happen as the system is being used.
+
+High-level areas of operation
+-----------------------------
+
+The session management logic, in WirePlumber, is divided into 6 different areas
+of operation:
+
+1. Device Enablement
+^^^^^^^^^^^^^^^^^^^^
+
+Enabling devices is a fundamental area of operation. It is achieved by using
+the device monitor objects (or just "monitors"), which are typically
+implemented as SPA plugins in PipeWire, but they are loaded by WirePlumber.
+Their task is to discover available media devices and create objects in PipeWire
+that offer a way to interact with them.
+
+Well-known monitors include:
+
+  - The ALSA monitor, which enables audio devices
+  - The ALSA MIDI monitor, which enables MIDI devices
+  - The libcamera monitor, which enables cameras
+  - The Video4Linux2 (V4L2) monitor, which also enables cameras, but also
+    other video capture devices through the V4L2 Linux API
+  - The BlueZ monitor, which enables bluetooth audio devices
+
+2. Device Configuration
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Most devices expose complex functionality, from the computer's perspective, that
+needs to be managed in order to provide a simple and smooth user experience.
+For that reason, for example, audio devices are organized into *profiles* and
+*routes*, which allow setting them up to serve a specific use case. These
+need to be configured and managed by the session manager.
+
+3. Client Access Control
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+When client applications connect to PipeWire, they need to obtain permissions
+in order to be able to access the objects exposed by PipeWire and interact
+with them. In some circumstances and configurations, the session manager is also
+tasked with deciding which permissions should be granted to each client.
+
+4. Node Configuration
+^^^^^^^^^^^^^^^^^^^^^
+
+Nodes are the fundamental elements of media processing. They are typically
+created either by the device monitors or by client applications. When they are
+created, they are in a state where they cannot be linked. Linking them requires
+some configuration, such as configuring the media format and subsequently
+the number and the type of ports that should be exposed. Additionally, some
+properties and metadata related to the node might need to be set according to
+user preferences. All of this is taken care of by the session manager.
+
+5. Link Management
+^^^^^^^^^^^^^^^^^^
+
+When nodes are finally ready to use, the session manager is also tasked to
+decide how they should be linked together in order for media to flow though.
+For instance, an audio playback stream node most likely needs to be linked to
+the default audio output device node. The session manager then also needs to
+create all these links and monitor all conditions that may affect them so that
+dynamic re-linking is possible in case something changes
+(ex. if a device disconnects). In some cases, device and node configuration
+may also need to change as a result of links being created or destroyed.
+
+6. Metadata Management
+^^^^^^^^^^^^^^^^^^^^^^
+
+While in operation, PipeWire and WirePlumber both store some additional
+properties about objects and their operation in storage that lives outside
+these objects. These properties are referred to as "metadata" and they are
+stored in "metadata objects". This metadata can be changed externally by tools
+such as `pw-metadata`, but also others.
+
+In some circumstances, this metadata needs to interact with logic inside
+the session manager. Most notably, selecting the default audio and video inputs
+and outputs is done by setting metadata. The session manager then needs to
+validate this information, store it and restore it on the next restart, but also
+ensure that the default inputs and outputs stay valid and reasonable when
+devices are plugged and unplugged dynamically.

docs/rst/design/understanding_wireplumber.rst

@@ -0,0 +1,101 @@
+.. _design_understanding_wireplumber:
+
+Understanding WirePlumber
+=========================
+
+Knowing the fundamentals of session management, let's see here how WirePlumber
+is structured.
+
+The library
+-----------
+
+WirePlumber is built on top of the `libwireplumber` library, which provides
+fundamental building blocks for expressing all the session management logic.
+Libwireplumber, which is written in C and based on GObject, wraps the PipeWire
+API and offers a higher level and more convenient API. While the WirePlumber
+daemon implements the session management logic, the underlying library can also
+be utilized outside the scope of the WirePlumber daemon. This allows for the
+creation of external tools and GUIs that interact with PipeWire.
+
+Being GObject based, the library is introspectable and can be used from any
+language that supports `GObject Introspection <https://gi.readthedocs.io/en/latest/>`_.
+The library is also available as a C API.
+
+The object model
+^^^^^^^^^^^^^^^^
+
+The most fundamental code contained in the WirePlumber library is the object
+model, i.e. its representation of PipeWire's objects.
+
+PipeWire exposes several objects, such nodes and ports, via the IPC protocol
+in a manner that is hard to interact with using standard object-oriented
+principles, because it is asynchronous. For example, when an object is created,
+its existence is announced over the protocol, but its properties are announced
+later, on a secondary message. If something needs to react on this object
+creation event, it typically needs to access the object's properties, so it
+must wait until the properties have been sent. Doing this might sound simple,
+and it is, but it becomes a tedious repetitive process to be doing this
+everywhere instead of focusing on writing the actual event handling logic.
+
+WirePlumber's library solves this by creating proxy objects that cache all the
+information and updates received from PipeWire throughout each object's lifetime.
+Then, it makes them available via the :ref:`WpObjectManager <obj_manager_api>`
+API, which has the ability to wait until certain information (ex, the
+properties) has been cached on each object before announcing it.
+
+Session management utilities
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The library also provides a set of utilities that are useful for session
+management. For example, it provides the :ref:`WpSessionItem <session_item_api>`
+class that can be used to abstract a part of the graph with some logic attached
+to it. It also provides the :ref:`Events & Hooks API <design_events_and_hooks>`,
+which is a way to express event handling logic in a declarative way.
+
+Misc utilities
+^^^^^^^^^^^^^^
+
+The library also provides a set of miscellaneous utilities that bridge the
+PipeWire API with the GObject API, such as :ref:`WpProperties <properties_api>`,
+:ref:`WpSpaPod <spa_pod_api>`, :ref:`WpSpaJson <spa_json_api>` and others.
+These complement the object model and make it easier to interact with PipeWire
+objects.
+
+The daemon
+----------
+
+The WirePlumber daemon is implemented on top of the library API and its job is
+to host components that implement the session management logic. By itself, it
+doesn't do anything except load and activate these components. The actual logic
+is implemented inside them.
+
+Modular design ensures that it is possible to swap the implementation of
+specific functionality without having to re-implement the rest of it, allowing
+flexibility on target-sensitive parts, such as policy management and
+making use of non-standard hardware.
+
+There are several kinds of components, each with a different purpose. The two
+main kinds are `modules` and `Lua scripts`. See also
+:ref:`config_components_and_profiles`.
+
+Modules
+^^^^^^^
+
+Modules extend the libwireplumber API for specific purposes, usually to provide
+support code or to allow WirePlumber to communicate with external services (ex
+D-Bus APIs). They either expose their own APIs via GObject signals (i.e. dynamic
+APIs that do not require linking at compile time) or implement certain objects
+through interfaces. They are written in C.
+
+Lua scripts
+^^^^^^^^^^^
+
+Lua scripts implement most of the session management. The libwireplumber API is
+made available in Lua with idiomatic bindings that make it very easy to write
+session management logic.
+
+Lua has been chosen because it is a very lightweight scripting language that is
+suitable for embedding. It is also very easy to learn and use, as well as bind
+it to C code. However, WirePlumber can be easily extended to support scripting
+languages other than Lua. The entire Lua scripting system is implemented as a
+module.

docs/rst/index.rst

@@ -7,23 +7,54 @@ Table of Contents
    :maxdepth: 2
    :caption: The WirePlumber Daemon
 
-   installing-wireplumber.rst
+   daemon/installing.rst
-   running-wireplumber-daemon.rst
+   daemon/running.rst
-   configuration.rst
+   daemon/configuration.rst
-   daemon-logging.rst
+   daemon/locations.rst
+   daemon/logging.rst
+   daemon/multi_instance.rst
+
+.. toctree::
+   :maxdepth: 2
+   :caption: WirePlumber's Design
+
+   design/understanding_session_management.rst
+   design/understanding_wireplumber.rst
+   design/events_and_hooks.rst
+
+.. toctree::
+   :maxdepth: 2
+   :caption: WirePlumber's Policies
+
+   policies/linking.rst
+   policies/smart_filters.rst
+   policies/software_dsp.rst
 
 .. toctree::
    :maxdepth: 2
    :caption: The WirePlumber Library
 
-   c_api.rst
+   library/c_api.rst
-   lua_api.rst
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Scripting
+
+   scripting/lua_api.rst
+   scripting/existing_scripts.rst
+   scripting/custom_scripts.rst
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Tools
+
+   tools/wpctl.rst
 
 .. toctree::
    :maxdepth: 2
    :caption: Resources
 
-   contributing.rst
+   resources/contributing.rst
-   testing.rst
+   resources/testing.rst
-   community.rst
+   resources/community.rst
-   releases.rst
+   resources/releases.rst

docs/rst/library/c_api.rst

@@ -1,4 +1,4 @@
- .. _library_root:
+.. _library_c_api:
 
 C API Documentation
 ===================
@@ -23,8 +23,8 @@ C API Documentation
    c_api/link_api.rst
    c_api/device_api.rst
    c_api/client_api.rst
+   c_api/permission_manager_api.rst
    c_api/metadata_api.rst
-   c_api/endpoint_api.rst
    c_api/spa_device_api.rst
    c_api/impl_node_api.rst
    c_api/impl_module_api.rst
@@ -34,7 +34,10 @@ C API Documentation
    c_api/spa_pod_api.rst
    c_api/plugin_api.rst
    c_api/component_loader_api.rst
+   c_api/settings_api.rst
+   c_api/conf_api.rst
    c_api/session_item_api.rst
    c_api/si_interfaces_api.rst
    c_api/si_factory_api.rst
    c_api/state_api.rst
+   c_api/base_dirs_api.rst

docs/rst/library/c_api/base_dirs_api.rst

@@ -0,0 +1,6 @@
+.. _base_dirs_api:
+
+Base Directories File Lookup
+============================
+.. doxygengroup:: wpbasedirs
+   :content-only:

docs/rst/library/c_api/component_loader_api.rst

@@ -7,14 +7,12 @@ Component Loader
 
    digraph inheritance {
       rankdir=LR;
-      GObject -> WpObject;
+      GInterface -> WpComponentLoader;
-      WpObject -> WpPlugin;
-      WpPlugin -> WpComponentLoader;
    }
 
 .. doxygenstruct:: WpComponentLoader
 
-.. doxygenstruct:: _WpComponentLoaderClass
+.. doxygenstruct:: _WpComponentLoaderInterface
 
 .. doxygengroup:: wpcomponentloader
    :content-only:

docs/rst/library/c_api/conf_api.rst

@@ -0,0 +1,16 @@
+.. _conf_api:
+
+Static Configuration
+====================
+.. graphviz::
+  :align: center
+
+   digraph inheritance {
+      rankdir=LR;
+      GObject -> WpConf;
+   }
+
+.. doxygenstruct:: WpConf
+
+.. doxygengroup:: wpconf
+   :content-only:

docs/rst/library/c_api/core_api.rst

@@ -7,7 +7,8 @@ Core
 
    digraph inheritance {
       rankdir=LR;
-      GObject -> WpCore;
+      GObject -> WpObject;
+      WpObject -> WpCore;
    }
 
 .. doxygenstruct:: WpCore

docs/rst/library/c_api/meson.build

@@ -1,10 +1,11 @@
 # you need to add here any files you add to the api directory as well
 sphinx_files += files(
+  'base_dirs_api.rst',
   'client_api.rst',
   'component_loader_api.rst',
+  'conf_api.rst',
   'core_api.rst',
   'device_api.rst',
-  'endpoint_api.rst',
   'global_proxy_api.rst',
   'impl_module_api.rst',
   'impl_node_api.rst',
@@ -17,11 +18,13 @@ sphinx_files += files(
   'obj_manager_api.rst',
   'object_api.rst',
   'pipewire_object_api.rst',
+  'permission_manager_api.rst',
   'plugin_api.rst',
   'port_api.rst',
   'properties_api.rst',
   'proxy_api.rst',
   'session_item_api.rst',
+  'settings_api.rst',
   'si_factory_api.rst',
   'si_interfaces_api.rst',
   'spa_device_api.rst',

docs/rst/library/c_api/metadata_api.rst

@@ -7,6 +7,7 @@ PipeWire Metadata
 
    digraph inheritance {
       rankdir=LR;
+      GBoxed -> WpMetadataItem
       GObject -> WpObject;
       WpObject -> WpProxy;
       WpProxy -> WpGlobalProxy;
@@ -14,6 +15,8 @@ PipeWire Metadata
       WpMetadata-> WpImplMetadata;
    }
 
+.. doxygenstruct:: WpMetadataItem
+
 .. doxygenstruct:: WpMetadata
 
 .. doxygenstruct:: WpImplMetadata

docs/rst/library/c_api/permission_manager_api.rst

@@ -0,0 +1,17 @@
+.. _permission_manager_api:
+
+WpPermissionManager
+===================
+.. graphviz::
+  :align: center
+
+   digraph inheritance {
+      rankdir=LR;
+      GObject -> WpObject;
+      WpObject -> WpPermissionManager;
+   }
+
+.. doxygenstruct:: WpPermissionManager
+
+.. doxygengroup:: wppermissionmanager
+   :content-only:

docs/rst/library/c_api/settings_api.rst

@@ -0,0 +1,23 @@
+.. _settings_api:
+
+Settings
+========
+.. graphviz::
+  :align: center
+
+   digraph inheritance {
+      rankdir=LR;
+      GBoxed -> WpSettingsSpec;
+      GBoxed -> WpSettingsItem;
+      GObject -> WpObject;
+      WpObject -> WpSettings;
+   }
+
+.. doxygenstruct:: WpSettingsSpec
+
+.. doxygenstruct:: WpSettingsItem
+
+.. doxygenstruct:: WpSettings
+
+.. doxygengroup:: wpsettings
+   :content-only:

docs/rst/library/c_api/si_interfaces_api.rst

@@ -7,17 +7,12 @@ Session Items Interfaces
 
    digraph inheritance {
       rankdir=LR;
-      GInterface -> WpSiEndpoint;
       GInterface -> WpSiAdapter;
       GInterface -> WpSiLinkable;
       GInterface -> WpSiLink;
       GInterface -> WpSiAcquisition;
    }
 
-.. doxygenstruct:: WpSiEndpoint
-
-.. doxygenstruct:: _WpSiEndpointInterface
-
 .. doxygenstruct:: WpSiAdapter
 
 .. doxygenstruct:: _WpSiAdapterInterface

docs/rst/library/meson.build

@@ -0,0 +1,6 @@
+# you need to add here any files you add to the toc directory as well
+sphinx_files += files(
+  'c_api.rst',
+)
+
+subdir('c_api')

docs/rst/meson.build

@@ -1,18 +1,12 @@
 # you need to add here any files you add to the toc directory as well
 sphinx_files += files(
   'index.rst',
-  'installing-wireplumber.rst',
-  'running-wireplumber-daemon.rst',
-  'configuration.rst',
-  'daemon-logging.rst',
-  'contributing.rst',
-  'community.rst',
-  'testing.rst',
-  'releases.rst',
-  'c_api.rst',
-  'lua_api.rst',
 )
 
-subdir('c_api')
+subdir('daemon')
-subdir('lua_api')
+subdir('design')
-subdir('configuration')
+subdir('policies')
+subdir('library')
+subdir('scripting')
+subdir('tools')
+subdir('resources')

docs/rst/policies/linking.rst

@@ -0,0 +1,140 @@
+.. _policies_linking:
+
+Linking Policy
+==============
+
+Introduction
+------------
+
+The linking policy in WirePlumber is the logic charged to link a PipeWire stream
+node with a PipeWire device node (most cases), or with another PipeWire stream
+node (monitoring applications).
+
+PipeWire stream nodes always have one of the following media classes:
+
+- Stream/Output/Audio: For audio playback applications (Eg pw-play).
+- Stream/Input/Audio: For audio capture applications (Eg pw-record).
+- Stream/Input/Video: For video capture applications (Eg cheese).
+
+And Pipewire device nodes always have one of the following media classes:
+
+- Audio/Sink: For audio playback devices (Eg Speakers).
+- Audio/Source: For audio capture devices (Eg Microphones).
+- Video/Source: For video capture devices (Eg Cameras).
+
+By default, since in most cases we want to link a stream node with a device
+node, the linking policy logic when linking 2 nodes always follows the following
+assignments:
+
+.. graphviz::
+
+   digraph nodes {
+      rankdir=LR;
+      APS [shape=box label=<audio playback stream<BR/>(Stream/Output/Audio)>];
+      APD [shape=box label=<audio playback device<BR/>(Audio/Sink)>];
+      ACS [shape=box label=<audio capture stream<BR/>(Stream/Input/Audio)>];
+      ACD [shape=box label=<audio capture device<BR/>(Audio/Source)>];
+      VCS [shape=box label=<video capture stream<BR/>(Stream/Input/Video)>];
+      VCD [shape=box label=<video capture device<BR/>(Video/Source)>];
+      APS -> APD;
+      ACD -> ACS;
+      VCD -> VCS;
+   }
+
+
+After that, once the media class of a device node has been selected for a
+particular stream node, and there are more than 1 device node matching such
+media class, WirePlumber will select one based on a set of priorities:
+
+First, it will check if there is a default configured device node for the
+selected device media class. If there is one, and the node exists, it will link
+the stream node with such configured default node. Users can easily configure
+default device nodes for all the 3 different device media classes using tools
+such as ``pavucontrol`` or ``wpctl``. The logic is implemented in the
+``linking/find-default-target.lua`` Lua script.
+
+If there isn't any default node configured, or there is a default node
+configured but the node does not exist, WirePlumber will instead select the
+best device node available. The best device node is the node with highest
+session priority and available routes to the physical device. The logic is
+implemented in the ``linking/find-best-target.lua`` Lua script.
+
+If the best node could not be found because the system does not have any,
+WirePlumber won't link the stream and will send a "no target node available"
+error to the client.
+
+
+Stream node linking properties
+------------------------------
+
+The above default linking logic behavior can be changed by setting specific
+properties on the nodes.
+
+.. note::
+
+   These properties must be set in the **stream** nodes (not the device nodes),
+   otherwise they won't have any effect.
+
+- **target.object**:
+
+  The name of the desired node for this stream to be linked with.
+  If this property is present, WirePlumber will try to find such node, see if it
+  can be linked with the stream, and if so, will use it instead of the default
+  node or best node. The logic is implemented in the ``linking/find-defined-target.lua``
+  Lua script. Since this property is not set by default, WirePlumber will always
+  link stream nodes to the default or best device node found. This property can be
+  easily set using tools such as ``pw-play`` with the ``--target`` flag.
+
+  Note that any node name can be specified there, even if the name is not a device
+  node name, but another stream node name. If this is the case, WirePlumber will
+  link 2 stream nodes together. An example of this case is the monitoring nodes
+  created by ``pavucontrol`` to monitor audio of all audio devices and streams.
+
+- **node.dont-reconnect**:
+
+  Boolean indicating whether the stream node should not be reconnected to a new
+  node if its current linked node (target) was destroyed or not. By default it
+  is set to ``false``, so if the property is not present in the stream node, WirePlumber
+  will always try to reconnect the stream node to a new target instead of sending
+  an error to the client. The logic is implemented in the ``linking/prepare-link.lua``
+  Lua script.
+
+- **node.dont-move**:
+
+  Boolean indicating whether the stream node should not be movable or not at runtime
+  using the metadata. If a stream node is not movable, it means that users cannot
+  relink the stream node to a new target at runtime (using tools such as ``pavucontrol``
+  or ``pw-metadata``) when the stream node is already linked to a different node. By
+  default it is set to ``false``, so if the property is not present, WirePlumber will
+  always move, and therefore link the stream node to a new target if it is defined and
+  updated in the ``target.object`` metadata key.
+
+- **node.dont-fallback**:
+
+  Boolean indicating whether the stream node should not fallback to a different
+  target if its defined target does not exist (the one defined with the ``target.object``
+  property) or not. Therefore, if this property is set to ``true``, WirePlumber sends
+  a "defined target not found" error to the client and will also destroy the stream
+  node. By default it is set to ``false``, so if the property is not present in the
+  stream node, WirePlumber will always fallback to the default or best target if
+  the defined target was not found.
+
+- **node.linger**:
+
+  Boolean indicating whether the stream node should linger or not if its defined
+  target was not found and the ``node.dont-fallback`` is set to true. Therefore, if
+  this property is set to ``true``, the defined target was not found, and the
+  ``node.dont-fallback`` is set to true, WirePlumber won't send a "defined target not found"
+  error to the client, and won't destroy the stream node. This is useful if we want
+  the stream to wait (without processing any data) until its defined target becomes
+  available. By default it is set to ``false``, so if the property is not present in the
+  stream node, WirePlumber will always destroy the node and send an error to the client
+  if its target was not found and ``node.dont-fallback`` was set to true.
+
+
+Linking settings
+----------------
+
+Apart from the above properties, there are also global settings for the linking
+policy. See :ref:`config_settings` for more information, the linking settings
+are prefixed with ``linking.``.

docs/rst/policies/meson.build

@@ -0,0 +1,6 @@
+# you need to add here any files you add to the toc directory as well
+sphinx_files += files(
+   'linking.rst',
+   'smart_filters.rst',
+   'software_dsp.rst',
+)

docs/rst/policies/smart_filters.rst

@@ -0,0 +1,380 @@
+.. _policies_smart_filters:
+
+Smart Filters
+=============
+
+Introduction
+------------
+
+The smart filters policy allows automatically linking filters together, in a
+chain, and tied to a specific target node. This is useful when we want to apply
+a specific processing chain to a specific device, for example. When a stream is
+about to be linked to a target node that is associated with a smart filter
+chain, the policy will automatically link the stream with the first filter in
+the chain, and the last filter in the chain with the target node. This is done
+transparently to the client, allowing users to define a specific processing
+chain for a specific device without having to create setups with virtual sinks
+(or sources) that must be explicitly targeted by the clients.
+
+Filters, in general, are nodes that are placed in the middle of the graph and
+are used to modify the data that passes through them. For example, the
+*echo-cancel*, the *filter-chain*, or the *loopback* nodes are filters.
+Filters can be implemented either as a single node or as a pair of nodes with
+opposite directions. For example, the *null-audio-sink* node can be configured
+to be a single-node filter. On the other hand, the *filter-chain* is a pair of
+nodes with opposite directions, where one node captures the audio from the graph
+and the other node sends the modified audio back to the graph.
+
+For the purpose of the **smart filters** policy, WirePlumber will only consider
+pairs of nodes as filters, not single-node ones. More specifically, a pair of
+nodes will be considered to be a filter by WirePlumber if they have the
+``node.link-group`` property set to a common value. This property is always set
+on pairs of nodes that are internally linked together and is a good indicator
+that the nodes are implementing a filter.
+
+That pair of nodes **must** always consist of a *stream* node and a *main* node.
+The main node acts as a virtual device, where the data is sent or captured
+to/from, and the stream node acts as a regular stream, where the data is sent
+or received to/from the next node in the graph. This is designated by their
+media class, as shown in the table below:
+
+.. list-table::
+   :widths: 30 35 35
+   :header-rows: 1
+   :stub-columns: 1
+
+   * -
+     - Input filter (virtual sink)
+     - Output filter (virtual source)
+   * - Main node
+     - ``Audio/Sink`` (capture)
+     - ``Audio/Source`` (playback)
+   * - Stream node
+     - ``Stream/Output/Audio`` (playback)
+     - ``Stream/Input/Audio`` (capture)
+
+For instance, if a smart filter is used between an application playback stream
+and the default audio sink, the graph would look like this:
+
+.. graphviz::
+
+   digraph nodes {
+      rankdir=LR;
+      A [shape=box label=<application stream node<BR/>(Stream/Output/Audio)>];
+      FM [shape=box label=<filter main node<BR/>(Audio/Sink)>];
+      FS [shape=box label=<filter stream node<BR/>(Stream/Output/Audio)>];
+      D [shape=box label=<default device node<BR/>(Audio/Sink)>];
+      A -> FM;
+      FS -> D;
+      subgraph cluster_filter {
+        style="dotted";
+        FM; FS;
+      }
+   }
+
+The same logic is applied if the smart filter is used between an application
+capture stream and the default audio source, it is just all in the opposite
+direction. This is how the graph would look like in this case:
+
+.. graphviz::
+
+   digraph nodes {
+      rankdir=LR;
+      A [shape=box label=<application stream node<BR/>(Stream/Input/Audio)>];
+      FM [shape=box label=<filter main node<BR/>(Audio/Source)>];
+      FS [shape=box label=<filter stream node<BR/>(Stream/Input/Audio)>];
+      D [shape=box label=<default device node<BR/>(Audio/Source)>];
+      D -> FS;
+      FM -> A;
+      subgraph cluster_filter {
+        style="dotted";
+        FM; FS;
+      }
+   }
+
+When multiple filters have the same direction, they can also be chained together
+so that the output of one filter is sent to the input of the next filter. The
+next section describes how these chains can be described with properties so that
+they are automatically linked by WirePlumber in any way we want.
+
+Filter properties
+-----------------
+
+When a filter node is created, WirePlumber will check for the presence of the
+following optional node properties on the **main** node:
+
+- **filter.smart**
+
+  Boolean indicating whether smart policy will be used for these filter nodes or
+  not. This is disabled by default, therefore filter nodes will be treated as
+  regular nodes, without applying any kind of extra logic. On the other hand, if
+  this property is set to ``true``, automatic (smart) filter policy will be used
+  when linking them. The properties below will then also apply, providing
+  further instructions.
+
+- **filter.smart.name**
+
+  The unique name of the filter. WirePlumber will use the value of the
+  ``node.link-group`` property as the filter name if this property is not set.
+
+- **filter.smart.disabled**
+
+  Boolean indicating whether the filter should be disabled or not. A disabled
+  filter will never be used under any circumstances. If the property is not set,
+  WirePlumber will consider the filter as enabled (i.e. disabled = false).
+
+- **filter.smart.targetable**
+
+  Boolean indicating whether the filter can be directly linked with clients that
+  have it defined as a target (Eg: ``pw-play --target <filter-name>``) or not.
+  This can be useful when a client wants to be linked with a filter that is in
+  the middle of the chain in order to bypass the filters that are placed before
+  the selected one. If the property is not set, WirePlumber will consider the
+  filter not targetable by default, meaning filters will never by bypassed by
+  clients, and clients will always be linked with the first filter in the chain.
+
+- **filter.smart.target**
+
+  A JSON object that defines the matching properties of the filter's target
+  node. A filter target can never be another filter node (WirePlumber will
+  ignore it), it must be a device or virtual sink (or source, depending on the
+  direction of the filter). If this property is not set, WirePlumber will use
+  the default sink/source as the target.
+
+- **filter.smart.before**
+
+  A JSON array containing the names of the filters that are supposed to be
+  chained after this filter (i.e. this filter here should be chained *before*
+  those). If not set, WirePlumber will link the filters by order of creation.
+
+- **filter.smart.after**
+
+  A JSON array containing the names of the filters that are supposed to be
+  chained before this filter (i.e. this filter here should be chained *after*
+  those). If not set, WirePlumber will link the filters by order of creation.
+
+.. note::
+
+   These properties must be set on the filter's **main** node, not the stream
+   node.
+
+As an example, we will describe here how to create 2 loopback filters in
+PipeWire's configuration, with names loopback-1 and loopback-2, that will be
+linked with the default audio device, and use loopback-2 filter as the last
+filter in the chain.
+
+The PipeWire configuration files for the 2 filters should be like this:
+
+- ~/.config/pipewire/pipewire.conf.d/loopback-1.conf:
+
+  .. code-block::
+     :emphasize-lines: 8-11
+
+     context.modules = [
+         {   name = libpipewire-module-loopback
+             args = {
+                 node.name = loopback-1-sink
+                 node.description = "Loopback 1 Sink"
+                 capture.props = {
+                     audio.position = [ FL FR ]
+                     media.class = Audio/Sink
+                     filter.smart = true
+                     filter.smart.name = loopback-1
+                     filter.smart.before = [ loopback-2 ]
+                 }
+                 playback.props = {
+                     audio.position = [ FL FR ]
+                     node.passive = true
+                     stream.dont-remix = true
+                 }
+             }
+         }
+     ]
+
+- ~/.config/pipewire/pipewire.conf.d/loopback-2.conf:
+
+  .. code-block::
+     :emphasize-lines: 8-10
+
+     context.modules = [
+         {   name = libpipewire-module-loopback
+             args = {
+                 node.name = loopback-2-sink
+                 node.description = "Loopback 2 Sink"
+                 capture.props = {
+                     audio.position = [ FL FR ]
+                     media.class = Audio/Sink
+                     filter.smart = true
+                     filter.smart.name = loopback-2
+                 }
+                 playback.props = {
+                     audio.position = [ FL FR ]
+                     node.passive = true
+                     stream.dont-remix = true
+                 }
+             }
+         }
+     ]
+
+After restarting PipeWire to apply the configuration changes, playing a test
+wave audio file with paplay to the default device should result in the following
+graph:
+
+.. graphviz::
+
+   digraph nodes {
+      rankdir=LR;
+      paplay [shape=box label=<paplay node<BR/>(Stream/Output/Audio)>];
+      L1M [shape=box label=<loopback-1 main node<BR/>(Audio/Sink)>];
+      L1S [shape=box label=<loopback-1 stream node<BR/>(Stream/Output/Audio)>];
+      L2M [shape=box label=<loopback-2 main node<BR/>(Audio/Sink)>];
+      L2S [shape=box label=<loopback-2 stream node<BR/>(Stream/Output/Audio)>];
+      device [shape=box label=<default device node<BR/>(Audio/Sink)>];
+      paplay -> L1M;
+      L1S -> L2M;
+      L2S -> device;
+      subgraph cluster_filter1 {
+        style="dotted";
+        L1M; L1S;
+      }
+      subgraph cluster_filter2 {
+        style="dotted";
+        L2M; L2S;
+      }
+   }
+
+Now, if we remove the ``filter.smart.before = [ loopback-2 ]`` property from the
+loopback-1 filter, and add a ``filter.smart.before = [ loopback-1 ]`` property
+in the loopback-2 filter configuration file, WirePlumber should link the
+loopback-1 filter as the last filter in the chain, like this:
+
+.. graphviz::
+
+   digraph nodes {
+      rankdir=LR;
+      paplay [shape=box label=<paplay node<BR/>(Stream/Output/Audio)>];
+      L1M [shape=box label=<loopback-1 main node<BR/>(Audio/Sink)>];
+      L1S [shape=box label=<loopback-1 stream node<BR/>(Stream/Output/Audio)>];
+      L2M [shape=box label=<loopback-2 main node<BR/>(Audio/Sink)>];
+      L2S [shape=box label=<loopback-2 stream node<BR/>(Stream/Output/Audio)>];
+      device [shape=box label=<default device node<BR/>(Audio/Sink)>];
+      paplay -> L2M;
+      L2S -> L1M;
+      L1S -> device;
+      subgraph cluster_filter1 {
+        style="dotted";
+        L1M; L1S;
+      }
+      subgraph cluster_filter2 {
+        style="dotted";
+        L2M; L2S;
+      }
+   }
+
+In addition, the filters can have different targets. For example, we can define
+the filters like this:
+
+- ~/.config/pipewire/pipewire.conf.d/loopback-1.conf:
+
+  .. code-block::
+     :emphasize-lines: 12
+
+     context.modules = [
+         {   name = libpipewire-module-loopback
+             args = {
+                 node.name = loopback-1-sink
+                 node.description = "Loopback 1 Sink"
+                 capture.props = {
+                     audio.position = [ FL FR ]
+                     media.class = Audio/Sink
+                     filter.smart = true
+                     filter.smart.name = loopback-1
+                     filter.smart.after = [ loopback-2 ]
+                     filter.smart.target = { node.name = "not-default-audio-device" }
+                 }
+                 playback.props = {
+                     audio.position = [ FL FR ]
+                     node.passive = true
+                     stream.dont-remix = true
+                 }
+             }
+         }
+     ]
+
+- ~/.config/pipewire/pipewire.conf.d/loopback-2.conf:
+
+  .. code-block::
+
+     context.modules = [
+         {   name = libpipewire-module-loopback
+             args = {
+                 node.name = loopback-2-sink
+                 node.description = "Loopback 2 Sink"
+                 capture.props = {
+                     audio.position = [ FL FR ]
+                     media.class = Audio/Sink
+                     filter.smart = true
+                     filter.smart.name = loopback-2
+                 }
+                 playback.props = {
+                     audio.position = [ FL FR ]
+                     node.passive = true
+                     stream.dont-remix = true
+                 }
+             }
+         }
+     ]
+
+In this case, playing a test wave audio file with paplay to the
+``not-default-audio-device`` device should result in the following graph:
+
+.. graphviz::
+
+   digraph nodes {
+      rankdir=LR;
+      paplay [shape=box label=<paplay node<BR/>(Stream/Output/Audio)>];
+      L1M [shape=box label=<loopback-1 main node<BR/>(Audio/Sink)>];
+      L1S [shape=box label=<loopback-1 stream node<BR/>(Stream/Output/Audio)>];
+      L2M [shape=box label=<loopback-2 main node<BR/>(Audio/Sink)>];
+      L2S [shape=box label=<loopback-2 stream node<BR/>(Stream/Output/Audio)>];
+      device [shape=box label=<not-default-audio-device node<BR/>(Audio/Sink)>];
+      paplay -> L2M;
+      L2S -> L1M;
+      L1S -> device;
+      subgraph cluster_filter1 {
+        style="dotted";
+        L1M; L1S;
+      }
+      subgraph cluster_filter2 {
+        style="dotted";
+        L2M; L2S;
+      }
+   }
+
+In this configuration, the loopback-1 filter will only be linked if the
+application stream is targeting the device node called
+"not-default-audio-device".
+
+Filters metadata
+----------------
+
+Similar to the default metadata, it is also possible to override the filter
+properties using the "filters" metadata object. This allow users to change the
+filters policy at runtime.
+
+For example, assuming the id of the *loopback-1* main node is ``40``, we can
+disable the filter by setting its ``filter.smart.disabled`` metadata key to
+``true`` using the ``pw-metadata`` tool like this:
+
+.. code-block:: bash
+
+   $ pw-metadata -n filters 40 "filter.smart.disabled" true Spa:String:JSON
+
+We can also change the target of a filter at runtime:
+
+.. code-block:: bash
+
+   $ pw-metadata -n filters 40 "filter.smart.target" "{ node.name = new-target-node-name }" Spa:String:JSON
+
+Every time a key in the filters metadata changes, all filters are unlinked and
+re-linked properly, following the new policy.

docs/rst/policies/software_dsp.rst

@@ -0,0 +1,106 @@
+.. _policies_software_dsp:
+
+Automatic Software DSP
+======================
+
+Introduction
+------------
+
+WirePlumber provides a mechanism for transparently handling oddball and embedded
+devices that require software DSP to be done in userspace. Devices such as smartphones,
+TVs, portable speakers, and even some laptops implement an audio subsystem designed
+under the assumption that the hardware sink/source will be "backed" by some sort
+of transparent DSP mechanism. That is, the hardware device itself should not be
+directly accessed, and expects to be sent preprocessed/pre-routed samples. Often,
+especially with Android handsets, these samples are preprocessed or pre-routed
+by the vendor's proprietary userspace.
+
+WirePlumber's automatic software DSP mechanism aims to replicate this functionality in
+a standardised and configurable way. The target device sink/source is hidden from
+other PipeWire clients, and a virtual node is linked to it. This virtual
+node is then presented to clients as *the* node, allowing implementers to specify
+any custom processing or routing in a way that is transparent to users, the kernel,
+and the hardware.
+
+
+Activating
+----------
+
+In addition to the ``node.software-dsp.rules`` section, the ``node.software-dsp``
+:ref:`feature <config_features>` must be enabled in the desired profile(s).
+
+
+Matching a node
+---------------
+
+Matching rules are specified in ``node.software-dsp.rules``. The ``create-filter``
+action specifies behaviour at node insertion. All node properties can be matched
+on, including any type-specific properties such as ``alsa.id``.
+
+
+Configurable properties
+-----------------------
+
+.. describe:: filter-graph
+
+   SPA-JSON object describing the software DSP node. This is passed as-is as
+   an argument to ``libpipewire-module-filter-chain``. See the
+   `filter-chain documentation <https://docs.pipewire.org/page_module_filter_chain.html>`_
+   for details on what options can be set in this object.
+
+   .. note::
+
+      The ``target.object`` property of the virtual node should be configured
+      statically to point to the node matched by the rule.
+
+.. describe:: filter-path
+
+   Absolute path to a file on disk storing a SPA-JSON object as plain text. This will be
+   parsed by WirePlumber into a WpConf object with a single section called
+   ``node.software-dsp.graph``, then passed as-is into ``libpipewire-module-filter-chain``.
+
+   .. note::
+
+    ``filter-graph`` and ``filter-path`` are mutually exclusive, with the former taking
+    precedence if both are present in the matched rule.
+
+.. describe:: hide-parent
+
+   Boolean indicating whether or not the matched node should be hidden from
+   clients. ``node/software-dsp.lua`` will set the permissions for all clients other
+   than WirePlumber itself to ``'-'``. This prevents use of the node by any
+   userspace software except for WirePlumber itself.
+
+
+Examples
+--------
+
+.. code-block::
+   :caption: wireplumber.conf.d/99-my-dsp.conf
+
+   node.software-dsp.rules = [
+     {
+       matches = [
+         { "node.name" = "alsa_output.platform-sound.HiFi__Speaker__sink" }
+         { "alsa.id" = "~WeirdHardware*" } # Wildcard match
+       ]
+
+       actions = {
+         create-filter = {
+           filter-graph = {} # Virtual node goes here
+           filter-path = "/path/to/spa.json"
+           hide-parent = true
+         }
+       }
+     }
+   ]
+
+   wireplumber.profiles = {
+     main = {
+       node.software-dsp = required
+     }
+   }
+
+
+This will match any sinks with the UCM HiFi Speaker profile set or cards
+containing the string "WeirdHardware" at the start of their name.

docs/rst/releases.rst

@@ -1,6 +0,0 @@
-.. _releases:
-
-Releases
-========
-
-.. include:: ../../NEWS.rst

docs/rst/resources/community.rst

@@ -1,4 +1,4 @@
- .. _community:
+.. _resources_community:
 
 Community Resources
 ===================

docs/rst/resources/contributing.rst

@@ -1,4 +1,4 @@
- .. _contributing:
+.. _resources_contributing:
 
 Contributing to WirePlumber
 ===========================
@@ -25,7 +25,7 @@ the indentation settings.
 Tests
 -----
 
-See :ref:`testing`
+See :ref:`resources_testing`
 
 Running in gdb / valgrind / etc...
 ----------------------------------

docs/rst/resources/meson.build

@@ -0,0 +1,7 @@
+# you need to add here any files you add to the toc directory as well
+sphinx_files += files(
+   'contributing.rst',
+   'testing.rst',
+   'community.rst',
+   'releases.rst',
+)

docs/rst/resources/releases.rst

@@ -0,0 +1,6 @@
+.. _resources_releases:
+
+Releases
+========
+
+.. include:: ../../../NEWS.rst

docs/rst/resources/testing.rst

@@ -1,4 +1,4 @@
- .. _testing:
+.. _resources_testing:
 
 Testing
 =======
@@ -62,16 +62,16 @@ Native API clients
 pw-cat
 ^^^^^^
 
-Using the default endpoint:
+Using the default device:
 
 .. code:: console
 
-   $ wpctl status  # verify the default endpoints
+   $ wpctl status  # verify the default device
    $ pw-record test.wav
    $ pw-play test.wav
 
 
-Using a non-default endpoint:
+Using a non-default device:
 
 .. code:: console
 
@@ -84,19 +84,18 @@ or
 
 .. code:: console
 
-   $ wpctl status  # find the capture & playback endpoint ids
+   $ wpctl status  # find the capture & playback node ids
-   $ pw-record --target <endpoint_id> test.wav
+   $ pw-record --target <node_id> test.wav
-   $ pw-play --target <endpoint_id> test.wav
+   $ pw-play --target <node_id> test.wav
 
 .. note::
 
-   node ids and endpoint ids can be used interchangeably when specifying
+   node ids can be used interchangeably when specifying targets in all use cases
-   targets in all use cases
 
 video-play
 ^^^^^^^^^^
 
-Using the default endpoint:
+Using the default device:
 
 .. code:: console
 
@@ -104,13 +103,13 @@ Using the default endpoint:
    $ ./build/src/examples/video-play
 
 
-Using a non-default endpoint:
+Using a non-default device:
 
 .. code:: console
 
-   $ wpctl status  # find the endpoint id from the list
+   $ wpctl status  # find the device node id from the list
    $ cd path/to/pipewire-source-dir
-   $ ./build/src/examples/video-play <endpoint_id>
+   $ ./build/src/examples/video-play <node_id>
 
 .. tip::
 
@@ -123,11 +122,11 @@ PulseAudio compat API clients
 pacat
 ^^^^^
 
-Using the default endpoint:
+Using the default device:
 
 .. code:: console
 
-   $ wpctl status  # verify the default endpoints
+   $ wpctl status  # verify the default device
    $ parecord test.wav
    $ paplay test.wav
 
@@ -158,29 +157,29 @@ aplay / arecord
    ``pipewire-alsa/conf/50-pipewire.conf`` in your ``~/.asoundrc``
    (or anywhere else, system-wide, where libasound can read it)
 
-Using the default endpoint:
+Using the default device:
 
 .. code:: console
 
-   $ wpctl status  # verify the default endpoints
+   $ wpctl status  # verify the default devices
    $ arecord -D pipewire -f S16_LE -r 48000 test.wav
    $ aplay -D pipewire test.wav
 
-Using a non-default endpoint:
+Using a non-default device:
 
 .. code:: console
 
-   $ wpctl status  # find the capture & playback endpoint ids
+   $ wpctl status  # find the capture & playback node ids
-   $ PIPEWIRE_NODE=<endpoint_id> arecord -D pipewire -f S16_LE -r 48000 test.wav
+   $ PIPEWIRE_NODE=<node_id> arecord -D pipewire -f S16_LE -r 48000 test.wav
-   $ PIPEWIRE_NODE=<endpoint_id> aplay -D pipewire test.wav
+   $ PIPEWIRE_NODE=<node_id> aplay -D pipewire test.wav
 
 or
 
 .. code:: console
 
-   $ wpctl status  # find the capture & playback endpoint ids
+   $ wpctl status  # find the capture & playback device node ids
-   $ arecord -D pipewire:NODE=<endpoint_id> -f S16_LE -r 48000 test.wav
+   $ arecord -D pipewire:NODE=<node_id> -f S16_LE -r 48000 test.wav
-   $ aplay -D pipewire:NODE=<endpoint_id> test.wav
+   $ aplay -D pipewire:NODE=<node_id> test.wav
 
 
 JACK compat API clients
@@ -201,15 +200,14 @@ jack_simple_client
 
 .. code:: console
 
-   $ wpctl status  # find the target endpoint id
+   $ wpctl status  # find the target device node id
-   $ wpctl inspect <endpoint_id>  # find the node.id
+   $ wpctl inspect <node_id>  # find the node.id
    $ PIPEWIRE_NODE=<node_id> pw-jack jack_simple_client
 
 .. note::
 
    The JACK layer is not controlled by the session manager, it creates its own
-   links; which is why it is required to specify a node id (endpoint id will not
+   links; which is why it is required to specify a node id.
-   work)
 
 Device Reservation
 ------------------
@@ -263,7 +261,7 @@ with JACK
 3. Wait a few seconds and run ``wpctl status`` to inspect
 
    - The devices taken by JACK should no longer be available
-   - There should be two *JACK System* endpoints (sink & source)
+   - There should be two *JACK System* nodes (sink & source)
 
 4. Run an audio client on PipeWire (ex ``pw-play test.wav``)
 
@@ -277,7 +275,7 @@ with JACK
 6. Wait a few seconds and run ``wpctl status`` to inspect
 
    - The devices that were release by JACK should again be available
-   - There should be no *JACK System* endpoint
+   - There should be no *JACK System* nodes
 
 .. note::
 

docs/rst/scripting/custom_scripts.rst

@@ -0,0 +1,41 @@
+.. _scripting_custom_scripts:
+
+Custom Scripts
+==============
+
+The locations where WirePlumber searches for scripts is explained in
+:ref:`config_locations_scripts`.
+
+Scripts are not loaded automatically; a component muse be defined for them, and
+this component must be included in a profile. See
+:ref:`config_components_and_profiles`.
+
+Full example
+------------
+
+Let's assume that ``~/.local/share/wireplumber/scripts/90-hello-world.lua``
+contains the following script:
+
+.. code-block:: lua
+
+   log = Log.open_topic("hello-world")
+   log.info("Hello world")
+
+In order for it to run, we'll define a component and include it in the default
+profile by including the following configuration (for example, in
+``~/.config/wireplumber/wireplumber.conf.d/90-hello-world.conf``):
+
+.. code-block::
+
+    wireplumber.components = [
+      {
+        name = "90-hello-world.lua", type = script/lua
+        provides = hello-world
+      }
+    ]
+
+    wireplumber.profiles = {
+      main = {
+        hello-world = required
+      }
+    }

docs/rst/scripting/existing_scripts.rst

@@ -0,0 +1,15 @@
+.. _scripting_existing_scripts:
+
+Existing Scripts
+================
+
+This section documents all the existing lua scripts that are shipped with
+WirePlumber, including information on the hooks that they provide and
+information on how to extend the logic with additional custom scripts & hooks.
+
+.. toctree::
+   :maxdepth: 1
+
+   existing_scripts/default_nodes.rst
+   existing_scripts/device.rst
+   existing_scripts/linking.rst

docs/rst/scripting/existing_scripts/default_nodes.rst

@@ -0,0 +1,3 @@
+.. _existing_scripts_default_nodes:
+
+.. include:: ../../../../src/scripts/default-nodes/README.rst

docs/rst/scripting/existing_scripts/device.rst

@@ -0,0 +1,3 @@
+.. _existing_scripts_device:
+
+.. include:: ../../../../src/scripts/device/README.rst

docs/rst/scripting/existing_scripts/linking.rst

@@ -0,0 +1,3 @@
+.. _existing_scripts_linking:
+
+.. include:: ../../../../src/scripts/linking/README.rst

docs/rst/scripting/existing_scripts/meson.build

@@ -0,0 +1,6 @@
+# you need to add here any files you add to the toc directory as well
+sphinx_files += files(
+  'default_nodes.rst',
+  'device.rst',
+  'linking.rst',
+)

docs/rst/scripting/lua_api.rst

@@ -1,4 +1,4 @@
- .. _lua_api:
+.. _scripting_lua_api:
 
 Lua API Documentation
 =====================

docs/rst/scripting/lua_api/lua_core_api.rst

@@ -8,6 +8,17 @@ object is not exposed to the scripts.
 
 For some functionality, though, the following static functions are exposed.
 
+.. function:: Core.get_properties()
+
+   Binds :c:func:`wp_core_get_properties`
+
+   Returns a table with the properties of the core. These are the same
+   properties that appear on WirePlumber's *client* object in the PipeWire
+   global registry.
+
+   :returns: the properties of the core
+   :rtype: table
+
 .. function:: Core.get_info()
 
    Returns a table with information about the core. The table contains
@@ -120,3 +131,14 @@ For some functionality, though, the following static functions are exposed.
       the api plugins to load, if they are not already loaded
    :param callback: the function to call after the plugins have been loaded;
       this function takes references to the plugins as parameters
+
+.. function:: Core.test_feature()
+
+   Binds :c:func:`wp_core_test_feature`
+
+   Tests if the specified feature is provided in the current WirePlumber
+   configuration.
+
+   :param string feature: the name of the feature to test
+   :returns: true if the feature is provided, false otherwise
+   :rtype: boolean