### Install and Run Development Server

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/web/README.md

Installs project dependencies and starts the development server for Vocalinux website.

```bash
npm install
npm run dev
```

--------------------------------

### Automated Development Setup

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/CONTRIBUTING.md

Use this script for a quick and recommended setup of the development environment. It handles dependency installation and testing.

```bash
git clone https://github.com/YOUR-USERNAME/vocalinux.git
cd vocalinux

# Install in development mode (includes all dev dependencies)
./install.sh --dev
```

--------------------------------

### Manual Development Setup: System Dependencies (Ubuntu)

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/CONTRIBUTING.md

Installs necessary system packages for Ubuntu. Ensure you have `sudo` privileges.

```bash
# Ubuntu
sudo apt update
sudo apt install -y python3-pip python3-gi python3-gi-cairo \
    gir1.2-gtk-3.0 libgirepository1.0-dev \
    python3-dev portaudio19-dev python3-venv xdotool
```

--------------------------------

### Interactive Installation

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/INSTALL.md

Launches the interactive installer script, which guides you through engine selection (whisper.cpp, OpenAI Whisper, or VOSK) and auto-detects hardware.

```bash
./install.sh
```

--------------------------------

### Manual Development Setup: Python Environment

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/CONTRIBUTING.md

Sets up a Python virtual environment and installs the project with development dependencies.

```bash
python3 -m venv venv --system-site-packages
source venv/bin/activate
pip install --upgrade pip setuptools wheel
pip install -e ".[dev]"
```

--------------------------------

### Development Setup for Vocalinux

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/README.md

Steps to clone the Vocalinux repository, install it in development mode, activate the virtual environment, and run tests or the application from source.

```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
```

--------------------------------

### Interactive Install Vocalinux

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/README.md

Use this command to download and run the interactive installer for Vocalinux. It guides you through setup with hardware detection and engine recommendations.

```bash
curl -fsSL raw.githubusercontent.com/jatinkrmalik/vocalinux/main/install.sh -o /tmp/vl.sh && bash /tmp/vl.sh
```

--------------------------------

### Manual Development Setup: System Dependencies (Debian 11/12)

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/CONTRIBUTING.md

Installs necessary system packages for Debian 11/12. Ensure you have `sudo` privileges.

```bash
# Debian 11/12
sudo apt install -y python3-pip python3-gi python3-gi-cairo \
    gir1.2-gtk-3.0 libgirepository1.0-dev libcairo2-dev \
    python3-dev portaudio19-dev python3-venv xdotool
```

--------------------------------

### Manual Development Setup: System Dependencies (Debian 13+)

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/CONTRIBUTING.md

Installs necessary system packages for Debian 13 and newer. Ensure you have `sudo` privileges.

```bash
# Debian 13+
sudo apt install -y python3-pip python3-gi python3-gi-cairo \
    gir1.2-gtk-3.0 libgirepository-2.0-dev libcairo2-dev \
    python3-dev portaudio19-dev python3-venv xdotool
```

--------------------------------

### Display Installer Help

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/INSTALL.md

Shows all available options and modes for the Vocalinux installer script.

```bash
./install.sh --help

```

--------------------------------

### Install from Source

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/INSTALL.md

Clones the Vocalinux repository and runs the install script to build from source.

```bash
git clone https://github.com/jatinkrmalik/vocalinux.git && cd vocalinux && ./install.sh
```

--------------------------------

### Install and Build for Production

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/web/README.md

Installs project dependencies and builds the static site for production deployment.

```bash
npm install
npm run build
```

--------------------------------

### Execute Vocalinux Installer

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/tests/distro-testing-checklist.md

Run the downloaded Vocalinux installation script. Monitor for any errors during the installation process.

```bash
bash /tmp/vl.sh
```

--------------------------------

### Install Vocalinux with Options

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/INSTALL.md

Use the install script to install Vocalinux. The --auto flag reuses an existing pywhispercpp build by default, while --rebuild-whispercpp forces a rebuild.

```bash
./install.sh --auto
```

```bash
./install.sh --auto --rebuild-whispercpp
```

--------------------------------

### Manual Development Setup: Install Pre-commit Hooks

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/CONTRIBUTING.md

Installs pre-commit hooks for automated code style checks before committing. This is optional as CI also performs these checks.

```bash
pre-commit install
```

--------------------------------

### Install Text Injection Tools

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/INSTALL.md

Install 'xdotool' for X11 or 'wtype' for Wayland to enable text injection into applications. Test the installation by typing a short string.

