Require pipewire-gobject 0.3.7 for active route checks

Author: bhack

.github/workflows/ci.yml

@@ -11,6 +11,10 @@ on:
         description: Run the experimental Flatpak PipeWire routing smoke test
         type: boolean
         default: false
+      headless_pipewire_runtime_smoke:
+        description: Run the headless PipeWire/WirePlumber controller smoke test
+        type: boolean
+        default: false
       live_ui_runtime_smoke:
         description: Run the live GTK/AT-SPI/PipeWire smoke test
         type: boolean
@@ -49,8 +53,8 @@ concurrency:
   cancel-in-progress: true
 
 env:
-  PWG_VERSION: "0.3.6"
-  PWG_REQUIREMENT: "pipewire-gobject>=0.3.6,<0.4"
+  PWG_VERSION: "0.3.7"
+  PWG_REQUIREMENT: "pipewire-gobject>=0.3.7,<0.4"
 
 jobs:
   changes:
@@ -135,7 +139,7 @@ jobs:
               README.md|pyproject.toml|MANIFEST.in|src/*|tests/*|data/*|extensions/*)
                 test=true
                 ;;
-              tools/check_gnome_shell_extension.py|tools/pack_gnome_shell_extension.sh|tools/prepare_release.py|tools/release_gates.py|tools/release_preflight.py|tools/release_runtime_gate.py|tools/release_status.py|tools/run_live_ui_runtime_smoke_ci.sh)
+              tools/check_gnome_shell_extension.py|tools/check_headless_pipewire_runtime.py|tools/pack_gnome_shell_extension.sh|tools/prepare_release.py|tools/release_gates.py|tools/release_preflight.py|tools/release_runtime_gate.py|tools/release_status.py|tools/run_headless_pipewire_runtime_smoke_ci.sh|tools/run_live_ui_runtime_smoke_ci.sh)
                 test=true
                 ;;
             esac
@@ -153,7 +157,7 @@ jobs:
             esac
 
             case "$path" in
-              .github/workflows/*.yml|tools/check_pipewire_gobject.py|tools/release_gates.py|tools/release_runtime_gate.py|src/mini_eq/pipewire_backend.py|src/mini_eq/analyzer.py)
+              .github/workflows/*.yml|tools/check_headless_pipewire_runtime.py|tools/check_pipewire_gobject.py|tools/release_gates.py|tools/release_runtime_gate.py|tools/run_headless_pipewire_runtime_smoke_ci.sh|src/mini_eq/pipewire_backend.py|src/mini_eq/analyzer.py)
                 pwg=true
                 ;;
             esac
@@ -484,6 +488,49 @@ jobs:
           MINI_EQ_FLATPAK_EXPECT_VERSION: ${{ inputs.flatpak_runtime_expected_version }}
         run: tools/run_flatpak_runtime_smoke_ci.sh
 
+  headless-pipewire-runtime-smoke:
+    needs: changes
+    if: ${{ github.event_name == 'workflow_dispatch' && inputs.headless_pipewire_runtime_smoke }}
+    runs-on: ubuntu-24.04
+    timeout-minutes: 45
+
+    steps:
+      - name: Require change detection
+        if: ${{ needs.changes.result != 'success' }}
+        run: exit 1
+
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Install headless PipeWire runtime dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            build-essential \
+            dbus-user-session \
+            gobject-introspection \
+            libebur128-1 \
+            libgirepository1.0-dev \
+            libglib2.0-dev \
+            libpipewire-0.3-dev \
+            libspa-0.2-modules \
+            meson \
+            ninja-build \
+            pipewire \
+            pipewire-bin \
+            pkg-config \
+            python3 \
+            python3-dev \
+            python3-gi \
+            python3-numpy \
+            python3-pip \
+            python3-setuptools \
+            python3-venv \
+            wireplumber
+
+      - name: Build source environment and run headless PipeWire smoke
+        run: tools/run_headless_pipewire_runtime_smoke_ci.sh
+
   live-ui-runtime-smoke:
     needs: changes
     if: ${{ github.event_name == 'workflow_dispatch' && inputs.live_ui_runtime_smoke }}

AGENTS.md

@@ -79,18 +79,27 @@ nested headless GNOME Shell session:
 MINI_EQ_RUN_ATSPI=1 .venv/bin/python -m pytest tests/test_mini_eq_atspi_widgets.py -q
 ```
 
-For a deeper live runtime smoke, run the real GTK app in a private
-PipeWire/WirePlumber graph with synthetic playback and AT-SPI UI driving:
+For PipeWire graph behavior without nested GNOME/AT-SPI, run the headless
+controller smoke. It owns synthetic stream routing, default-output moves,
+monitor toggles, and active processing-link assertions:
+
+```bash
+.venv/bin/python tools/check_headless_pipewire_runtime.py --timeout 35 --cycles 2
+```
+
+For a deeper live UI smoke, run the real GTK app in a private PipeWire/WirePlumber
+graph with synthetic playback and AT-SPI UI driving:
 
 ```bash
 .venv/bin/python tools/check_live_ui_runtime.py --timeout 35 --cycles 1
 MINI_EQ_RUN_LIVE_UI=1 .venv/bin/python -m pytest tests/test_mini_eq_live_ui_runtime.py -q
 ```
 
-The live UI smoke is opt-in locally because it needs nested GNOME Shell,
-AT-SPI, PipeWire, and WirePlumber. Treat it as a maintainer confidence check on
-a supported recent GNOME/GTK stack; the blocking public release runtime gate is
-the Flatpak routing smoke.
+The headless PipeWire smoke is the stable native controller/graph gate and is
+part of release preflight. The live UI smoke is opt-in locally because it needs
+nested GNOME Shell, AT-SPI, PipeWire, and WirePlumber. Treat it as a maintainer
+confidence check on a supported recent GNOME/GTK stack; the blocking public
+release runtime gates are release preflight and the Flatpak routing smoke.
 
 For manual GNOME Shell extension testing against an installed Flatpak build,
 run the nested devkit smoke. It loads the extension from this checkout and
@@ -113,8 +122,11 @@ before being installed into a `--system-site-packages` Mini EQ venv.
 - Keep the pipewire-gobject API boundary small, general-purpose, and
   app-facing. Mini EQ may validate new pipewire-gobject API in a real GTK app,
   but do not add Mini EQ-shaped concepts, preset/filter-chain policy, or
-  hardware-selection policy to pipewire-gobject. WirePlumber stays the host
-  session manager, not a bundled GI dependency.
+  hardware-selection policy to pipewire-gobject. When changing public
+  pipewire-gobject API, follow the sibling checkout's `AGENTS.md` bindable API
+  gate: plain C/C99 public scalar types, no public GLib collections, explicit
+  ownership/nullability annotations, and generated GIR/test updates. WirePlumber
+  stays the host session manager, not a bundled GI dependency.
 - Treat the Mini EQ D-Bus control interface as a project-internal app/Shell
   extension contract with version-skew tolerance. Keep `api_version = 1`
   additive only: add state fields, methods, and capabilities when needed, but do

CHANGELOG.md

@@ -5,9 +5,9 @@
 - Run filter-chain readiness callbacks from the GLib main context when PipeWire
   reports the virtual sink asynchronously, avoiding thread-loop sync failures
   during system-wide EQ startup.
-- Re-apply the active filter controls when PipeWire creates a link to the Mini
-  EQ virtual sink, so a newly routed stream starts processing without requiring
-  an A/B toggle.
+- Require pipewire-gobject 0.3.7 and re-apply the active filter controls when
+  PipeWire creates or activates links on the Mini EQ processing path, so audio
+  resumed after silence starts processing without requiring an A/B toggle.
 - Refresh port-aware output preset scope when PipeWire reports route parameter
   serial changes on the active output device.
 

data/io.github.bhack.mini-eq.metainfo.xml

@@ -47,7 +47,11 @@
   <releases>
     <release version="0.7.4" date="2026-05-11">
       <description>
-        <p>Run filter-chain readiness callbacks from the GLib main context when PipeWire reports the virtual sink asynchronously, avoiding thread-loop sync failures during system-wide EQ startup.</p>
+        <ul>
+          <li>Run filter-chain readiness callbacks from the GLib main context when PipeWire reports the virtual sink asynchronously.</li>
+          <li>Re-apply active filter controls when PipeWire creates or activates links on the Mini EQ processing path.</li>
+          <li>Refresh port-aware output preset scope when PipeWire reports route parameter serial changes on the active output device.</li>
+        </ul>
       </description>
     </release>
     <release version="0.7.3" date="2026-05-11">

docker/preflight.Dockerfile

@@ -22,6 +22,7 @@ RUN apt-get update \
       meson \
       ninja-build \
       pipewire \
+      pipewire-bin \
       pkg-config \
       python3 \
       python3-cairo \

docs/development.md

@@ -87,11 +87,11 @@ Install the Python package after the system packages are present:
 ```bash
 python3 -m venv /tmp/mini-eq-pwg-build
 /tmp/mini-eq-pwg-build/bin/python -m pip install --upgrade pip
-/tmp/mini-eq-pwg-build/bin/python -m pip wheel 'pipewire-gobject>=0.3.6,<0.4' -w /tmp/mini-eq-wheelhouse
+/tmp/mini-eq-pwg-build/bin/python -m pip wheel 'pipewire-gobject>=0.3.7,<0.4' -w /tmp/mini-eq-wheelhouse
 
 python3 -m venv --system-site-packages ~/.local/share/mini-eq/venv
 ~/.local/share/mini-eq/venv/bin/python -m pip install --upgrade pip
-~/.local/share/mini-eq/venv/bin/python -m pip install --no-index --find-links /tmp/mini-eq-wheelhouse 'pipewire-gobject>=0.3.6,<0.4'
+~/.local/share/mini-eq/venv/bin/python -m pip install --no-index --find-links /tmp/mini-eq-wheelhouse 'pipewire-gobject>=0.3.7,<0.4'
 ~/.local/share/mini-eq/venv/bin/python -m pip install mini-eq
 ~/.local/share/mini-eq/venv/bin/mini-eq --check-deps
 ~/.local/share/mini-eq/venv/bin/mini-eq
@@ -144,7 +144,16 @@ For real GTK widget behavior, run the opt-in AT-SPI smoke test:
 MINI_EQ_RUN_ATSPI=1 python3 -m pytest tests/test_mini_eq_atspi_widgets.py -q
 ```
 
-For a deeper live runtime smoke, run the real GTK app in a private
+For PipeWire graph behavior without GTK or AT-SPI, run the headless controller
+smoke. It starts a private PipeWire/WirePlumber graph, synthetic playback,
+Mini EQ's routing controller, and checks route toggles, default-output moves,
+monitor toggles, and active processing links:
+
+```bash
+python3 tools/check_headless_pipewire_runtime.py --timeout 35 --cycles 2
+```
+
+For a deeper live UI smoke, run the real GTK app in a private
 PipeWire/WirePlumber graph with synthetic playback and AT-SPI UI driving:
 
 ```bash
@@ -153,10 +162,12 @@ MINI_EQ_RUN_LIVE_UI=1 python3 -m pytest tests/test_mini_eq_live_ui_runtime.py -q
 ```
 
 These integration smokes are intentionally separate from the default pytest
-suite because they require nested GNOME Shell, AT-SPI services, PipeWire, and
-WirePlumber. Use the live UI smoke as a maintainer confidence check on a
-supported recent GNOME/GTK stack; the public release workflow does not treat
-the hosted Ubuntu native GTK stack as the blocking UI runtime.
+suite because they require PipeWire and WirePlumber; the live UI smoke also
+requires nested GNOME Shell and AT-SPI services. Use the headless smoke for
+stable controller/graph coverage and the live UI smoke as a maintainer
+confidence check on a supported recent GNOME/GTK stack; the public release
+workflow does not treat the hosted Ubuntu native GTK stack as the blocking UI
+runtime.
 
 ## Local Flatpak Build
 

docs/release.md

@@ -84,7 +84,9 @@ graph behaves correctly. Treat their claims narrowly:
 - Unit and seam tests verify deterministic model, routing, metadata, and UI
   state transitions.
 - The release preflight verifies source cleanliness, package build/install,
-  dependency importability, metadata, and the full default pytest suite.
+  dependency importability, metadata, the full default pytest suite, and a
+  headless PipeWire/WirePlumber controller smoke with synthetic stream routing,
+  default-output moves, monitor toggles, and active processing-link assertions.
 - The Flatpak routing smoke verifies the installed Flatpak can route and
   restore a synthetic stream in an isolated PipeWire/WirePlumber graph.
 - The live UI smoke verifies the real GTK app can be driven through AT-SPI
@@ -169,7 +171,8 @@ preflight and post-publish checks.
 
 Prefer the containerized preflight. It keeps host machines clean while testing a
 fresh venv, `pipewire-gobject` sdist build dependencies, package metadata, a
-private PipeWire/WirePlumber session, the leak scan, and release smoke checks:
+private PipeWire/WirePlumber session, the headless controller/graph smoke, the
+leak scan, and release smoke checks:
 
 ```bash
 tools/run_release_preflight_container.sh
@@ -189,8 +192,8 @@ Flathub manifest still has old bundled dependencies or permissions.
 
 The preflight prints change-aware notices for GNOME Shell extension upload,
 Flatpak runtime smoke, and background portal smoke. Treat those notices as
-release gates when they apply; the generic preflight deliberately does not
-mutate the host audio graph.
+release gates when they apply; the generic preflight deliberately uses a private
+PipeWire graph instead of mutating the host audio graph.
 
 ## Runtime Checks
 
@@ -201,6 +204,15 @@ access, Flatpak permissions, runtime dependencies, or shutdown behavior changed:
 python3 tools/check_flatpak_runtime.py --app-ref <installed-app-ref>
 ```
 
+Run the native headless PipeWire smoke when working on routing, analyzer
+capture, monitor toggles, output following, or `pipewire-gobject` integration.
+The containerized release preflight runs this automatically, but it is useful as
+a focused local loop:
+
+```bash
+python3 tools/check_headless_pipewire_runtime.py --timeout 35 --cycles 2
+```
+
 For background portal changes, run one clean-permission Flatpak smoke in a real
 GNOME session. Enable **Keep Running in Background**, approve the portal
 prompt, enable **Start at Login**, close the window, and confirm the app stays

io.github.bhack.mini-eq.yaml

@@ -124,8 +124,8 @@ modules:
     sources:
       - type: git
         url: https://github.com/bhack/pipewire-gobject.git
-        tag: 0.3.6
-        commit: 7e20b29865c0a869695bc730bacb68e2f0853077
+        tag: 0.3.7
+        commit: 1cd6ccc0f5e0d1d62ab8fd42dc9f200a112554f6
 
   - python3-dependencies.yaml
 

pyproject.toml

@@ -40,7 +40,7 @@ classifiers = [
     "Topic :: Multimedia :: Sound/Audio :: Analysis",
     "Topic :: Multimedia :: Sound/Audio :: Mixers",
 ]
-dependencies = ["numpy>=1.26", "pipewire-gobject>=0.3.6,<0.4"]
+dependencies = ["numpy>=1.26", "pipewire-gobject>=0.3.7,<0.4"]
 
 [project.urls]
 Homepage = "https://github.com/bhack/mini-eq"

src/mini_eq/deps.py

@@ -12,8 +12,8 @@
 
 Status = Literal["ok", "missing", "warning"]
 
-PWG_REQUIRED_VERSION = "0.3.6"
-PWG_REQUIRED_VERSION_PARTS = (0, 3, 6)
+PWG_REQUIRED_VERSION = "0.3.7"
+PWG_REQUIRED_VERSION_PARTS = (0, 3, 7)
 PWG_REQUIRED_SYMBOLS = (
     "Core.set_pipewire_property",
     "Core.sync",
@@ -23,6 +23,9 @@
     "Device.new",
     "Device.subscribe_params",
     "Device.sync",
+    "Link.get_state",
+    "Link.new",
+    "Link.sync",
     "Metadata.sync",
     "Node.sync",
     "Param.new_props_controls",