RFC: Vocalinux Technology Stack Analysis & Porting Recommendations

[jatinkrmalik]

RFC: Vocalinux Technology Stack Analysis & Porting Recommendations

Status: Open for discussion
Author: @jatinkrmalik + AI Agent swarm to analyze code repo
Date: 2026-05-02

---

TL;DR

After auditing the Vocalinux codebase (~13,800 lines Python) and researching the Linux desktop ecosystem, I propose a tiered modernization roadmap:

1. Ship Flatpak now (2–3 months) — highest ROI, fixes distribution gap
2. Migrate to GTK4 in parallel (2–3 months) — future-proof the UI
3. Hybrid Rust core later (optional, 2–3 months) — fix performance if needed
4. Full Rust rewrite (optional, 6–12 months) — only if maintainer bandwidth allows

Not recommended: Dropping everything for a full Rust rewrite immediately.

---

Background

Vocalinux is a mature Python/GTK3 voice dictation app with:

• ✅ GTK3 UI (system tray, settings dialog, log viewer)
• ✅ Wayland support (wtype, ydotool, IBus, clipboard, XWayland fallback)
• ✅ X11 support (xdotool)
• ✅ 3 speech engines (whisper.cpp default, Vosk, OpenAI Whisper)
• ✅ Dual keyboard backends (pynput for X11, evdev for Wayland)
• ❌ No distribution packaging (users run a 2,890-line bash install script)

The codebase is well-architected. The question is where to invest next.

---

Key Findings

1. GTK3 is maintenance-only

GTK3 receives only crash/build fixes. New platform features (GPU rendering, fractional scaling, modern dialogs) are GTK4-only. PyGObject 3.55 (Nov 2025) fully supports GTK4.

Migration complexity: Medium-High. Not a drop-in upgrade. Major changes:

• AppIndicator3 → D-Bus StatusNotifierItem (biggest blocker)
• Gtk.Dialog + Gtk.Notebook → Adw.PreferencesDialog
• Event signals → Event Controllers
• ~500 lines inline CSS need rewriting

Recommended strategy: Gaphor's "keep the shop open" — parallel GTK3/GTK4 branches, ship from GTK3 while GTK4 matures.

2. Wayland support exists but is fragile

Vocalinux already supports Wayland via a sophisticated fallback chain:

• wtype (GNOME/Sway with virtual-keyboard protocol)
• ydotool (universal but needs daemon + uinput)
• IBus (best Unicode, needs engine registration)
• Clipboard + Ctrl+V (universal fallback)
• XWayland + xdotool (fallback for XWayland apps)

The problem: Each backend has compositor-specific gaps. No single path works everywhere. And none are Flatpak-safe.

Upgrade path: libei + RemoteDesktop portal. This is the official Wayland-native replacement for XTEST. Works on GNOME 46+ and KDE Plasma 6. User-approved via permission dialog. Flatpak-safe.

3. Python's GIL is a risk, not a showstopper

The GIL serializes audio orchestration (capture → VAD → transcription → injection). pywhispercpp and NumPy release the GIL during C++ execution, but Python-level queue management is serialized.

Honest framing: Vocalinux works today. The GIL becomes a problem under sustained load or with larger models. It is a scalability ceiling, not a current failure.

4. Distribution is the biggest gap

No Flatpak, AppImage, deb, rpm, or AUR packages exist. The bash install script is robust but a barrier to adoption.

Flatpak is the clear winner: 438M downloads on Flathub (2025), cross-distro, GNOME runtime bundles GTK3 + Python.

---

Proposed Roadmap

Phase 1: Flatpak + Wayland Robustness (Months 1–2)

Goal: Get Vocalinux into users' hands.

• Write Flatpak manifest (com.vocalinux.app.yml)
• Test audio capture, tray icon, and text injection in sandbox
• Add libei/RemoteDesktop portal backend for Flatpak-safe Wayland injection
• Add GlobalShortcuts portal for sandboxed global hotkeys
• Submit to Flathub
• Provide AppImage on GitHub Releases as secondary

Effort: 2–3 months
Risk: Low
Impact: Highest

Phase 2: GTK4 Migration (Months 3–5, parallel)

Goal: Future-proof the UI.

• Create gtk4 branch, keep main on GTK3
• Replace AppIndicator3 with trayer (PyPI) or D-Bus SNI
• Rewrite settings dialog with Adw.PreferencesDialog
• Port about/logging/first-run dialogs
• Audit deprecated GTK3 APIs (event signals, container API)
• Ship GTK4 version once stable, deprecate GTK3 over 6–12 months

Effort: 2–3 months
Risk: Medium
Impact: High

Phase 3: Hybrid Rust Core (Months 6–9, optional)

Goal: Fix GIL jitter without full UI rewrite.

• Extract audio capture + VAD + whisper.cpp into Rust daemon (cpal + whisper-rs)
• Extract text injection into Rust daemon (libei + wtype + clipboard)
• Expose via Unix socket API
• Keep Python GTK4 UI as frontend
• Deliver 80% of Rust's performance benefit with 30% of the effort

Effort: 2–3 months
Risk: Medium
Impact: Medium-High

Phase 4: Full Rust Rewrite (Year 2+, optional)

Goal: Maximum performance, single-binary distribution.

• Only if maintainer has 6–12 months of part-time capacity
• Reuse Rust daemon code from Phase 3
• Port UI to gtk4-rs + libadwaita-rs

Effort: 6–12 months
Risk: High
Impact: High (but diminishing returns after Phase 3)

---

Alternatives Considered

Approach	Time	Distribution	GTK3	GIL	Wayland Flatpak	Verdict
A. Flatpak + Wayland	2–3mo	✅	❌	❌	✅	Do first
B. Python/GTK4	2–3mo	❌	✅	❌	❌	Do parallel
C. Hybrid Rust	2–3mo	❌	❌	✅	✅	Do if needed
D. Rust rewrite	6–12mo	✅	✅	✅	✅	Only if ambitious
A + B	3–4mo	✅	✅	❌	✅	Realistic target
A + B + C	5–7mo	✅	✅	✅	✅	Ideal

---

Open Questions

1. Does the existing Wayland fallback chain cause real user pain? If users report issues, libei portal becomes higher priority.
2. Is AppIndicator3 replacement the biggest GTK4 blocker? Should we drop the system tray in favor of a background daemon + settings window?
3. Is GIL jitter noticeable to users? If not, Phase 3 (hybrid Rust) may be unnecessary.
4. Who would maintain a Flatpak manifest? Is there community interest in helping with packaging?

---

Call for Feedback

This is a starting point for discussion, not a mandate. I'd especially like feedback on:

• Priority ordering (should GTK4 come before Flatpak?)
• The daemon vs foreground process question
• Whether to keep or drop the system tray
• Experiences with libei/RemoteDesktop portal