```bash
sudo apt install xdotool
```

```bash
xdotool type "hello"
```

```bash
sudo apt install wtype
```

```bash
wtype "hello"
```

--------------------------------

### Install Vocalinux from PyPI on Ubuntu/Debian

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/INSTALL.md

Installs system packages and then Vocalinux within a virtual environment using pip. Ensure system packages are installed first.

```bash
sudo apt install -y \
    python3-venv python3-dev python3-gi python3-gi-cairo \
    gir1.2-gtk-3.0 gir1.2-ayatanaappindicator3-0.1 \
    libgirepository1.0-dev libcairo2-dev portaudio19-dev \
    pkg-config xdotool wtype

python3 -m venv ~/.local/share/vocalinux-pypi/venv --system-site-packages
source ~/.local/share/vocalinux-pypi/venv/bin/activate
pip install --upgrade pip setuptools wheel
pip install vocalinux
vocalinux
```

--------------------------------

### Manual Development Setup: Appindicator Dependencies

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/CONTRIBUTING.md

Installs dependencies for the appindicator (system tray icon) on different Debian/Ubuntu versions.

```bash
# For appindicator (system tray icon):
# On older Ubuntu:
sudo apt install -y gir1.2-appindicator3-0.1
# On Debian 11+ or newer Ubuntu:
sudo apt install -y gir1.2-ayatanaappindicator3-0.1
```

--------------------------------

### Install Vocalinux from PyPI on Fedora

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/INSTALL.md

Installs system packages and then Vocalinux within a virtual environment using pip. Ensure system packages are installed first.

```bash
sudo dnf install -y \
    python3-virtualenv python3-devel python3-gobject gtk3 gtk3-devel \
    libappindicator-gtk3 gobject-introspection-devel portaudio-devel \
    pkg-config xdotool wtype

python3 -m venv ~/.local/share/vocalinux-pypi/venv --system-site-packages
source ~/.local/share/vocalinux-pypi/venv/bin/activate
pip install --upgrade pip setuptools wheel
pip install vocalinux
vocalinux
```

--------------------------------

### Manual Development Setup: Clone and Navigate

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/CONTRIBUTING.md

Steps to manually clone the repository and navigate into the project directory.

```bash
git clone https://github.com/YOUR-USERNAME/vocalinux.git
cd vocalinux
```

--------------------------------

### Install Vocalinux from PyPI on Arch Linux

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/INSTALL.md

Installs system packages and then Vocalinux within a virtual environment using pip. Ensure system packages are installed first.

```bash
sudo pacman -S --needed \
    python python-virtualenv python-gobject gtk3 libappindicator-gtk3 \
    gobject-introspection python-cairo portaudio pkg-config xdotool wtype

python -m venv ~/.local/share/vocalinux-pypi/venv --system-site-packages
source ~/.local/share/vocalinux-pypi/venv/bin/activate
pip install --upgrade pip setuptools wheel
pip install vocalinux
vocalinux
```

--------------------------------

### Install Vocalinux from Source

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/README.md

Clone the Vocalinux repository and run the install script from the source code. This method allows for more control and is suitable for developers.

```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
```

--------------------------------

### Install Vocalinux with Skipped System Dependencies

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/DISTRO_COMPATIBILITY.md

Installs Vocalinux using the installer script, explicitly skipping the system dependency check and installation phase.

```bash
./install.sh --skip-system-deps
```

--------------------------------

### Manual Development Setup: Run Application

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/CONTRIBUTING.md

Activates the virtual environment and runs the application with debug mode enabled.

```bash
source venv/bin/activate
vocalinux --debug
```

--------------------------------

### Compile and Install ydotool on Debian

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/DISTRO_COMPATIBILITY.md

ydotool is not packaged in Debian's standard repos. Compile it from source if you specifically need it, for example, for KDE Plasma Wayland. The installer falls back to wtype for most Wayland compositors.

```bash
sudo apt install -y git cmake libevdev-dev
git clone https://github.com/ReimuNotMoe/ydotool.git /tmp/ydotool
cmake -S /tmp/ydotool -B /tmp/ydotool/build
sudo cmake --build /tmp/ydotool/build --target install
sudo systemctl enable --now ydotoold
```

--------------------------------

### Automatic Installation with whisper.cpp

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/INSTALL.md

Runs the install script with the --auto flag to skip interactive prompts and use whisper.cpp as the default engine.

```bash
./install.sh --auto
```

--------------------------------

### Install Vocalinux in Development Mode

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/AGENTS.md

Installs the project in development mode, including necessary dependencies for local development.

