mini-eq 0.7.2__tar.gz → 0.7.4__tar.gz

{mini_eq-0.7.2 → mini_eq-0.7.4}/AGENTS.md

@@ -34,6 +34,8 @@ paths in ignored repo-local skills under `.agents/skills/`.
 - `io.github.bhack.mini-eq.yaml`: local Flatpak manifest.
 - `python3-dependencies.yaml`: generated Flatpak Python dependencies.
 - `tests/`: pytest suite for core behavior and non-visual integration seams.
+- `docs/development.md`: source checkout, PyPI, local Flatpak, and extended
+  development test commands.
 
 ## Development Commands
 
@@ -61,15 +63,8 @@ and no-assert tests are candidates for human review, not automatic removals.
 GTK virtual methods, signal callbacks, property bindings, and other framework
 entry points often look unused to static analysis.
 
-For release/package checks:
-
-```bash
-appstreamcli validate --no-net data/io.github.bhack.mini-eq.metainfo.xml
-desktop-file-validate data/io.github.bhack.mini-eq.desktop
-.venv/bin/python tools/check_gnome_shell_extension.py
-.venv/bin/python -m build
-.venv/bin/python -m twine check dist/*
-```
+For source install, PyPI package validation, local Flatpak builds, and extended
+runtime smoke commands, use `docs/development.md`.
 
 The app depends on system GI/audio packages that Python packaging cannot fully
 install: GTK4, Libadwaita, PipeWire, a WirePlumber-managed session, and the
