Wyoming & Whisper Vulkan

A containerized speech-to-text service for Home Assistant using:

• whisper.cpp for high-performance ASR
• Vulkan GPU acceleration
• Wyoming protocol for Home Assistant integration
• Separated Wyoming and Whisper for distributed solutions
• Multilingual support (English/French auto-detection)

This project is a modified fork/derivative of: 👉 https://github.com/jstebbins/wyoming-whisper-vulkan-service

Licensed under GNU General Public License (GPL) (see LICENSE for details).

---

🚀 Features

• GPU-accelerated inference via Vulkan (AMD/Intel/NVIDIA where supported)
• Runs entirely in Docker (no host dependencies beyond GPU drivers)
• Home Assistant Wyoming integration compatible
• Multilingual Whisper model support (depends on model for auto language detection)
• Persistent model storage via Docker volumes
• Designed for self-hosted LAN or VPN use

---

🧠 Architecture

Home Assistant
      │
      │ Wyoming TCP (8888)
      ▼
Wyoming Service
      │
      | Whisper HTTP (8910)
      ▼
whisper.cpp (Vulkan backend)

---

Requirements

• Docker + Docker Compose
• Linux host with Vulkan support (optional but recommended)
• GPU drivers installed (Mesa / AMDVLK / NVIDIA Vulkan support)
• Home Assistant with Wyoming integration

---

Quick Start

1. Clone the repository

git clone https://git.armstrong-services.ca/BlazingNeutron/wyoming-whisper-vulkan.git
cd wyoming-whisper-vulkan

2. Build and start

docker compose up -d

Configuration

Environment variables

Variable	Description	Default
WHISPER_MODEL	Whisper model name	large-v3-turbo
WHISPER_LANG	Language hint (optional)	auto-detect
WYOMING_PORT	Internal service port	8888
WHISPER_URL	Whisper Inference URL	http://whisper:8910/inference

Models

Models are stored in a Docker volume:

/opt/whisper.cpp/models

On first run, the model will be downloaded automatically if missing.

Recommended model:

• large-v3-turbo (multilingual, balance of speed and accuracy)

---

Home Assistant Setup

Add a Wyoming STT server:

speech_to_text:
  - platform: wyoming
    host: YOUR_SERVER_IP
    port: 8888

---

Optional: Reverse Proxy Access via NGINX

DO NOT expose Wyoming outside your local network, it does not have SSL/TLS and Home Assistant does not have API Key settings for the Wyoming Protocol settings.

However, if exposing Whisper service via Reverse Proxy such as NPM, then update nginx/nginx.conf with custom API Keys. Consider using https://generate-random.org/api-keys to generate random API Keys.

Example Advanced NPM config

# NPM Advanced Configuration - Convert Bearer to X-API-Key header
#   Update nginx/nginx.conf with custom API keys
location / {
    proxy_pass http://192.168.x.x:8910;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;

    # # If using Bearer uncomment this line
    # if ($http_authorization ~* ^Bearer\s+(.*)) {
    #       set $bearer_token $1;
    # }
    # proxy_set_header X-API-Key "$bearer_token";
}

---

Security Notes

⚠️ Wyoming has no authentication layer.

If exposing externally:

• Use IP allowlisting
• Or use a VPN (Tailscale/WireGuard)
• Do NOT expose publicly without restrictions

---

Why this project exists

The original Fedora-based build works well, but this version:

• Migrates to Ubuntu base images
• Improves Docker Compose workflow
• Moves models to persistent volumes
• Adds automatic model download
• Simplifies deployment for Home Assistant users
• Makes remote sharing easier

---

Performance Notes

• Vulkan backend provides significant speedup on modern GPUs
• large-v3-turbo is recommended for best accuracy/performance balance
• Multiple concurrent users will share GPU resources (requests are serialized)

---

License

This project inherits the original license from: Wyoming Whisper Vulkan Service

Original components:

• whisper.cpp: MIT License
• Wyoming protocol client/server: MIT License

Modifications in this repository are provided under the GPL terms.

---

Acknowledgements

• OpenAI Whisper
• whisper.cpp project by ggerganov
• Wyoming protocol by the Home Assistant ecosystem
• Original Fedora-based service by jstebbins

---