voicemode
Natural voice conversations with Claude Code
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026. Its scripts were only partly scanned.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/mbailey/voicemode with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/mbailey/voicemode'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/mbailey--voicemode)HTML
<a href="/listings/mbailey--voicemode"><img src="/api/listings/mbailey--voicemode/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
These steps run a script from the network that findsafeskills does not scan.
**Requirements:** Computer with microphone and speakers
Option 1: Claude Code Plugin (Recommended)
The fastest way for Claude Code users to get started:
# Add the VoiceMode marketplace claude plugin marketplace add mbailey/voicemode # Install VoiceMode plugin claude plugin install voicemode@voicemode ## Install dependencies (CLI, Local Voice Services) /voicemode:install # Start talking! /voicemode:converse
Option 2: Python installer package
Installs dependencies and the VoiceMode Python package.
# Install UV package manager (if needed) curl -LsSf https://astral.sh/uv/install.sh | sh # Run the installer (sets up dependencies and local voice services) uvx voice-mode-install # Add to Claude Code claude mcp add --scope user voicemode -- uvx --refresh --from voice-mode voicemode-mcp-launcher # Optional: Add OpenAI API key as fallback for local services export OPENAI_API_KEY=your-openai-key # Start a conversation claude converse
For manual setup, see the [Getting Started Guide](docs/tutorials/getting-started.md).
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/marketplace.json · Manifest · 38 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- {
- "name": "voicemode",
- "metadata": {
- "description": "VoiceMode - Voice conversations for Claude Code",
- "version": "1.1.0"
- },
- "owner": {
- "name": "VoiceMode",
- "email": "hello@voicemode.dev"
- },
- "plugins": [
- {
- "name": "voicemode",
- "description": "Voice conversations with Claude Code using local speech-to-text and text-to-speech. Includes support for remote agents via mobile, web and CLI.",
- "author": {
- "name": "Mike Bailey",
- "email": "mike@voicemode.dev"
- },
- "source": "./",
- "category": "productivity",
- "homepage": "https://github.com/mbailey/voicemode"
- },
- {
- "name": "show-me",
- "description": "Visual context sharing between AI and users - display files/URLs/commands with 'show', observe screen context with 'look'",
- "author": {
- "name": "Mike Bailey",
- "email": "mike@voicemode.dev"
- },
- "source": {
- "source": "url",
- "url": "https://github.com/mbailey/show-me.git"
- },
- "category": "productivity",
- "homepage": "https://github.com/mbailey/show-me"
- }
- ]
- }
README.md · README · 228 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- # VoiceMode
- > Natural voice conversations with Claude Code (and other MCP capable agents)
- **New, 9 Nov 2026: [Session Kit](https://github.com/sessionkit/sessionkit)**,
- from the people who brought you VoiceMode. A voice, a phone line and mail for
- your Claude Code sessions. Works on macOS; preliminary testing on Linux.
- [](https://pepy.tech/project/voice-mode)
- [](https://pepy.tech/project/voice-mode)
- [](https://pepy.tech/project/voice-mode)
- VoiceMode enables natural voice conversations with Claude Code. Voice isn't about replacing typing - it's about being available when typing isn't.
- **Perfect for:**
- - Walking to your next meeting
- - Cooking while debugging
- - Giving your eyes a break after hours of screen time
- - Holding a coffee (or a dog)
- - Any moment when your hands or eyes are busy
- ## See It In Action
- [](https://www.youtube.com/watch?v=cYdwOD_-dQc)
- ## Quick Start
- **Requirements:** Computer with microphone and speakers
- ### Option 1: Claude Code Plugin (Recommended)
- The fastest way for Claude Code users to get started:
- ```bash
- # Add the VoiceMode marketplace
- claude plugin marketplace add mbailey/voicemode
- # Install VoiceMode plugin
- claude plugin install voicemode@voicemode
- ## Install dependencies (CLI, Local Voice Services)
- /voicemode:install
- # Start talking!
- /voicemode:converse
- ```
- ### Option 2: Python installer package
- Installs dependencies and the VoiceMode Python package.
- ```bash
- # Install UV package manager (if needed)
- curl -LsSf https://astral.sh/uv/install.sh | sh
- # Run the installer (sets up dependencies and local voice services)
- uvx voice-mode-install
- # Add to Claude Code
- claude mcp add --scope user voicemode -- uvx --refresh --from voice-mode voicemode-mcp-launcher
- # Optional: Add OpenAI API key as fallback for local services
- export OPENAI_API_KEY=your-openai-key
- # Start a conversation
- claude converse
- ```
- For manual setup, see the [Getting Started Guide](docs/tutorials/getting-started.md).
- ## Features
- - **Natural conversations** - speak naturally, hear responses immediately
- - **Works offline** - optional local voice services (Whisper STT, Kokoro TTS)
- - **Low latency** - fast enough to feel like a real conversation
- - **Smart silence detection** - stops recording when you stop speaking
- - **Privacy options** - run entirely locally or use cloud services
- ## Compatibility
- **Platforms:** Linux, macOS, Windows (native or WSL), NixOS
- **Python:** 3.10-3.14
- ## Configuration
- VoiceMode works out of the box. For customization:
- ```bash
- # Set OpenAI API key (if using cloud services)
- export OPENAI_API_KEY="your-key"
- # Or configure via file
- voicemode config edit
- ```
- See the [Configuration Guide](docs/guides/configuration.md) for all options.
- ## Permissions Setup (Optional)
- To use VoiceMode without permission prompts, add to `~/.claude/settings.json`:
- ```json
- {
- "permissions": {
- "allow": [
- "mcp__voicemode__converse",
- "mcp__voicemode__service"
- ]
- }
- }
- ```
- See the [Permissions Guide](docs/guides/permissions.md) for more options.
- ## Local Voice Services
- For privacy or offline use, install local speech services:
- - **[Whisper.cpp](docs/guides/whisper-setup.md)** - Local speech-to-text
- - **[Kokoro](docs/guides/kokoro-setup.md)** - Local text-to-speech with multiple voices
- These provide the same API as OpenAI, so VoiceMode switches seamlessly between them.
- ## Installation Details
- <details>
- <summary><strong>System Dependencies by Platform</strong></summary>
- #### Ubuntu/Debian
- ```bash
- sudo apt update
- sudo apt install -y ffmpeg gcc libasound2-dev libasound2-plugins libportaudio2 portaudio19-dev pulseaudio pulseaudio-utils python3-dev
- ```
- **WSL2 users**: The pulseaudio packages above are required for microphone access.
- #### Fedora/RHEL
- ```bash
- sudo dnf install alsa-lib-devel ffmpeg gcc portaudio portaudio-devel python3-devel
- ```
- #### macOS
- ```bash
- brew install ffmpeg node portaudio
- ```
- #### NixOS
- ```bash
- # Use development shell
- nix develop github:mbailey/voicemode
- # Or install system-wide
- nix profile install github:mbailey/voicemode
- ```
- </details>
- <details>
- <summary><strong>Alternative Installation Methods</strong></summary>
- #### From source
- ```bash
- git clone https://github.com/mbailey/voicemode.git
- cd voicemode
- uv tool install -e .
- ```
- #### NixOS system-wide
- ```nix
- # In /etc/nixos/configuration.nix
- environment.systemPackages = [
- (builtins.getFlake "github:mbailey/voicemode").packages.${pkgs.system}.default
- ];
- ```
- </details>
- ## Troubleshooting
- | Problem | Solution |
- |---------|----------|
- | No microphone access | Check terminal/app permissions. WSL2 needs pulseaudio packages. |
- | UV not found | Run `curl -LsSf https://astral.sh/uv/install.sh \| sh` |
- | OpenAI API error | Verify `OPENAI_API_KEY` is set correctly |
- | No audio output | Check system audio settings and available devices |
- ### Save Audio for Debugging
- ```bash
- export VOICEMODE_SAVE_AUDIO=true
- # Files saved to ~/.voicemode/audio/YYYY/MM/
- ```
- ## Documentation
- - [Getting Started](docs/tutorials/getting-started.md) - Full setup guide
- - [Configuration](docs/guides/configuration.md) - All environment variables
- - [Whisper Setup](docs/guides/whisper-setup.md) - Local speech-to-text
- - [Kokoro Setup](docs/guides/kokoro-setup.md) - Local text-to-speech
- - [Development Setup](docs/tutorials/development-setup.md) - Contributing guide
- Full documentation: [voicemode.dev](https://voicemode.dev)
- ## Links
- - **Website**: [voicemode.dev](https://voicemode.dev)
- - **GitHub**: [github.com/mbailey/voicemode](https://github.com/mbailey/voicemode)
- - **PyPI**: [pypi.org/project/voice-mode](https://pypi.org/project/voice-mode/)
- - **YouTube**: [@getvoicemode](https://youtube.com/@getvoicemode)
- - **Twitter/X**: [@getvoicemode](https://twitter.com/getvoicemode)
- - **Newsletter**: [](https://buttondown.com/voicemode)
- ## License
- MIT - A [Failmode](https://failmode.com) Project
- ---
- mcp-name: dev.voicemode/voicemode
docs/web/install.sh · Bundled script · 1,188 lines · 3 findings marked
- #!/usr/bin/env bash
- # VoiceMode Installer
- # https://getvoicemode.com/install.sh
- #
- # Usage:
- # curl -fsSL https://getvoicemode.com/install.sh | bash
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 6 on GitHub
- # curl -fsSL https://getvoicemode.com/install.sh | bash -s -- -y # non-interactive
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 7 on GitHub
- # curl -fsSL https://getvoicemode.com/install.sh | bash -s -- -y --voice mlx
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 8 on GitHub
- #
- # This script installs VoiceMode and its dependencies.
- # It supports macOS and Linux (Debian/Ubuntu, Fedora).
- #
- # Voice backend (--voice, or VOICEMODE_VOICE_ENGINE env):
- # mlx Apple Silicon only: mlx-audio (one fast on-device server for
- # STT+TTS). Recommended on Apple Silicon; opt-in.
- # local whisper.cpp + Kokoro (cross-platform; the only option off
- # Apple Silicon).
- # skip install no local voice services.
- # Default when unset: interactive prompt; non-interactive skips the large
- # local-voice download (unchanged prior behaviour).
- set -o nounset -o pipefail -o errexit
- # -----------------------------------------------------------------------------
- # Configuration
- # -----------------------------------------------------------------------------
- VOICEMODE_PACKAGE="voice-mode"
- INTERACTIVE=true
- # Voice backend selection (VM-1330).
- # "" - not explicitly chosen; resolved interactively or by the
- # non-interactive skip default (preserves prior behaviour).
- # mlx - Apple Silicon only: install mlx-audio (one fast on-device
- # server for STT+TTS) and point VoiceMode at it.
- # local - whisper.cpp + Kokoro (the cross-platform path; the only
- # option off Apple Silicon).
- # skip - install no local voice services.
- # Explicit --voice (or VOICEMODE_VOICE_ENGINE env) takes precedence over
- # the interactive prompt and the non-interactive skip default.
- VOICE_CHOICE="${VOICEMODE_VOICE_ENGINE:-}"
- # Parse command line arguments
- while [[ $# -gt 0 ]]; do
- case $1 in
- -y|--yes)
- INTERACTIVE=false
- shift
- ;;
- --voice)
- VOICE_CHOICE="${2:-}"
- shift 2
- ;;
- --voice=*)
- VOICE_CHOICE="${1#*=}"
- shift
- ;;
- *)
- shift
- ;;
- esac
- done
- # Validate --voice value early so a typo fails fast rather than silently
- # falling through to the wrong backend.
- case "$VOICE_CHOICE" in
- ""|mlx|local|skip) ;;
- *)
- echo "Error: --voice must be one of: mlx, local, skip (got: '$VOICE_CHOICE')" >&2
- exit 1
- ;;
- esac
- # -----------------------------------------------------------------------------
- # Color Support
- # -----------------------------------------------------------------------------
- # Respect NO_COLOR environment variable (see https://no-color.org/)
- # Also disable colors when not connected to a terminal
- setup_colors() {
- if [[ -n "${NO_COLOR:-}" ]] || [[ ! -t 1 ]]; then
- # No colors
- RED=""
- GREEN=""
- YELLOW=""
- BLUE=""
- ORANGE=""
- BOLD=""
- DIM=""
- RESET=""
- else
- RED=$'\033[0;31m'
- GREEN=$'\033[0;32m'
- YELLOW=$'\033[0;33m'
- BLUE=$'\033[0;34m'
- ORANGE=$'\033[38;2;255;135;0m' # Claude Code orange (24-bit truecolor, theme-independent)
- BOLD=$'\033[1m'
- DIM=$'\033[2m'
- RESET=$'\033[0m'
- fi
- }
- # Initialize colors
- setup_colors
- # -----------------------------------------------------------------------------
- # Output helpers
- # -----------------------------------------------------------------------------
- # Print error message to stderr and exit
- die() {
- echo "${RED}Error:${RESET} $1" >&2
- exit 1
- }
- # Print status message with checkmark
- ok() {
- echo "${GREEN}✓${RESET} $1"
- }
- # Print warning message
- warn() {
- echo "${YELLOW}⚠${RESET} $1"
- }
- # Print info message (for progress)
- info() {
- echo " $1"
- }
- # Display VoiceMode logo
- # Large orange ASCII-art banner (Claude Code orange, ANSI 256-color 208)
- show_logo() {
- echo ""
- printf '%s' "${ORANGE}${BOLD}"
- cat <<'EOF'
- ╔════════════════════════════════════════════╗
- ║ ║
- ║ ██╗ ██╗ ██████╗ ██╗ ██████╗███████╗ ║
- ║ ██║ ██║██╔═══██╗██║██╔════╝██╔════╝ ║
- ║ ██║ ██║██║ ██║██║██║ █████╗ ║
- ║ ╚██╗ ██╔╝██║ ██║██║██║ ██╔══╝ ║
- ║ ╚████╔╝ ╚██████╔╝██║╚██████╗███████╗ ║
- ║ ╚═══╝ ╚═════╝ ╚═╝ ╚═════╝╚══════╝ ║
- ║ ║
- ║ ███╗ ███╗ ██████╗ ██████╗ ███████╗ ║
- ║ ████╗ ████║██╔═══██╗██╔══██╗██╔════╝ ║
- ║ ██╔████╔██║██║ ██║██║ ██║█████╗ ║
- ║ ██║╚██╔╝██║██║ ██║██║ ██║██╔══╝ ║
- ║ ██║ ╚═╝ ██║╚██████╔╝██████╔╝███████╗ ║
- ║ ╚═╝ ╚═╝ ╚═════╝ ╚═════╝ ╚══════╝ ║
- ║ ║
- ║ VoiceMode for Claude Code ║
- ║ ║
- ╚════════════════════════════════════════════╝
- EOF
- printf '%s\n' "${RESET}"
- echo ""
- echo "${BOLD}Talk to Claude like a colleague, not a chatbot.${RESET}"
- echo ""
- echo "${DIM}Transform your AI coding experience with natural voice conversations.${RESET}"
- echo ""
- }
- # Check if a command exists
- command_exists() {
- command -v "$1" >/dev/null 2>&1
- }
- # Check if /dev/tty is available for interactive input
- # (needed for curl|bash and SSH scenarios)
- tty_available() {
- # Try to open /dev/tty in a subshell to avoid polluting fd table
- # and to properly suppress errors
- (exec </dev/tty) 2>/dev/null
- }
- # -----------------------------------------------------------------------------
- # Platform Detection
- # -----------------------------------------------------------------------------
- detect_os() {
- case "$(uname -s)" in
- Darwin)
- echo "macos"
- ;;
- Linux)
- echo "linux"
- ;;
- MINGW*|MSYS*|CYGWIN*)
- echo "windows"
- ;;
- *)
- die "Unsupported operating system: $(uname -s)"
- ;;
- esac
- }
- detect_arch() {
- case "$(uname -m)" in
- x86_64|amd64)
- echo "x86_64"
- ;;
- arm64|aarch64)
- echo "arm64"
- ;;
- armv7l)
- echo "armv7"
- ;;
- *)
- die "Unsupported architecture: $(uname -m)"
- ;;
- esac
- }
- detect_linux_distro() {
- if [[ -f /etc/os-release ]]; then
- # shellcheck source=/dev/null
- . /etc/os-release
- case "$ID" in
- ubuntu|debian|pop|linuxmint|elementary)
- echo "debian"
- ;;
- fedora|rhel|centos|rocky|alma)
- echo "fedora"
- ;;
- arch|manjaro)
- echo "arch"
- ;;
- *)
- # Check for ID_LIKE as fallback
- case "${ID_LIKE:-}" in
- *debian*)
- echo "debian"
- ;;
- *fedora*|*rhel*)
- echo "fedora"
- ;;
- *)
- echo "unknown"
- ;;
- esac
- ;;
- esac
- else
- echo "unknown"
- fi
- }
- # -----------------------------------------------------------------------------
- # Prerequisite Installation
- # -----------------------------------------------------------------------------
- # Ensure uv package manager is available
- # uv can be installed without sudo
- ensure_uv() {
- if command_exists uv; then
- ok "uv found"
- return 0
- fi
- info "Installing uv package manager..."
- if command_exists curl; then
- curl -LsSf https://astral.sh/uv/install.sh | sh
- elif command_exists wget; then
- wget -qO- https://astral.sh/uv/install.sh | sh
- else
- die "Neither curl nor wget found. Cannot install uv."
- fi
- # Add uv to PATH for this session
- export PATH="$HOME/.local/bin:$HOME/.cargo/bin:$PATH"
- if command_exists uv; then
- ok "uv installed"
- else
- die "uv installation failed. Please install manually: https://docs.astral.sh/uv/getting-started/installation/"
- fi
- }
- # Ensure Rust is available (for ARM64 Kokoro dependencies)
- # Uses rustup for latest version since distro packages are often too old
- ensure_rust() {
- # Check if Rust is already installed and recent enough (1.82+)
- if command_exists rustc; then
- local rust_version
- rust_version=$(rustc --version | sed -E 's/rustc ([0-9]+\.[0-9]+).*/\1/')
- local major minor
- major=$(echo "$rust_version" | cut -d. -f1)
- minor=$(echo "$rust_version" | cut -d. -f2)
- if [[ "$major" -gt 1 ]] || { [[ "$major" -eq 1 ]] && [[ "$minor" -ge 82 ]]; }; then
- ok "Rust $rust_version found"
- return 0
- fi
- info "Rust $rust_version is too old (need 1.82+), installing via rustup..."
- else
- info "Installing Rust via rustup..."
- fi
- if command_exists curl; then
- curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --no-modify-path
- elif command_exists wget; then
- wget -qO- https://sh.rustup.rs | sh -s -- -y --no-modify-path
- else
- die "Neither curl nor wget found. Cannot install Rust."
- fi
- # Add cargo to PATH for this session
- export PATH="$HOME/.cargo/bin:$PATH"
- if command_exists rustc; then
- ok "Rust installed via rustup"
- else
- die "Rust installation failed. Please install manually: https://rustup.rs/"
- fi
- }
- # -----------------------------------------------------------------------------
- # macOS System Dependencies
- # -----------------------------------------------------------------------------
- # Install all macOS prerequisites (Homebrew + packages + uv) with single confirmation
- install_macos_prerequisites() {
- local -a packages=(portaudio ffmpeg)
- local -a to_install=()
- local need_homebrew=false
- local need_uv=false
- local pkg
- # Check if Homebrew is installed
- if ! command_exists brew; then
- need_homebrew=true
- # If no Homebrew, we'll need all packages too
- to_install=("${packages[@]}")
- else
- ok "Homebrew found"
- # Check which packages are missing
- for pkg in "${packages[@]}"; do
- if ! brew list "$pkg" &>/dev/null; then
- to_install+=("$pkg")
- fi
- done
- fi
- # Check if uv is installed
- if ! command_exists uv; then
- need_uv=true
- else
- ok "uv found"
- fi
- # If nothing to install, we're done
- if [[ "$need_homebrew" == "false" ]] && [[ ${#to_install[@]} -eq 0 ]] && [[ "$need_uv" == "false" ]]; then
- ok "All dependencies already installed"
- return 0
- fi
- # Show what will be installed
- info "The following will be installed:"
- if [[ "$need_homebrew" == "true" ]]; then
- echo " - Homebrew (package manager)"
- fi
- for pkg in "${to_install[@]}"; do
- echo " - $pkg"
- done
- if [[ "$need_uv" == "true" ]]; then
- echo " - uv (Python package manager)"
- fi
- # Prompt for confirmation in interactive mode (only if TTY available)
- if [[ "$INTERACTIVE" == "true" ]] && tty_available; then
- echo ""
- read -r -p "Proceed with installation? [Y/n] " response </dev/tty
- case "$response" in
- [nN][oO]|[nN])
- if [[ "$need_homebrew" == "true" ]]; then
- die "Homebrew is required for VoiceMode on macOS"
- fi
- warn "Skipping package installation"
- warn "VoiceMode may not work correctly without these packages"
- return 0
- ;;
- esac
- elif [[ "$need_homebrew" == "true" ]] && { [[ "$INTERACTIVE" == "false" ]] || ! tty_available; }; then
- # Non-interactive mode can't install Homebrew (needs sudo)
- die "Homebrew not found. Install it first, then re-run:
- /bin/bash -c \"\$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\""
- fi
- # Install Homebrew if needed
- if [[ "$need_homebrew" == "true" ]]; then
- info "Installing Homebrew (may require password)..."
- /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
- # Add Homebrew to PATH for this session (Apple Silicon uses /opt/homebrew)
- local brew_path=""
- if [[ -x /opt/homebrew/bin/brew ]]; then
- brew_path="/opt/homebrew/bin/brew"
- elif [[ -x /usr/local/bin/brew ]]; then
- brew_path="/usr/local/bin/brew"
- fi
- if [[ -n "$brew_path" ]]; then
- eval "$($brew_path shellenv)"
- # Persist to shell profile for future sessions
- local shell_profile=""
- if [[ -n "${ZSH_VERSION:-}" ]] || [[ "$SHELL" == */zsh ]]; then
- shell_profile="$HOME/.zprofile"
- else
- shell_profile="$HOME/.bash_profile"
- fi
- local shellenv_line="eval \"\$($brew_path shellenv)\""
- if ! grep -q "brew shellenv" "$shell_profile" 2>/dev/null; then
- echo "" >> "$shell_profile"
- echo "# Homebrew" >> "$shell_profile"
- echo "$shellenv_line" >> "$shell_profile"
- fi
- fi
- if command_exists brew; then
- ok "Homebrew installed"
- else
- die "Homebrew installation failed"
- fi
- fi
- # Install packages if needed
- if [[ ${#to_install[@]} -gt 0 ]]; then
- info "Installing packages..."
- brew install "${to_install[@]}"
- ok "Packages installed"
- fi
- # Install uv if needed
- if [[ "$need_uv" == "true" ]]; then
- info "Installing uv..."
- if command_exists curl; then
- curl -LsSf https://astral.sh/uv/install.sh | sh
- elif command_exists wget; then
- wget -qO- https://astral.sh/uv/install.sh | sh
- else
- die "Neither curl nor wget found. Cannot install uv."
- fi
- export PATH="$HOME/.local/bin:$HOME/.cargo/bin:$PATH"
- if command_exists uv; then
- ok "uv installed"
- else
- die "uv installation failed"
- fi
- fi
- }
- # -----------------------------------------------------------------------------
- # Linux System Dependencies
- # -----------------------------------------------------------------------------
- # Check if a package is installed (distro-specific)
- is_package_installed() {
- local distro="$1"
- local package="$2"
- case "$distro" in
- debian)
- dpkg -s "$package" &>/dev/null
- ;;
- fedora)
- rpm -q "$package" &>/dev/null
- ;;
- arch)
- pacman -Q "$package" &>/dev/null
- ;;
- *)
- return 1
- ;;
- esac
- }
- # Install required system packages on Linux (+ uv)
- # These are needed for compiling webrtcvad and simpleaudio
- install_linux_deps() {
- local distro="$1"
- local -a all_packages missing_packages
- local SUDO=""
- local pkg
- local need_uv=false
- # Use sudo if not running as root and sudo is available
- if [[ "$(id -u)" != "0" ]]; then
- if command_exists sudo; then
- SUDO="sudo"
- else
- die "This script requires root privileges or sudo. Please run as root or install sudo."
- fi
- fi
- # Define packages per distro
- case "$distro" in
- debian)
- all_packages=(python3-dev gcc libasound2-dev libportaudio2 ffmpeg)
- # ARM64 needs g++ for Kokoro's mojimoji dependency
- if [[ "$(uname -m)" == "aarch64" || "$(uname -m)" == "arm64" ]]; then
- all_packages+=(g++)
- fi
- ;;
- fedora)
- all_packages=(python3-devel gcc alsa-lib-devel portaudio ffmpeg)
- # ARM64 needs g++ for Kokoro's mojimoji dependency
- if [[ "$(uname -m)" == "aarch64" || "$(uname -m)" == "arm64" ]]; then
- all_packages+=(gcc-c++)
- fi
- ;;
- arch)
- all_packages=(python gcc alsa-lib portaudio ffmpeg)
- # Arch gcc package includes g++, no extras needed
- ;;
- *)
- warn "Unknown Linux distro. Please install build dependencies manually:"
- echo " - C compiler (gcc)"
- echo " - Python development headers"
- echo " - ALSA development libraries"
- echo " - PortAudio library"
- echo " - FFmpeg"
- return 0
- ;;
- esac
- # Check which packages are missing
- missing_packages=()
- for pkg in "${all_packages[@]}"; do
- if ! is_package_installed "$distro" "$pkg"; then
- missing_packages+=("$pkg")
- fi
- done
- # Check if uv is installed
- if ! command_exists uv; then
- need_uv=true
- else
- ok "uv found"
- fi
- # If everything is installed, we're done
- if [[ ${#missing_packages[@]} -eq 0 ]] && [[ "$need_uv" == "false" ]]; then
- ok "All dependencies already installed"
- return 0
- fi
- # Show what needs to be installed
- info "The following will be installed:"
- for pkg in "${missing_packages[@]}"; do
- echo " - $pkg"
- done
- if [[ "$need_uv" == "true" ]]; then
- echo " - uv (Python package manager)"
- fi
- # Prompt for confirmation in interactive mode (only if TTY available)
- if [[ "$INTERACTIVE" == "true" ]] && tty_available; then
- echo ""
- read -r -p "Install these? [Y/n] " response </dev/tty
- case "$response" in
- [nN][oO]|[nN])
- warn "Skipping dependency installation"
- warn "VoiceMode may not work correctly without these packages"
- return 0
- ;;
- esac
- fi
- # Install missing packages
- if [[ ${#missing_packages[@]} -gt 0 ]]; then
- info "Installing packages..."
- case "$distro" in
- debian)
- export DEBIAN_FRONTEND=noninteractive
- $SUDO apt-get update -qq >/dev/null
- $SUDO apt-get install -y -qq "${missing_packages[@]}" >/dev/null
- ;;
- fedora)
- $SUDO dnf install -y -q "${missing_packages[@]}" >/dev/null
- ;;
- arch)
- $SUDO pacman -S --noconfirm -q "${missing_packages[@]}" >/dev/null
- ;;
- esac
- ok "Packages installed"
- fi
- # Install uv if needed
- if [[ "$need_uv" == "true" ]]; then
- info "Installing uv..."
- if command_exists curl; then
- curl -LsSf https://astral.sh/uv/install.sh | sh
- elif command_exists wget; then
- wget -qO- https://astral.sh/uv/install.sh | sh
- else
- die "Neither curl nor wget found. Cannot install uv."
- fi
- export PATH="$HOME/.local/bin:$HOME/.cargo/bin:$PATH"
- if command_exists uv; then
- ok "uv installed"
- else
- die "uv installation failed"
- fi
- fi
- }
- # -----------------------------------------------------------------------------
- # System Dependencies (orchestration)
- # -----------------------------------------------------------------------------
- # Install all system dependencies for the detected platform
- install_system_deps() {
- local os="$1"
- local arch="$2"
- local distro
- case "$os" in
- macos)
- ok "Platform: macOS ($arch)"
- install_macos_prerequisites
- ;;
- linux)
- distro=$(detect_linux_distro)
- ok "Platform: Linux/$distro ($arch)"
- install_linux_deps "$distro"
- # ARM64 Linux needs Rust via rustup for Kokoro dependencies
- if [[ "$arch" == "arm64" ]]; then
- ensure_rust
- fi
- ;;
- windows)
- die "Windows is not yet supported. Please use WSL2 instead."
- ;;
- esac
- }
- # -----------------------------------------------------------------------------
- # Local Voice Services (Whisper & Kokoro)
- # -----------------------------------------------------------------------------
- # Check if Whisper STT is installed
- is_whisper_installed() {
- [[ -d "$HOME/.voicemode/services/whisper" ]]
- }
- # Check if Kokoro TTS is installed
- is_kokoro_installed() {
- [[ -d "$HOME/.voicemode/services/kokoro" ]]
- }
- # -----------------------------------------------------------------------------
- # mlx-audio (Apple Silicon) -- VM-1330
- # -----------------------------------------------------------------------------
- #
- # mlx-audio is a single MLX-native server (STT + TTS + clone-voice) that runs
- # on its OWN port 8890. We point VoiceMode at it by putting the mlx-audio URL
- # FIRST in the preference-ordered base-URL lists (OpenAI kept as a trailing
- # cloud fallback). This mirrors voice_mode/tools/mlx_audio/install.py and the
- # VM-1088 port decision (8880 compat-shim was rejected).
- #
- # IMPORTANT (VM-1318 gate): mlx-audio is RECOMMENDED + opt-in on Apple
- # Silicon. It is NOT the silent non-interactive default until the
- # security/project-health review (VM-1318) clears. Selection is explicit:
- # an interactive choice, or an explicit --voice mlx flag.
- MLX_AUDIO_PORT=8890
- WHISPER_CPP_PORT=2022
- KOKORO_PORT=8880
- # True only on Apple Silicon (macOS arm64) -- the hard gate per ADR VM-1086.
- # Mirrors voice_mode/tools/mlx_audio/install.py::_is_apple_silicon and the
- # assess_voice_capability "excellent" branch.
- is_apple_silicon() {
- local os="$1"
- local arch="$2"
- [[ "$os" == "macos" && "$arch" == "arm64" ]]
- }
- # Check if mlx-audio is already installed (uv-tool entry point present).
- is_mlx_audio_installed() {
- [[ -x "$HOME/.local/bin/mlx_audio.server" ]]
- }
- # Point VoiceMode at the chosen STT + TTS backends by writing the two
- # preference-ordered base-URL lists separately. STT always goes to
- # whisper.cpp (VM-1421); only the TTS URL varies between mlx-audio (8890)
- # and Kokoro (8880). OpenAI stays as the trailing cloud fallback on both
- # so a cold local server still degrades gracefully. Uses the existing
- # `voicemode config set` primitive (writes ~/.voicemode/voicemode.env) --
- # no fragile shell-side env munging.
- configure_voice_urls() {
- local stt_url="$1"
- local tts_url="$2"
- local stt_urls="${stt_url},https://api.openai.com/v1"
- local tts_urls="${tts_url},https://api.openai.com/v1"
- info "Pointing VoiceMode at STT ${stt_url} and TTS ${tts_url}..."
- if voicemode config set VOICEMODE_STT_BASE_URLS "$stt_urls" \
- && voicemode config set VOICEMODE_TTS_BASE_URLS "$tts_urls"; then
- ok "VoiceMode configured (OpenAI cloud fallback kept)"
- else
- warn "Could not write voice base-URL config"
- warn "Set it later with:"
- warn " voicemode config set VOICEMODE_STT_BASE_URLS \"$stt_urls\""
- warn " voicemode config set VOICEMODE_TTS_BASE_URLS \"$tts_urls\""
- fi
- }
- # Install whisper.cpp via the existing CLI primitive. install.sh stays a
- # thin orchestrator -- the build, launchd plist and model download all live
- # in `voicemode whisper install`.
- install_whisper_cpp() {
- if is_whisper_installed; then
- ok "whisper.cpp already installed"
- return 0
- fi
- echo ""
- echo "${BOLD}Installing whisper.cpp${RESET} (on-device STT on port ${WHISPER_CPP_PORT})"
- if voicemode whisper install; then
- ok "whisper.cpp installed"
- else
- warn "whisper.cpp installation failed - retry with: voicemode whisper install"
- return 1
- fi
- }
- # Install mlx-audio via the existing CLI primitive. install.sh stays a thin
- # orchestrator -- the uv tool install + post-install checks + launchd plist all
- # live in `voicemode service install mlx-audio` (mlx_audio_install()),
- # which is already Apple-Silicon-gated. URL config is the caller's job
- # (see install_voice_services) so STT + TTS get written together.
- install_mlx_audio() {
- if is_mlx_audio_installed; then
- ok "mlx-audio already installed"
- return 0
- fi
- echo ""
- echo "${BOLD}Installing mlx-audio${RESET} (Apple Silicon on-device TTS on port ${MLX_AUDIO_PORT})"
- info "No Xcode, no source compile. Models pull on first voice use."
- if voicemode service install mlx-audio; then
- ok "mlx-audio installed"
- else
- warn "mlx-audio installation failed - retry with: voicemode service install mlx-audio"
- return 1
- fi
- }
- # Install Kokoro-FastAPI TTS via the existing CLI primitive. Used both for
- # the explicit "local" choice and as the Apple-Silicon fallback when
- # mlx-audio install fails. URL config stays at the call-site.
- install_kokoro() {
- if is_kokoro_installed; then
- ok "Kokoro already installed"
- return 0
- fi
- echo ""
- echo "${BOLD}Installing Kokoro${RESET} (cross-platform TTS on port ${KOKORO_PORT})"
- if voicemode kokoro install; then
- ok "Kokoro installed"
- else
- warn "Kokoro installation failed - retry with: voicemode kokoro install"
- return 1
- fi
- }
- # Resolve the voice backend choice on Apple Silicon.
- # Precedence (per VM-1330 plan):
- # explicit --voice flag > interactive prompt > non-interactive skip
- # Echoes one of: mlx | local | skip
- # Honors the VM-1318 gate: non-interactive without an explicit --voice
- # stays "skip" (the prior behaviour) -- mlx is never the silent default.
- resolve_apple_silicon_choice() {
- # Explicit flag / env wins outright.
- if [[ -n "$VOICE_CHOICE" ]]; then
- echo "$VOICE_CHOICE"
- return 0
- fi
- if [[ "$INTERACTIVE" == "true" ]] && tty_available; then
- echo "" >&2
- echo "${BOLD}Install local voice services${RESET} -- speech-to-text & text-to-speech?" >&2
- echo "" >&2
- echo " [1] Whisper (STT) + mlx-audio (TTS) -- fast on-device, voice cloning ${GREEN}(recommended)${RESET}" >&2
- echo " [2] Whisper (STT) + Kokoro (TTS) -- classic, cross-platform" >&2
- echo " [3] no thanks" >&2
- echo "" >&2
- local response
- read -r -p "> " response </dev/tty
- case "$response" in
- ""|1) echo "mlx" ;;
- 2) echo "local" ;;
- 3|[sS]) echo "skip" ;;
- *)
- warn "Unrecognised choice '$response' -- defaulting to recommended (Whisper + mlx-audio)" >&2
- echo "mlx"
- ;;
- esac
- return 0
- fi
- # Non-interactive, no explicit choice: preserve prior behaviour
- # (skip the large download). Do NOT silently default to mlx --
- # that decision is gated by VM-1318.
- echo "skip"
- }
- # Assess system capability for local voice services
- # Returns: "excellent", "good", or "limited"
- assess_voice_capability() {
- local os="$1"
- local arch="$2"
- local ram_gb=0
- # Get RAM in GB
- case "$os" in
- macos)
- ram_gb=$(( $(sysctl -n hw.memsize) / 1024 / 1024 / 1024 ))
- ;;
- linux)
- ram_gb=$(( $(grep MemTotal /proc/meminfo | awk '{print $2}') / 1024 / 1024 ))
- ;;
- esac
- # Apple Silicon Mac: excellent (unified memory, Neural Engine)
- # Everything else: depends on RAM
- if [[ "$os" == "macos" && "$arch" == "arm64" ]]; then
- echo "excellent"
- elif [[ $ram_gb -ge 16 ]]; then
- echo "good"
- elif [[ $ram_gb -ge 8 ]]; then
- echo "limited"
- else
- echo "limited"
- fi
- }
- # Get human-readable capability message
- get_capability_message() {
- local capability="$1"
- case "$capability" in
- excellent)
- echo "Local voice services should run excellently on this system."
- ;;
- good)
- echo "Local voice services should run well on this system."
- ;;
- limited)
- echo "Local voice services may be slow on this system."
- ;;
- esac
- }
- # Print the install status of each voice engine relevant to this platform,
- # mirroring the existing "✓ ... already installed" style. On Apple Silicon
- # this also covers mlx-audio; off Apple Silicon mlx-audio is never mentioned
- # (it can't run there).
- show_voice_status() {
- local os="$1"
- local arch="$2"
- echo ""
- echo "${BOLD}Local voice services${RESET}"
- if is_apple_silicon "$os" "$arch"; then
- if is_mlx_audio_installed; then
- ok "mlx-audio already installed"
- else
- info "${DIM}–${RESET} mlx-audio not installed"
- fi
- fi
- if is_whisper_installed; then
- ok "Whisper STT already installed"
- else
- info "${DIM}–${RESET} Whisper STT not installed"
- fi
- if is_kokoro_installed; then
- ok "Kokoro TTS already installed"
- else
- info "${DIM}–${RESET} Kokoro TTS not installed"
- fi
- }
- # Prompt user to install local voice services
- install_voice_services() {
- local os="$1"
- local arch="$2"
- local whisper_installed=false
- local kokoro_installed=false
- # Set when the user has explicitly opted into whisper.cpp+Kokoro
- # (Apple-Silicon "local" choice). Lets that choice bypass the legacy
- # confirmation prompt / non-interactive skip below and install directly.
- local explicit_local=false
- # STATUS DISPLAY FIRST: report what's installed before any prompt.
- show_voice_status "$os" "$arch"
- # Track install state (status already printed above; don't re-print
- # the per-service "already installed" lines a second time).
- if is_whisper_installed; then
- whisper_installed=true
- fi
- if is_kokoro_installed; then
- kokoro_installed=true
- fi
- # --- Apple Silicon: whisper.cpp (STT) + choice of TTS engine (VM-1421) ---
- # All three Apple-Silicon paths (mlx / local / skip) return from inside
- # the case below -- the off-Apple-Silicon legacy block further down
- # never runs on arm64 macs. This block MUST run BEFORE the "both
- # already installed" early-return so a user on a prior release (likely
- # already has whisper + Kokoro) is still offered the mlx-audio TTS
- # upgrade.
- if is_apple_silicon "$os" "$arch"; then
- local stt_url="http://127.0.0.1:${WHISPER_CPP_PORT}/v1"
- local mlx_tts_url="http://127.0.0.1:${MLX_AUDIO_PORT}/v1"
- local kokoro_tts_url="http://127.0.0.1:${KOKORO_PORT}/v1"
- # Already-satisfied shortcut: if whisper.cpp + mlx-audio are both
- # installed and the user did NOT explicitly force a backend,
- # there's nothing to ask. Just idempotently write the split URLs
- # and finish cleanly. An explicit --voice (or VOICEMODE_VOICE_ENGINE)
- # always wins and bypasses this shortcut so the user can force the
- # other path.
- if is_whisper_installed && is_mlx_audio_installed && [[ -z "$VOICE_CHOICE" ]]; then
- configure_voice_urls "$stt_url" "$mlx_tts_url"
- ok "Whisper + mlx-audio already installed and configured -- all set, nothing to do"
- return 0
- fi
- local choice
- choice=$(resolve_apple_silicon_choice)
- case "$choice" in
- mlx)
- # Whisper is load-bearing for STT regardless of which TTS
- # is chosen (VM-1421 -- mlx-whisper repetition bug VM-94
- # blocks using mlx-audio for STT). Install whisper.cpp
- # first, then mlx-audio for TTS. If mlx-audio install
- # fails, install Kokoro and re-point TTS at port
- # ${KOKORO_PORT} instead of leaving the user with no TTS.
- if ! install_whisper_cpp; then
- warn "STT not available -- retry with: voicemode whisper install"
- return 1
- fi
- if install_mlx_audio; then
- configure_voice_urls "$stt_url" "$mlx_tts_url"
- return 0
- fi
- warn "mlx-audio failed -- falling back to Kokoro for TTS"
- if install_kokoro; then
- configure_voice_urls "$stt_url" "$kokoro_tts_url"
- return 0
- fi
- warn "Kokoro fallback also failed -- TTS not configured"
- return 1
- ;;
- skip)
- info "Skipping local voice services"
- info "Install Whisper + mlx-audio later with:"
- info " voicemode whisper install && voicemode service install mlx-audio"
- info " (or Whisper + Kokoro: voicemode whisper install && voicemode kokoro install)"
- return 0
- ;;
- local)
- # Whisper (STT) + Kokoro (TTS). Install both, then write
- # the split URLs explicitly (don't rely on package
- # defaults). Treat as explicit opt-in so the legacy
- # confirm/skip prompt below is bypassed -- but skip the
- # legacy install block by handling it inline here.
- if install_whisper_cpp && install_kokoro; then
- configure_voice_urls "$stt_url" "$kokoro_tts_url"
- return 0
- fi
- warn "Whisper + Kokoro install incomplete -- check messages above"
- return 1
- ;;
- esac
- fi
- # Off Apple Silicon only (the arm64 branch above always returns from
- # inside its case). If both are installed, nothing to do.
- if [[ "$whisper_installed" == "true" && "$kokoro_installed" == "true" ]]; then
- return 0
- fi
- # Assess system capability
- local capability
- capability=$(assess_voice_capability "$os" "$arch")
- local capability_msg
- capability_msg=$(get_capability_message "$capability")
- # Show info about local voice services
- echo ""
- echo "${BOLD}Local Voice Services${RESET}"
- info "$capability_msg"
- # Build list of what would be installed
- local services_to_install=""
- if [[ "$whisper_installed" == "false" ]]; then
- services_to_install="Whisper (STT)"
- fi
- if [[ "$kokoro_installed" == "false" ]]; then
- if [[ -n "$services_to_install" ]]; then
- services_to_install="$services_to_install, Kokoro (TTS)"
- else
- services_to_install="Kokoro (TTS)"
- fi
- fi
- # Show download size estimate
- local download_size="~3GB"
- if [[ "$whisper_installed" == "false" && "$kokoro_installed" == "false" ]]; then
- download_size="~3GB total"
- elif [[ "$whisper_installed" == "false" ]]; then
- download_size="~1.5GB"
- elif [[ "$kokoro_installed" == "false" ]]; then
- download_size="~1.5GB"
- fi
- info "Available: $services_to_install ($download_size download)"
- # Honor an explicit backend choice on ANY platform (VM-1330). On
- # non-Apple-Silicon, `--voice mlx` is not viable -- mlx-audio is
- # Apple-Silicon-only -- so warn and treat it as the local path.
- if [[ "$explicit_local" == "false" && -n "$VOICE_CHOICE" ]]; then
- case "$VOICE_CHOICE" in
- skip)
- info "Skipping local voice services (--voice skip)"
- info "Install later with: voicemode whisper install && voicemode kokoro install"
- return 0
- ;;
- mlx)
- # Reached here only if NOT Apple Silicon (the arm64 mac
- # branch above handles mlx and returns). mlx-audio can't
- # run here -- fall back to whisper.cpp + Kokoro.
- warn "mlx-audio requires Apple Silicon (macOS arm64); using whisper.cpp + Kokoro instead"
- explicit_local=true
- ;;
- local)
- explicit_local=true
- ;;
- esac
- fi
- # Prompt for installation. An explicit local opt-in bypasses both the
- # confirmation prompt and the non-interactive skip default.
- if [[ "$explicit_local" == "true" ]]; then
- info "Installing Whisper (STT) + Kokoro (TTS) (explicitly selected)"
- elif [[ "$INTERACTIVE" == "true" ]] && tty_available; then
- echo ""
- read -r -p "Install Whisper (STT) + Kokoro (TTS)? [Y/n] " response </dev/tty
- case "$response" in
- [nN][oO]|[nN])
- info "Skipping local voice services"
- info "You can install them later with: voicemode whisper install && voicemode kokoro install"
- return 0
- ;;
- esac
- else
- # Non-interactive: skip voice services by default (they're large downloads)
- info "Skipping local voice services (non-interactive mode)"
- info "Install later with: voicemode whisper install && voicemode kokoro install"
- return 0
- fi
- # Install Whisper if needed
- if [[ "$whisper_installed" == "false" ]]; then
- info "Installing Whisper (STT)..."
- if voicemode whisper install; then
- ok "Whisper (STT) installed"
- else
- warn "Whisper installation failed - you can retry with: voicemode whisper install"
- fi
- fi
- # Install Kokoro if needed
- if [[ "$kokoro_installed" == "false" ]]; then
- info "Installing Kokoro (TTS)..."
- if voicemode kokoro install; then
- ok "Kokoro (TTS) installed"
- else
- warn "Kokoro installation failed - you can retry with: voicemode kokoro install"
- fi
- fi
- # Write split URLs explicitly (don't rely on package defaults) so STT
- # lands on whisper.cpp and TTS on Kokoro -- matches the Apple-Silicon
- # "local" branch above (VM-1421).
- if is_whisper_installed && is_kokoro_installed; then
- configure_voice_urls \
- "http://127.0.0.1:${WHISPER_CPP_PORT}/v1" \
- "http://127.0.0.1:${KOKORO_PORT}/v1"
- fi
- }
- # -----------------------------------------------------------------------------
- # VoiceMode Installation
- # -----------------------------------------------------------------------------
- # Install VoiceMode using uv
- install_voicemode() {
- info "Installing VoiceMode..."
- local output
- # Use uv tool install for isolated tool installation
- # Capture output to check for "already installed" message
- if output=$(uv tool install "$VOICEMODE_PACKAGE" 2>&1); then
- if echo "$output" | grep -q "already installed"; then
- ok "VoiceMode already installed"
- else
- ok "VoiceMode installed"
- fi
- else
- # Installation failed
- if command_exists voicemode; then
- # Already installed but uv failed (shouldn't happen normally)
- ok "VoiceMode already installed"
- else
- echo "$output" >&2
- die "VoiceMode installation failed"
- fi
- fi
- }
- # Verify VoiceMode installation and show version
- verify_voicemode() {
- # Refresh PATH to pick up newly installed tools
- export PATH="$HOME/.local/bin:$PATH"
- if ! command_exists voicemode; then
- die "VoiceMode command not found after installation.
- Please ensure ~/.local/bin is in your PATH:
- export PATH=\"\$HOME/.local/bin:\$PATH\""
- fi
- local version
- version=$(voicemode --version 2>/dev/null | sed 's/VoiceMode, version //' || echo "unknown")
- ok "VoiceMode $version ready"
- }
- # Display next steps for the user
- show_next_steps() {
- echo ""
- echo "Next steps:"
- echo " voicemode --help Show available commands"
- echo " voicemode status Check service status"
- echo ""
- echo "Documentation: https://getvoicemode.com/docs"
- }
- # -----------------------------------------------------------------------------
- # Main
- # -----------------------------------------------------------------------------
- main() {
- local os arch distro
- # Detect platform
- os=$(detect_os)
- arch=$(detect_arch)
- # Display logo
- show_logo
- # Install system dependencies (includes uv)
- install_system_deps "$os" "$arch"
- # Install and verify VoiceMode
- install_voicemode
- verify_voicemode
- # Offer to install local voice services
- install_voice_services "$os" "$arch"
- show_next_steps
- }
- main "$@"
voice_mode/templates/scripts/start-voicemode-serve.sh · Bundled script · 133 lines · 1 finding marked
- #!/bin/bash
- # VoiceMode HTTP Server Startup Script
- # This script is used by both macOS (launchd) and Linux (systemd) to start the VoiceMode HTTP server
- # It sources the voicemode.env file to get configuration for VOICEMODE_SERVE_* variables
- # VoiceMode configuration directory
- VOICEMODE_DIR="$HOME/.voicemode"
- LOG_DIR="$VOICEMODE_DIR/logs/serve"
- # Create log directory if it doesn't exist
- mkdir -p "$LOG_DIR"
- # Log file for this script (separate from server logs)
- STARTUP_LOG="$LOG_DIR/startup.log"
- # >>> voicemode_load_env_file — safe replacement for `source` (GHSA-h97v-r3jw-cf6f) >>>
- # Load KEY=VALUE pairs from voicemode.env as INERT DATA. We must NOT `source`
- # the file: bash runs command substitution even inside double quotes, so a
- # value like VOICEMODE_VOICES='x$(rm -rf ~)' would execute as the service user
- Note: Quoted as data in code: Runs `rm -rf` against a root or home-directory path
- Line 20 on GitHub
- # on every start. This reader only ever assigns; it never evaluates the value.
- voicemode_load_env_file() {
- local file="$1" line key val
- [ -f "$file" ] || return 0
- while IFS= read -r line || [ -n "$line" ]; do
- # Trim leading whitespace
- line="${line#"${line%%[![:space:]]*}"}"
- # Skip blank lines and comments
- if [ -z "$line" ]; then continue; fi
- case "$line" in '#'*) continue ;; esac
- # Require KEY=VALUE with a valid shell-identifier key
- case "$line" in [A-Za-z_]*=*) : ;; *) continue ;; esac
- key="${line%%=*}"
- case "$key" in *[!A-Za-z0-9_]*) continue ;; esac
- val="${line#*=}"
- # Strip ONE layer of surrounding quotes; contents are never expanded.
- # (Multiline-quoted values are read by the Python config loader, not
- # needed by this script — their continuation lines are skipped above.)
- case "$val" in
- \"*\") val="${val#\"}"; val="${val%\"}" ;;
- \'*\') val="${val#\'}"; val="${val%\'}" ;;
- esac
- export "$key=$val"
- done < "$file"
- return 0
- }
- # <<< voicemode_load_env_file <<<
- # Load voicemode configuration if it exists (without executing it)
- if [ -f "$VOICEMODE_DIR/voicemode.env" ]; then
- echo "[$(date '+%Y-%m-%d %H:%M:%S')] Loading voicemode.env" >> "$STARTUP_LOG"
- voicemode_load_env_file "$VOICEMODE_DIR/voicemode.env"
- else
- echo "[$(date '+%Y-%m-%d %H:%M:%S')] Warning: voicemode.env not found, using defaults" >> "$STARTUP_LOG"
- fi
- # Configuration with environment variable support (defaults match config.py)
- SERVE_HOST="${VOICEMODE_SERVE_HOST:-127.0.0.1}"
- SERVE_PORT="${VOICEMODE_SERVE_PORT:-8765}"
- SERVE_TRANSPORT="${VOICEMODE_SERVE_TRANSPORT:-streamable-http}"
- SERVE_LOG_LEVEL="${VOICEMODE_SERVE_LOG_LEVEL:-info}"
- # Security configuration
- SERVE_ALLOW_LOCAL="${VOICEMODE_SERVE_ALLOW_LOCAL:-true}"
- SERVE_ALLOW_ANTHROPIC="${VOICEMODE_SERVE_ALLOW_ANTHROPIC:-false}"
- SERVE_ALLOW_TAILSCALE="${VOICEMODE_SERVE_ALLOW_TAILSCALE:-false}"
- SERVE_ALLOWED_IPS="${VOICEMODE_SERVE_ALLOWED_IPS:-}"
- SERVE_SECRET="${VOICEMODE_SERVE_SECRET:-}"
- SERVE_TOKEN="${VOICEMODE_SERVE_TOKEN:-}"
- echo "[$(date '+%Y-%m-%d %H:%M:%S')] Starting VoiceMode HTTP server" >> "$STARTUP_LOG"
- echo "[$(date '+%Y-%m-%d %H:%M:%S')] Host: $SERVE_HOST" >> "$STARTUP_LOG"
- echo "[$(date '+%Y-%m-%d %H:%M:%S')] Port: $SERVE_PORT" >> "$STARTUP_LOG"
- echo "[$(date '+%Y-%m-%d %H:%M:%S')] Transport: $SERVE_TRANSPORT" >> "$STARTUP_LOG"
- echo "[$(date '+%Y-%m-%d %H:%M:%S')] Log level: $SERVE_LOG_LEVEL" >> "$STARTUP_LOG"
- # Build command arguments
- CMD_ARGS=(
- --host "$SERVE_HOST"
- --port "$SERVE_PORT"
- --transport "$SERVE_TRANSPORT"
- --log-level "$SERVE_LOG_LEVEL"
- )
- # Add security flags based on configuration
- if [ "$SERVE_ALLOW_LOCAL" = "true" ]; then
- CMD_ARGS+=(--allow-local)
- echo "[$(date '+%Y-%m-%d %H:%M:%S')] Allowing local connections" >> "$STARTUP_LOG"
- else
- CMD_ARGS+=(--no-allow-local)
- echo "[$(date '+%Y-%m-%d %H:%M:%S')] Blocking local connections" >> "$STARTUP_LOG"
- fi
- if [ "$SERVE_ALLOW_ANTHROPIC" = "true" ]; then
- CMD_ARGS+=(--allow-anthropic)
- echo "[$(date '+%Y-%m-%d %H:%M:%S')] Allowing Anthropic IP ranges" >> "$STARTUP_LOG"
- fi
- if [ "$SERVE_ALLOW_TAILSCALE" = "true" ]; then
- CMD_ARGS+=(--allow-tailscale)
- echo "[$(date '+%Y-%m-%d %H:%M:%S')] Allowing Tailscale IP range" >> "$STARTUP_LOG"
- fi
- # Add custom allowed IPs if configured (comma-separated list)
- if [ -n "$SERVE_ALLOWED_IPS" ]; then
- IFS=',' read -ra IP_ARRAY <<< "$SERVE_ALLOWED_IPS"
- for ip in "${IP_ARRAY[@]}"; do
- # Trim whitespace
- ip=$(echo "$ip" | xargs)
- if [ -n "$ip" ]; then
- CMD_ARGS+=(--allow-ip "$ip")
- echo "[$(date '+%Y-%m-%d %H:%M:%S')] Allowing custom IP: $ip" >> "$STARTUP_LOG"
- fi
- done
- fi
- # Add authentication if configured
- if [ -n "$SERVE_SECRET" ]; then
- CMD_ARGS+=(--secret "$SERVE_SECRET")
- echo "[$(date '+%Y-%m-%d %H:%M:%S')] Secret path authentication enabled" >> "$STARTUP_LOG"
- fi
- if [ -n "$SERVE_TOKEN" ]; then
- CMD_ARGS+=(--token "$SERVE_TOKEN")
- echo "[$(date '+%Y-%m-%d %H:%M:%S')] Bearer token authentication enabled" >> "$STARTUP_LOG"
- fi
- echo "[$(date '+%Y-%m-%d %H:%M:%S')] Executing: voicemode serve ${CMD_ARGS[*]}" >> "$STARTUP_LOG"
- # Start VoiceMode HTTP server
- # Using exec to replace this script process with the server
- # Use voicemode CLI command which is in ~/.local/bin (added to PATH by launchd plist)
- exec voicemode serve "${CMD_ARGS[@]}"
voice_mode/templates/scripts/start-whisper-server.sh · Bundled script · 212 lines · 1 finding marked
- #!/usr/bin/env bash
- set -o nounset -o pipefail -o errexit
- # Whisper Service Startup Script
- # This script is used by both macOS (launchd) and Linux (systemd) to start the whisper service
- # It sources the voicemode.env file to get configuration, especially VOICEMODE_WHISPER_MODEL
- #
- # Features:
- # - Startup health check with 120s timeout
- # - Auto-fallback: disables CoreML if server hangs during init
- # - Thread count reduction when CoreML is active (commented out pending VM-642)
- # Determine whisper directory (script is in bin/, whisper root is parent)
- SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
- WHISPER_DIR="$(dirname "$SCRIPT_DIR")"
- # Voicemode configuration directory
- VOICEMODE_DIR="$HOME/.voicemode"
- LOG_DIR="$VOICEMODE_DIR/logs/whisper"
- # Create log directory if it doesn't exist
- mkdir -p "$LOG_DIR"
- # Log file for this script (separate from whisper server logs)
- STARTUP_LOG="$LOG_DIR/startup.log"
- log() {
- echo "[$(date '+%Y-%m-%d %H:%M:%S')] $1" >> "$STARTUP_LOG"
- }
- # >>> voicemode_load_env_file — safe replacement for `source` (GHSA-h97v-r3jw-cf6f) >>>
- # Load KEY=VALUE pairs from voicemode.env as INERT DATA. We must NOT `source`
- # the file: bash runs command substitution even inside double quotes, so a
- # value like VOICEMODE_VOICES='x$(rm -rf ~)' would execute as the service user
- Note: Quoted as data in code: Runs `rm -rf` against a root or home-directory path
- Line 34 on GitHub
- # on every start. This reader only ever assigns; it never evaluates the value.
- voicemode_load_env_file() {
- local file="$1" line key val
- [ -f "$file" ] || return 0
- while IFS= read -r line || [ -n "$line" ]; do
- # Trim leading whitespace
- line="${line#"${line%%[![:space:]]*}"}"
- # Skip blank lines and comments
- if [ -z "$line" ]; then continue; fi
- case "$line" in '#'*) continue ;; esac
- # Require KEY=VALUE with a valid shell-identifier key
- case "$line" in [A-Za-z_]*=*) : ;; *) continue ;; esac
- key="${line%%=*}"
- case "$key" in *[!A-Za-z0-9_]*) continue ;; esac
- val="${line#*=}"
- # Strip ONE layer of surrounding quotes; contents are never expanded.
- # (Multiline-quoted values are read by the Python config loader, not
- # needed by this script — their continuation lines are skipped above.)
- case "$val" in
- \"*\") val="${val#\"}"; val="${val%\"}" ;;
- \'*\') val="${val#\'}"; val="${val%\'}" ;;
- esac
- export "$key=$val"
- done < "$file"
- return 0
- }
- # <<< voicemode_load_env_file <<<
- # Load voicemode configuration if it exists (without executing it)
- if [ -f "$VOICEMODE_DIR/voicemode.env" ]; then
- log "Loading voicemode.env"
- voicemode_load_env_file "$VOICEMODE_DIR/voicemode.env"
- else
- log "Warning: voicemode.env not found"
- fi
- # Model selection with environment variable support
- MODEL_NAME="${VOICEMODE_WHISPER_MODEL:-base}"
- MODEL_PATH="$WHISPER_DIR/models/ggml-$MODEL_NAME.bin"
- log "Starting whisper-server with model: $MODEL_NAME"
- # Check if model exists
- if [ ! -f "$MODEL_PATH" ]; then
- log "Error: Model $MODEL_NAME not found at $MODEL_PATH"
- log "Available models:"
- ls -1 "$WHISPER_DIR/models/" 2>/dev/null | grep "^ggml-.*\.bin$" >> "$STARTUP_LOG" || true
- # Try to find any available model as fallback
- FALLBACK_MODEL=$(ls -1 "$WHISPER_DIR/models/" 2>/dev/null | grep "^ggml-.*\.bin$" | head -1)
- if [ -n "$FALLBACK_MODEL" ]; then
- MODEL_PATH="$WHISPER_DIR/models/$FALLBACK_MODEL"
- log "Using fallback model: $FALLBACK_MODEL"
- else
- log "Fatal: No whisper models found"
- exit 1
- fi
- fi
- # Port configuration (with environment variable support)
- WHISPER_PORT="${VOICEMODE_WHISPER_PORT:-2022}"
- # Thread configuration - auto-detect CPU cores if not specified
- # Works on macOS, Linux, and WSL
- if [ -n "${VOICEMODE_WHISPER_THREADS:-}" ]; then
- WHISPER_THREADS="$VOICEMODE_WHISPER_THREADS"
- elif [ "$(uname -s)" = "Darwin" ]; then
- # macOS - use sysctl
- WHISPER_THREADS=$(sysctl -n hw.ncpu 2>/dev/null || echo 4)
- else
- # Linux/WSL - use nproc
- WHISPER_THREADS=$(nproc 2>/dev/null || echo 4)
- fi
- # Thread capping when CoreML active — commented out pending VM-642 testing
- # The whisper.cpp issue #779 suggests high thread counts conflict with CoreML,
- # but we haven't confirmed this is needed. Uncomment if VM-642 testing shows it helps.
- # See: https://github.com/ggml-org/whisper.cpp/issues/779
- # COREML_MODEL_DIR="$WHISPER_DIR/models/ggml-${MODEL_NAME}-encoder.mlmodelc"
- # if [ -d "$COREML_MODEL_DIR" ]; then
- # if [ "$WHISPER_THREADS" -gt 4 ]; then
- # log "CoreML model detected — capping threads at 4 (was $WHISPER_THREADS) to avoid ANE threading conflict"
- # WHISPER_THREADS=4
- # fi
- # fi
- log "Using $WHISPER_THREADS threads"
- # Determine server binary location
- # Check new CMake build location first, then legacy location
- if [ -f "$WHISPER_DIR/build/bin/whisper-server" ]; then
- SERVER_BIN="$WHISPER_DIR/build/bin/whisper-server"
- elif [ -f "$WHISPER_DIR/server" ]; then
- SERVER_BIN="$WHISPER_DIR/server"
- else
- log "Error: whisper-server binary not found"
- log "Checked: $WHISPER_DIR/build/bin/whisper-server"
- log "Checked: $WHISPER_DIR/server"
- exit 1
- fi
- log "Using binary: $SERVER_BIN"
- log "Model path: $MODEL_PATH"
- log "Port: $WHISPER_PORT"
- # CoreML model path (used by timeout fallback to disable CoreML if server hangs)
- COREML_MODEL_DIR="$WHISPER_DIR/models/ggml-${MODEL_NAME}-encoder.mlmodelc"
- # Startup timeout configuration
- STARTUP_TIMEOUT="${VOICEMODE_WHISPER_STARTUP_TIMEOUT:-120}"
- HEALTH_URL="http://127.0.0.1:${WHISPER_PORT}/health"
- # Start whisper-server in background to monitor startup
- cd "$WHISPER_DIR"
- "$SERVER_BIN" \
- --host 0.0.0.0 \
- --port "$WHISPER_PORT" \
- --model "$MODEL_PATH" \
- --inference-path /v1/audio/transcriptions \
- --threads "$WHISPER_THREADS" \
- --convert &
- SERVER_PID=$!
- log "Started whisper-server (PID: $SERVER_PID), waiting for health check..."
- # Poll health endpoint until ready or timeout
- ELAPSED=0
- while [ "$ELAPSED" -lt "$STARTUP_TIMEOUT" ]; do
- # Check if process is still alive
- if ! kill -0 "$SERVER_PID" 2>/dev/null; then
- log "whisper-server process exited unexpectedly"
- wait "$SERVER_PID" 2>/dev/null || true
- exit 1
- fi
- # Check if health endpoint responds
- if curl -sf "$HEALTH_URL" >/dev/null 2>&1; then
- log "whisper-server is ready (took ${ELAPSED}s)"
- # Server is healthy — wait for it (keeps this script as the parent)
- wait "$SERVER_PID"
- exit $?
- fi
- sleep 2
- ELAPSED=$((ELAPSED + 2))
- done
- # Timeout reached — server hung during initialization (likely CoreML ANE compilation)
- log "WARNING: whisper-server failed to start within ${STARTUP_TIMEOUT}s"
- # Kill the hung process
- kill "$SERVER_PID" 2>/dev/null || true
- sleep 1
- kill -9 "$SERVER_PID" 2>/dev/null || true
- wait "$SERVER_PID" 2>/dev/null || true
- # Disable CoreML model to prevent future hangs
- if [ -d "$COREML_MODEL_DIR" ]; then
- log "Disabling CoreML model to prevent ANE compilation hang: $COREML_MODEL_DIR -> ${COREML_MODEL_DIR}.disabled"
- mv "$COREML_MODEL_DIR" "${COREML_MODEL_DIR}.disabled"
- # Reset thread count since CoreML is now disabled
- if [ "$(uname -s)" = "Darwin" ]; then
- WHISPER_THREADS=$(sysctl -n hw.ncpu 2>/dev/null || echo 4)
- else
- WHISPER_THREADS=$(nproc 2>/dev/null || echo 4)
- fi
- log "Restarting without CoreML (Metal acceleration only), threads: $WHISPER_THREADS"
- else
- log "No CoreML model to disable — restarting with same configuration"
- fi
- # Restart whisper-server (exec replaces this script process)
- exec "$SERVER_BIN" \
- --host 0.0.0.0 \
- --port "$WHISPER_PORT" \
- --model "$MODEL_PATH" \
- --inference-path /v1/audio/transcriptions \
- --threads "$WHISPER_THREADS" \
- --convert
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.