@@ -84,19 +79,40 @@ 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
 ```
 
-When creating a fresh venv for pip/package validation, build pipewire-gobject in
-a plain wheel-build venv first, then install that wheel into a
-`--system-site-packages` Mini EQ venv. This keeps distro GI bindings visible at
-runtime without making Ubuntu/Debian `g-ir-scanner` import partial `distutils`
-modules from a system-site build venv.
+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
+launches the installed Flatpak app in the same isolated nested display and
+session bus:
+
+```bash
+tools/run_nested_flathub_extension_smoke.sh --replace-running
+```
+
+When creating a fresh venv for pip/package validation, follow
+`docs/development.md` so pipewire-gobject is built in a plain wheel-build venv
+before being installed into a `--system-site-packages` Mini EQ venv.
 
 ## Change Guidelines
 
@@ -106,8 +122,11 @@ modules from a system-site build 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
@@ -166,19 +185,13 @@ Use `docs/social-preview.png` for GitHub and social link previews. This is not a
 Flathub quality-check input, so it may use branded/dark promotional composition,
 but it should be refreshed when the public screenshot changes materially.
 
-Generate the public release screenshot with deterministic demo data:
-
-```bash
-PYTHONPATH=src python3 tools/render_demo_screenshot.py docs/screenshots/mini-eq.png
-PYTHONPATH=src python3 tools/render_demo_screenshot.py docs/screenshots/mini-eq-dark.png --appearance dark
-```
-
 Do not commit screenshots that show personal device names, Bluetooth device
 names, usernames, hostnames, local paths, or private preset names. Prefer
 `tools/render_demo_screenshot.py` over desktop screenshots because it renders
 only the Mini EQ window from deterministic demo data. Keep the public release
 screenshot in the platform-default light appearance unless you are adding
 additional screenshots that intentionally demonstrate other appearance modes.
+Use `docs/screenshots/README.md` for the generation commands.
 
 For visual or adaptive-layout changes, inspect deterministic screenshot
 matrices before considering the work done. Cover the minimum, default, narrow,
@@ -201,31 +214,16 @@ renders on light and dark backgrounds.
 
 ## Release And Security
 
-Use `docs/release.md` as the public release checklist. Before publishing
-release artifacts, verify the rendered README, package URLs, issue tracker,
-license, screenshots, and AppStream metadata.
-During release preparation, verify that version-bearing files agree:
-`pyproject.toml`, `CHANGELOG.md`, and the AppStream release entry and screenshot
-URL. The package `__version__` is derived from release metadata and should not
-be hardcoded separately.
-
-Before publishing artifacts, run the release preflight. Prefer the
-containerized wrapper when the host does not already have the `pipewire-gobject`
-sdist build dependencies installed:
+Use `docs/release.md` as the public release checklist. Use
+`tools/prepare_release.py`, `tools/release_status.py`,
+`tools/run_release_preflight_container.sh`, and
+`tools/release_post_publish.py` for repeatable release checks. Keep
+owner-specific workflow dispatch, deployment approval, and local Flathub merge
+steps in ignored repo-local skills under `.agents/skills/`.
 
-```bash
-tools/run_release_preflight_container.sh
-```
-
-Set `MINI_EQ_FLATHUB_MANIFEST` to a Flathub publishing manifest path when the
-containerized preflight should include the manifest drift check.
 The preflight owns the focused leak scan for `HEAD`, tracked worktree changes,
 and untracked non-ignored text files. Use Gitleaks as an extra check when
-release history or generated artifacts look suspicious:
-
-```bash
-gitleaks git --no-banner --redact .
-```
+release history or generated artifacts look suspicious.
 
 Do not push local scratch branches or local safety tags.
 Do not rewrite public history unless the user explicitly asks for it and accepts

{mini_eq-0.7.2 → mini_eq-0.7.4}/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.7.4 - 2026-05-11
+
+- 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.
+- 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.
+
+## 0.7.3 - 2026-05-11
+
+- Require pipewire-gobject 0.3.6 and use its synchronous PipeWire registry,
+  metadata, node, and device APIs for startup and routing state.
+- Replace Mini EQ's PipeWire startup and routing sleep loops with bounded sync
+  or registry-event waits for route params, virtual sink creation, and stream
+  routing.
+- Avoid a headless startup hang when system-wide EQ fails synchronously before
+  the GLib main loop starts.
+- Hide the GNOME Shell extension's mini analyzer while monitoring is turned
+  off, keeping the panel item available without showing stale meter bars.
+
 ## 0.7.2 - 2026-05-10
 
 - Finish GNOME Shell startup notification after Mini EQ's delayed first-window

{mini_eq-0.7.2 → mini_eq-0.7.4}/MANIFEST.in

@@ -9,6 +9,7 @@ include src/mini_eq/assets/icons/hicolor/symbolic/apps/*.svg
 include data/*.desktop
 include data/*.metainfo.xml
 include docs/flathub.md
+include docs/development.md
 include docs/performance.md
 include docs/release.md
 include docs/social-preview.png

{mini_eq-0.7.2/src/mini_eq.egg-info → mini_eq-0.7.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mini-eq
-Version: 0.7.2
+Version: 0.7.4
 Summary: Compact PipeWire system-wide parametric equalizer for Linux desktops.
 Author: bhack
 License-Expression: GPL-3.0-or-later
@@ -25,7 +25,7 @@ Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: numpy>=1.26
-Requires-Dist: pipewire-gobject<0.4,>=0.3.5
+Requires-Dist: pipewire-gobject<0.4,>=0.3.7
 Provides-Extra: test
 Requires-Dist: pytest>=8; extra == "test"
 Provides-Extra: dev
@@ -87,126 +87,26 @@ headphone measurement data, targets, and optimizer behind the web app.
 
 ## Install
 
-Recommended install paths:
-
-1. Flathub, the preferred desktop install path.
-2. PyPI, after the system desktop/audio dependencies below are installed.
-3. Source checkout, for development or testing unreleased changes.
-
-Install from Flathub:
+The recommended desktop install path is Flathub:
 
 ```bash
 flatpak install flathub io.github.bhack.mini-eq
 flatpak run io.github.bhack.mini-eq
 ```
 
-Mini EQ depends on system desktop/audio packages that Python packaging cannot
-fully install: GTK 4.12+ and Libadwaita 1.7+ GI bindings, PyGObject, PipeWire,
-WirePlumber as the session manager, and the native libraries required by
-pipewire-gobject. Install PyGObject from your distro, such as `python3-gi` or
-`python3-gobject`, rather than adding a PyPI PyGObject dependency to Mini EQ.
-
-If your distro ships older GTK or Libadwaita builds, prefer the Flatpak build.
-
-Package names vary by distro release. If pip builds pipewire-gobject from its
-source distribution, install the GLib, GObject-Introspection, and PipeWire
-development packages first. Virtual environments that need distro GI bindings
-should use `--system-site-packages`; on Ubuntu/Debian, build the
-pipewire-gobject wheel in a plain venv first, then install that wheel into the
-system-site Mini EQ venv.
-
-These are good starting points:
-
-```bash
-# Ubuntu / Debian
-sudo apt install \
-  gir1.2-adw-1 \
-  gir1.2-gtk-4.0 \
-  gobject-introspection \
-  libgirepository1.0-dev \
-  libglib2.0-dev \
-  libpipewire-0.3-dev \
-  meson \
-  ninja-build \
-  pkg-config \
-  pipewire \
-  python3-cairo \
-  python3-pip \
-  python3-gi \
-  python3-setuptools \
-  python3-venv \
-  wireplumber \
-  libebur128-1
-
-# Fedora
-sudo dnf install \
-  gtk4 \
-  libadwaita \
-  gobject-introspection-devel \
-  glib2-devel \
-  meson \
-  ninja-build \
-  pkgconf-pkg-config \
-  pipewire \
-  pipewire-devel \
-  python3-cairo \
-  python3-gobject \
-  python3-pip \
-  wireplumber \
-  libebur128
-
-# Arch Linux
-sudo pacman -S \
-  gtk4 \
-  libadwaita \
-  gobject-introspection \
-  glib2 \
-  meson \
-  ninja \
-  pkgconf \
-  pipewire \
-  python-cairo \
-  python-gobject \
-  python-pip \
-  wireplumber \
-  libebur128
-```
-
-Install the Python package after the system packages are present:
+PyPI and source installs are available for development or for systems with a
+recent GTK/Libadwaita stack plus PyGObject, PipeWire, WirePlumber, and native
+pipewire-gobject build/runtime packages already installed:
 
 ```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.5,<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.5,<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