```bash
# Install in development mode
./install.sh --dev
```

```bash
# Or manually:
pip install -e ".[dev]"
```

--------------------------------

### Install Vocalinux from PyPI on openSUSE Tumbleweed

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/INSTALL.md

Installs system packages and then Vocalinux within a virtual environment using pip. Ensure system packages are installed first. Dynamically determines Python version for package names.

```bash
PYVER=$(python3 -c 'import sys; print(f"python{sys.version_info.major}{sys.version_info.minor}")')

sudo zypper install -y \
    "${PYVER}-gobject" "${PYVER}-gobject-cairo" gtk3 \
    typelib-1_0-AyatanaAppIndicator3-0_1 libayatana-appindicator3-1 \
    typelib-1_0-Notify-0_7 libnotify4 \
    gobject-introspection-devel portaudio-devel "${PYVER}-devel" \
    "${PYVER}-virtualenv" pkg-config xdotool wtype

python3 -m venv ~/.local/share/vocalinux-pypi/venv --system-site-packages
source ~/.local/share/vocalinux-pypi/venv/bin/activate
pip install --upgrade pip setuptools wheel
pip install vocalinux
vocalinux
```

--------------------------------

### Vocalinux Release Announcement Example

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/RELEASE_PROCESS.md

Example markdown for a release announcement in `README.md`, indicating the release phase and its readiness for testing.

```markdown
> 🎉 **Beta Release!**
>
> We're excited to share Vocalinux Beta with the community.
> This release is feature-complete and ready for broader testing.

```

--------------------------------

### Install Neural Voice Activity Detection Support

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/README.md

Command to install the necessary package for neural VAD support in Vocalinux. Restart the application after installation.

```bash
pip install "vocalinux[vad]"
```

--------------------------------

### Automatic Installation with VOSK

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/INSTALL.md

Runs the install script with the --auto flag and specifies the VOSK engine.

```bash
./install.sh --auto --engine=vosk
```

--------------------------------

### Vocalinux Configuration File Example

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/README.md

An example JSON configuration file for Vocalinux, specifying speech recognition engine, model size, VAD sensitivity, and silence timeout.

```json
{
  "speech_recognition": {
    "engine": "whisper_cpp",
    "model_size": "tiny",
    "vad_sensitivity": 3,
    "silence_timeout": 2.0
  }
}
```

--------------------------------

### Install Vocalinux from Source in a Virtual Environment

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/DISTRO_COMPATIBILITY.md

Sets up a Python virtual environment and installs Vocalinux in editable mode from local source, including Whisper dependencies.

```bash
python3 -m venv venv
source venv/bin/activate
pip install -e .[whisper]
```

--------------------------------

### Install Fedora System Packages

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/DISTRO_COMPATIBILITY.md

Installs required development libraries and tools for Vocalinux on Fedora systems.

```bash
sudo dnf install python3-gobject gtk3 gtk3-devel libappindicator-gtk3 \
  gobject-introspection-devel portaudio-devel python3-devel \
  python3-virtualenv pkg-config xdotool wtype
```

--------------------------------

### Install Ubuntu/Debian System Packages

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/DISTRO_COMPATIBILITY.md

Installs necessary development libraries and tools for Vocalinux on Ubuntu and Debian-based systems.

```bash
sudo apt install python3-gi gir1.2-gtk-3.0 gir1.2-ayatanaappindicator3-0.1 \
  libgirepository1.0-dev libcairo2-dev portaudio19-dev python3-dev \
  python3-venv pkg-config xdotool wtype
```

--------------------------------

### Test Installation Script

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/tests/distro-testing-checklist.md

Performs a syntax check on the installation script without actually executing it. This helps catch basic errors in the script.

```bash
bash -n install.sh
```

--------------------------------

### Build and Run whisper.cpp Server

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/HTTP_REMOTE.md

Build the whisper.cpp server from source and start it with a specified model and host/port. Ensure the model is downloaded.

```bash
git clone https://github.com/ggerganov/whisper.cpp
cd whisper.cpp
make server
./models/download-ggml-model.sh medium.en
./build/bin/whisper-server \
    --model models/ggml-medium.en.bin \
    --host 0.0.0.0 \
    --port 8080
```

--------------------------------

### Install openSUSE System Packages

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/DISTRO_COMPATIBILITY.md

Installs necessary development libraries and tools for Vocalinux on openSUSE, dynamically determining Python version.

