voculinux/docs/UPDATE.md

Updating Vocalinux

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

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

If You Installed via curl (Recommended)

Simply re-run the installation command:

curl -fsSL https://raw.githubusercontent.com/jatinkrmalik/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.13.0-beta
./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/jatinkrmalik/vocalinux/main/install.sh | bash

Old Version Still Running

# Kill any running instances
pkill -f vocalinux

# Start fresh
vocalinux

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