-```
-
-For a source checkout:
-
-```bash
-python3 -m pip install -e .
+python3 -m pip install mini-eq
 mini-eq --check-deps
 mini-eq
 ```
 
-For a source checkout without installing the package:
-
-```bash
-PYTHONPATH=src python3 -m mini_eq --check-deps
-PYTHONPATH=src python3 -m mini_eq
-```
-
-Install the desktop launcher and icon for the current user:
-
-```bash
-mini-eq --install-desktop
-```
+See [Development](https://github.com/bhack/mini-eq/blob/main/docs/development.md)
+for distro package names, PyPI virtualenv details, source checkout commands,
+tests, and local Flatpak builds.
 
 ## GNOME Shell Extension
 
@@ -216,53 +116,14 @@ routing, EQ, analyzer status, presets, and auto preset links.
 Install it from GNOME Shell Extensions:
 https://extensions.gnome.org/extension/9803/mini-eq-controls/
 
-## Test
-
-```bash
-python3 -m pip install -e '.[dev]'
-python3 -m ruff check .
-python3 -m ruff format --check .
-python3 -m pytest -q
-```
-
-Some integration tests are skipped automatically when optional PipeWire runtime
-tools are not installed.
-
-Check the pipewire-gobject GI compatibility surface:
-
-```bash
-PYTHONPATH=src python3 tools/check_pipewire_gobject.py
-```
-
-## Flatpak
-
-The Flatpak manifest uses the GNOME runtime. It does not ship a full PipeWire
-daemon or session manager; it builds only the local PipeWire filter-chain module
-and SPA builtin filter-graph support that Mini EQ loads inside the app process.
-It also builds pipewire-gobject for Mini EQ's app-facing PipeWire access and
-bundles NumPy and libebur128 for analyzer and live LUFS support.
-
-Install the local build tools:
-
-```bash
-flatpak --user install flathub org.flatpak.Builder org.gnome.Sdk//50
-```
-
-Build and install the local Flatpak:
-
-```bash
-flatpak run org.flatpak.Builder --user --install --force-clean --install-deps-from=flathub \
-  flatpak-build io.github.bhack.mini-eq.yaml
-flatpak run io.github.bhack.mini-eq --check-deps
-flatpak run io.github.bhack.mini-eq
-```
-
 ## Notes
 
 Runtime data is stored under `~/.config/mini-eq`.
 
-`pip install mini-eq` installs only the Python package. The system packages
-above are still required for the app to connect to GTK, PipeWire, and the host
+`pip install mini-eq` installs only the Python package. The recent desktop and
+audio system packages listed in
+[Development](https://github.com/bhack/mini-eq/blob/main/docs/development.md)
+are still required for the app to connect to GTK, PipeWire, and the host
 WirePlumber-managed session.
 
 ## Acknowledgements

mini_eq-0.7.4/README.md

@@ -0,0 +1,91 @@
+# Mini EQ
+
+[![CI](https://github.com/bhack/mini-eq/actions/workflows/ci.yml/badge.svg)](https://github.com/bhack/mini-eq/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/mini-eq.svg?cacheSeconds=3600)](https://pypi.org/project/mini-eq/)
+[![GitHub release](https://img.shields.io/github/v/release/bhack/mini-eq?sort=semver)](https://github.com/bhack/mini-eq/releases)
+[![License](https://img.shields.io/github/license/bhack/mini-eq.svg)](https://github.com/bhack/mini-eq/blob/main/LICENSE)
+
+<a href="https://flathub.org/apps/io.github.bhack.mini-eq"><img width="240" alt="Get it on Flathub" src="https://flathub.org/api/badge?locale=en"/></a>
+
+Mini EQ is a small system-wide parametric equalizer for PipeWire desktops.
+It uses GTK/Libadwaita for the UI, pipewire-gobject for app-facing PipeWire
+routing, metadata, and monitor streams, and PipeWire filter-chain with builtin
+biquad filters for the equalizer. When libebur128 is available, the monitor can
+also show live LUFS loudness.
+
+![Mini EQ screenshot](https://raw.githubusercontent.com/bhack/mini-eq/main/docs/screenshots/mini-eq.png)
+
+## Features
+
+- System-wide parametric EQ for PipeWire desktop playback.
+- GTK/Libadwaita interface with a compact 10-band fader workflow.
+- PipeWire routing and default-output tracking through pipewire-gobject.
+- PipeWire filter-chain DSP using builtin biquad filters.
+- Optional spectrum analyzer and LUFS loudness readout through a PipeWire monitor
+  capture stream.
+- Auto preset links can follow the detected PipeWire port when available and
+  fall back to the selected EQ output when a port is not reported.
+- Optional background mode keeps the EQ active after closing the window, with a
+  separate Start at Login preference and optional active-at-login routing.
+- Optional GNOME Shell extension for quick panel access to routing, EQ,
+  analyzer status, presets, and auto preset links.
+- Equalizer APO preset import from the UI or `--import-apo`, including
+  compatible presets exported by [AutoEq](https://autoeq.app/).
+
+## AutoEq And APO Presets
+
+Mini EQ can import Equalizer APO-style parametric EQ text presets. This makes it
+usable with headphone correction presets exported by
+[AutoEq](https://autoeq.app/): export an Equalizer APO/parametric EQ preset from
+AutoEq, then use **Import Equalizer APO...** in Mini EQ or start the app with
+`mini-eq --import-apo path/to/ParametricEQ.txt`. The
+[AutoEq project](https://github.com/jaakkopasanen/AutoEq) provides the source,
+headphone measurement data, targets, and optimizer behind the web app.
+
+## Install
+
+The recommended desktop install path is Flathub:
+
+```bash
+flatpak install flathub io.github.bhack.mini-eq
+flatpak run io.github.bhack.mini-eq
+```
+
+PyPI and source installs are available for development or for systems with a
+recent GTK/Libadwaita stack plus PyGObject, PipeWire, WirePlumber, and native
+pipewire-gobject build/runtime packages already installed:
+
+```bash
+python3 -m pip install mini-eq
+mini-eq --check-deps
+mini-eq
+```
+
+See [Development](https://github.com/bhack/mini-eq/blob/main/docs/development.md)
+for distro package names, PyPI virtualenv details, source checkout commands,
+tests, and local Flatpak builds.
+
+## GNOME Shell Extension
+
+Mini EQ also has an optional GNOME Shell extension for quick panel access to
+routing, EQ, analyzer status, presets, and auto preset links.
+
+Install it from GNOME Shell Extensions:
+https://extensions.gnome.org/extension/9803/mini-eq-controls/
+
+## Notes
+
+Runtime data is stored under `~/.config/mini-eq`.
+
+`pip install mini-eq` installs only the Python package. The recent desktop and
+audio system packages listed in
+[Development](https://github.com/bhack/mini-eq/blob/main/docs/development.md)
+are still required for the app to connect to GTK, PipeWire, and the host
+WirePlumber-managed session.
+
+## Acknowledgements
+
+Mini EQ is inspired in part by [EasyEffects](https://github.com/wwmm/easyeffects)
+and the broader [PipeWire](https://pipewire.org/) audio tooling ecosystem.
+Mini EQ is a separate project focused on a compact system-wide parametric EQ
+workflow.

{mini_eq-0.7.2 → mini_eq-0.7.4}/data/io.github.bhack.mini-eq.metainfo.xml

@@ -33,11 +33,11 @@
   </description>
   <screenshots>
     <screenshot type="default">
-      <image>https://raw.githubusercontent.com/bhack/mini-eq/v0.7.2/docs/screenshots/mini-eq.png</image>
+      <image>https://raw.githubusercontent.com/bhack/mini-eq/v0.7.4/docs/screenshots/mini-eq.png</image>
       <caption>Adjust sound output with equalizer controls</caption>
     </screenshot>
     <screenshot>
-      <image>https://raw.githubusercontent.com/bhack/mini-eq/v0.7.2/docs/screenshots/mini-eq-dark.png</image>
+      <image>https://raw.githubusercontent.com/bhack/mini-eq/v0.7.4/docs/screenshots/mini-eq-dark.png</image>
       <caption>Use the equalizer with dark style</caption>
     </screenshot>
   </screenshots>
@@ -45,6 +45,25 @@
   <url type="bugtracker">https://github.com/bhack/mini-eq/issues</url>
   <url type="vcs-browser">https://github.com/bhack/mini-eq</url>
   <releases>
+    <release version="0.7.4" date="2026-05-11">
+      <description>
+        <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">
+      <description>
+        <ul>
+          <li>Require pipewire-gobject 0.3.6 and use its synchronous PipeWire registry, metadata, node, and device APIs for startup and routing state.</li>
+          <li>Replace Mini EQ's PipeWire startup and routing sleep loops with bounded sync or registry-event waits for route params, virtual sink creation, and stream routing.</li>
+          <li>Avoid a headless startup hang when system-wide EQ fails synchronously before the GLib main loop starts.</li>
+          <li>Hide the GNOME Shell extension's mini analyzer while monitoring is turned off.</li>
+        </ul>
+      </description>
+    </release>
     <release version="0.7.2" date="2026-05-10">
       <description>
         <ul>