```bash
PYVER=$(python3 -c 'import sys; print(f"python{sys.version_info.major}{sys.version_info.minor}")')

sudo zypper install "${PYVER}-gobject" "${PYVER}-gobject-cairo" gtk3 \
  typelib-1_0-AyatanaAppIndicator3-0_1 libayatana-appindicator3-1 \
  typelib-1_0-Notify-0_7 libnotify4 \
  portaudio-devel "${PYVER}-devel" "${PYVER}-virtualenv" pkg-config xdotool wtype
```

--------------------------------

### Install Vocalinux via pip

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/DISTRO_COMPATIBILITY.md

Installs the Vocalinux package from the Python Package Index (PyPI).

```bash
pip install vocalinux
```

--------------------------------

### Verify Icon Installation

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/tests/distro-testing-checklist.md

Confirm that Vocalinux icons have been installed in the system's icon directories.

```bash
ls -la ~/.local/share/icons/hicolor/scalable/apps/vocalinux*
```

--------------------------------

### Python Logging Setup

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/AGENTS.md

Shows the standard way to set up a module-level logger in Python using the `logging` module.

```python
import logging
logger = logging.getLogger(__name__)
```

--------------------------------

### Install Vocalinux with Whisper Engine

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/README.md

Install Vocalinux using the default installer script, specifying the 'whisper' engine for PyTorch-based transcription. This option requires an NVIDIA GPU and takes longer due to PyTorch and CUDA downloads.

```bash
curl -fsSL raw.githubusercontent.com/jatinkrmalik/vocalinux/main/install.sh -o /tmp/vl.sh && bash /tmp/vl.sh --engine=whisper
```

--------------------------------

### Install Arch Linux System Packages

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/DISTRO_COMPATIBILITY.md

Installs essential development libraries and tools for Vocalinux on Arch Linux.

```bash
sudo pacman -S python-gobject gtk3 libappindicator gobject-introspection \
  python-cairo portaudio python-virtualenv pkg-config xdotool wtype
```

--------------------------------

### Run Vocalinux After Installation

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/README.md

Commands to launch Vocalinux after installation. It can be run directly if ~/.local/bin is in your PATH, by activating its virtual environment, or by using the full path to the executable.

```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
```

--------------------------------

### Download Vocalinux Installer

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/tests/distro-testing-checklist.md

Download the Vocalinux installation script using curl. Ensure the download is saved to a temporary location for execution.

```bash
curl -fsSL https://raw.githubusercontent.com/jatinkrmalik/vocalinux/main/install.sh -o /tmp/vl.sh
```

--------------------------------

### Automatic Installation with OpenAI Whisper

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/INSTALL.md

Runs the install script with the --auto flag and specifies the OpenAI Whisper engine.

```bash
./install.sh --auto --engine=whisper
```

--------------------------------

### Run Vocalinux Start Minimized

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/INSTALL.md

Launches Vocalinux in a minimized state, skipping initial prompts.

```bash
vocalinux --start-minimized

```

--------------------------------

### Install Vocalinux via pipx

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/DISTRO_COMPATIBILITY.md

Installs the Vocalinux package using the pipx package manager.

```bash
pipx install vocalinux
```

--------------------------------

### Install Solus System Packages

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/DISTRO_COMPATIBILITY.md

Required system packages for Solus.

```bash
sudo eopkg install python3-pip python3-gobject gtk3 libappindicator 
  gobject-introspection-devel portaudio-devel python3-virtualenv pkg-config
```

--------------------------------

### Install Text Injection Tools on openSUSE

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/DISTRO_COMPATIBILITY.md

Installs xdotool and wtype, essential text injection tools for X11 and Wayland sessions, on openSUSE.

```bash
sudo zypper install xdotool wtype
```

--------------------------------

### Install pipx on Fedora

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/DISTRO_COMPATIBILITY.md

Installs the pipx package manager on Fedora systems and ensures its path is set.

```bash
sudo dnf install pipx
pipx ensurepath
```

--------------------------------

### Install pipx on Ubuntu/Debian

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/DISTRO_COMPATIBILITY.md

Installs the pipx package manager on Ubuntu and Debian systems and ensures its path is set.

```bash
sudo apt install pipx
pipx ensurepath
```

--------------------------------

### Development Installation

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/INSTALL.md

Installs Vocalinux in development mode, including additional tools like pytest, black, isort, flake8, and pre-commit.

```bash
./install.sh --dev

```

--------------------------------

### Conventional Commits Examples

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/CONTRIBUTING.md

Demonstrates practical applications of Conventional Commits for different types of changes. These examples show how to format commit messages effectively.

