# NousResearch/hermes-agent · faster-whisper voice STT setup and install fixes

## Open now

- Nothing open on GitHub.

These items cover adding local Whisper transcription support via faster-whisper and fixing related installation instructions, including venv targeting, Docker issues, and lazy-install behavior on first use.

## TL;DR

- 6 member(s): 0 open issue(s), 2 closed issue(s), 0 open PR(s), 2 merged PR(s), 2 PR(s) closed without merging.
- A fix was merged to main in PR #29800. Verify it addresses your case.
- **Recommended:** read PR #29800 (and any competing PRs below) before filing. Confirm the merged change covers your symptom.

## Maintainer resolution verdict

- Internal-tracker verdict over this cluster's issue members: `partially_resolved` · deciding PR(s): `pr-29800`. This is distinct from the fix status above. Weigh it yourself.

## How this cluster was grouped

- Link evidence (`STRUCTURAL_PARTIAL`): some members are connected by structural evidence (shared changed files, or a closing/superseded reference); the rest are joined by an automated relevance judgement over their text.
- Members outside that structural core may belong to a different underlying problem.
- Pairwise link density `0.29`: the share of member pairs that carry a link, counting a structural link in full and a relevance-only link at 0.36. `1.00` means every pair is linked.

## Closed / duplicate issues

- #29782: \[Bug\]: I can not install voice for Telegram in Docker
- #44364: Docs: voice extra install command fails unless installer venv is activated or targeted

## Prior & competing PRs

- **#29800: docs(voice): use \`uv pip install faster-whisper\` in STT install hints**. merged to main · fix tier `verified`
  - maintainer direction: category `merged`; implication `superseded`
  - files: `cli.py`, `gateway/run.py`, `tools/voice_mode.py`
  - fix hunks:
  - `cli.py`

    ```diff
    @@ -10640,7 +10640,8 @@ def _voice_start_recording(self):
             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)"
                 )
    ```
  - `gateway/run.py`

    ```diff
    @@ -7938,7 +7938,8 @@ async def _prepare_inbound_message_text(
                                     "🎤 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."
                                 )
    ```
  - `tools/voice_mode.py`

    ```diff
    @@ -1077,7 +1077,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)"
             )
     
    ```
- **#73520: fix(voice): CLI/TUI voice mode UX and environment fixes (15 items)**. merged to main · fix tier `verified`
  - maintainer direction: category `merged`; implication `superseded`
  - files: `cli.py`, `contributors/emails/[redacted:email]`, `contributors/emails/[redacted:email]`, `contributors/emails/[redacted:email]`, `contributors/emails/[redacted:email]`, `contributors/emails/[redacted:email]`, `contributors/emails/[redacted:email]`, `hermes_cli/config.py`, `hermes_cli/voice.py`, `tests/hermes_cli/test_voice_wrapper.py`, `tests/test_tui_gateway_server.py`, `tests/test_voice_max_recording_seconds.py`, `tests/tools/test_clipboard.py`, `tests/tools/test_termux_api_detection.py`, `tests/tools/test_tts_macos_output.py`, `tests/tools/test_voice_cli_integration.py`, `tests/tools/test_voice_mode.py`, `tests/tools/test_voice_wsl_pipewire.py`, `tools/tts_tool.py`, `tools/voice_mode.py` (+4 more)
- **#29815: fix(stt): lazy-install faster-whisper on first voice message (#29782)**. closed without merge
  - maintainer direction: category `partial_fix`; implication `needs_llm`; refs `#29800`
- **#44367: fix(docs): target installer venv in voice extra install command**. closed without merge
  - maintainer direction: category `merged_via`; implication `superseded`; refs `e04c2a9ebd`, `#73520`

## Fix status

- Merged to main in PR #29800 (cited above). No release data is tracked. Verify downstream.
- Fix last verified (merged) `2026-07-28`.
- Subsystem: `docs`