* fix(flatpak): bundle onnxruntime for Silero VAD
Bundle the [vad] extra in the Flatpak and select the matching CPython wheel for each architecture.
Fixes#969
* docs(flatpak): keep the runtime.txt history in the sync script docstring
---------
Co-authored-by: Jatin K Malik <jatinkrmalik@gmail.com>
* fix(packaging): build pywhispercpp at the portable x86-64 baseline
Every packaged channel shipped a libggml-cpu compiled for AVX2+FMA:
the manylinux PyPI wheel itself carries -mavx2 -mfma -mbmi2 code, so
any package that bundles it dies with SIGILL when whisper.cpp loads a
model on a pre-Haswell CPU (the reporter's i5-3337U). GGML_NATIVE=OFF
alone is not the portable baseline either; while the native default
is on, ggml turns every GGML_* SIMD option on, so each is pinned off.
- Snap: force the sdist (PIP_NO_BINARY) with the flag floor via
CMAKE_ARGS in the part's build-environment.
- Flatpak: extend the module's CMAKE_ARGS with the same floor.
- Native .deb/.rpm: the build still vendors the wheels, then rebuilds
libggml-cpu alone from the same hash-pinned sdist and swaps it into
the vendored copies, asserting no AVX/FMA survives; the container
image gains cmake, g++, make and binutils.
- AppImage: extract the pinned-sdist reinstall into a shared helper
and route every CPU-only fallback of the Vulkan path through a new
baseline rebuild at the same floor; the Vulkan compile keeps its
own flags via the same helper. Keeping the wheel on those paths was
the bug's exact binary.
Fixes#957
* style(tests): apply black/isort to the new packaging guards
* fix(native): keep the wheel's libggml providers, alias its base/gomp sonames
Swapping the whole libggml set for the baseline build broke the import
smoke: the wheel's auditwheel-mangled core lib doubles as the
extension's __cxa_call_terminate provider, and its NEEDED entries are
the mangled names. Swap only libggml-cpu, and satisfy the baseline
library's own unmangled NEEDEDs (libggml-base.so.0, libgomp.so.1) with
aliases of the vendored copies, which carry no generated SIMD and are
the same upstream version. Fail closed when the vendored set has
restructured instead of silently shipping the AVX2 wheel.
* fix(packaging): fail builds that lose the speech engine, unblock the ISA assert
Greptile findings on the baseline work:
- A failed baseline rebuild in the AppImage returned success after
remove_appdir_pywhispercpp, so the bundle would ship with no speech
engine at all while logging that the wheel was kept. Propagate the
failure through every CPU-only fallback so the build stops instead.
- The native libggml-cpu assertion used grep -q under pipefail, where
grep's early exit SIGPIPEs objdump and the pipeline reports a miss,
letting an AVX2 library through. Read the full disassembly instead.
* fix(installer): build pywhispercpp from sdist on the CPU path
install_cpu_pywhispercpp let pip pick the manylinux wheel, whose
libggml-cpu is compiled for AVX2+FMA and SIGILLs on pre-Haswell CPUs
(#957). Pass --no-binary pywhispercpp like the Vulkan/CUDA paths so the
sdist compiles against this machine's own instruction set.
* fix(installer): install C++ toolchain on distros that ship without one
Forcing the pywhispercpp sdist on the CPU path needs a compiler, and the
fedora, mageia, alpine, void and solus package maps did not request one.
Add gcc-c++/make (rpm), build-base (alpine), base-devel (void) and
gcc/g++/make (solus) so source installs compile on minimal systems.
---------
Co-authored-by: Jatin K Malik <jatinkrmalik@gmail.com>
* fix(installer): keep piped script on stdin and prompt via /dev/tty
`curl | bash` left bash reading the installer itself from stdin, and the
detection block's `exec < /dev/tty` (from #315) closed that pipe about 300
lines into a 3000-line script. curl died with error 23 writing to the
closed pipe, and bash read the rest of the installer from the terminal as
commands instead of finishing the script.
stdin now stays on the pipe and a reachable terminal is recorded in
TERMINAL_PROMPTS. Every interactive prompt goes through read_prompt, which
reads /dev/tty explicitly only for that read, so user input still works in
a terminal while the script body keeps flowing through the pipe. The
interactive-mode gate now checks TERMINAL_PROMPTS rather than `-t 0`,
which also lets `--interactive` work under a pipe.
Regression coverage: the remote-install gate's second run now pipes the
bootstrap in under a `script` pty (the literal `cat | bash` shape a
curl user takes), and new tests run install.sh in a pty with the script on
a pipe to assert the mode and engine prompts still answer on the terminal.
Fixes#933
* fix(installer): drain the piped bootstrap before the handoff exec
A curl|bash bootstrap leaves its unread tail on stdin; the tagged installer
reads its commands from a file, so nothing drained the pipe and a still-
streaming curl reported error 23 when the installer exited. Drain stdin to
EOF before exec (Greptile P2 on #935).
Gate: drip-feed the piped run so the producer is mid-write at the handoff
like real curl, and run it under pipefail so a producer killed early fails
the run. Tests: pass --tag so a slow release lookup cannot eat the window,
wait for the engine prompt before Ctrl+C, and quote the installer path.
* test(installer): propagate a killed producer's status in the piped gate
A cat dying mid-drip (SIGPIPE when the consumer abandons the pipe) was
swallowed by the loop and the final rm, so drip returned success and
pipefail could not see the download failure the arm exists to catch.
---------
Co-authored-by: Jatin K Malik <jatinkrmalik@gmail.com>
The pinned pycairo builds from source everywhere, and the sdist needs
cairo.pc. Fedora, mageia and the debian/ubuntu maps list the headers
explicitly; suse relied on gobject-introspection-devel pulling
pkgconfig(cairo) transitively, which the current Tumbleweed image no
longer does, so the opensuse/tumbleweed install gate now fails at
"Dependency cairo not found" during pycairo metadata generation.
void, solus and alpine have the same latent gap; each gets the same
package spelled in its own convention.
Co-authored-by: Jatin K Malik <jatinkrmalik@gmail.com>
* feat(settings): add proxy support for model downloads and update checks
Add a Proxy page to Settings (above About) with Off / System / Manual
modes. Manual mode supports SOCKS5 and HTTPS (HTTP CONNECT) proxies
with optional username/password auth; the password is stored in
config.json in plaintext like the other settings. System mode honors
the *_proxy environment variables and falls back to the GNOME
org.gnome.system.proxy manual configuration.
The resolved proxy is applied to every in-app outbound path that
fetches models or checks updates: the shared requests download path in
recognition_manager (_stream_model_download, used by the whisper.cpp,
whisper, Vosk, Parakeet and faster-whisper downloaders) and the
release checks in update_checker. A small Test Connection button on
the Proxy page verifies reachability through the configured proxy.
SOCKS5 needs PySocks, added as a runtime dependency; uv.lock, the
requirements/*.txt exports and the Flatpak dependency manifest are
regenerated by just lock (with a fix in sync_flatpak_deps.py for
packages like PySocks that publish more than one universal wheel).
Fixes#655
* fix(proxy): bracket IPv6 hosts, escape test errors, declare pysocks for AUR
---------
Co-authored-by: Jatin K Malik <jatinkrmalik@gmail.com>
* ci(install): gate the remote install path end to end
A curl|bash user takes a different path than the local install gate
covers: bootstrap outside a checkout, tag selection, clone/fetch of the
selected tag, then handoff to the tagged installer with the original
arguments. Add scripts/install-remote-test.sh, which publishes HEAD as a
tag in a local mirror, runs install.sh against it twice (fresh clone,
then fetch+reset of the existing clone), and fails closed when the
clone's HEAD is not the selected tag commit. install.sh gains a
VOCALINUX_REPO_URL override so the mirror can stand in for the public
remote. Wire a single-distro job into the distro matrix and a just
remote-install-gate recipe.
Refs #701
* ci(install): publish the gate tag as an orphan from HEAD's tree
CI checks out with fetch-depth 1, and git refuses to push or fetch a
shallow boundary commit into a ref. Build the tag on an orphan commit
created from HEAD's tree instead, and make tree equality the fail-closed
check that installer, modules and exports are this commit's files.
* test(install): force the re-run arm to prove fetch and reset
Review feedback on the remote-install gate: the second run reused a clone
already on the tag, so a broken fetch or reset would still pass. Move the
clone onto a descendant commit and delete its local tag ref before the
re-run, so only a real fetch + reset restores them. Also list the new
recipe in AGENTS.md's command guide.
---------
Co-authored-by: Jatin K Malik <jatinkrmalik@gmail.com>
* feat(transcribe): add TinyDiarize file transcription surface
Catalog small.en-tdrz (hosted at akashmjn/tinydiarize-whisper.cpp,
pinned commit) while keeping it out of every dictation-model selection
path: its [SPEAKER_TURN] markup would type noise into the focused
window. The checksum generator resolves side-repo models at their own
pinned revision, parakeet-style.
Add speech_recognition.diarization (strict-WAV fast path with ffmpeg
fallback, tdrz transcription, speaker-turn parsing, timestamped
formatting) and surface it through a tray Transcribe Audio File flow
with on-demand model download plus a headless --transcribe-file CLI.
TranscriptDialog offers copy and save of the diarized transcript.
Closes#756
* docs(user-guide): document --transcribe-file
* fix(transcribe): pass tdrz_enable as a pywhispercpp kwarg
pywhispercpp's Model takes decode params as keyword arguments; a
params= dict crashes on the C-level whisper_full_params object. Also
let --transcribe-file report unexpected failures cleanly instead of
dumping a traceback.
* fix(tray): dismiss the tdrz download dialog on response
* test(diarization): pin real wave/numpy/tempfile around sibling mocks
Several test modules replace sys.modules entries with MagicMocks at
import time and never restore them, so diarization's wave/numpy/
tempfile bindings resolved to mocks when this file ran after them in
CI. An autouse fixture reimports the real stdlib modules per test, the
same remedy test_audio_feedback already applies for wave.
* fix(transcribe): verify tdrz model, preload libs, gate formats on ffmpeg
- Hash the on-disk TinyDiarize model against the pinned digest before
native code maps it, matching the dictation load path
- Extract the bundled-lib preloader to utils/pywhispercpp_loader.py and
preload before the lazy pywhispercpp import so the headless
--transcribe-file path works on source-built installs without RPATH
- Offer only WAV in the file picker when ffmpeg is absent; name the
dependency in the filter label
- Type the new tray/diarization callbacks; document --transcribe-file
and the new modules in AGENTS.md
* style(audio): finish type annotations on capture helpers and download path
_setup_alsa_error_handler now declares Optional[Any] and its ctypes
callback gets concrete parameter types; the remaining capture helpers
take audio: Any (PyAudio has no importable type) and test_audio_input's
device_index becomes Optional[int], which also clears the preexisting
implicit-Optional error. _download_whispercpp_model gains -> None and
its HF url is narrowed to str so the concatenation and download call
stop adding new mypy findings.
* style(tests): wrap long monkeypatch line in preload test
* refactor(main): narrow transcribe-file errors and add file context
* style(ui): annotate TranscriptDialog constructor
* fix(diarize): log worker tracebacks, isort test helpers, document --transcribe-file
---------
Co-authored-by: Jatin K Malik <jatinkrmalik@gmail.com>
* feat(parakeet): add optional verified Orukeet model
* fix(parakeet): recover from invalid release manifests
* chore: mark Orukeet tip verified
Empty signed tip so the ready-bar Verified gate clears on contributor unsigned history.
---------
Co-authored-by: Jatin K Malik <jatinkrmalik@gmail.com>
* fix(deps): export and cap every engine extra
* fix(deps): docstring main and tighten export pairing tests
Give check_exports.main the required public docstring, annotate the
dependency export test helpers, and require --extra to sit with its -o
on the same just lock line (whisper pip-compile stays special-cased).
---------
Co-authored-by: Jatin K Malik <jatinkrmalik@gmail.com>
* fix(packaging): derive the Flatpak and AUR dependency sets from the lock
* test(packaging): add return annotations on new packaging tests
Greptile asked for -> None on the new tests, matching AGENTS.md.
* test(packaging): type parametrized Flatpak source arguments
Greptile asked for type hints on the source parameter, matching AGENTS.md.
---------
Co-authored-by: jatinkrmalik <jatinkrmalik@gmail.com>
* feat(speech_recognition): add EngineType enum and Engine Protocol
Introduce a typed EngineType enum and an Engine Protocol in common_types.py,
plus an engines/ registry so new speech recognition backends can be plugged in
without scattering string comparisons across the manager.
* feat(speech_recognition): add faster-whisper engine backend
Add a faster-whisper engine implementation using CTranslate2/INT8 for fast
CPU inference. Includes model metadata utility, wiring through the recognition
manager, CLI, settings UI, config, optional dependency, and unit tests. Also
updates the suspend-handler test fixture for the new engine attribute.
* style(ui): format faster-whisper imports for isort 8
* test(speech_recognition): expand faster-whisper coverage for codecov
* test(speech_recognition): fix failing faster-whisper coverage tests
- Import missing get_compute_type helper
- Add tests for English-only detection, cache exceptions, and import-error registry path
- Clear _has_torch_cuda lru_cache around exception test to avoid cached True
- Replace broad builtins.__import__ patch with a fake engine module for registry test
- Restore registry module state after test
* test(speech_recognition): add coverage for faster-whisper edge cases
Cover previously missing lines in:
- faster_whisper_model_info.py: HF cache path/none, hf_hub lookup, fallback traversal, torch CUDA true, psutil exception
- faster_whisper_engine.py: model None guard after is_ready()
- engine registry import-error path
* feat(install): add faster_whisper engine option to install.sh
- Add faster_whisper to --engine help text and examples
- Add faster-whisper as interactive option 5 with description
- Install faster-whisper package and verify import at install time
- Add fallback to whisper.cpp if faster-whisper installation fails
- Add smoke test for faster-whisper import
- Update welcome message engine display name
- Note: faster-whisper models download automatically on first use
* refactor(faster_whisper): apply ponytail review cleanups
- Inline FASTER_WHISPER_MODEL_INFO dict literal; drop unused AVAILABLE_MODELS/MODEL_SIZES
- Reuse _has_torch_cuda() in FasterWhisperEngine.device property
- Remove redundant model None guard after is_ready() verification
- Shrink faster-whisper default config in install.sh to engine + model_size
- Update device tests to manage _has_torch_cuda lru_cache
- Remove test for deleted dead-code guard
* fix(faster_whisper): integrate optional engine with current main
Keep whisper_cpp as default and Parakeet as an extra. Put engine selection
in the Advanced island, install faster-whisper via the optional extra, and
refuse unpinned Hugging Face downloads until model_checksums.txt pins them.
* fix(faster_whisper): download verified models and refresh uv.lock
Settings already opened a download dialog for uncached faster-whisper, but
init only raised ChecksumError. Wire a Parakeet-style downloader that stores
bundles under models_dir, verifies each file against model_checksums.txt, and
loads WhisperModel from that path. Regenerate uv.lock for the optional
faster-whisper extra, pin digests for all eleven Systran models, and add the
missing -> None return annotations.
* fix(faster_whisper): clear engine on unload and fix auto-pause fixture
Auto-pause tests stub __init__, so they never set _faster_whisper_engine.
reinitialize_after_resume then AttributeErrors once Test Python runs.
Mirror the suspend-handler fixture, and release the faster-whisper engine
inside unload_model the same way resume already does.
* fix(faster_whisper): restore previous engine after a failed switch
reconfigure() selected the new engine and released the live model before
init. A failed faster-whisper download then left the manager in ERROR on
the new backend while Settings reverted the pickers to the saved engine,
so dictation stayed dead until restart. Reload the previous engine from
disk (no download) before re-raising so the UI and live manager agree.
* fix(speech_recognition): restore all live settings after failed switch
Failed reconfigure already put the previous engine back, but VAD, device,
remote API, and whisper.cpp knobs stayed on the attempted values while
config on disk did not. Snapshot every field reconfigure writes and restore
the lot before reloading the old backend. Also bind the real
_init_selected_engine onto the MagicMock in the force_reinit test.
* fix(speech_recognition): restore every live field after failed reconfigure
A failed engine switch already reloaded the previous backend, but Greptile
could still miss that VAD, audio device, remote API, and whisper.cpp knobs
were part of the snapshot. Keep one explicit attr list for snapshot/restore,
including the derived voice-commands flag, so live state matches persisted
config after a failed Settings apply.
* chore(speech_recognition): sign tip after rollback follow-up
* feat(asr): add Parakeet engine via sherpa-onnx
Adds a "parakeet" engine backed by sherpa-onnx, running NVIDIA Parakeet
TDT 0.6B int8 models on CPU: v3 (25 European languages, auto-detected)
and v2 (English). Output is punctuated and capitalized.
On an Intel Core Ultra 7 155H it decodes at about 12x realtime on CPU
(RTF 0.08), roughly 8x faster than whisper.cpp large-v3-turbo over the
same clips with its Vulkan GPU backend (RTF 0.59). Being a transducer it
also has no 30s window to pad, so a short push-to-talk utterance returns
in ~0.3s instead of ~2.4s.
Follows the existing engine layout: utils/parakeet_model_info.py holds
the catalog and the get_model_path / is_model_downloaded /
list_downloaded_models / delete_model helpers, while _init_parakeet /
_transcribe_with_parakeet / _download_parakeet_model follow the same shape as their
whisper.cpp counterparts and reuse _stream_model_download for progress
and cancellation.
Registered in the engine dispatch, the settings engine/model/language
pickers, the model info card, the download prompts, the unused-downloads
list and install.sh.
Models download to <models_dir>/parakeet/<model>/ via temp files renamed
on success; is_model_downloaded requires all four files, so an
interrupted download is retried rather than loaded.
Requires the new "parakeet" extra (sherpa-onnx).
* fix(install): write only the engine key for parakeet
The parakeet branch duplicated a full default config.json. ConfigManager
deep-merges DEFAULT_CONFIG on load, so every other key was redundant:
a config holding only "engine": "parakeet" still resolves
parakeet_model_size to v3-european along with the VAD, shortcut and
text-injection defaults.
* fix(install): keep push-to-talk defaults and switch existing configs
Writing only the engine key left config.json without a shortcuts
section, which _migrate_shortcuts_config reads as a pre-push-to-talk
upgrade and pins back to ctrl+ctrl/toggle - contradicting the
installer's own "Hold Right Alt while you speak" message. Seed that
section too.
Point the config at parakeet with set_configured_engine rather than only
on first create, so --engine=parakeet also switches a machine that
already has a config.json, and give print_welcome_message a parakeet arm
so the summary is not blank.
The interactive picker overwrites SELECTED_ENGINE, so document the flag
combination that reaches this branch.
* fix(asr): pin Parakeet bundles and report one progress bar
Pin each bundle to a Hugging Face commit instead of resolve/main, so a
file replaced upstream cannot change what an install downloads. This is
the same approach whispercpp_model_info takes with its pinned revision.
Remap each file's progress into its slice of the bundle. The four files
were reported through the single-file downloader independently, so the
fraction ran to 1.0 and restarted four times; it now advances once and
names the file being fetched.
* fix(asr): reject a truncated Parakeet download
_stream_model_download only rejects an empty body, so a truncated but
nonempty response was renamed into the model directory and then reported
as installed, because is_model_downloaded checks existence.
Record the byte size of each file at the pinned revision and check it
before the rename, the same order whisper.cpp verifies its digest in. A
short file is a truncated transfer rather than an upstream change, since
the revision is pinned, so it raises and the temp file is removed.
* style(asr): annotate the Parakeet model catalog
mypy inferred the catalog values as object, so reading file_sizes out of
an entry raised attr-defined and no-any-return under `just typecheck`.
* fix(asr): pin Parakeet digests in model_checksums.txt
AGENTS.md requires every speech model to be verified against a pinned
digest before install, failing closed on an unpinned one. Parakeet was
checking only the byte size.
Teach scripts/generate-model-checksums.py to emit Parakeet entries: the
ONNX files are LFS so Hugging Face publishes their sha256, and tokens.txt
is hashed from the downloaded bytes the way VOSK archives are. Several
bundles ship the same file names, so a key carries the model name.
_download_parakeet_model now calls verify_model_file before the rename
and catches ChecksumError alongside the other download failures, matching
the whisper.cpp downloader.
* fix(asr): verify on-disk Parakeet models before load
Existing bundle files were trusted by path alone, so a leftover or
copied-in tree could reach sherpa-onnx unchecked. Hash each file against
its pin on download skip and on init, and cover the Parakeet pins in CI.
* fix(ui): hide Parakeet language picker that ignores the setting
Parakeet language coverage is the model choice, not a catalog language.
Hide the picker and persist auto so Settings does not write a lying value.
* fix(asr): normalize Parakeet language to auto at startup
CLI --language and stale saved languages still reached SpeechRecognitionManager
even though Parakeet ignores catalog language. Force auto on the shared helper
used by main and the manager so stored settings stay honest.
* fix(ui): restore language after leaving Parakeet
Remember the prior Whisper/cpp language across a Parakeet visit so switching
back does not leave recognition stuck on auto. Keep Parakeet forced to auto
and the picker hidden. Also satisfy black on the startup normalizer path.
* fix(ui): keep language memory across Vosk fallback
Vosk's unsupported-language en-us coercion was writing into
_last_non_parakeet_language, so Whisper→Parakeet→Vosk→Whisper restored
en-us instead of the user's Greek (or other) preference. Remember the
pre-coercion catalog language and prefer it when leaving Vosk.
* fix(ui): keep language memory when entering Parakeet from Vosk
Vosk's coerced en-us fallback was still written into
_last_non_parakeet_language on Parakeet entry, so Vosk→Parakeet→Whisper
restored en-us instead of the pre-coercion preference (Greek or auto).
Share one coerced-fallback predicate across entry, leave-Vosk, and language
sync, and cover those paths with regression tests.
* fix(tests): set initializing flags false on language-change stubs
Plain Mock attributes are truthy and were short-circuiting the handler.
---------
Co-authored-by: Alex Thunder <AlexThunder@gmail.com>
* feat(ci): verify the published release, not just the workflow
* fix(ci): filter attestations by predicate, name a missing distribution
Two findings from review on #791.
The attestations query accepted any predicate, so an SBOM would have read as
build provenance while `gh attestation verify`, the command the notes hand
users, rejected the artifact. It now sends the same
`predicate_type=https://slsa.dev/provenance/v1`. Checked on a real digest: the
SLSA filter returns the bundle, a foreign predicate returns 404.
check_pypi compared whatever distributions were left, so a release that lost its
sdist passed on the wheel alone. Each expected suffix is now named when absent.
The lazy urllib import moved past the early return, where it belonged.
The other two findings do not hold. `workflow_run.head_branch` carries the tag
for a tag-triggered run: the last four release runs report v0.16.2, v0.16.1,
v0.16.0 and v0.15.0. And `host_env()` is for the app spawning host binaries out
of an AppImage; `scripts/` is in no `packages` entry and the AppImage build
never references it, so this cannot run from a bundle.
* fix(ci): read release digests from the REST API
gh release view --json assets omits digest on gh 2.46, which is what
many distros ship and what just verify-release often runs, so every
asset failed as undigested. Pull the release through gh api instead,
treat a null body as notes FAIL, and prefer removeprefix for the tag.
* fix(ci): fail verify when PyPI has an extra distribution
Matching release digests alone left a differently named wheel or
sdist on PyPI unchecked. Reject those extras too, same suffixes.
* fix(test): clear tempfile mock before urllib import
Other suites leave a MagicMock in sys.modules['tempfile'], which
breaks urllib.request import with a metaclass conflict in the extra
PyPI distribution check. Drop the stub (and stale urllib modules)
first, and assert the full problem list.
* fix(ci): restore real tempfile before urllib in verify test
The MagicMock tempfile left by recognition_manager still broke
urllib.error on CI. Put the real module back and drop cached urllib
packages before the import.
---------
Co-authored-by: Jatin K Malik <jatinkrmalik@gmail.com>
* chore(build): migrate justfile tooling to uv
All recipes now run through 'uv run' against .venv, with a shared
DEV_EXTRAS variable (dev + vad) because uv syncs the environment
exactly and would otherwise uninstall the dev tools between
recipes. 'deps' installs dev+vad; new 'deps-all' covers every
extra. 'build' switches to 'uv build'; 'version' uses --no-sync.
Bump [tool.uv] required-version to >=0.12,<0.13 for uv 0.12.x, and
raise the mypy python_version target to 3.12: mypy 1.19 in the lock
cannot target 3.9 and numpy 2.x stubs need a 3.12 target to parse
(mypy is not run in CI or pre-commit; this only affects 'just
typecheck').
* fix(tests): isolate test runs from real XDG state; fix Arch model-path crash
Local test runs failed en masse (185 failures) while CI stayed
green: tests picked up the developer's real ~/.local/share/vocalinux
models via the default XDG paths and switched IBus/keyboard code
paths through the desktop session env (XDG_CURRENT_DESKTOP/
XDG_SESSION_TYPE on GNOME/Wayland, issue #478 branches). conftest
now points XDG base dirs at a throwaway session-wide directory and
clears session variables at import time, mirroring a fresh CI
runner (paths like MODELS_DIR freeze at first import during
collection, so fixture-time isolation is too late).
Also guard the Arch branch of _get_system_model_paths(): it removed
/usr/local/share/vocalinux/models unconditionally and crashed with
ValueError on Arch hosts when a custom XDG_DATA_DIRS never added
that path. Add regression tests, and make the lock-file test assert
the actual $XDG_DATA_HOME/vocalinux contract instead of the
hardcoded ~/.local/share default.
* fix(tests): keep the IBus engine double a plain class
Python 3.14's unittest.mock re-instantiates a user subclass when it builds
child mocks (klass(name=...)). VocalinuxEngine inherits from whatever
IBus.Engine resolves to, and the test module bound that to the MagicMock
class itself, so every engine instantiation raised
TypeError: VocalinuxEngine.__init__() got an unexpected keyword argument 'name'
on 3.14 while passing on 3.13. Replace it with a plain stand-in class that
still hands out per-instance MagicMocks for the IBus API surface the engine
touches.
The same pattern remains in test_ibus_engine.py, test_ibus_engine_utils.py,
test_ibus_active_engine_guard.py and test_ibus_xkb_wayland.py; those never
instantiate the engine, so they are unaffected for now.
* fix(install): build the venv from the system Python
install.sh looked up a bare `python3` from PATH. Started from an activated
virtualenv — a shell left in uv's .venv after `just deps` — it built venv/
from that interpreter, where distro PyGObject is invisible even with
--system-site-packages, and the run aborted with
Distro PyGObject (python3-gi / python3-gobject) is not importable in the venv.
A mismatched venv/ then survived every retry, because the installer reuses
whatever venv it finds.
- drop an inherited VIRTUAL_ENV (and its bin from PATH) before any
interpreter lookup
- select the interpreter explicitly: $SYSTEM_PYTHON (default
/usr/bin/python3) or PATH python3, preferring one that can import gi,
and create the venv with it instead of `python3`
- recreate venv/ when it was built by a different interpreter
- name the interpreter in the PyGObject guard's error
Documents the two environments (uv's .venv for tooling, venv/ for the
installed app) in CONTRIBUTING, the justfile header and AGENTS.md, and adds
the mismatch symptom to the INSTALL troubleshooting section.
* chore(python): raise the supported floor to 3.11
requires-python promised 3.9 while the CI matrix ran 3.9/3.10/3.11/3.13,
the classifiers advertised up to 3.14, mypy targeted 3.12 and install.sh
enforced 3.9 — five different answers to "which Python does this support".
Settle on 3.11 everywhere: pyproject (requires-python, classifiers, black
targets), install.sh's MIN_VERSION, check-system-deps.sh, the distro package
map, the CI matrix (now 3.11-3.14, matching the classifiers), the release and
nightly workflows, and the docs.
mypy now targets the floor instead of 3.12, so type checking covers what we
promise; numpy 2.x ships stubs in 3.12 syntax that a 3.11 target cannot
parse, so its imports are skipped. (mypy has 71 pre-existing errors either
way; no CI job gates on it.)
uv.lock and the requirements/* exports are regenerated — dropping 3.9/3.10
removes most of the version-conditional resolution branches.
tests/test_python_version_policy.py pins the invariant: install.sh's floor,
requires-python, the classifiers and the CI matrix must agree.
* ci: run lint and tests from uv.lock
The lock file and the hash-pinned exports were not enforced anywhere: CI
still built a venv by hand and installed unpinned `PyGObject` plus
`-e ".[dev,vad]"`, so the tool versions it checked against had nothing to do
with the ones `just lint` uses locally.
Both Python jobs now use astral-sh/setup-uv and run through `uv sync
--locked` / `uv run --locked`, which also fails the build when uv.lock drifts
from pyproject.toml.
Partially covers phase 5 of #701 (tests install from the lock, lock freshness
gate); trusted publishing, artifact checksums and action SHA pinning are
still open there.
* ci: lint from a dedicated dependency group
The lint job failed on this branch: `uv run --extra dev` syncs the whole
project, so it tried to build pyaudio from source on a runner that installs
no system dependencies.
src/pyaudio/device_api.c:9:10: fatal error: portaudio.h: No such file or directory
Move black/isort/flake8 out of the `dev` extra into a `lint` dependency
group. CI runs `uv run --locked --only-group lint`, which installs the three
pure-Python tools and skips the project entirely — no portaudio or
girepository headers needed. `just deps` and DEV_EXTRAS request the group
alongside the dev extras, so the local environment still carries test and
lint tooling at once and `just lint` matches CI version for version.
pre-commit is unaffected: its hooks pin their own tool versions upstream.
* fix(install): never configure an engine the venv cannot import
vosk became an optional extra in #705, but the installer still writes
`"engine": "vosk"` into config.json on the whisper.cpp fallback path even
when installing the extra only produced a warning. config.json also survives
reinstalls — every writer guards on "file does not exist" — so an engine
picked by an earlier attempt outlives the venv that supported it. Either way
Vocalinux dies at startup:
ModuleNotFoundError: No module named 'vosk'
- the fallback now writes the vosk config only when `import vosk` actually
succeeds, and otherwise leaves the engine configuration alone
- a new verify_configured_engine() runs near the end of the install: if
config.json selects vosk and the venv cannot import it, it says so and
prints both fixes instead of leaving a broken install behind
* feat(models): verify every model download against a pinned digest
Pins a sha256/md5 per downloadable speech model in
src/vocalinux/utils/model_checksums.txt and verifies against it in both
install.sh and the runtime downloaders, before the file is moved into place.
Verification fails closed. Covers phase 2.5 of #701; see the PR for details.
* docs(agents): rebase AGENTS.md onto the #727 rewrite
* fix(install): hash models that are already on disk instead of trusting them
* refactor(models): one download path per engine, and fix Whisper's
* docs(install): drop distros that cannot meet the 3.11 floor
* docs: retire the distros and Python versions the 3.11 floor rules out
* fix(install): abort instead of warning when Python is below the floor
* fix(install): fall back to the system Python, not the one on PATH
* fix(install): match an existing venv by installation, not by X.Y
* fix(install): repair a config naming an engine the venv cannot import
* fix(models): pin VOSK by the sha256 of bytes we fetched, not upstream's md5
* fix(justfile): request the dev set in every recipe that syncs
* test(version): scan the docs and website trees for a stale Python floor
* docs: correct the stale model-checksum and distro claims
* fix(models): stamp the VOSK tree the app extracts, as the installer does
* fix(install): replace an unverified VOSK model only once its successor is ready
* docs(install): align the Fedora floor with the rest of the tree
* test(install): drop an f-string with no placeholders
* test(models): stub the downloader probe the VOSK installer test relies on
* docs: drop the long dashes from two model-checksum comments
* fix(install): gate on the interpreter, not on the distro release label
* fix(justfile): export the lint group into requirements/dev.txt
* fix(models): unpack the VOSK tree into staging and stamp it before the swap
* fix(whisper): adopt a checkpoint an earlier release stored under the catalog name
* docs(settings): state what a stray Whisper copy really means for deletion
* fix(models): hash a whisper.cpp model found on disk before it reaches ctypes
* docs(contributing): stop telling readers to uninstall their linters
* fix(install): stop warning off distros the project documents as supported
* docs(distros): file the supported derivatives under supported
#707 wrote generated start/stop files for the family picker. Swap those
for the downloaded preview bytes (voca is pair 05) and skip the catalog
ids in generate_sounds.py so they stay put.
Settings → Audio can pick start/stop cues from the shared catalog
(lift, flick, ember, step, voca, soft, chirp, scale, drop, glass, off).
New installs and any missing or unknown sound_effects.tone value use
voca. A saved id, including off, is left alone.
The old start_recording/stop_recording files stay on disk. They are
no longer the implicit default. Error cues still follow the existing
enable switch.
* docs(packaging): prefer Ayatana AppIndicator in Fedora/Arch hints
Follow-up to #621: align docs, AUR depends, package map, dependency
check messages, and troubleshooting copy with the Ayatana-first install
path so manual installs and AUR users get a working KDE tray icon.
Co-authored-by: Jatin K Malik <jatinkrmalik@users.noreply.github.com>
* style(main): black-format Ayatana install hint lines
CI black --check failed on the multi-line logger.error calls for the
Fedora/Arch package hints.
Co-authored-by: Jatin K Malik <jatinkrmalik@users.noreply.github.com>
---------
Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Jatin K Malik <jatinkrmalik@users.noreply.github.com>
* feat(asr): add chat audio remote benchmarking
* style(asr): apply black formatting
* test(main): include remote API model kwarg
* test(asr): add coverage for chat-completions error handling and parsing
Add 10 new tests to cover uncovered lines in PR #468:
- ConnectionError handler in _try_chat_completions_audio_api (lines 1601-1602)
- _parse_chat_completion_transcription edge cases: None, list content,
empty/whitespace strings, JSON without text field, plain text, and
single-line language metadata (lines 1610, 1613-1621, 1625, 1629-1640)
Coverage for recognition_manager.py improved from 85% to 86%.
* feat(asr): support FunASR remote responses
* refactor(asr): scope remote FunASR support to the #469 path
Drop chat-completions/Qwen client, evaluation notes, and the remote ASR
benchmark harness. Keep model field, tolerant OpenAI response parsing,
SenseVoice label stripping, FunASR docs, and tests.
Add a mock test server to help developers test the remote API feature
without needing a real server. The server supports both whisper.cpp
(/inference) and OpenAI-compatible (/v1/audio/transcriptions) formats.
- Move test_remote_server.py to scripts/ directory
- Make script executable
- Add documentation to CONTRIBUTING.md with usage examples
- Include instructions for testing both API formats
Usage:
python scripts/test_remote_server.py [--port PORT] [--delay SECONDS]
- Add 'sudo ldconfig' after zypper install in suse_install_appindicator_runtime()
to ensure GI typelib cache is refreshed so newly installed typelib packages
are immediately discoverable by GObject introspection
- Add section-level comment in distro-package-map.yaml explaining that
python3XY is a placeholder convention resolved at install time by
suse_python_package_prefix() / suse_python_package_candidates()
Follow-up polish from review of #420.
* chore(release): prepare v0.10.0-beta
Bump versions and release references across app, docs, installer, and website for the next beta release. Add v0.10.0-beta release notes entries covering reliability fixes and CI/test improvements since v0.9.0-beta.
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)
Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
* docs(release): align Python baseline references to 3.9+
Synchronize stale Python 3.8 references in agent guidance and distro dependency docs/scripts with the current 3.9+ minimum used by project metadata and release docs.
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)
Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
---------
Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
Add a comprehensive YAML reference file documenting package names
across different Linux distributions. This serves as:
1. Documentation for manual installation on unsupported distros
2. Reference for adding support for new distributions
3. Auxiliary reference for the installer's embedded package mappings
Completes Task 6 from the cross-distribution compatibility fix plan.
Related to: #158, #159, #160, #161
Add better error messages and documentation for cross-distribution compatibility.
**Task 9: System Dependency Checker (scripts/check-system-deps.sh)**
- New script to check system dependencies regardless of distribution
- Detects Python 3.8+, pkg-config, GTK3, PyGObject, PortAudio
- Checks for text injection tools (xdotool, wtype, ydotool)
- Provides distribution-specific installation instructions
- Supports all 10+ distribution families (Ubuntu, Debian, Fedora, Arch, openSUSE, Gentoo, Alpine, Void, Solus, Mageia)
**Task 10: Better Unsupported Distro Message (install.sh)**
- Enhanced error message for unsupported distributions
- References the new dependency checker script
- Provides manual installation options (skip-system-deps, venv install)
- Includes link to project wiki
- Interactive prompt to continue or cancel
**Task 11: Distro Compatibility Documentation (docs/DISTRO_COMPATIBILITY.md)**
- Comprehensive compatibility matrix for supported distros
- Experimental support section with known issues
- Requirements by distribution with exact commands
- Desktop environment compatibility (GNOME, KDE, Xfce, sway, i3, etc.)
- Display server support (X11, Wayland, XWayland)
- Architecture support (x86_64, arm64, armhf, riscv64)
- Testing checklist for new distributions
- Issue reporting guidelines
- Contributing guidelines for compatibility fixes
Part of cross-distribution compatibility improvements (Phase 3 of 5).
Related to #157
Replace the current jarring sound alerts with smoother, more pleasant
bell-like tones inspired by voice assistants like Siri and Gemini.
Changes:
- start_recording.wav: Ascending perfect fifth (A4→E5, 0.30s)
- stop_recording.wav: Descending perfect fifth (E5→A4, 0.25s)
- error.wav: Low gentle chime (E4, 0.35s)
Technical improvements:
- Smooth frequency sweeps (sigmoid curve transitions)
- Subtle vibrato (8Hz) for warmth and richness
- Harmonic overtones for fullness
- Elegant exponential decay envelopes
- Reduced file sizes (926KB → 80KB total)
The new sounds are shorter (0.25-0.35s vs 0.5-1s), quieter
(20-25% amplitude vs full volume), and more pleasant for frequent use.