```text
feat(commands): add "select all" voice command
fix(tray): resolve icon not updating on Wayland
docs(readme): update installation instructions
```

--------------------------------

### Create and Activate Virtual Environment for pip Installation

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/DISTRO_COMPATIBILITY.md

Creates a Python virtual environment with system site-packages enabled and installs/upgrades pip, setuptools, and wheel.

```bash
python3 -m venv ~/.local/share/vocalinux-pypi/venv --system-site-packages
source ~/.local/share/vocalinux-pypi/venv/bin/activate
pip install --upgrade pip setuptools wheel
```

--------------------------------

### Install Vocalinux with VOSK Engine

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/README.md

Install Vocalinux with the VOSK engine for low-RAM systems. This is a lightweight option suitable for systems with 4GB of RAM.

```bash
curl -fsSL raw.githubusercontent.com/jatinkrmalik/vocalinux/main/install.sh -o /tmp/vl.sh && bash /tmp/vl.sh --engine=vosk
```

--------------------------------

### Verify Vocalinux Installation

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/tests/distro-testing-checklist.md

Checks for the presence of Vocalinux executables and configuration files in their expected locations after installation.

```bash
ls -la ~/.local/bin/vocalinux*
ls -la ~/.local/share/vocalinux/
ls -la ~/.config/vocalinux/
```

--------------------------------

### Install Dependencies for Ubuntu/Debian

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/DISTRO_COMPATIBILITY.md

Installs necessary packages for Vocalinux on Ubuntu and Debian-based systems. For Debian 11+, use `gir1.2-ayatanaappindicator3-0.1` instead of `gir1.2-appindicator3-0.1`.

```bash
sudo apt install -y python3-gi gir1.2-gtk-3.0 gir1.2-gdkpixbuf-2.0 \
  portaudio19-dev python3-dev python3-venv pkg-config
```

--------------------------------

### Run Vocalinux with Wayland Compatibility

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/INSTALL.md

Starts Vocalinux in Wayland compatibility mode.

```bash
vocalinux --wayland

```

--------------------------------

### Run Vocalinux from Local Bin

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/INSTALL.md

Executes Vocalinux when installed via curl and ~/.local/bin is in the system's PATH.

```bash
vocalinux

```

--------------------------------

### Install System Dependencies on Ubuntu

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/INSTALL.md

Installs necessary system packages for Vocalinux on Ubuntu, including Python development tools, GTK, audio libraries, and utilities for system tray icons and window management.

```bash
sudo apt update
sudo apt install -y \
    python3-pip python3-venv python3-dev \
    python3-gi python3-gi-cairo \
    gir1.2-gtk-3.0 \
    libgirepository1.0-dev portaudio19-dev \
    wget curl unzip

# For appindicator (system tray icon):
# - On older Ubuntu versions:
sudo apt install -y gir1.2-appindicator3-0.1
# - On newer Ubuntu versions:
sudo apt install -y gir1.2-ayatanaappindicator3-0.1

# For X11
sudo apt install -y xdotool

# For Wayland
sudo apt install -y wtype
```

--------------------------------

### Activate Virtual Environment and Run Vocalinux

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/INSTALL.md

Activates the Python virtual environment created from source installation and then runs Vocalinux.

```bash
source venv/bin/activate
vocalinux

```

--------------------------------

### Install pipx on Arch Linux

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/DISTRO_COMPATIBILITY.md

Installs the pipx package manager on Arch Linux systems and ensures its path is set.

```bash
sudo pacman -S pipx
pipx ensurepath
```

--------------------------------

### Install Vocalinux Package

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/INSTALL.md

Installs the Vocalinux package from a local checkout using pip, with options for including Whisper and neural VAD support, or for development mode.

```bash
# Standard installation
pip install .

# With Whisper support
pip install ".[whisper]"

# With neural VAD support
pip install ".[vad]"

# Development mode
pip install -e ".[dev,vad]"
```

--------------------------------

### Install Text Injection Tools on Fedora

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/DISTRO_COMPATIBILITY.md

Installs xdotool and wtype, essential text injection tools for X11 and Wayland sessions, on Fedora.

```bash
sudo dnf install xdotool wtype
```

--------------------------------

### Install System Dependencies on openSUSE Tumbleweed

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/INSTALL.md

Installs system packages for Vocalinux on openSUSE Tumbleweed, dynamically determining the Python version and including optional packages for Vulkan GPU acceleration.

