voculinux/docs/UPDATE.md

Updating Vocalinux

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

What's New in v0.11.0-beta

🚀 Highlights

Feature	Description
⚙️ Advanced Settings Tab	New Advanced tab exposing whisper.cpp anti-hallucination parameters
🔌 IBus Hardening	Engine readiness probe, runtime failure recovery, proper destruction on layout switch
🎤 Recognition Reliability	Preserve final speech on stop and improved stop-sound timing
📦 Distro Compatibility	Hardened Debian layer, corrected openSUSE deps, Python 3.14 support
🔧 Installer Fixes	pywhispercpp loading repair, proj config validation, reused builds

✨ New Features

• Advanced Settings tab — New tab in the Settings dialog exposing whisper.cpp anti-hallucination parameters:
  • Temperature override
  • No-speech threshold
  • Max segment length
  • Other inference-time parameters for fine-tuning recognition

🐛 Bug Fixes

• IBus: Probe engine readiness at startup with hardened retries (#391)
• IBus: Handle engine instance destruction on layout switch (#389)
• IBus: Recover from runtime failures gracefully (#411)
• Recognition: Preserve final speech when stopping (#401)
• Recognition: Play stop sound immediately on release (#426) and after audio thread joins (#436)
• Install: Repair pywhispercpp library loading (#433)
• Install: Correct openSUSE Tumbleweed dependencies (#420, #418)
• Install: Harden Debian compatibility layer (#437)
• Install: Validate pyproject.toml/setup.py before local repo mode (#396)
• Install: Reuse existing whispercpp builds (#421)
• Install: Refresh ldconfig after openSUSE typelib install (#438)
• whisper.cpp: Reduce CPU threads and ensure GPU backend builds in dev mode (#439)
• Logging: Clean up runtime log noise and cache hardware detection
• Python 3.14 support: Compatibility fix and lxml>=6.1.0 (#404)

🔧 Improvements

• Installer refresh — openSUSE fallback handling, Debian compatibility hardening
• Test coverage — Recognition internals, IBus edge cases, CI notification suppression (#410, #414)
• Dependency bumps — Next.js security updates (#399, #429), PostCSS
• PyPI docs — Clarify installation requirements (#423)

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

If You Installed from Source

cd vocalinux
git fetch origin
git checkout v0.11.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