Files

T

Jatin K MalikandGitHub 9886e8cb9d feat(ui): add auto-start on boot support (#207 )

* feat(ui): add auto-start on boot support

- Add --start-minimized CLI flag for autostart entry
- Create autostart_manager.py to handle XDG autostart desktop entry
- Add autostart config option in config_manager.py
- Add Start on Login toggle in Settings dialog
- Add Start Minimized toggle in Settings dialog
- Add Start on Login checkbox in system tray menu
- Add first-run dialog to ask about autostart preference

Closes #184

* fix(test): add first_run: False to mock config settings

The tests were failing with StopIteration because main() now checks
for first_run and shows a dialog if True. By setting first_run: False
in the mock config, we skip the first-run dialog code path.

* fix(ui): harden autostart behavior across Linux sessions

Use XDG-compliant autostart paths and robust Exec command resolution, keep first-run prompt semantics correct, and fix GTK toggle handling so state changes are applied reliably.

* docs(autostart): document XDG startup model and limits

Clarify that Vocalinux uses desktop-session XDG autostart, not systemd services, and explain compatibility expectations for mainstream DEs versus minimal/custom WM sessions.

* feat(ui): add first-run quick-start guidance text

Expand the welcome dialog with concise first-time usage guidance and clear direction to the tray menu Settings entry while preserving the existing autostart decision flow.

* fix(uninstall): remove XDG autostart desktop entry

Ensure uninstall removes ~/.config autostart registration and reports leftover autostart entries during verification.

* fix(install): ignore defunct processes in running-check

Filter installer process detection to exclude defunct entries and installer/uninstaller shells so stale zombie rows do not block reinstall.

* fix(uninstall): ignore defunct processes in running-check

Use filtered process detection so zombie entries and installer shells do not trigger false running-process warnings during uninstall.

2026-02-21 15:06:20 -08:00

5.8 KiB

Raw Blame History

User Guide

This guide explains how to use Vocalinux effectively.

Getting Started

After installing Vocalinux (see the Installation Guide), you can start the application from the terminal and optionally enable start-on-login.

Vocalinux supports login autostart using the standard Linux desktop-session mechanism.

Where to enable it:
- First-run welcome dialog
- Tray menu: Start on Login
- Settings dialog: Start on Login
What Vocalinux creates:
- vocalinux.desktop in $XDG_CONFIG_HOME/autostart/ or ~/.config/autostart/
How it starts:
- As a regular user GUI app in your desktop session (--start-minimized)
What it does not do:
- It does not create a systemd service/unit for autostart

Desktop Compatibility Notes

Works on most mainstream desktop environments (GNOME, KDE, Xfce, Cinnamon, MATE, LXQt)
On minimal/custom window managers, autostart may require an autostart manager or desktop-specific startup hook

Basic Usage

Starting and Stopping Voice Typing

Launch the application: Run vocalinux in a terminal or launch it from your application menu
Find the tray icon: Look for the microphone icon in your system tray
Start voice typing: Click the tray icon and select "Start Voice Typing" from the menu, or use the double-tap Ctrl keyboard shortcut
Speak clearly: As you speak, your words will be transcribed into the currently focused application
Stop voice typing: Click the tray icon and select "Stop Voice Typing" when you're done, or use the double-tap Ctrl keyboard shortcut again

Understanding the Status Icons

Microphone off (gray): Voice typing is inactive
Microphone on (blue): Voice typing is active and listening
Microphone processing (orange): Voice typing is processing your speech

Voice Commands

Vocalinux supports several commands that you can speak to control formatting:

Command	Action
"new line" or "new paragraph"	Inserts a line break
"period" or "full stop"	Types a period (.)
"comma"	Types a comma (,)
"question mark"	Types a question mark (?)
"exclamation point" or "exclamation mark"	Types an exclamation point (!)
"semicolon"	Types a semicolon (;)
"colon"	Types a colon (:)
"delete that" or "scratch that"	Deletes the last sentence
"capitalize" or "uppercase"	Capitalizes the next word
"all caps"	Makes the next word ALL CAPS

Tips for Better Recognition

Use a good microphone: A quality microphone significantly improves recognition accuracy
Speak clearly: Enunciate your words clearly but naturally
Moderate pace: Don't speak too quickly or too slowly
Quiet environment: Minimize background noise when possible
Learn commands: Familiarize yourself with voice commands for punctuation and formatting
Use GPU acceleration: If you have a GPU (AMD, Intel, or NVIDIA), whisper.cpp will automatically use it for faster transcription
Choose the right model:
- For real-time dictation: Use tiny or base (fastest)
- For better accuracy: Use vocalinux --model medium or --model large
Check debug logs: Run vocalinux --debug to see which backend is being used (Vulkan, CUDA, or CPU)

Customization

Keyboard Shortcut

Vocalinux uses a double-tap Ctrl keyboard shortcut for starting and stopping voice typing:

Double-tap Ctrl: Quickly press the Ctrl key twice to toggle voice typing on or off
The time between taps should be less than 0.3 seconds to be recognized as a double-tap

Model Settings

You can change the speech recognition engine and model for better accuracy or faster performance:

Choosing Your Engine

Vocalinux now offers three speech recognition engines:

whisper.cpp ⭐ (Default) - High-performance C++ engine
- Fastest installation (~1-2 min)
- Works with AMD, Intel, NVIDIA GPUs via Vulkan
- True multi-threading (no Python GIL)
- Best for most users
Whisper (OpenAI) - PyTorch-based engine
- NVIDIA GPU only (requires CUDA)
- Larger download (~2.3GB with PyTorch)
- Installation takes ~5-10 min
- Use if you specifically need PyTorch features
VOSK - Lightweight engine
- Smallest footprint (~40MB)
- CPU only
- Great for older systems or minimal resource usage

Changing Engine and Model

Open settings from the tray icon menu (right-click)
Go to the "Recognition" tab
Select your Speech Engine:
- whisper_cpp (recommended)
- whisper
- vosk
Select your Model Size:
- tiny (~39MB) - Fastest, good for real-time dictation
- base (~74MB) - Good balance
- small (~244MB) - Better accuracy
- medium (~769MB) - High accuracy
- large (~1.5GB) - Best accuracy, slower

When to Use Each Model

For real-time dictation: Use tiny or base - they're fast enough to keep up with your speech.

For transcription: Use small or medium - better accuracy for recorded audio.

For maximum accuracy: Use large - best results but requires more RAM and GPU power.

GPU Acceleration

whisper.cpp automatically uses GPU acceleration when available:

Vulkan (AMD, Intel, NVIDIA) - Automatically detected and used
CUDA (NVIDIA only) - Fallback if Vulkan not available
CPU - Always works as fallback

To check which backend is being used, look for these log messages when starting Vocalinux:

[INFO] whisper.cpp using Vulkan GPU backend: AMD Radeon RX 6800
[INFO] whisper.cpp configured with n_threads=16

Troubleshooting

If you encounter issues, check the Installation Guide troubleshooting section or run the application with debug logging:

vocalinux --debug

Check the logs for error messages and possible solutions.

5.8 KiB Raw Blame History