```bash
PYVER=$(python3 -c 'import sys; print(f"python{sys.version_info.major}{sys.version_info.minor}")')

sudo zypper install -y \
    "${PYVER}-pip" "${PYVER}-gobject" "${PYVER}-gobject-cairo" \
    "${PYVER}-devel" "${PYVER}-virtualenv" \
    gtk3 typelib-1_0-AyatanaAppIndicator3-0_1 libayatana-appindicator3-1 \
    typelib-1_0-Notify-0_7 libnotify4 \
    gobject-introspection-devel portaudio-devel pkg-config cmake \
    wget curl unzip xdotool wtype

# Optional: only needed for whisper.cpp Vulkan GPU builds
sudo zypper install -y vulkan-tools vulkan-devel shaderc
```

--------------------------------

### Confirm Wrapper Scripts Exist

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/tests/distro-testing-checklist.md

Verify that the Vocalinux wrapper scripts have been installed in the user's local bin directory.

```bash
ls -la ~/.local/bin/vocalinux*
```

--------------------------------

### Install Mageia System Packages (dnf)

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/DISTRO_COMPATIBILITY.md

Required system packages for Mageia using dnf.

```bash
sudo dnf install -y python3-gobject gtk3-devel gobject-introspection-devel 
  portaudio-devel python3-devel python3-virtualenv pkg-config
```

--------------------------------

### Install Text Injection Tools on Ubuntu/Debian

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/DISTRO_COMPATIBILITY.md

Installs xdotool and wtype, essential text injection tools for X11 and Wayland sessions, on Ubuntu and Debian.

```bash
sudo apt install xdotool wtype
```

--------------------------------

### Install Fedora/RHEL-based System Packages

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/DISTRO_COMPATIBILITY.md

Required system packages for Fedora and RHEL-based distributions.

```bash
sudo dnf install -y python3-gobject gtk3-devel gobject-introspection-devel \
  portaudio-devel python3-devel python3-virtualenv pkg-config
```

--------------------------------

### Run OpenAI-Compatible Server with Speaches

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/HTTP_REMOTE.md

Start an OpenAI-compatible Whisper server using Docker with the Speaches image. The server will be accessible on the specified port.

```bash
docker run --rm -p 8000:8000 ghcr.io/speaches-ai/speaches:latest
```

--------------------------------

### Install Mageia System Packages (urpmi)

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/DISTRO_COMPATIBILITY.md

Required system packages for Mageia using urpmi.

```bash
sudo urpmi -y python3-gobject gtk3-devel gobject-introspection-devel 
  portaudio-devel python3-devel python3-virtualenv pkg-config
```

--------------------------------

### Install System Dependencies on Debian 11/12

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/INSTALL.md

Installs required system packages for Vocalinux on Debian 11/12, covering Python development, GTK, audio libraries, and utilities for system tray icons and window management.

```bash
sudo apt update
sudo apt install -y \
    python3-pip python3-venv python3-dev \
    python3-gi python3-gi-cairo \
    gir1.2-gtk-3.0 \
    libgirepository1.0-dev libcairo2-dev portaudio19-dev \
    wget curl unzip

# For appindicator (system tray icon):
sudo apt install -y gir1.2-ayatanaappindicator3-0.1

# For X11
sudo apt install -y xdotool

# For Wayland
sudo apt install -y wtype
```

--------------------------------

### Install System Dependencies on Fedora

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/INSTALL.md

Installs required system packages for Vocalinux on Fedora, including Python development tools, GTK, audio libraries, and utilities for system tray icons and window management.

```bash
sudo dnf install -y \
    python3-pip python3-devel python3-virtualenv \
    python3-gobject gtk3 libappindicator-gtk3 \
    gobject-introspection-devel portaudio-devel \
    wget curl unzip xdotool
```

--------------------------------

### Install System Dependencies on Arch Linux

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/INSTALL.md

Installs necessary system packages for Vocalinux on Arch Linux, including Python development tools, GTK, audio libraries, and utilities for system tray icons and window management.

```bash
sudo pacman -S --noconfirm \
    python-pip python-gobject gtk3 \
    libappindicator-gtk3 gobject-introspection \
    python-cairo portaudio python-virtualenv \
    wget curl unzip xdotool
```

--------------------------------

### Website Development Commands

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/AGENTS.md

Commands for managing the Next.js website, including installation, development server, building, and linting.

```bash
cd web
npm install
npm run dev      # Development server
npm run build    # Production build
npm run lint     # ESLint
npm run test     # Jest tests
```

--------------------------------

### Install Gentoo System Packages

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/DISTRO_COMPATIBILITY.md

