Jatin K MalikandGitHub
1dc1d44665
* feat: prepare for v0.2.0-alpha release * feat: prepare for v0.2.0-alpha release * chore: remove CHANGELOG.md, use GitHub Releases instead * refactor: use existing About dialog instead of Settings section * style: enhance About dialog UI readability * style: fix formatting with black and isort * feat: show VAD and silence timeout settings for Whisper engine - Renamed 'VOSK Settings' to 'Recognition Settings' - VAD Sensitivity and Silence Timeout now apply to both engines - Added tooltips explaining each setting - VOSK-specific model info only shown when VOSK selected * fix: resolve overlapping UI elements in settings dialog * fix: save VAD and silence timeout settings for both engines Previously these settings were only saved when VOSK was selected. Now they persist correctly for Whisper as well. * fix: show download progress when selecting undownloaded model Previously when auto-applying settings, models would download silently in the background without showing the progress dialog. Now: - Download progress dialog appears for undownloaded models - Model icons update correctly after download completes * feat: add download progress, speed, ETA and cancel button - Show real download progress percentage for VOSK models - Display download speed (MB/s) and estimated time remaining - Add Cancel button to abort downloads - Update status during extraction phase - Whisper downloads still pulse (uses internal downloader) * fix: defer model download until needed, don't block startup - App now starts instantly even if models aren't downloaded - Models are downloaded on-demand when selected in Settings - If user tries to dictate without a model, plays error sound - Added model_ready property to check if engine is usable * fix: improve first-run UX without downloaded models - Settings dialog now defaults to smallest available model, not saved config - Only show saved model if it's actually downloaded - Add desktop notification when trying to dictate without a model - Prevents auto-downloading large models on first launch * feat: add download progress tracking for Whisper models - Implement custom Whisper model download with progress/speed/ETA - Uses OpenAI's CDN URLs directly instead of whisper.load_model() - Progress callback works the same as VOSK downloads - Supports cancellation during download * fix: enable download progress callback for Whisper models Progress callback was only being set for VOSK downloads, not Whisper. Now both engines show real-time progress, speed, and ETA. * fix: update tests for defer_download and config manager mocking - test_main: Mock ConfigManager to prevent saved config from overriding test values - test_settings_dialog: Mock ModelDownloadDialog to prevent GTK init errors - test_speech_recognition: Use proper MockVoskModule class instead of MagicMock, pass defer_download=False for download test - test_whisper_support: Pass defer_download=False to trigger model loading in test * fix: resolve test failures for CI - test_main: Fix ConfigManager patch path to use source module - test_settings_dialog: Mock _is_vosk_model_downloaded and _is_whisper_model_downloaded to skip download flow, add missing dialog attributes - test_speech_recognition: Replace recognizer with properly configured mock that returns valid JSON, fixing test isolation issues when running all tests together * fix: mock _download_whisper_model in whisper test to avoid requests exception handling issue * fix: add gir1.2-girepository-2.0 dep for PyGObject on Ubuntu 24.04 - Add missing girepository-2.0 package for newer Ubuntu runners - Use --no-build-isolation for PyGObject to use system packages * fix: skip PyGObject pip install, use system python3-gi package - Use --no-deps for editable install to skip PyGObject - Install other deps explicitly without PyGObject - Add python3-gi-cairo for complete GTK support - Removes problematic girepository-2.0 build requirement * fix: install PyGObject via pip with proper build deps - Remove python3-gi/python3-gi-cairo (doesn't work with setup-python) - Install PyGObject from pip after installing build dependencies - Simplify venv setup without --system-site-packages hack * Fix GObject * fix: set GI_TYPELIB_PATH for pip-installed PyGObject to find AppIndicator3
7.3 KiB
7.3 KiB
Installation Guide
This guide provides detailed instructions for installing Vocalinux on Linux systems.
Quick Start
One-liner Installation
git clone https://github.com/jatinkrmalik/vocalinux.git && cd vocalinux && ./install.sh
That's it! The installer handles everything automatically.
System Requirements
| Requirement | Details |
|---|---|
| Operating System | Ubuntu 22.04+ (recommended), Debian 11+, Fedora 38+, Arch Linux |
| Python | 3.8 or newer |
| Display Server | X11 or Wayland |
| Hardware | Microphone for speech input |
| Disk Space | ~500MB (including speech models) |
| RAM | 4GB minimum, 8GB recommended for Whisper |
Installation Options
Standard Installation
# Clone the repository
git clone https://github.com/jatinkrmalik/vocalinux.git
cd vocalinux
# Run the installer
./install.sh
Installation with Whisper Support
Whisper provides better accuracy but requires more resources:
./install.sh --with-whisper
Development Installation
For contributing or development work:
./install.sh --dev
This installs additional tools: pytest, black, isort, flake8, pre-commit.
All Installer Options
./install.sh --help
Options:
--dev Install in development mode with all dev dependencies
--test Run tests after installation
--venv-dir=PATH Specify custom virtual environment directory (default: venv)
--skip-models Skip downloading VOSK models during installation
--with-whisper Install Whisper AI support (requires more disk space)
--help Show this help message
What the Installer Does
- Detects your Linux distribution and installs appropriate system packages
- Creates a Python virtual environment with system site-packages access
- Installs the Vocalinux package and all dependencies
- Downloads speech recognition models (VOSK small model by default)
- Installs desktop integration (icons, .desktop file)
- Creates activation script for easy environment activation
Running Vocalinux
After installation:
# Activate the virtual environment
source activate-vocalinux.sh
# Run Vocalinux
vocalinux
Command Line Options
vocalinux --help # Show all options
vocalinux --debug # Enable debug logging
vocalinux --engine whisper # Use Whisper AI engine
vocalinux --engine vosk # Use VOSK engine (default)
vocalinux --model small # Use small model
vocalinux --model medium # Use medium model
vocalinux --model large # Use large model
vocalinux --wayland # Force Wayland compatibility mode
Directory Structure
Vocalinux follows the XDG Base Directory Specification:
| Directory | Purpose |
|---|---|
~/.config/vocalinux/ |
Configuration files |
~/.local/share/vocalinux/ |
Application data, speech models |
~/.local/share/applications/ |
Desktop entry |
~/.local/share/icons/hicolor/scalable/apps/ |
Application icons |
Manual Installation
If you prefer manual installation or the automatic installer doesn't work:
1. Install System Dependencies
Ubuntu/Debian:
sudo apt update
sudo apt install -y \
python3-pip python3-venv python3-dev \
python3-gi python3-gi-cairo \
gir1.2-gtk-3.0 gir1.2-appindicator3-0.1 \
libgirepository1.0-dev portaudio19-dev \
wget curl unzip
# For X11
sudo apt install -y xdotool
# For Wayland
sudo apt install -y wtype
Fedora:
sudo dnf install -y \
python3-pip python3-devel python3-virtualenv \
python3-gobject gtk3 libappindicator-gtk3 \
gobject-introspection-devel portaudio-devel \
wget curl unzip xdotool
Arch Linux:
sudo pacman -S --noconfirm \
python-pip python-gobject gtk3 \
libappindicator-gtk3 gobject-introspection \
python-cairo portaudio python-virtualenv \
wget curl unzip xdotool
2. Create Virtual Environment
cd vocalinux
python3 -m venv venv --system-site-packages
source venv/bin/activate
pip install --upgrade pip setuptools wheel
3. Install Package
# Standard installation
pip install .
# With Whisper support
pip install ".[whisper]"
# Development mode
pip install -e ".[dev]"
4. Set Up Desktop Integration
# Create directories
mkdir -p ~/.config/vocalinux
mkdir -p ~/.local/share/vocalinux/models
mkdir -p ~/.local/share/applications
mkdir -p ~/.local/share/icons/hicolor/scalable/apps
# Install desktop entry
cp vocalinux.desktop ~/.local/share/applications/
VENV_PATH=$(realpath venv/bin/vocalinux)
sed -i "s|^Exec=vocalinux|Exec=$VENV_PATH|" ~/.local/share/applications/vocalinux.desktop
# Install icons
cp resources/icons/scalable/*.svg ~/.local/share/icons/hicolor/scalable/apps/
# Update icon cache
gtk-update-icon-cache -f -t ~/.local/share/icons/hicolor
Troubleshooting
Virtual Environment Issues
Symptom: "command not found: vocalinux"
Solution:
# Make sure you've activated the environment
source activate-vocalinux.sh
# Or activate directly
source venv/bin/activate
Audio Input Problems
Symptom: "No audio detected" or microphone not working
Solutions:
- Check system audio settings
- Run
arecord -lto list audio devices - Try with debug mode:
vocalinux --debug - Check microphone permissions
GTK/AppIndicator Errors
Symptom: "No module named gi" or AppIndicator errors
Solution:
# Reinstall GTK dependencies
sudo apt install python3-gi python3-gi-cairo gir1.2-appindicator3-0.1
# Recreate venv with system packages
rm -rf venv
python3 -m venv venv --system-site-packages
source venv/bin/activate
pip install -e .
Text Injection Not Working
Symptom: Recognized text doesn't appear in applications
Solutions:
For X11:
sudo apt install xdotool
# Test: xdotool type "hello"
For Wayland:
sudo apt install wtype
# Test: wtype "hello"
Model Download Fails
Symptom: Can't download speech models
Solution:
# Models will auto-download on first run
# Or manually download:
mkdir -p ~/.local/share/vocalinux/models
cd ~/.local/share/vocalinux/models
wget https://alphacephei.com/vosk/models/vosk-model-small-en-us-0.15.zip
unzip vosk-model-small-en-us-0.15.zip
Icons Not Displaying
Symptom: Tray icon missing or generic
Solution:
# Refresh icon cache
gtk-update-icon-cache -f -t ~/.local/share/icons/hicolor
# Restart the application
Uninstallation
Using the Uninstaller
./uninstall.sh
Options:
--keep-config- Keep configuration files--keep-data- Keep application data (models, etc.)
Manual Uninstallation
# Remove application files
rm -rf venv
rm -f activate-vocalinux.sh
# Remove user data
rm -rf ~/.config/vocalinux
rm -rf ~/.local/share/vocalinux
rm -f ~/.local/share/applications/vocalinux.desktop
rm -f ~/.local/share/icons/hicolor/scalable/apps/vocalinux*.svg
# Update icon cache
gtk-update-icon-cache -f -t ~/.local/share/icons/hicolor