How jatinkrmalik/vocalinux works
Project Type and Purpose
• Vocalinux is primarily a desktop voice-dictation application for Linux (Python-based, offline speech-to-text with injection into arbitrary apps)
• It also contains a separate Next.js/React-based static “web” folder for the project’s website/documentation
File-Structure Analysis
Top-level directories and their roles:
• .github/ – CI pipelines (release, unified-pipeline)
• docs/ – Installation and user guides
• src/vocalinux/ – Core application code
– common_types.py – shared data types
– main.py – CLI entrypoint & startup orchestration
– speech_recognition/ – RecognitionManager + CommandProcessor
– text_injection/ – TextInjector & OS-injection logic
– ui/ – TrayIndicator, dialogs, config & logging managers, keyboard shortcut handling, audio feedback
• tests/ – Pytest suite for each module
• web/ – Next.js site (React components, hooks, Tailwind, Dockerfile)
Key README Insights
• Hot-key activation (double-tap Ctrl)
• Offline engines: VOSK or Whisper
• Real-time transcription → command processing (“new line”, “period”) → keystroke injection
• Configurable via JSON in ~/.config/vocalinux/
• Separate “web” site purely for marketing/documentation
a. Main Components
• CLI Entrypoint (main.py)
• Hotkey Listener & UI Layer
– TrayIndicator, SettingsDialog, LoggingDialog
• Core Orchestrator
– RecognitionManager (manages engines & recording sessions)
– CommandProcessor (maps transcripts to actions)
• Speech-Recognition Engines
– VOSK engine wrapper
– Whisper engine wrapper
• TextInjector
– Injects keystrokes/text into active window (X11/Wayland)
• AudioFeedback
– Plays start/stop/error sounds via ResourceManager
• ResourceManager
• ConfigManager
– Loads/saves JSON config; injected wherever needed
• OS & External Layers
– X11/Wayland desktop environment
– System audio input/output
– Keyboard event APIs
– Next.js app (layout.tsx, page.tsx)
– React components, hooks, API utilities
– Static hosting / Dockerized build
b. Relationships & Data Flows
1. User double-taps Ctrl → Hotkey Listener in UI
2. UI notifies RecognitionManager → start audio capture
3. Audio data → chosen engine (VOSK/Whisper) → transcript
4. Transcript → CommandProcessor → either:
– Plain text → TextInjector → OS → active window
– Control commands (new line, delete) → OS actions
5. RecognitionManager emits events → AudioFeedback (start/stop/error)
7. ConfigManager consults user settings at startup & on-the-fly
c. Architectural Patterns & Principles
• Layered architecture (Entrypoint → UI → Core → OS)
• Separation of concerns (recognition, injection, UI, config, resources)
• Event-driven flows (hotkey events, recognition events, UI events)
• Plug-in style for engines (VOSK vs. Whisper)
d. Key Technologies
• Python 3.8+, virtualenv (activate-vocalinux.sh)
• Speech engines: VOSK, Whisper
• GTK/PyGObject or equivalent for tray & dialogs
• OS hooks: evdev/libinput or xdotool for injection
• JSON for config (~/.config/vocalinux/config.json)
• Node.js, Next.js, React, Tailwind CSS for the web site
• GitHub Actions for CI/CD