Required system packages for Gentoo. Note that Gentoo compiles packages from source, which will take longer.

```bash
sudo emerge dev-python/pygobject:3 x11-libs/gtk+:3 dev-libs/libappindicator:3 
  media-libs/portaudio dev-lang/python:3.9
```

--------------------------------

### Install Void Linux System Packages

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/DISTRO_COMPATIBILITY.md

Required system packages for Void Linux.

```bash
sudo xbps-install -Sy python3-pip python3-gobject gtk+3 libappindicator 
  gobject-introspection portaudio-devel python3-devel pkg-config
```

--------------------------------

### Verify libwhisper.so Resolution on Debian

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/DISTRO_COMPATIBILITY.md

If Vocalinux fails to start due to libwhisper.so.1, use this command to check for unresolved symbols in pywhispercpp shared objects. If libraries are not found, re-run the installer or switch to the VOSK engine.

```bash
ldd $(find ~/.local/share/vocalinux/venv -name '*.so' -path '*/pywhispercpp*' 2>/dev/null | head -1) | grep 'not found'
```

--------------------------------

### Install Debian pywhispercpp Build Prerequisites

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/DISTRO_COMPATIBILITY.md

On a clean Debian install, these packages are required when pywhispercpp must be compiled from source, such as for GPU support. The installer now installs these automatically.

```bash
sudo apt install -y libssl-dev autoconf automake libtool patchelf
```

--------------------------------

### Set Up Desktop Integration

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/INSTALL.md

Configures Vocalinux for desktop integration by creating necessary directories, copying the desktop entry file, updating its executable path, and installing application icons.

```bash
# 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
```

--------------------------------

### Manual Deployment Script

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/web/README.md

Builds the static site and prepares it for GitHub Pages deployment by adding .nojekyll and CNAME files.

```bash
cd web
npm install
npm run deploy
```

--------------------------------

### Run Vocalinux after pip installation

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/DISTRO_COMPATIBILITY.md

Executes the Vocalinux application after it has been installed using pip.

```bash
vocalinux
```

--------------------------------

### Start Local Test Server for Remote API

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/CONTRIBUTING.md

Launch a local mock server to simulate the remote speech recognition API. This is essential for testing the remote API functionality without a live server.

```bash
# Start the test server (default: port 8080)
python scripts/test_remote_server.py

# Custom port
python scripts/test_remote_server.py --port 9000

# Simulate processing delay (useful for testing timeouts)
python scripts/test_remote_server.py --delay 2
```

--------------------------------

### Display System Release Information

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/tests/distro-testing-checklist.md

Use this command to display the distribution name and version. This is a crucial first step in documenting the testing environment.

```bash
cat /etc/os-release
```

--------------------------------

### Create and Activate Virtual Environment

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/INSTALL.md

Sets up a Python virtual environment named 'venv' with system site packages enabled, activates it, and upgrades pip, setuptools, and wheel.

```bash
cd vocalinux
python3 -m venv venv --system-site-packages
source venv/bin/activate
pip install --upgrade pip setuptools wheel
```

--------------------------------

### Install Missing Dependencies on Arch

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/UPDATE.md

Install required Python and GTK+ 3 dependencies for Vocalinux on Arch Linux.

```bash
# Arch
sudo pacman -S python-gobject gtk3
```

--------------------------------

### Install Missing Dependencies on Fedora

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/UPDATE.md

Install required Python and GTK+ 3 dependencies for Vocalinux on Fedora systems.

```bash
# Fedora
sudo dnf install -y python3-gobject gtk3
```

--------------------------------

### Install Missing Dependencies on Ubuntu/Debian

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/UPDATE.md

Install required Python and GTK+ 3 dependencies for Vocalinux on Ubuntu or Debian-based systems.

```bash
# Ubuntu/Debian
sudo apt update
sudo apt install -y python3-gi python3-gi-cairo gir1.2-gtk-3.0
```

--------------------------------

### Display Vocalinux Command Line Options

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/INSTALL.md

Shows all available command-line options for running the Vocalinux application.

```bash
vocalinux --help

```

--------------------------------

### Manual Uninstallation Steps

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/INSTALL.md

Perform a manual uninstallation by removing application files, user data, and desktop entries. Remember to update the icon cache afterwards.

```bash
rm -rf venv
rm -f activate-vocalinux.sh
```

```bash
rm -rf ~/.config/vocalinux
rm -rf ~/.local/share/vocalinux
```

