Jatin K MalikandGitHub
2d85afee70
* feat(docs): add Voca Ecosystem section to README and website Add cross-project ecosystem shoutouts linking VocaLinux, VocaMac, and VocaWin. README gets a table with platform, project, website, GitHub, and status columns. Website gets animated cards with platform logos, tech badges, status indicators, and links. Uses simpleicons CDN for Apple logo and inline SVG for Windows logo (simpleicons CDN does not serve a Windows icon). * feat(web): UI refinements — terminal install boxes, contrast fixes, wider card grids - Replace CodeBlock components with terminal-style command boxes (traffic-light dots, copy button, dark bg) - Fix dark mode contrast: add dark:text-black to badges and buttons on green backgrounds - Header: replace GitHub icon with filled yellow Star icon next to star count - Hero buttons: rename and reorder (Install Now, We're Open Source, Use Windows or Mac?) - Engine section: widen container from max-w-5xl to max-w-7xl to match features - Ecosystem section: add VocaLinux 'You are here' card, widen from max-w-4xl to max-w-7xl - Fix Windows icon color to official Microsoft Fluent blue (#0078D4) - Remove unused CodeBlock import * feat(web): link sub-pages, reorder cards, restyle hero, update FAQ, remove em-dashes - Add href prop to FeatureCard: 6 tiles link to /offline/, /use-cases/, /gpu-acceleration/, /shortcuts/, /wayland/, /for-developers/ - Engine section: reorder to Whisper > whisper.cpp (center) > VOSK, move 'Compare all engines' to centered link below cards - whisper.cpp card keeps 'GPU acceleration' link - FAQ answers: convert to ReactNode with inline links to sub-pages, fix 6 stale answers (distros, requirements, languages, shortcuts, voice commands, engine switching) - Hero buttons: GitHub-dark 'We're Open Source', ghost 'Use Windows or Mac?' - Ecosystem: reorder to VocaMac > VocaLinux (center) > VocaWin, change badge from 'You are here' to 'Beta' - Remove all em-dashes (9 occurrences)
408 lines
16 KiB
Markdown
408 lines
16 KiB
Markdown
# <img src="https://github.com/user-attachments/assets/56dabe5c-5c65-44d5-a36a-429c9fea0719" width="30" height="30"> Vocalinux
|
|
|
|
#### Voice-to-text for Linux, finally done right!
|
|
|
|
<!-- Project Status -->
|
|
[](https://github.com/jatinkrmalik/vocalinux)
|
|
[](https://github.com/jatinkrmalik/vocalinux/releases)
|
|
[](https://www.gnu.org/licenses/gpl-3.0)
|
|
|
|
|
|
<!-- Build & Quality -->
|
|
[](https://github.com/jatinkrmalik/vocalinux/actions)
|
|
[](https://github.com/jatinkrmalik/vocalinux)
|
|
[](https://www.python.org/downloads/)
|
|
[](https://www.gtk.org/)
|
|
[](https://codecov.io/gh/jatinkrmalik/vocalinux)
|
|
|
|
<!-- Tech & Community -->
|
|
[](https://github.com/jatinkrmalik/vocalinux/stargazers)
|
|
[](https://github.com/jatinkrmalik/vocalinux/network)
|
|
[](https://github.com/jatinkrmalik/vocalinux/watchers)
|
|
[](https://github.com/jatinkrmalik/vocalinux/commits)
|
|
[](https://github.com/jatinkrmalik/vocalinux/commits)
|
|
[](CONTRIBUTING.md)
|
|
[](https://github.com/jatinkrmalik/vocalinux/issues)
|
|
|
|
|
|
|
|
**A seamless free open-source private voice dictation system for Linux**, comparable to built-in solutions on macOS and Windows.
|
|
|
|
## 📚 What's New in v0.9.0-beta
|
|
|
|
> 🎉 **Release: Left/Right modifier keys, sound effects toggle, Wayland clipboard fallback, and more.**
|
|
|
|
### 🚀 Highlights (v0.8.0 → v0.9.0)
|
|
|
|
| Feature | Description |
|
|
|---------|-------------|
|
|
| **⌨️ Left/Right Modifier Keys** | Choose Left Ctrl vs Right Ctrl (etc.) as your shortcut trigger |
|
|
| **🔔 Sound Effects Toggle** | Enable or disable audio feedback from the Settings dialog |
|
|
| **📋 Wayland Clipboard Fallback** | Automatic clipboard copy when virtual keyboard injection isn't available |
|
|
| **🛠️ Installation Polish** | Better pipx/Debian guidance and headless display detection |
|
|
|
|
### ✨ New Features (v0.9.0)
|
|
|
|
- **Left/Right Modifier Key Distinction** — Shortcuts now support `Left Ctrl`, `Right Alt`, etc., with grouped UI in Settings
|
|
- **Sound Effects Toggle** — New Audio Settings toggle to silence start/stop/error sounds
|
|
- **Clipboard Fallback for Wayland** — Auto-copies text via `wl-copy`/`xclip` when injection unavailable (KDE Plasma etc.)
|
|
- **Display Availability Check** — Graceful error message when running in headless environments
|
|
|
|
### 🐛 Bug Fixes (v0.9.0)
|
|
|
|
- **#308**: Distinguish left vs right modifier keys (evdev + pynput backends)
|
|
- **#307**: Remove unwanted leading space when starting a new transcription session
|
|
- **#305**: Pass configured shortcut mode to `KeyboardShortcutManager` on startup
|
|
- **#299**: Add clipboard fallback for Wayland compositors without virtual keyboard support
|
|
- **#289**: Improve Debian/pipx installation error messages and cross-distro dependency guidance
|
|
|
|
### 🔧 Improvements
|
|
|
|
- **Grouped shortcut selector** — Settings dropdown now organises shortcuts by Either/Left/Right side
|
|
- **pipx documentation** — New `DISTRO_COMPATIBILITY.md` section for pipx users
|
|
|
|
---
|
|
|
|
## ✨ Features
|
|
|
|
- 🎤 **Toggle or Push-to-Talk** activation modes
|
|
- ⚡ **Real-time transcription** with minimal latency
|
|
- 🌎 **Universal compatibility** across all Linux applications
|
|
- 🔒 **100% Offline operation** for privacy and reliability
|
|
- 🤖 **whisper.cpp by default** - High-performance C++ speech recognition
|
|
- 🎮 **Universal GPU support** - Vulkan acceleration for AMD, Intel, and NVIDIA
|
|
- 🎨 **System tray integration** with visual status indicators
|
|
- 🚀 **Start on login support** via XDG autostart (desktop-session startup)
|
|
- 🔊 **Pleasant audio feedback** - smooth gliding tones, headphone-friendly
|
|
- ⚙️ **Graphical settings** dialog for easy configuration
|
|
- 📦 **3 engine choices** - whisper.cpp (default), OpenAI Whisper, or VOSK
|
|
|
|
## 📸 Screenshots
|
|
|
|
Here are some screenshots showcasing Vocalinux in action:
|
|
|
|
<table>
|
|
<tr>
|
|
<td align="center">
|
|
<img src="resources/screenshots/00-transcription.png" alt="Transcription in Action" width="350"><br>
|
|
<em>Real-time voice-to-text transcription</em>
|
|
</td>
|
|
<td align="center">
|
|
<img src="resources/screenshots/02-system-tray.png" alt="System Tray" width="350"><br>
|
|
<em>System tray with listening indicator</em>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center">
|
|
<img src="resources/screenshots/05-about-view.png" alt="About View" width="350"><br>
|
|
<em>About view with version info</em>
|
|
</td>
|
|
<td align="center">
|
|
<img src="resources/screenshots/03-log-viewer.png" alt="Log Viewer" width="350"><br>
|
|
<em>Log viewer for debugging</em>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="2" align="center">
|
|
<img src="resources/screenshots/04-features-overview.png" alt="Features Overview" width="500"><br>
|
|
<em>Overview of key features and configuration options with annotations</em>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
## 🚀 Quick Install
|
|
|
|
### Interactive Install (Recommended)
|
|
|
|
Our new interactive installer guides you through setup with intelligent hardware detection:
|
|
|
|
```bash
|
|
curl -fsSL raw.githubusercontent.com/jatinkrmalik/vocalinux/main/install.sh -o /tmp/vl.sh && bash /tmp/vl.sh
|
|
```
|
|
|
|
**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
|
|
|
|
The installer will:
|
|
- **Auto-detect your hardware** (GPU, RAM, Vulkan support)
|
|
- **Recommend the best engine** for your system
|
|
- **Download the appropriate model** (~39MB for whisper.cpp tiny)
|
|
- **Install in ~1-2 minutes** (vs 5-10 min with old Whisper)
|
|
|
|
> **Note**: Always installs the latest release. For a specific version, check [GitHub Releases](https://github.com/jatinkrmalik/vocalinux/releases).
|
|
|
|
### Installation Options
|
|
|
|
**Default (whisper.cpp - recommended):**
|
|
```bash
|
|
curl -fsSL raw.githubusercontent.com/jatinkrmalik/vocalinux/main/install.sh -o /tmp/vl.sh && bash /tmp/vl.sh
|
|
```
|
|
Fastest installation (~1-2 min), universal GPU support via Vulkan.
|
|
|
|
**Whisper (OpenAI) - if you prefer PyTorch:**
|
|
```bash
|
|
curl -fsSL raw.githubusercontent.com/jatinkrmalik/vocalinux/main/install.sh -o /tmp/vl.sh && bash /tmp/vl.sh --engine=whisper
|
|
```
|
|
NVIDIA GPU only (~5-10 min, downloads PyTorch + CUDA).
|
|
|
|
**VOSK only - for low-RAM systems:**
|
|
```bash
|
|
curl -fsSL raw.githubusercontent.com/jatinkrmalik/vocalinux/main/install.sh -o /tmp/vl.sh && bash /tmp/vl.sh --engine=vosk
|
|
```
|
|
Lightweight option (~40MB), works on systems with 4GB RAM.
|
|
|
|
### Alternative: Install from Source
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone https://github.com/jatinkrmalik/vocalinux.git
|
|
cd vocalinux
|
|
|
|
# Run the installer (will prompt for Whisper)
|
|
./install.sh
|
|
|
|
# Or with Whisper support
|
|
./install.sh --with-whisper
|
|
```
|
|
|
|
The installer handles everything: system dependencies, Python environment, speech models, and desktop integration.
|
|
|
|
### 🌙 Nightly Releases (Bleeding Edge)
|
|
|
|
For developers and early adopters who want to test the latest features, check out our [GitHub Releases page](https://github.com/jatinkrmalik/vocalinux/releases) which includes both beta and nightly builds.
|
|
|
|
> **⚠️ Warning**: Nightly releases contain the absolute latest code and may be unstable. For production use, we recommend using the latest beta release.
|
|
|
|
Nightly builds are automatically generated from the `main` branch every day. They include all merged changes but haven't undergone the same testing as beta releases.
|
|
|
|
**Release Channels:**
|
|
- **Beta** (Recommended) — Tested pre-releases with known features
|
|
- **Nightly** — Untested bleeding edge with latest commits
|
|
|
|
### After Installation
|
|
|
|
```bash
|
|
# If ~/.local/bin is in your PATH (recommended):
|
|
vocalinux
|
|
|
|
# Or activate the virtual environment first:
|
|
source ~/.local/bin/activate-vocalinux.sh
|
|
vocalinux
|
|
|
|
# Or run directly:
|
|
~/.local/share/vocalinux/venv/bin/vocalinux
|
|
```
|
|
|
|
Or launch it from your application menu!
|
|
|
|
## 📋 Requirements
|
|
|
|
- **OS**: Linux (tested on Ubuntu 22.04+, Debian 11+, Fedora 39+, Arch Linux, openSUSE Tumbleweed)
|
|
- **Python**: 3.8 or newer
|
|
- **Display**: X11 or Wayland
|
|
- **Hardware**: Microphone for voice input
|
|
|
|
**Note:** See [Distribution Compatibility](docs/DISTRO_COMPATIBILITY.md) for distribution-specific information and experimental support for Gentoo, Alpine, Void, Solus, and more.
|
|
|
|
## 🎙️ Usage
|
|
|
|
### Voice Dictation
|
|
|
|
1. **Toggle mode**: Double-tap the shortcut key (default Ctrl) to start recording
|
|
2. Speak clearly into your microphone
|
|
3. **Toggle mode**: Double-tap again (or pause speaking) to stop, or **Push-to-Talk mode**: release the key to stop
|
|
|
|
### Voice Commands
|
|
|
|
| Command | Action |
|
|
|---------|--------|
|
|
| "new line" | Inserts a line break |
|
|
| "period" / "full stop" | Types a period (.) |
|
|
| "comma" | Types a comma (,) |
|
|
| "question mark" | Types a question mark (?) |
|
|
| "exclamation mark" | Types an exclamation mark (!) |
|
|
| "delete that" | Deletes the last sentence |
|
|
| "capitalize" | Capitalizes the next word |
|
|
|
|
### Command Line Options
|
|
|
|
```bash
|
|
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 medium # Use medium-sized model
|
|
vocalinux --wayland # Force Wayland mode
|
|
vocalinux --start-minimized # Start without first-run modal prompts
|
|
```
|
|
|
|
### Autostart on Login
|
|
|
|
Vocalinux uses the Linux desktop standard for autostart:
|
|
|
|
- **Mechanism**: XDG autostart desktop entry (`vocalinux.desktop`)
|
|
- **Path**: `$XDG_CONFIG_HOME/autostart/` or `~/.config/autostart/` (fallback)
|
|
- **Launch mode**: Starts as a regular **user desktop app** in your graphical session
|
|
- **Not used**: No `systemd` unit/service is created by Vocalinux for autostart
|
|
|
|
How to enable/disable:
|
|
|
|
- First-run welcome dialog
|
|
- Tray menu: **Start on Login**
|
|
- Settings dialog: **Start on Login**
|
|
|
|
Compatibility notes:
|
|
|
|
- Works on mainstream desktop environments (GNOME, KDE, Xfce, Cinnamon, MATE, LXQt)
|
|
- On minimal/custom window-manager sessions, an autostart handler may be required
|
|
(for example DE-specific startup hooks or tools like `dex`)
|
|
|
|
## ⚙️ Configuration
|
|
|
|
Configuration is stored in `~/.config/vocalinux/config.json`:
|
|
|
|
```json
|
|
{
|
|
"speech_recognition": {
|
|
"engine": "whisper_cpp",
|
|
"model_size": "tiny",
|
|
"vad_sensitivity": 3,
|
|
"silence_timeout": 2.0
|
|
}
|
|
}
|
|
```
|
|
|
|
You can also configure settings through the graphical Settings dialog (right-click the tray icon).
|
|
|
|
## 🔧 Development Setup
|
|
|
|
```bash
|
|
# Clone and install in dev mode
|
|
git clone https://github.com/jatinkrmalik/vocalinux.git
|
|
cd vocalinux
|
|
./install.sh --dev
|
|
|
|
# Activate environment
|
|
source venv/bin/activate
|
|
|
|
# Run tests
|
|
pytest
|
|
|
|
# Run from source with debug
|
|
python -m vocalinux.main --debug
|
|
```
|
|
|
|
## 📁 Project Structure
|
|
|
|
```
|
|
vocalinux/
|
|
├── src/vocalinux/ # Main application code
|
|
│ ├── speech_recognition/ # Speech recognition engines (VOSK, Whisper, whisper.cpp)
|
|
│ │ └── recognition_manager.py # Unified engine interface
|
|
│ ├── text_injection/ # Text injection (X11/Wayland)
|
|
│ ├── ui/ # GTK UI components
|
|
│ └── utils/ # Utility functions
|
|
│ ├── whispercpp_model_info.py # whisper.cpp model metadata & hardware detection
|
|
│ └── vosk_model_info.py # VOSK model metadata
|
|
├── tests/ # Test suite
|
|
├── scripts/ # Development utilities
|
|
│ └── generate_sounds.py # Sound generation script
|
|
├── resources/ # Icons and sounds
|
|
├── docs/ # Documentation
|
|
└── web/ # Website source
|
|
```
|
|
|
|
## 📖 Documentation
|
|
|
|
- [Installation Guide](docs/INSTALL.md) - Detailed installation instructions
|
|
- [Update Guide](docs/UPDATE.md) - How to update Vocalinux
|
|
- [User Guide](docs/USER_GUIDE.md) - Complete user documentation
|
|
- [Distribution Compatibility](docs/DISTRO_COMPATIBILITY.md) - Distro/session behavior and caveats
|
|
- [Contributing](CONTRIBUTING.md) - Development setup and contribution guidelines
|
|
|
|
## 🔊 Sound Customization
|
|
|
|
Vocalinux uses smooth, pleasant gliding tones for audio feedback:
|
|
|
|
- **Start**: Ascending F4→A4 (0.6s) - positive, uplifting
|
|
- **Stop**: Descending A4→F4 (0.6s) - resolves completion
|
|
- **Error**: Lower descending E4→C4 (0.7s) - gentle but noticeable
|
|
|
|
All sounds use pure sine waves with smoothstep interpolation for buttery smooth pitch transitions - perfect for headphone use!
|
|
|
|
### Regenerate Sounds
|
|
|
|
To modify or regenerate the notification sounds:
|
|
|
|
```bash
|
|
python scripts/generate_sounds.py
|
|
```
|
|
|
|
This script generates all three sounds using the same smooth glide algorithm. You can edit the frequencies, durations, and amplitudes in the script to customize the sounds to your preference.
|
|
|
|
## 🗺️ Roadmap
|
|
|
|
- [x] ~~Custom icon design~~ ✅
|
|
- [x] ~~Graphical settings dialog~~ ✅
|
|
- [x] ~~Whisper AI support~~ ✅
|
|
- [x] ~~Multi-language support (FR, DE, RU)~~ ✅
|
|
- [x] ~~whisper.cpp integration (default engine)~~ ✅
|
|
- [x] ~~Vulkan GPU support~~ ✅
|
|
- [ ] In-app update mechanism
|
|
- [ ] Application-specific commands
|
|
- [ ] Debian/Ubuntu package (.deb)
|
|
- [x] ~~Wayland support via IBus~~ ✅
|
|
- [ ] Voice command customization
|
|
|
|
## 🌐 The Voca Ecosystem
|
|
|
|
Vocalinux is part of a family of privacy-first, offline voice dictation tools. Same mission, every operating system.
|
|
|
|
| Platform | Project | Website | GitHub | Status |
|
|
|----------|---------|---------|--------|--------|
|
|
| 🐧 Linux | **VocaLinux** | [vocalinux.com](https://vocalinux.com) | [jatinkrmalik/vocalinux](https://github.com/jatinkrmalik/vocalinux) | ✅ Beta v0.9.0 |
|
|
| 🍎 macOS | **VocaMac** | [vocamac.com](https://vocamac.com) | [jatinkrmalik/vocamac](https://github.com/jatinkrmalik/vocamac) | 🚀 Beta |
|
|
| 🪟 Windows | **VocaWin** | [vocawin.com](https://vocawin.com) | [jatinkrmalik/vocawin](https://github.com/jatinkrmalik/vocawin) | 📋 Planned |
|
|
|
|
> Each platform uses native technologies for the best possible integration, while sharing the same privacy-first philosophy and offline-only architecture.
|
|
|
|
## 🤝 Contributing
|
|
|
|
We welcome contributions! Whether it's bug reports, feature requests, or code contributions, please check out our [Contributing Guide](CONTRIBUTING.md).
|
|
|
|
### Contributors
|
|
|
|
Thanks to everyone who has contributed to Vocalinux! 🙌
|
|
|
|
<a href="https://github.com/jatinkrmalik/vocalinux/graphs/contributors">
|
|
<img src="https://contrib.rocks/image?repo=jatinkrmalik/vocalinux" />
|
|
</a>
|
|
|
|
### Quick Links
|
|
|
|
- 🐛 [Report a Bug](https://github.com/jatinkrmalik/vocalinux/issues/new?template=bug_report.md)
|
|
- 💡 [Request a Feature](https://github.com/jatinkrmalik/vocalinux/issues/new?template=feature_request.md)
|
|
- 💬 [Discussions](https://github.com/jatinkrmalik/vocalinux/discussions)
|
|
|
|
|
|
## ⭐ Support
|
|
|
|
If you find Vocalinux useful, please consider:
|
|
- ⭐ Starring this repository
|
|
- 🐛 Reporting bugs you encounter
|
|
- 📖 Improving documentation
|
|
- 🔀 Contributing code
|
|
|
|
## 📜 License
|
|
|
|
This project is licensed under the **GNU General Public License v3.0** - see the [LICENSE](LICENSE) file for details.
|
|
|
|
---
|
|
|
|
<p align="center">
|
|
Made with ❤️ for the Linux community
|
|
</p>
|