xavierk/voculinux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity

chore(release): prepare v0.6.0-beta with whisper.cpp as default (#181)

Browse Source 
* docs: update all documentation for whisper.cpp as default engine

Comprehensive documentation update highlighting whisper.cpp as the new
default speech recognition engine:

README.md:
- Added 'Major Change: whisper.cpp is Now Default!' section
- Updated Features to highlight whisper.cpp and Vulkan GPU support
- Updated Quick Install section with engine choices
- Changed default engine from whisper to whisper_cpp in examples
- Updated configuration examples
- Updated roadmap to mark whisper.cpp as complete

docs/INSTALL.md:
- Added whisper.cpp section with performance benefits
- Updated installation options (--engine flag)
- Added GPU support matrix and Vulkan detection info
- Added installation time comparison table
- Updated system requirements (lower disk space for whisper.cpp)

docs/USER_GUIDE.md:
- Added comprehensive 'Choosing Your Engine' section
- Added GPU acceleration information
- Updated tips to mention whisper.cpp benefits
- Added model size recommendations

web/src/app/page.tsx:
- Updated hero to mention whisper.cpp (C++ optimized, Vulkan support)
- Changed installation time from ~5-10 min to ~1-2 min
- Updated Features section to mention Vulkan GPU support
- Added whisper.cpp as default engine card (3-column layout)
- Updated installation commands (--engine flags)
- Updated FAQ about switching engines

This ensures all documentation reflects whisper.cpp as the new default
and highlights its major benefits: 10x faster install, universal GPU
support, and C++ optimized performance.

* chore(release): prepare v0.6.0-beta

This release brings whisper.cpp as the new default speech recognition engine:

Version Updates:
- Bump version from 0.5.0-beta to 0.6.0-beta
- Update src/vocalinux/version.py
- Update web/package.json

Documentation Updates:
- README.md: Update all v0.5.0-beta references to v0.6.0-beta
- docs/INSTALL.md: Update version references and installation commands
- docs/UPDATE.md: Add new 'What's New' section highlighting whisper.cpp
- SECURITY.md: Update supported versions table (0.6.x now supported)

Website Updates:
- web/src/app/layout.tsx: Update softwareVersion to 0.6.0-beta

Release Highlights:
- whisper.cpp is now the default engine (10x faster install!)
- Universal GPU support via Vulkan (AMD, Intel, NVIDIA)
- C++ optimized inference with multi-threading
- ~1-2 minute installation vs ~5-10 minutes before

Testing:
- All 472 tests passing
- Black formatting clean
- Flake8 linting clean
- isort import ordering clean

* ui(website): improve hero section layout

* docs(readme): remove duplicate What's New section
This commit is contained in:
Jatin K Malik
2026-02-11 20:33:28 -08:00
committed by GitHub
parent 051c84fd84
commit 03d55a989f
9 changed files with 403 additions and 178 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/INSTALL.md
+142 -34
View File
@@ -2,19 +2,23 @@
This guide provides detailed instructions for installing Vocalinux on Linux systems.
## Quick Start
## 🚀 Quick Start
### One-liner Installation (Recommended)
```bash
curl -fsSL https://raw.githubusercontent.com/jatinkrmalik/vocalinux/main/install.sh | bash -s -- --tag=v0.5.0-beta
curl -fsSL https://raw.githubusercontent.com/jatinkrmalik/vocalinux/main/install.sh | bash -s -- --tag=v0.6.0-beta
```
> **Note**: Installs v0.5.0-beta. For other versions, check [GitHub Releases](https://github.com/jatinkrmalik/vocalinux/releases).
> **Note**: Installs v0.6.0-beta with **whisper.cpp** (our new default engine). For other versions, check [GitHub Releases](https://github.com/jatinkrmalik/vocalinux/releases).
That's it! The installer handles everything automatically, including Whisper AI support.
That's it! The installer handles everything automatically:
- ✅ Installs whisper.cpp (~1-2 minutes, no heavy dependencies!)
- ✅ Auto-detects your GPU (AMD, Intel, NVIDIA all supported)
- ✅ Downloads the tiny model (~39MB)
- ✅ Configures everything automatically
> ⏱️ **Note**: Installation takes ~5-10 minutes due to Whisper AI dependencies.
> ⏱️ **Installation Time**: ~1-2 minutes (vs 5-10 minutes with old Whisper AI)
### From Source
@@ -30,28 +34,45 @@ git clone https://github.com/jatinkrmalik/vocalinux.git && cd vocalinux && ./ins
| **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 |
| **Disk Space** | ~200MB (including whisper.cpp model) |
| **RAM** | 4GB minimum, works great with 8GB |
### GPU Support (Optional)
**whisper.cpp** supports GPU acceleration via **Vulkan**, which works with:
- ✅ AMD GPUs (RX series, integrated graphics)
- ✅ Intel GPUs (Arc, integrated graphics)
- ✅ NVIDIA GPUs (RTX, GTX series)
No special drivers needed - if your GPU supports Vulkan, whisper.cpp will use it automatically!
To check Vulkan support: `vulkaninfo --summary`
## Installation Options
### Standard Installation
### Interactive Installation (Recommended)
The new interactive installer guides you through engine selection:
```bash
# Clone the repository
git clone https://github.com/jatinkrmalik/vocalinux.git
cd vocalinux
# Run the installer
./install.sh
```
### Installation with Whisper Support
**Choose your engine:**
1. **whisper.cpp** ⭐ (Recommended) - Fast, works with any GPU via Vulkan
2. **Whisper** (OpenAI) - PyTorch-based, NVIDIA GPU only
3. **VOSK** - Lightweight, works on older systems
Whisper provides better accuracy but requires more resources:
The installer will auto-detect your hardware and recommend the best option!
### Automatic Installation
Skip the interactive prompts with `--auto`:
```bash
./install.sh --with-whisper
./install.sh --auto # Default: whisper.cpp
./install.sh --auto --engine=whisper # Use OpenAI Whisper
./install.sh --auto --engine=vosk # Use VOSK only
```
### Development Installation
@@ -69,15 +90,27 @@ This installs additional tools: pytest, black, isort, flake8, pre-commit.
```bash
./install.sh --help
Installation Modes:
(no flags) Interactive mode - guided setup with recommendations
--auto Automatic mode - install with defaults (whisper.cpp)
--auto --engine=whisper Auto mode with Whisper engine
Options:
--interactive, -i Force interactive mode (default)
--auto Non-interactive automatic installation
--engine=NAME Speech engine: whisper_cpp (default), whisper, vosk
--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 (default in curl install)
--no-whisper Skip Whisper installation (faster, VOSK only)
-y, --yes Non-interactive mode (accept defaults)
--venv-dir=PATH Specify custom virtual environment directory
--skip-models Skip downloading speech models during installation
--tag=TAG Install specific release tag
--help Show this help message
Examples:
./install.sh # Interactive mode (recommended)
./install.sh --auto # Auto-install with whisper.cpp
./install.sh --auto --engine=vosk # Auto-install VOSK only
./install.sh --dev --test # Dev mode with tests
```
## What the Installer Does
@@ -85,9 +118,24 @@ Options:
1. **Detects your Linux distribution** and installs appropriate system packages
2. **Creates a Python virtual environment** with system site-packages access
3. **Installs the Vocalinux package** and all dependencies
4. **Downloads speech recognition models** (Whisper tiny model by default, VOSK as fallback)
5. **Installs desktop integration** (icons, .desktop file)
6. **Creates activation script** for easy environment activation
4. **Installs the speech recognition engine** you selected:
- **whisper.cpp** (default): High-performance C++ engine with Vulkan GPU support
- **Whisper**: OpenAI's PyTorch-based engine (NVIDIA GPU only)
- **VOSK**: Lightweight engine for older systems
5. **Downloads speech recognition models**:
- whisper.cpp: ~39MB tiny model (or larger if selected)
- Whisper: ~75MB tiny model + PyTorch dependencies (~2.3GB with CUDA)
- VOSK: ~40MB small model
6. **Installs desktop integration** (icons, .desktop file)
7. **Creates activation script** for easy environment activation
### Installation Time Comparison
| Engine | Download Size | Install Time | GPU Support |
|--------|---------------|--------------|-------------|
| **whisper.cpp** (default) | ~39-500MB | ~1-2 min | AMD, Intel, NVIDIA (Vulkan) |
| Whisper (OpenAI) | ~2.3GB+ | ~5-10 min | NVIDIA only (CUDA) |
| VOSK | ~40MB | ~30 sec | CPU only |
## Running Vocalinux
@@ -108,15 +156,16 @@ vocalinux
### Command Line Options
```bash
vocalinux --help # Show all options
vocalinux --debug # Enable debug logging
vocalinux --engine whisper # Use Whisper AI engine (default)
vocalinux --engine vosk # Use VOSK engine
vocalinux --model tiny # Use tiny model (default, fastest)
vocalinux --model small # Use small model
vocalinux --model medium # Use medium model
vocalinux --model large # Use large model
vocalinux --wayland # Force Wayland compatibility mode
vocalinux --help # Show all options
vocalinux --debug # Enable debug logging
vocalinux --engine whisper_cpp # Use whisper.cpp engine (default)
vocalinux --engine whisper # Use OpenAI Whisper engine
vocalinux --engine vosk # Use VOSK engine
vocalinux --model tiny # Use tiny model (default, fastest)
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
@@ -260,6 +309,65 @@ cp resources/icons/scalable/*.svg ~/.local/share/icons/hicolor/scalable/apps/
gtk-update-icon-cache -f -t ~/.local/share/icons/hicolor
```
## About whisper.cpp
### What is whisper.cpp?
**whisper.cpp** is a high-performance C++ port of OpenAI's Whisper speech recognition model. It's now the **default engine** in Vocalinux because it offers significant advantages:
**Performance Benefits:**
- **10x faster installation** - No 2.3GB PyTorch download (just ~39MB model)
- **C++ optimized inference** - Faster than Python-based Whisper
- **True multi-threading** - Uses all CPU cores (no Python GIL limitations)
- **Lower memory usage** - More efficient than PyTorch
**GPU Support:**
- **Vulkan acceleration** - Works with AMD, Intel, and NVIDIA GPUs
- **Automatic backend selection** - Uses Vulkan → CUDA → CPU (in that order)
- **No special drivers** - Just needs standard Vulkan support
**Models:**
whisper.cpp uses the same models as OpenAI Whisper, converted to `ggml` format:
- **tiny** (~39MB) - Fastest, good for real-time dictation
- **base** (~74MB) - Good balance of speed and accuracy
- **small** (~244MB) - Better accuracy, still fast
- **medium** (~769MB) - High accuracy
- **large** (~1.5GB) - Best accuracy, slower
### Checking GPU Support
To verify your GPU is detected:
```bash
# Check Vulkan support (for AMD, Intel, NVIDIA)
vulkaninfo --summary | grep -i "deviceName"
# In Vocalinux, look for these log messages:
# [INFO] whisper.cpp backend selection priority: Vulkan -> CUDA -> CPU
# [INFO] whisper.cpp using Vulkan GPU backend: AMD Radeon RX 6800
```
### Switching Engines
If you want to try a different engine after installation:
```bash
# Edit the config file
nano ~/.config/vocalinux/config.json
```
Change the `engine` field:
```json
{
"speech_recognition": {
"engine": "whisper_cpp", // Options: whisper_cpp, whisper, vosk
"model_size": "tiny"
}
}
```
Or use the GUI: Right-click tray icon → Settings → Speech Engine
## Troubleshooting
### Virtual Environment Issues
@@ -387,7 +495,7 @@ Already have Vocalinux installed? See the [Update Guide](UPDATE.md) for instruct
Quick update command:
```bash
curl -fsSL https://raw.githubusercontent.com/jatinkrmalik/vocalinux/main/install.sh | bash -s -- --tag=v0.5.0-beta
curl -fsSL https://raw.githubusercontent.com/jatinkrmalik/vocalinux/main/install.sh | bash -s -- --tag=v0.6.0-beta
```
## Getting Help
docs/UPDATE.md
+23 -14
View File
@@ -9,7 +9,7 @@ This guide explains how to update Vocalinux to the latest version.
Simply re-run the installation command with the new version tag:
```bash
curl -fsSL https://raw.githubusercontent.com/jatinkrmalik/vocalinux/main/install.sh | bash -s -- --tag=v0.5.0-beta
curl -fsSL https://raw.githubusercontent.com/jatinkrmalik/vocalinux/main/install.sh | bash -s -- --tag=v0.6.0-beta
```
The installer will:
@@ -24,7 +24,7 @@ The installer will:
```bash
cd vocalinux
git fetch origin
git checkout v0.5.0-beta
git checkout v0.6.0-beta
./install.sh
```
@@ -50,7 +50,7 @@ cd vocalinux
./install.sh --tag=v0.4.1-alpha
# Or via curl (for any installation)
curl -fsSL https://raw.githubusercontent.com/jatinkrmalik/vocalinux/main/install.sh | bash -s -- --tag=v0.5.0-beta
curl -fsSL https://raw.githubusercontent.com/jatinkrmalik/vocalinux/main/install.sh | bash -s -- --tag=v0.6.0-beta
```
**What gets preserved:**
@@ -68,7 +68,7 @@ cd vocalinux
# 2. Pull the latest changes
git fetch origin
git checkout v0.5.0-beta
git checkout v0.6.0-beta
# 3. Activate your virtual environment
source venv/bin/activate
@@ -97,17 +97,26 @@ git describe --tags
---
## What's New in v0.5.0-beta
## What's New in v0.6.0-beta
- **Customizable keyboard shortcuts**: Configure your own activation shortcuts via GUI
- **Modern settings dialog**: Redesigned with GNOME HIG styling
- **Improved audio feedback**: Pleasant gliding tones for recording status
- **Enhanced Wayland support**: Better keyboard shortcut handling on Wayland
- **Microphone reconnection**: Automatic reconnection when microphone disconnects
- **80%+ test coverage**: Comprehensive test suite for reliability
- **Interactive installer**: Smart hardware detection and guided installation
### 🚀 Major Feature: whisper.cpp is Now Default!
See the [full changelog](https://github.com/jatinkrmalik/vocalinux/releases/tag/v0.5.0-beta).
This release brings **whisper.cpp** as the new default speech recognition engine—a game-changing upgrade!
**Key Improvements:**
- **⚡ 10x faster installation** — No more 2.3GB PyTorch downloads (~1-2 min vs ~5-10 min)
- **🎮 Universal GPU support** — Works with AMD, Intel, and NVIDIA via Vulkan (not just NVIDIA CUDA)
- **💾 Smaller footprint** — Tiny model is only ~39MB vs ~75MB
- **🔥 Better performance** — C++ optimized inference with true multi-threading (no Python GIL)
- **🌍 99+ languages** with automatic language detection
**Additional Improvements:**
- **Interactive installer**: Choose between 3 engines (whisper.cpp, Whisper, VOSK)
- **Hardware auto-detection**: Automatically detects your GPU and recommends optimal settings
- **Enhanced logging**: Comprehensive debug info for whisper.cpp troubleshooting
- **Better documentation**: Updated all docs to reflect whisper.cpp as the new default
See the [full changelog](https://github.com/jatinkrmalik/vocalinux/releases/tag/v0.6.0-beta).
---
@@ -142,7 +151,7 @@ See the [full changelog](https://github.com/jatinkrmalik/vocalinux/releases/tag/
./uninstall.sh --keep-config --keep-data
# Reinstall
curl -fsSL https://raw.githubusercontent.com/jatinkrmalik/vocalinux/main/install.sh | bash -s -- --tag=v0.5.0-beta
curl -fsSL https://raw.githubusercontent.com/jatinkrmalik/vocalinux/main/install.sh | bash -s -- --tag=v0.6.0-beta
```
### Old Version Still Running
docs/USER_GUIDE.md
+62 -5
View File
@@ -46,7 +46,11 @@ Vocalinux supports several commands that you can speak to control formatting:
3. **Moderate pace**: Don't speak too quickly or too slowly
4. **Quiet environment**: Minimize background noise when possible
5. **Learn commands**: Familiarize yourself with voice commands for punctuation and formatting
6. **Use larger models**: For better accuracy, use `vocalinux --model medium` or `--model large`
6. **Use GPU acceleration**: If you have a GPU (AMD, Intel, or NVIDIA), whisper.cpp will automatically use it for faster transcription
7. **Choose the right model**:
- For real-time dictation: Use `tiny` or `base` (fastest)
- For better accuracy: Use `vocalinux --model medium` or `--model large`
8. **Check debug logs**: Run `vocalinux --debug` to see which backend is being used (Vulkan, CUDA, or CPU)
## Customization
@@ -59,12 +63,65 @@ Vocalinux uses a double-tap Ctrl keyboard shortcut for starting and stopping voi
### Model Settings
You can change the speech recognition model for better accuracy or faster performance:
You can change the speech recognition engine and model for better accuracy or faster performance:
1. Open settings from the tray icon menu
### Choosing Your Engine
Vocalinux now offers **three speech recognition engines**:
1. **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
2. **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
3. **VOSK** - Lightweight engine
- Smallest footprint (~40MB)
- CPU only
- Great for older systems or minimal resource usage
### Changing Engine and Model
1. Open settings from the tray icon menu (right-click)
2. Go to the "Recognition" tab
3. Select your preferred model size (tiny is the default, use larger models for better accuracy)
4. Choose between Whisper (default, more accurate) and VOSK (lighter weight, faster)
3. Select your **Speech Engine**:
- whisper_cpp (recommended)
- whisper
- vosk
4. 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