```bash
rm -f ~/.local/share/applications/vocalinux.desktop
rm -f ~/.local/share/icons/hicolor/scalable/apps/vocalinux*.svg
```

```bash
gtk-update-icon-cache -f -t ~/.local/share/icons/hicolor
```

--------------------------------

### Run Verification Suite

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/RELEASE_PROCESS.md

Execute the full suite of tests, linting, type checking, and build commands for verification.

```bash
# Run tests
make test

# Run linting
make lint

# Run type checking
make typecheck

# Build package
make build

# Website build
cd web && npm run build && cd ..

# Install script sanity checks (optional but recommended)
bash -n install.sh
./install.sh --help | grep -- --tag
```

--------------------------------

### Check Desktop Entry Creation

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/tests/distro-testing-checklist.md

Ensure the desktop entry file for Vocalinux has been created, allowing it to appear in application menus.

```bash
ls -la ~/.local/share/applications/vocalinux.desktop
```

--------------------------------

### Install Text Injection Tools on Arch Linux

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/DISTRO_COMPATIBILITY.md

Installs xdotool and wtype, essential text injection tools for X11 and Wayland sessions, on Arch Linux.

```bash
sudo pacman -S xdotool wtype
```

--------------------------------

### Conventional Commits Type Examples

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/AGENTS.md

Examples of commit types used in Conventional Commits, such as 'feat' for new features, 'fix' for bug fixes, and 'docs' for documentation updates.

```markdown
feat(commands): add "select all" voice command
```

```markdown
fix(tray): resolve icon not updating on Wayland
```

```markdown
docs(readme): update installation instructions
```

--------------------------------

### Update Vocalinux Changelog in UPDATE.md

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/RELEASE_PROCESS.md

Example markdown for adding a 'What's New' section to `docs/UPDATE.md` for a new release, including a link to the full changelog.

```markdown
## What's New in v0.5.0-beta

- Feature 1
- Feature 2
- Bug fix 1

See the [full changelog](https://github.com/jatinkrmalik/vocalinux/releases/tag/v0.5.0-beta).

---

## Previous Versions

### v0.4.1-alpha
...
```

--------------------------------

### Update Vocalinux Installation

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/SECURITY.md

Follow these steps to update your Vocalinux installation to the latest version, ensuring you have the most recent security fixes. This involves pulling the latest code and reinstalling dependencies.

```bash
cd vocalinux
git pull origin main
pip install --upgrade -e .
```

--------------------------------

### Verify Virtual Environment Creation

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/tests/distro-testing-checklist.md

Check if the virtual environment for Vocalinux was successfully created in the user's local share directory.

```bash
ls -la ~/.local/share/vocalinux/venv/
```

--------------------------------

### Update Vocalinux from Source to Latest Development Version

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/UPDATE.md

Use this method if you installed Vocalinux from source and want to update to the latest development version. It involves pulling the latest changes from the main branch and running the install script.

```bash
cd vocalinux
git pull origin main
./install.sh
```

--------------------------------

### Install System Dependencies on Debian 13+

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/INSTALL.md

Installs essential system packages for Vocalinux on Debian 13 and later, including Python development tools, GTK, audio libraries, and utilities for system tray icons and window management.

```bash
sudo apt update
sudo apt install -y \
    python3-pip python3-venv python3-dev \
    python3-gi python3-gi-cairo \
    gir1.2-gtk-3.0 \
    libgirepository-2.0-dev libcairo2-dev portaudio19-dev \
    wget curl unzip

# For appindicator (system tray icon):
sudo apt install -y gir1.2-ayatanaappindicator3-0.1

# For X11
sudo apt install -y xdotool

# For Wayland
sudo apt install -y wtype
```

--------------------------------

### Update Vocalinux from Source to a Specific Version

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/docs/UPDATE.md

Use this method if you installed Vocalinux from source and want to update to a specific tagged version. It involves navigating to the project directory, fetching changes, checking out the desired tag, and running the install script.

```bash
cd vocalinux
git fetch origin
git checkout v0.12.0-beta
./install.sh
```

--------------------------------

### Check System Architecture

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/tests/distro-testing-checklist.md

Verify the system's architecture. This ensures compatibility with any architecture-specific builds or requirements.

```bash
uname -m
```

--------------------------------

### Launch Vocalinux GUI from Terminal

Source: https://github.com/jatinkrmalik/vocalinux/blob/main/tests/distro-testing-checklist.md

Launch the Vocalinux graphical user interface directly from the terminal using its executable path. Check for startup errors and tray icon appearance.

```bash
~/.local/bin/vocalinux-gui
```