voculinux/docs/UPDATE.md

Updating Vocalinux

This guide explains how to update Vocalinux to the latest version.

What's New in v0.16.2

0.16.2 is a stability patch on the 0.16 series. The feature set is the same as 0.16.x. This release fixes KDE leftover IBus so dictation types into real apps, Wayland and IBus keyboard shortcuts through wtype/ydotool, real BackSpace for "delete that", Fedora/Arch installer glslc packages, nightly version stamping, and release integrity pins. CI now gates AUR PKGBUILD builds and the distros the docs promise.

0.16 series highlights

Feature	Description
Update checker	Settings → About checks stable/nightly; tray shows Update Available for newer GitHub releases (#631, #645)
Right Alt PTT default	New installs default to hold Right Alt (push-to-talk); existing configs keep their shortcut (#648)
Searchable languages	Type to filter the Speech Model language list (#672)
Delete unused models	Remove leftover downloaded speech models from Settings (#671)
AGPL-3.0	License aligned with other VocaHQ projects (#660)
Family mic icons	App icon, tray states, and site favicons use the shared Voca family mic (#704)
Tone picker	Settings → Audio: Lift, Flick, Ember, Step, Voca, Soft, Chirp, Scale, Drop, Glass, Off, plus Preview. New installs default to Voca. Catalog uses family preview WAVs (#707, #708)
Installer	Justfile, uv lockfiles, distro python3-gi required (no pip sdist of PyGObject). Epic #701 still open (#700, #705, #706)

Bug fixes in v0.16.2

• KDE inject: skip leftover IBus when it is not the session IM so dictation types into Kate, browsers, and terminals (#753 by @jatinkrmalik, fixes #752 by @justTravis)
• Wayland shortcuts: wtype and ydotool deliver real chords instead of refusing or silently doing nothing (#715 by @eiseleb47)
• IBus shortcuts: route X11_IBUS through xdotool and WAYLAND_IBUS through wtype/ydotool (#716 by @eiseleb47)
• Delete that: send real BackSpace key events instead of U+0008 text (#714 by @eiseleb47)
• Installer: Fedora and Arch need glslc/shaderc packages, not glslang (#763 by @jatinkrmalik, see #604)
• Nightly: stamp version.py before python -m build so wheel metadata matches the filename (#762 by @sesav)
• Release integrity: checksums, signatures, and pinned builders for release artifacts (#759 by @sesav, epic #701 phase 5)
• CI: gate AUR PKGBUILD builds on every PR (#772 by @sesav)
• CI / docs: test the distros the docs promise and fix docs drift (#773 by @sesav)
• Site: VocaGateway family card is Beta; README logo, badges, and privacy copy (#765 by @jatinkrmalik, #764)

See the full changelog.

---

What's New in v0.16.1

0.16.1 is a stability patch on the 0.16 series. The feature set is the same as 0.16.x. This release fixes wrong-model startup, leftover tray state after toggle stop, paste into terminals, GNOME XWayland layout after inject, and AppImages that needed a glibc newer than Debian 12. The installer now requires Python 3.11 and verifies model downloads.

0.16 series highlights

Feature	Description
Update checker	Settings → About checks stable/nightly; tray shows Update Available for newer GitHub releases (#631, #645)
Right Alt PTT default	New installs default to hold Right Alt (push-to-talk); existing configs keep their shortcut (#648)
Searchable languages	Type to filter the Speech Model language list (#672)
Delete unused models	Remove leftover downloaded speech models from Settings (#671)
AGPL-3.0	License aligned with other VocaHQ projects (#660)
Family mic icons	App icon, tray states, and site favicons use the shared Voca family mic (#704)
Tone picker	Settings → Audio: Lift, Flick, Ember, Step, Voca, Soft, Chirp, Scale, Drop, Glass, Off, plus Preview. New installs default to Voca. Catalog uses family preview WAVs (#707, #708)
Installer	Justfile, uv lockfiles, distro python3-gi required (no pip sdist of PyGObject). Epic #701 still open (#700, #705, #706)

Bug fixes in v0.16.1

• Startup: resolve model size per engine instead of the leftover generic model_size key, so a VOSK save does not make whisper.cpp look for a missing medium model (#684 by @kacperpaczos, fixes #681)
• Settings: save the model only after the engine loaded it, so a cancelled or failed download does not leave config pointing at a file that is not on disk (#685 by @kacperpaczos)
• Settings: unused downloads list sized to its real rows so leftover models are not clipped (#686 by @kacperpaczos, fixes #683)
• Config: one ConfigManager for the process so Settings writes are not overwritten by a stale cache (#691 by @kacperpaczos, fixes #689)
• Tray: stay idle after leftover transcription on toggle stop (#741)
• Tray: the missing-model notification can download the recommended model (#687 by @kacperpaczos)
• Injection: Ctrl+Shift+V when pasting into terminals, so Ctrl+V is not treated as verbatim insert (#734)
• IBus: sync the XWayland layout from GNOME after scoped inject (#742)
• Installer: survive a release without a checksum manifest; stop inventing GPUs (#736 by @sesav)
• Installer: leftover engine repair, just --no-sync, ggml verify from #713 (#732)
• 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.

---

What's New in v0.16.0

0.16.0 is a minor release on the stable line. It adds an in-app update checker with tray notifications, defaults new installs to hold Right Alt push-to-talk, makes the language picker searchable, lets you delete unused downloaded models, and adds a family dictation tone picker. The license is AGPL-3.0. The installer is hardened (Justfile, uv lockfiles, distro python3-gi). The app icon, tray states, and site favicons use the shared Voca family mic.

Highlights

Feature	Description
Update checker	Settings → About checks stable/nightly; tray shows Update Available for newer GitHub releases (#631, #645)
Right Alt PTT default	New installs default to hold Right Alt (push-to-talk); existing configs keep their shortcut (#648)
Searchable languages	Type to filter the Speech Model language list (#672)
Delete unused models	Remove leftover downloaded speech models from Settings (#671)
AGPL-3.0	License aligned with other VocaHQ projects (#660)
Family mic icons	App icon, tray states, and site favicons use the shared Voca family mic (#704)
Tone picker	Settings → Audio: Lift, Flick, Ember, Step, Voca, Soft, Chirp, Scale, Drop, Glass, Off, plus Preview. New installs default to Voca. Catalog uses family preview WAVs (#707, #708)
Installer	Justfile, uv lockfiles, distro python3-gi required (no pip sdist of PyGObject). Epic #701 still open (#700, #705, #706)

New Features

• In-app update checker: Settings → About with stable/nightly channels (#631)
• Update notifications: Tray menu Update Available entry and About badge when a newer release exists (#645)
• Right Alt push-to-talk default: New installs only; existing configs are unchanged (#648)
• Searchable language combobox: Filter the long language list by name or code (#672, fixes #652)
• Delete unused models: Remove leftover downloaded speech models from Settings (#671, fixes #650)
• Disable missing-tray warning: Settings toggle for desktops that false-positive the tray check (#628, fixes #620)
• Family mic icons: App icon, tray states, and site favicons use the shared Voca family mic instead of the old Linux rounded-rect (#704)
• Family dictation tone picker: Settings → Audio dropdown (Lift, Flick, Ember, Step, Voca, Soft, Chirp, Scale, Drop, Glass, Off) plus Preview. New installs and unknown saved names default to Voca. A saved catalog id, including Off, is left alone. Enable remains the master mute; Off skips start/stop only (#707)
• About page: Settings → About groups this app, VocaHQ family sites, and talk-to-us (GitHub issues, Discord, X, email) (#718)

Bug Fixes

• IBus: Require a restorable engine for scoped injection (#623); restore engine after register_component teardown (#643, fixes #558); restore XKB layout after scoped injection on X11 (#665, fixes #664)
• Injection: Stop typing test during the wtype probe (#627, fixes #622)
• whisper.cpp: Skip unsupported context_params on pywhispercpp 1.4 (#626, fixes #625); use CUDA device 0 when CUDA-backed (#636); honor bundled GPU libs and skip software Vulkan devices (#674)
• Audio: Filter unsafe virtual capture devices (#629, fixes #624); open stereo mics at native channel count (#673, fixes #666); catalog tones are the family preview WAVs, not the synthesized #707 files. generate_sounds.py does not clobber catalog ids (#708)
• Tray / Settings: Prefer Ayatana AppIndicator on KDE (#621); reuse Settings/Logs windows (#669, fixes #653); separate Close from Test Dictation (#670, fixes #651)
• Settings: Test Dictation no longer reports no speech when recognition never started (missing model / auto-pause / live engine out of sync) (#702)
• Clipboard: Restore after ydotool clipboard-paste (#588); text-only reads and safer overlapping restore (#646)
• AppImage: Ship transitive GI typelibs for non-Debian hosts (also hotfixed onto the v0.15.0 AppImages on 2026-08-03) (#637); pin pywhispercpp to the version install.sh declares so a newer PyPI wheel cannot break the Vulkan rebuild (#718)
• Installer: Distro python3-gi is required; pip no longer builds PyGObject from sdist. Unset XDG_SESSION_TYPE / XDG_CURRENT_DESKTOP no longer crash under set -u (#706)
• Installer / downloads / tests: Gate util-linux-extra to Ubuntu 24.04+ (#635, fixes #526); report failed model downloads (#690); stop the suite from overwriting real config.json (#694)

Docs / maintenance

• Website screenshot refresh for v0.15 (#630)
• Prefer Ayatana AppIndicator in Fedora/Arch packaging hints (#638)
• CUDA device 0 note for dual NVIDIA (#644)
• Discord and VocaHQ README shields; VocaHQ URL migration; VocaGateway rename (#695, #696, #697)
• Discord invite and X handle point at VocaHQ (#722)
• vocalinux.com restyled to the Voca family workbench; Open Graph card uses the flat Tux (#728, #729)
• Website copy drops the stale 100% offline claim and marks VocaWin as alpha on the site (#717)
• Codeberg mirror tag force-push (#633)
• Installer hardening, Justfile in place of Makefile, and uv lockfiles with pinned build inputs. Epic #701 remains open (#700, #705 by @sesav)

See the full changelog.

---

What's New in v0.15.0

0.15.0 is a minor release on the stable line. It redesigns settings navigation, adds AppImage packages, expands the speech-language catalog (Hungarian and many more), cleans up continuous dictation spacing/capitalization, adds power/GPU controls, and improves Wayland IBus on compositors that ship ibus-wayland, on top of the 0.14 packaging work (Flatpak, AUR, configurable hotkeys).

Highlights

Feature	Description
Searchable settings	Sidebar navigation with search replaces the seven-tab notebook (#601)
AppImage	Self-contained x86_64 and aarch64 builds attached to GitHub Releases (#573, #602)
Language catalog	~33 selectable speech languages plus Auto-detect (incl. Hungarian); CLI choices derived from the same catalog; VOSK hides Whisper-only langs (#616, fixes #565)
Dictation polish	Auto-capitalize after . / ! / ?; append a trailing space after each completed utterance (#554, #608)
Auto-pause + keep-alive	Unload the model while configured apps run, or after an idle timeout (#592)
Vulkan GPU selection	Prefer a discrete GPU automatically; pick a device under Advanced settings (#590)
ibus-wayland	Prefer IBus on previously “unbridged” compositors when ibus-wayland is running (#614)
CLI --version	Print the installed version and exit (#563)

New Features

• Searchable sidebar settings — Topic pages in a sidebar with live search instead of seven notebook tabs (#601)
• AppImage packaging — Relocatable x86_64 and aarch64 AppImages built in the release workflow (#573, #602)
• Expanded speech languages — Hungarian plus many high-demand Whisper languages in Settings/CLI; official Alphacephei VOSK models where available; Whisper-only languages stay hidden in the VOSK dropdown (#616 by @jatinkrmalik, fixes #565)
• Sidebar dictation controls — Recognition status, mic level, Test Dictation, and Close stay visible in the settings sidebar footer while switching pages (#618)
• Sentence capitalization — Capitalize at the start of dictation and after sentence-ending punctuation (#554, closes #553)
• Trailing space between utterances — Completed transcriptions leave a trailing space so the next session does not glue onto the previous sentence (#608, fixes #605)
• Auto-pause apps + model keep-alive — Optional unload while selected processes run; idle timeout unload for battery/Optimus laptops (#592, closes #445, #591)
• Vulkan discrete GPU auto-select + manual device — Prefer discrete devices; override in Advanced settings (#590, closes #589)
• IBus via ibus-wayland — On compositors previously treated as unbridged, use IBus when ibus-wayland is available (#614 by @eiseleb47, closes #607)
• vocalinux --version — Print package version (#563, closes #555)

Bug Fixes

• Settings: Restore Custom Shortcut entry / Record / Set controls after the sidebar settings refactor (#619)
• Languages: Map English (India) (en-in) to Whisper code en for whisper.cpp / Whisper / remote API (#617)
• Audio: Stop Bluetooth mic probing from corrupting the heap — one PortAudio open per capture session, stop-before-close, no stereo probe on mono-only devices (#599, fixes #567)
• IBus: Keep engine teardown correct when parent do_destroy fails (#613 by @eiseleb47, fixes #606)
• Settings UI: Flatten info notices so helper text matches the rest of the dialog (#615)
• KDE Plasma Wayland: Skip unbridged IBus when ibus-wayland is not present so injection does not silently fail (#577, fixes #574)
• xdotool: Preserve input focus after injection (#564, fixes #549)
• Uninstall: Remove IBus data dir; stop the app by PID file; remove ~/.local/bin launcher wrappers reliably (#597, #569)
• Installer: Prefer both libgirepository 1.0 and 2.0 when present (#583, fixes #571)
• AUR: Virtual python-pywhispercpp dependency; clipboard/wtype tools as optdepends (#579, #586)
• UI: First-run dialog response without Gtk.Dialog.do_response (#580, fixes #566)
• Vosk: Italian and English-India entries in medium/large model tables (#551, fixes #550)
• Docs: Correct ydotool service setup guidance (#560, fixes #557)

Docs / website

• Marketing site redesign with workstation craft (#582)
• Languages marketing page with honest per-engine badges (#616)
• Multi-distro tray icon FAQ (#584)
• robots.txt no longer blocks indexable pages (#610)
• Website CI lint / action warning cleanup (#611)

See the full changelog.

---

What's New in v0.14.2

0.14.2 is a stability patch on the 0.14 series. The feature set is the same as 0.14.x; this release fixes IBus reliability and settings dialog sizing.

0.14 series highlights

Feature	Description
Configurable Shortcuts	Bind any modifier combination to a key — e.g. Alt+R, Ctrl+Shift+V, or Super+F10
FunASR / SenseVoice Remote API	Remote-API engine supports FunASR and SenseVoice via OpenAI-compatible endpoints
Flatpak packaging	Universal Flatpak (whisper.cpp) with sandbox-aware paths, global hotkeys, and Wayland paste injection
AUR package	Official Arch packaging and CI publish path
Layout-aware hotkeys	Combo keys respect non-US layouts
Wayland / IBus reliability	GNOME and KDE injection fixes, first-dictation FocusIn gate, engine process launch restored
Audio / hybrid-CPU	Recording device-index crash fixed; whisper.cpp no longer defaults to all cores on hybrid CPUs

Bug fixes in v0.14.2

• IBus: Restore engine process launch after the Flatpak XDG path import change. start_engine_process and the IBus component exec run ibus_engine.py by path, so the relative import failed with ImportError and Vocalinux fell back to ydotool/clipboard paste (#534)
• IBus: Wait for FocusIn before commit on scoped injection. Cold first activation on GNOME Wayland could commit before mutter bound a client context, so the first dictation of a session was dropped while logs still reported success (#533, fixes #523)
• Settings UI: Wrap each notebook tab in a vertical ScrolledWindow so the dialog fits 1080p monitors instead of growing past the screen; forward wheel events from unfocused combos/spins to the tab scroller and drop nested Advanced ScrolledWindow shadows (#538, #541)

See the full changelog.

---

What's New in v0.14.1

Highlights

Feature	Description
Flatpak packaging	Universal Flatpak (whisper.cpp) with sandbox-aware paths, global hotkeys, and Wayland paste injection
AUR package	Official Arch packaging and CI publish path
Layout-aware hotkeys	Combo keys respect non-US layouts
Installer / injection fixes	sg on Ubuntu 26.04/Debian 13; XIM none treated as unset

New Features

• Flatpak packaging — GNOME Platform 50, whisper.cpp + Vulkan, ydotool/wl-copy injection, evdev global shortcuts; build via packaging/flatpak/ (#484, closes #167)
• AUR release package — PKGBUILD and CI publish for Arch Linux (#518)

Bug Fixes

• Hotkeys: Layout-aware combo keys for non-US layouts (#514)
• Installer: sg not found on Ubuntu 26.04 / Debian 13 (#524)
• Text injection: Treat XIM none as unset (#512)
• Web: Dependabot npm alerts in package-lock (#515)

Docs

• Refreshed v0.14 UI screenshots and website gallery (#521)
• README Star History and related polish

See the full changelog.

---

What's New in v0.14.0-beta

Highlights

Feature	Description
Configurable Shortcuts	Bind any modifier combination to a key — e.g. Alt+R, Ctrl+Shift+V, or Super+F10
FunASR / SenseVoice Remote API	Remote-API engine now supports FunASR and SenseVoice models via OpenAI-compatible endpoints
GNOME Wayland IBus Reliability	Text injection works again on GNOME Wayland with bare xkb layouts and engine restore fallbacks are fixed
Audio Crash Fix	Recording no longer crashes when the system audio device index changes between sessions
Hybrid-CPU Efficiency	whisper.cpp no longer defaults to all cores on hybrid Intel/AMD processors

✨ New Features

• Configurable modifier+key hotkeys — The Settings dialog now lets you set custom shortcuts using any combination of Ctrl, Alt, Shift, and Super plus a letter/number key. The legacy defaults still work, and you can now bind combinations like Alt+R or Ctrl+Shift+V (#493)
• Remote API FunASR/SenseVoice support — OpenAI-compatible remote endpoints can specify FunASR/SenseVoice model names (e.g. sensevoice) and return richer response shapes; SenseVoice metadata labels are stripped before text injection (#468)

🐛 Bug Fixes

• GNOME Wayland/IBus: Restore text injection when only a bare xkb engine is configured; the engine restore fallback now picks the correct IM engine instead of silently dropping text (#506, #500)
• KDE Wayland/IBus: Restore the KDE Plasma Wayland IBus text-injection path that was regressed in recent compositor-detection changes (#502)
• Wayland injection: Wait for held modifiers (Ctrl/Alt/Shift/Super) to release before injecting text, preventing accidental shortcut triggers and garbled output on modifier-heavy workflows (#494)
• Shortcuts UI: Keep preset and custom shortcut selection exclusive — selecting a preset now clears the custom field, and setting a custom combo selects the "Custom Shortcut" preset (#509)
• whisper.cpp: Stop defaulting to all CPU cores on hybrid processors (Intel Performance + Efficient cores), which caused UI lag and excess battery drain (#492)
• Audio: Fix a crash on recording start when the selected audio device index no longer matches the current system enumeration (#499)
• Installer: Include xsel as a fallback for the Wayland clipboard path when xclip is unavailable (#496)

🔧 Improvements

• Code style — Removed an outdated long comment about whisper.cpp default thread counts (#505)

See the full changelog.

---

What's New in v0.13.0-beta

🚀 Highlights

Feature	Description
🎙️ Guided Whisper Models	Pick a whisper.cpp size and specialization (English-only, quantized, Turbo) with in-app guidance
🔌 Hotplug Keyboard Support	Shortcuts keep working on keyboards connected after startup
✍️ Dictation Spacing	Spacing preserved between speech segments separated by a pause in the same session
🖥️ Wayland Reliability	Fixes silent text drops on wlroots/COSMIC compositors and garbled non-US-layout output

✨ New Features

• Guided whisper.cpp model variants — The Settings dialog now splits whisper.cpp selection into Model Size and Specialization, exposing English-only, quantized (Q5/Q8), Large v3 Turbo, and legacy large models with language-aware recommendations and hover guidance. Exact model IDs (e.g. medium.en-q5_0, large-v3-turbo) can also be passed to --model (#465)

🐛 Bug Fixes

• Dictation: Preserve spacing between speech segments separated by a pause (#464)
• Shortcuts: Rescan for hotplugged keyboards so shortcuts work on devices connected after startup (#467)
• KDE Plasma Wayland: Detect KDE Plasma Wayland sessions and guide you to enable IBus Wayland when wtype injection fails (#466)
• Wayland: Fix garbled output on non-US keyboard layouts and a clipboard-copy hang; ydotool now pastes through the clipboard (#480)
• Wayland/IBus: Use wtype/ydotool instead of IBus on compositors that don't bridge IBus to native apps like COSMIC, Sway, and Hyprland (#486)
• Wayland/IBus: Require a real IM engine on Wayland so a bare xkb layout no longer causes silent text drops on GNOME/Mutter and similar (#478)
• Wayland: Preserve the keyboard layout on Wayland by not running setxkbmap (was flipping XWayland apps to us) (#474)
• UI: Cap the settings dialog height on high-resolution displays (#465)

🔧 Improvements

• Performance: Faster ydotool text injection via an explicit --key-delay (#488)
• Website: New documentation pages for Remote API, Silero VAD, advanced whisper.cpp settings, and desktop reliability (#470)
• CI: Automatic pull-request labeling by changed files (#473)

See the full changelog.

---

What's New in v0.12.0-beta

🚀 Highlights

Feature	Description
🌐 Remote API Engine	New backend for compatible remote transcription services
🎙️ Silero VAD	Neural VAD drops silence-only buffers for cleaner dictation
🧵 Thread Safety	Hardened Remote API, IBus, and text injection threading behavior
🔌 IBus Reliability	Preserves user engines for dead keys and scoped activation
⚙️ Settings Polish	Advanced-only Remote Server controls and lower dialog height
📦 Installer & Models	CUDA auto-remediation and corrected model download metadata

✨ New Features

• Remote API speech recognition engine — Configure compatible remote transcription services alongside local engines (#335)
• Silero VAD — Neural voice activity detection filters silence-only buffers when ONNX Runtime support is installed (#447)

🐛 Bug Fixes

• Threading: Harden Remote API, IBus, and text injection thread safety (#452)
• IBus: Preserve user engines for dead keys and capture the current engine during scoped activation (#457, #458)
• UI: Keep the Remote Server section behind the Advanced toggle and reduce settings dialog height (#454, #456)
• Installer: Harden CUDA diagnostics with auto-remediation and behavioral tests (#451)
• Models: Correct whisper.cpp and VOSK download size metadata (#453)
• Startup: Allow launch without the pynput backend (#448)
• Website: Clarify speech demo browser support (#449)

🔧 Improvements

• Developer docs — Remote API test server instructions for backend testing (#455)
• Community — GitHub Sponsors funding configuration added
• Behavioral coverage — CUDA diagnostics and release-facing reliability fixes include targeted tests

See the full changelog.

---

What's New in v0.10.2-beta

🚀 Highlights

Feature	Description
🌍 Non-ASCII Text Injection	ydotool now falls back to clipboard paste for non-ASCII characters (á, é, ñ, etc.)
🔌 IBus on Wayland	IBus now detected and started correctly on Wayland without legacy env vars
🚀 IBus Engine Startup	Engine process now starts before registration check — fixes startup on some systems
📦 Pop!_OS / Ubuntu 24.04+	Added missing system dependencies (cmake, libcairo2-dev, libgirepository1.0-dev)
⚡ Code Quality	Systematic refactor across 20 quality dimensions
🖼️ Website OG Image	Redesigned Open Graph image — cleaner and more professional

🐛 Bug Fixes

• #362 / #376: Handle non-ASCII characters with ydotool via clipboard paste fallback
• #360 / #361: Start IBus engine process before checking registration
• #381: Detect IBus on Wayland without legacy env vars and fix text injection
• #379: Add missing dependencies for Pop!_OS and Ubuntu 24.04+

🔧 Improvements

• Systematic code quality refactor across 20 dimensions (#377)
• Clarify missing GNOME AppIndicator support on Debian (#385)
• Redesigned OG image for vocalinux.com (#392)

See the full changelog.

---

What's New in v0.10.1-beta

🚀 Highlights

Feature	Description
🖼️ Tray Resource Reliability	Bundled package resources now prevent missing system tray icons
🧠 Engine Switch Safety	Recognition now stops before engine changes to avoid segfaults
⌨️ Keyboard Layout Preservation	XKB layout is preserved when activating the Vocalinux IBus engine
🪟 Settings Dialog Compatibility	Added an explicit Close button for improved WM interoperability
⚡ Suspend/Resume Recovery	App now automatically recovers speech recognition and keyboard shortcuts after system suspend/resume
🎤 Push-to-Talk Reliability	Fixed premature transcription triggering on silence during push-to-talk mode

✨ Scope

• Patch-focused release — No new feature surface; this version is dedicated to stability and compatibility fixes
• Desktop reliability hardening — Improved behavior across tray, engine switching, settings dialog actions, and keyboard layout handling
• Suspend/Resume stability — New D-Bus handler ensures app survives system sleep cycles

🐛 Bug Fixes

• #349 / #354: Bundle resources in package to fix missing system tray icons
• #350 / #355: Stop recognition before switching engines to prevent segfaults
• #323 / #356: Add Close button to settings dialog for WM compatibility
• #292 / #343: Preserve XKB layout when activating Vocalinux IBus engine
• #359: Prevent premature transcription during push-to-talk silence
• #367 / #369: Auto-recover speech recognition after system resume via new suspend handler
• #371: Restart keyboard shortcut backend after system resume
• #372: Delay keyboard restart to allow USB device re-enumeration after resume

🔧 Improvements

• Bumped npm/yarn dependency group across the web workspace (#346)
• Bumped brace-expansion in development dependencies (#357)
• Disabled copy-to-clipboard by default in Settings (#370)

See the full changelog.

---

What's New in v0.9.0-beta

🚀 Highlights

Feature	Description
⌨️ Left/Right Modifier Keys	Choose Left Ctrl vs Right Ctrl (etc.) as your shortcut trigger
🔔 Sound Effects Toggle	Enable or disable audio feedback from the Settings dialog
📋 Wayland Clipboard Fallback	Automatic clipboard copy when virtual keyboard injection isn't available
🛠️ Installation Polish	Better pipx/Debian guidance and headless display detection

✨ New Features

• Left/Right Modifier Key Distinction — Shortcuts now support Left Ctrl, Right Alt, etc., with grouped UI in Settings
• Sound Effects Toggle — New Audio Settings toggle to silence start/stop/error sounds
• Clipboard Fallback for Wayland — Auto-copies text via wl-copy/xclip when injection unavailable (KDE Plasma etc.)
• Display Availability Check — Graceful error message when running in headless environments

🐛 Bug Fixes

• #308: Distinguish left vs right modifier keys (evdev + pynput backends)
• #307: Remove unwanted leading space when starting a new transcription session
• #305: Pass configured shortcut mode to KeyboardShortcutManager on startup
• #299: Add clipboard fallback for Wayland compositors without virtual keyboard support
• #289: Improve Debian/pipx installation error messages and cross-distro dependency guidance

🔧 Improvements

• Grouped shortcut selector — Settings dropdown now organises shortcuts by Either/Left/Right side
• pipx documentation — New DISTRO_COMPATIBILITY.md section for pipx users

See the full changelog.

---

What's New in v0.8.0-beta

🚀 Highlights

Feature	Description
🎤 Push-to-Talk Mode	Hold the shortcut key to speak, release to stop
⚙️ Voice Commands Toggle	Enable or disable voice commands, with VOSK auto-enable in auto mode
⌨️ Shortcut Reliability	Improved callback lifecycle and mode switching stability
🧠 Input Compatibility	Better IBus detection and audio device/channel compatibility

✨ New Features

• Push-to-Talk Shortcut Mode — Added hold-to-speak mode alongside double-tap toggle mode
• Mode-aware Shortcut UI — Updated settings text and behavior for toggle vs push-to-talk workflows
• Voice Commands Optional — Voice commands can be disabled, with automatic enable behavior for VOSK

🐛 Bug Fixes

• #277: Detect active IBus input method before using IBus injection
• #275: Detect and use device-supported channel count
• #268: Prevent GTK startup dialog crash on Fedora
• #261: Resolve text injection issues for better reliability
• #259: Prevent recognition thread state flicker
• #262/#263: Auto-detect audio sample rate for better hardware compatibility

🔧 Improvements

• Web SEO Enhancements — Added 8 additional optimized pages for discoverability
• Homepage Refresh — Updated voice-themed visual polish on the web landing page

See the full changelog.

---

Quick Update

Vocalinux checks GitHub Releases in the background about every six hours (and shortly after startup). When a newer build is on your selected channel, the tray menu gains an Update Available… entry and Settings → About shows a green New badge; open that page for release notes and download links. Updates are not installed automatically — re-run the installer (or your package manager) as below.

If You Installed via curl (Recommended)

Simply re-run the installation command:

curl -fsSL https://raw.githubusercontent.com/VocaHQ/vocalinux/main/install.sh | bash

The installer will:

• ✅ Detect and stop any running Vocalinux processes
• ✅ Update your existing installation
• ✅ Preserve your configuration and models
• ✅ Install any new dependencies
• ✅ Attempt to install neural VAD support, falling back safely if ONNX Runtime is unavailable

If You Installed from Source

cd vocalinux
git fetch origin
git checkout v0.16.2
./install.sh

Or to get the latest development version:

cd vocalinux
git pull origin main
./install.sh

---

Checking Your Current Version

python3 -c "import vocalinux; print(vocalinux.version.__version__)"

---

Troubleshooting

Update Issues?

If your update doesn't go smoothly, try a clean reinstall:

# Uninstall (keeps your config and models by default)
./uninstall.sh --keep-config --keep-data

# Or uninstall completely
./uninstall.sh

# Reinstall fresh
curl -fsSL https://raw.githubusercontent.com/VocaHQ/vocalinux/main/install.sh | bash

Old Version Still Running

# Prefer stopping from the tray, or kill by the PID in the lock file:
kill "$(tr -d '[:space:]' < "${XDG_DATA_HOME:-$HOME/.local/share}/vocalinux/instance.lock")"

# If you used IBus injection, also stop the engine:
kill "$(tr -d '[:space:]' < "${XDG_DATA_HOME:-$HOME/.local/share}/vocalinux-ibus/engine.pid")"

# Start fresh
vocalinux

Avoid pkill -f vocalinux — it matches any process whose command line mentions the repo path (editors, shells, test runners) and can kill unrelated work.

Missing Dependencies

If you see dependency errors:

# Ubuntu/Debian
sudo apt update
sudo apt install -y python3-gi python3-gi-cairo gir1.2-gtk-3.0

# Fedora
sudo dnf install -y python3-gobject gtk3

# Arch
sudo pacman -S python-gobject gtk3

---

Need Help?

• 📖 Installation Guide
• 🐛 Report Issues
• 💬 Discussions