fix(aur): build on Arch setuptools 84 and skip 1.4 context_params (#757)

AUR --no-isolation uses extra python-setuptools 84, so the <82 cap blocked the 0.16.0 rebuild. AUR pywhispercpp backends are still 1.4 and crash if we pass context_params; skip that argument below 1.5.

README.md

@@ -65,6 +65,7 @@ Models are downloaded once. After that, speech-to-text stays on your machine. No
 - **Tray**: stay idle after leftover transcription on toggle stop; the missing-model notification can download the recommended model (#741, #687)
 - **Injection / IBus**: Ctrl+Shift+V paste in terminals; keep the GNOME XWayland layout after scoped inject (#734, #742)
 - **Installer / AppImage**: Python 3.11 floor, verified model downloads, no invented GPUs; AppImage glibc that boots on Debian 12 through current Fedora (#713, #736, #743, #744)
+- **AUR**: build against Arch extra setuptools 84; skip `context_params` on AUR pywhispercpp 1.4 so the app starts
 - **Settings**: even dropdowns and a quieter About page with family platform marks (#754)
 
 See [docs/UPDATE.md](docs/UPDATE.md) and the [full changelog](https://github.com/VocaHQ/vocalinux/releases/tag/v0.16.1).

docs/AUR.md

@@ -31,3 +31,15 @@ git clone ssh://aur@aur.archlinux.org/vocalinux.git
 ```
 
 Sources: `packaging/aur/vocalinux/PKGBUILD`. Community git package: https://aur.archlinux.org/packages/vocalinux-git
+
+## Troubleshooting
+
+**`ERROR Missing dependencies: setuptools<82`**
+
+The AUR package builds with `python -m build --wheel --no-isolation`, so it uses Arch extra `python-setuptools` (currently 84). Vocalinux 0.16.1 drops the `<82` cap in `pyproject.toml`. Rebuild 0.16.1 or later.
+
+**`'_pywhispercpp.whisper_full_params' object has no attribute 'context_params'`**
+
+AUR `python-pywhispercpp-cpu` / `-cuda` / `-rocm` are still 1.4.x. Those wheels accept `context_params` in Python and then crash in the native object. 0.16.1 skips that argument on pywhispercpp older than 1.5 and still loads the model (default GPU, no device picker). PyPI and `install.sh` already use 1.5.0.
+
+There is no AUR `python-pywhispercpp-vulkan` package. GPU Vulkan 1.5 is the `install.sh` / AppImage path, not the AUR python backends.

docs/UPDATE.md

@@ -34,6 +34,7 @@ This guide explains how to update Vocalinux to the latest version.
 - **AppImage**: build against a glibc floor Debian 12 can run; boot tests on six distros (#743, #744 by @sesav)
 - **Installer**: Python 3.11 floor, uv tooling, verified model downloads (epic #701 phases 2.5 and 5) (#713 by @sesav)
 - **Settings / About**: even dropdowns, quieter About, family platform marks (#754)
+- **AUR**: `python -m build --no-isolation` works with Arch extra setuptools 84 (was capped at `<82`, AUR comment by simona). Skip `context_params` on AUR pywhispercpp 1.4.x so startup no longer dies with `whisper_full_params` (AUR comments by avocadoboat, Masalababa; GitHub #625)
 - **Docs**: canonical VocaHQ Discord invite; VocaWin is unsigned beta; screenshots page says v0.16; README family/on-device copy (#749, #733, #735, #737)
 
 See the [full changelog](https://github.com/VocaHQ/vocalinux/releases/tag/v0.16.1).

packaging/aur/vocalinux/PKGBUILD

@@ -32,6 +32,8 @@ depends=(
   'python-xlib'
   'hicolor-icon-theme'
 )
+# --no-isolation uses distro python-setuptools (Arch extra is 84+).
+# pyproject.toml build-system.requires must accept that version.
 makedepends=(
   'python-build'
   'python-installer'

packaging/flatpak/com.vocalinux.Vocalinux.metainfo.xml

@@ -107,7 +107,7 @@
   <releases>
     <release version="0.16.1" date="2026-08-30">
       <description>
-        <p>Stability patch: per-engine model size at startup, save the model only after it loaded, leftover-download list shows every row, one ConfigManager so Settings writes stick, tray stays idle after leftover transcription and can download the recommended model from the missing-model notification, Ctrl+Shift+V paste in terminals, GNOME XWayland layout after scoped IBus inject, Python 3.11 installer floor with verified model downloads, AppImage glibc that boots on Debian 12, and Settings/About layout polish.</p>
+        <p>Stability patch: per-engine model size at startup, save the model only after it loaded, leftover-download list shows every row, one ConfigManager so Settings writes stick, tray stays idle after leftover transcription and can download the recommended model from the missing-model notification, Ctrl+Shift+V paste in terminals, GNOME XWayland layout after scoped IBus inject, Python 3.11 installer floor with verified model downloads, AppImage glibc that boots on Debian 12, AUR build against Arch extra setuptools 84, skip context_params on AUR pywhispercpp 1.4, and Settings/About layout polish.</p>
       </description>
     </release>
     <release version="0.16.0" date="2026-08-23">

pyproject.toml

@@ -1,6 +1,7 @@
 [build-system]
-# >=77 for the SPDX license string below.
-requires = ["setuptools>=77,<82"]
+# >=77 for the SPDX license string below. No upper bound: Arch extra
+# python-setuptools is 84, and the AUR PKGBUILD builds with --no-isolation.
+requires = ["setuptools>=77"]
 build-backend = "setuptools.build_meta"
 
 [project]

src/vocalinux/speech_recognition/recognition_manager.py

@@ -41,6 +41,31 @@ from .command_processor import CommandProcessor
 from .silero_vad import SILERO_CHUNK_SIZE, load_silero_vad
 
 
+def _pywhispercpp_distribution_version() -> Optional[tuple[int, ...]]:
+    """Installed pywhispercpp version, or None if it cannot be read.
+
+    AUR ``python-pywhispercpp-{cpu,cuda,rocm}`` are still 1.4.x. Those wheels
+    advertise ``context_params`` on ``Model.__init__`` then setattr it onto
+    ``whisper_full_params``, which raises AttributeError (AUR comments on
+    vocalinux, GitHub #625).
+    """
+    try:
+        from importlib.metadata import version as pkg_version
+    except ImportError:
+        return None
+    try:
+        raw = pkg_version("pywhispercpp")
+    except Exception:
+        return None
+    parts: list[int] = []
+    for token in raw.split("."):
+        if token.isdigit():
+            parts.append(int(token))
+        else:
+            break
+    return tuple(parts) if parts else None
+
+
 def resolve_whisper_language(language: str) -> Optional[str]:
     """Map a catalog language id to a Whisper / whisper.cpp language code.
 
@@ -1416,15 +1441,25 @@ class SpeechRecognitionManager:
 
         compatible_kwargs = self._filter_whispercpp_model_kwargs(model_kwargs)
         if gpu_device is not None and gpu_device >= 0:
+            dist_version = _pywhispercpp_distribution_version()
+            too_old_for_context_params = dist_version is not None and dist_version < (1, 5, 0)
             try:
                 supports_context_params = (
-                    "context_params" in inspect.signature(Model.__init__).parameters
+                    not too_old_for_context_params
+                    and "context_params" in inspect.signature(Model.__init__).parameters
                 )
             except (TypeError, ValueError) as exc:
                 supports_context_params = False
                 logger.debug(f"Could not inspect pywhispercpp Model signature: {exc}")
 
-            if supports_context_params:
+            if too_old_for_context_params:
+                version_label = ".".join(str(part) for part in (dist_version or ()))
+                logger.warning(
+                    "pywhispercpp %s does not support GPU context_params; "
+                    "upgrade to 1.5+ for device selection. Using the default GPU.",
+                    version_label,
+                )
+            elif supports_context_params:
                 compatible_kwargs["context_params"] = {"gpu_device": gpu_device}
             else:
                 logger.warning(

tests/test_dependency_exports.py

@@ -36,6 +36,14 @@ def _exported_names(path: Path) -> set:
     return names
 
 
+def test_build_system_setuptools_accepts_arch_extra():
+    """AUR PKGBUILD uses python -m build --no-isolation against Arch extra setuptools 84."""
+    requires = _pyproject()["build-system"]["requires"]
+    setuptools_req = next(r for r in requires if r.lower().startswith("setuptools"))
+    assert "<82" not in setuptools_req
+    assert ">=77" in setuptools_req.replace(" ", "")
+
+
 def test_the_dev_export_requests_every_group_it_needs():
     """The export line has to name the lint group, not just the dev extra."""
     line = next(

tests/test_recognition_manager_device_config.py

@@ -1580,6 +1580,34 @@ class TestWhispercppGpuDeviceSelection(unittest.TestCase):
             }
             assert "context_params" not in self.AttributeErrorContextParamsModel.calls[1][1]
 
+    def test_gpu_device_skips_context_params_on_pywhispercpp_1_4(self):
+        """AUR 1.4 wheels advertise context_params then crash; skip them (#625)."""
+        manager = _make_manager(engine="whisper_cpp", whispercpp_gpu_device=1)
+        manager.model_size = "tiny"
+
+        mock_pywhispercpp = MagicMock()
+        self.ContextParamsModel.calls = []
+        mock_pywhispercpp.Model = self.ContextParamsModel
+
+        with patch.dict(
+            "sys.modules",
+            {
+                "pywhispercpp": mock_pywhispercpp,
+                "pywhispercpp.model": mock_pywhispercpp,
+            },
+        ):
+            with patch(
+                "vocalinux.speech_recognition.recognition_manager._pywhispercpp_distribution_version",
+                return_value=(1, 4, 0),
+            ):
+                result = manager._load_model_with_compatible_params(
+                    "/fake/model.bin", {}, gpu_device=1
+                )
+
+        assert isinstance(result, self.ContextParamsModel)
+        assert len(self.ContextParamsModel.calls) == 1
+        assert "context_params" not in self.ContextParamsModel.calls[0][1]
+
     def test_host_cuda_label_runtime_vulkan_selects_discrete(self):
         """Device selection follows bundled Vulkan libs, not a host CUDA label (#604)."""
         manager = _make_manager(engine="whisper_cpp", whispercpp_gpu_device=None)

web/src/app/changelog/page.tsx

@@ -25,6 +25,7 @@ const releases = [
       "Terminals get Ctrl+Shift+V paste; GNOME XWayland layout is restored after scoped IBus inject (PR #734, #742)",
       "Installer requires Python 3.11, verifies model downloads, and no longer invents GPUs (PR #713, #736)",
       "AppImage built against a glibc floor that boots on Debian 12 through current Fedora (PR #743, #744)",
+      "AUR: build against Arch extra setuptools 84, and skip context_params on AUR pywhispercpp 1.4 so the app starts",
       "Settings dropdowns share a width; About is quieter with family platform marks (PR #754)",
     ],
   },