From 3ad46933d30b4580a9d18fb6877aa551ab7e24d8 Mon Sep 17 00:00:00 2001 From: "Brian D. Evans" Date: Thu, 28 May 2026 07:23:14 +0100 Subject: [PATCH] docs(voice): use `uv pip install faster-whisper` in STT install hints (#29800) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs(voice): use `uv pip install faster-whisper` in STT install hints Three runtime messages told users to `pip install faster-whisper` (reported in #29782 for the gateway STT failure message under Telegram-in-Docker, where the user hit `bash: pip: command not found`). The Hermes Docker image is built on `ghcr.io/astral-sh/uv` with a uv-managed venv that doesn't ship `pip` on PATH; users on modern `uv tool install` / `uv venv` installs see the same problem. The canonical install command in this repo is `uv pip install` (see `tools/lazy_deps.py:509` `feature_install_command()`), which works in Docker (uv image), in `uv tool install` venvs, and in pip-based venvs that already have uv on PATH. Changed three locations to match: - `gateway/run.py` — Telegram/Discord/Slack/WhatsApp/etc. voice reply when no STT provider is configured. Suggests `uv pip install faster-whisper` and notes that `pip install faster-whisper` also works if `pip` is on PATH. - `tools/voice_mode.py` — `/voice` status line for missing STT. - `cli.py` — Voice-mode startup error, "Option 1". No behavior change beyond the user-facing text. No production code path was touched. * docs(voice): add pip fallback to cli + voice_mode STT hints Copilot flagged that cli.py and tools/voice_mode.py recommend `uv pip install faster-whisper` without a fallback for environments where uv isn't on PATH. The gateway/run.py message already lists `pip install faster-whisper` as an alternative; this commit aligns the two remaining call sites to match. Addresses inline Copilot review on #29800. --------- Co-authored-by: briandevans <252620095+briandevans@users.noreply.github.com> --- cli.py | 3 ++- gateway/run.py | 3 ++- tools/voice_mode.py | 3 ++- 3 files changed, 6 insertions(+), 3 deletions(-) diff --git a/cli.py b/cli.py index 6c77afc07a4..6a66595d300 100644 --- a/cli.py +++ b/cli.py @@ -10667,7 +10667,8 @@ class HermesCLI: if not reqs.get("stt_available", reqs.get("stt_key_set")): raise RuntimeError( "Voice mode requires an STT provider for transcription.\n" - "Option 1: pip install faster-whisper (free, local)\n" + "Option 1: uv pip install faster-whisper " + "(free, local; `pip install faster-whisper` also works if pip is on PATH)\n" "Option 2: Set GROQ_API_KEY (free tier)\n" "Option 3: Set VOICE_TOOLS_OPENAI_KEY (paid)" ) diff --git a/gateway/run.py b/gateway/run.py index 9525e087507..54dcebda3e6 100644 --- a/gateway/run.py +++ b/gateway/run.py @@ -8017,7 +8017,8 @@ class GatewayRunner: "🎤 I received your voice message but can't transcribe it — " "no speech-to-text provider is configured.\n\n" "To enable voice: install faster-whisper " - "(`pip install faster-whisper` in the Hermes venv) " + "(`uv pip install faster-whisper` in the Hermes venv; " + "`pip install faster-whisper` also works if pip is on PATH) " "and set `stt.enabled: true` in config.yaml, " "then /restart the gateway." ) diff --git a/tools/voice_mode.py b/tools/voice_mode.py index df21890db9e..0ba449d87ae 100644 --- a/tools/voice_mode.py +++ b/tools/voice_mode.py @@ -1090,7 +1090,8 @@ def check_voice_requirements() -> Dict[str, Any]: details_parts.append("STT provider: OK (OpenAI)") else: details_parts.append( - "STT provider: MISSING (pip install faster-whisper, " + "STT provider: MISSING (uv pip install faster-whisper — " + "`pip install faster-whisper` also works if pip is on PATH, " "or set GROQ_API_KEY / VOICE_TOOLS_OPENAI_KEY)" )