{"record":{"id":"19c9d53fb5f8ba16","repo":"NousResearch/hermes-agent","slug":"voice-mode-requires-an-stt-provider-for-transcript","errorCode":null,"errorMessage":"Voice mode requires an STT provider for transcription.\nOption 1: uv pip install faster-whisper  (free, local; `pip install faster-whisper` also works if pip is on PATH)\nOption 2: Set GROQ_API_KEY (free tier)\nOption 3: Set VOICE_TOOLS_OPENAI_KEY (paid)","messagePattern":"Voice mode requires an STT provider for transcription\\.\nOption 1: uv pip install faster-whisper  \\(free, local; `pip install faster-whisper` also works if pip is on PATH\\)\nOption 2: Set GROQ_API_KEY \\(free tier\\)\nOption 3: Set VOICE_TOOLS_OPENAI_KEY \\(paid\\)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"cli.py","lineNumber":12905,"sourceCode":"            if _is_termux_environment():\n                details = reqs.get(\"details\", \"\")\n                if \"Termux:API Android app is not installed\" in details:\n                    raise RuntimeError(\n                        \"Termux:API command package detected, but the Android app is missing.\\n\"\n                        \"Install/update the Termux:API Android app, then retry /voice on.\\n\"\n                        \"Fallback: pkg install python-numpy portaudio && python -m pip install sounddevice\"\n                    )\n                raise RuntimeError(\n                    \"Voice mode requires either Termux:API microphone access or Python audio libraries.\\n\"\n                    \"Option 1: pkg install termux-api and install the Termux:API Android app\\n\"\n                    \"Option 2: pkg install python-numpy portaudio && python -m pip install sounddevice\"\n                )\n            raise RuntimeError(\n                \"Voice mode requires sounddevice and numpy.\\n\"\n                f\"Install with: {sys.executable} -m pip install sounddevice numpy\"\n            )\n        if not reqs.get(\"stt_available\", reqs.get(\"stt_key_set\")):\n            raise RuntimeError(\n                \"Voice mode requires an STT provider for transcription.\\n\"\n                \"Option 1: uv pip install faster-whisper  \"\n                \"(free, local; `pip install faster-whisper` also works if pip is on PATH)\\n\"\n                \"Option 2: Set GROQ_API_KEY (free tier)\\n\"\n                \"Option 3: Set VOICE_TOOLS_OPENAI_KEY (paid)\"\n            )\n\n        # Prevent double-start from concurrent threads (atomic check-and-set)\n        with self._voice_lock:\n            if self._voice_recording:\n                return\n            self._voice_recording = True\n\n        # Load silence detection params from config. Shape-safe: a\n        # hand-edited ``voice: true`` / ``voice: cmd+b`` leaves\n        # ``load_config()['voice']`` as a non-dict; coerce to {} so\n        # continuous recording falls back to the documented defaults\n        # instead of crashing on ``.get()``.","sourceCodeStart":12887,"sourceCodeEnd":12923,"githubUrl":"https://github.com/NousResearch/hermes-agent/blob/c896c09c42910c584c4c7d2325b58c14713ea42c/cli.py#L12887-L12923","documentation":"Raised when microphone audio works but no speech-to-text backend is configured. Voice mode needs one of: local faster-whisper, GROQ_API_KEY (free-tier hosted Whisper), or VOICE_TOOLS_OPENAI_KEY (paid OpenAI). check_voice_requirements() reports stt_available/stt_key_set false for all three.","triggerScenarios":"Running `/voice on` after fixing audio, on a machine with none of faster-whisper installed, GROQ_API_KEY set, or VOICE_TOOLS_OPENAI_KEY set in ~/.hermes/.env.","commonSituations":"Fresh installs where STT was never configured; the key was added to the shell env of a different session than the one running Hermes; faster-whisper installed into the wrong venv.","solutions":["Free local: `uv pip install faster-whisper` (or plain pip) into the Hermes environment","Free hosted: set GROQ_API_KEY in ~/.hermes/.env","Paid: set VOICE_TOOLS_OPENAI_KEY in ~/.hermes/.env","Restart the CLI after adding a key so .env is re-read, then `/voice on`"],"exampleFix":"# before\n/voice on  # RuntimeError: Voice mode requires an STT provider for transcription.\n\n# after (pick one)\nuv pip install faster-whisper\necho 'GROQ_API_KEY=...' >> ~/.hermes/.env\n/voice on","handlingStrategy":"validation","validationCode":"import importlib.util, os\nfrom tools.voice_mode import check_voice_requirements\n\ndef stt_ready() -> bool:\n    reqs = check_voice_requirements()\n    return bool(reqs.get(\"stt_available\", reqs.get(\"stt_key_set\")))\n\ndef any_stt_path() -> bool:\n    return importlib.util.find_spec(\"faster_whisper\") is not None or \\\n           bool(os.getenv(\"GROQ_API_KEY\")) or bool(os.getenv(\"VOICE_TOOLS_OPENAI_KEY\"))","typeGuard":null,"tryCatchPattern":"try:\n    cli._voice_start_recording()\nexcept RuntimeError as e:\n    if \"STT provider\" in str(e):\n        show_setup_guide(\"voice-stt\")  # faster-whisper / GROQ_API_KEY / VOICE_TOOLS_OPENAI_KEY\n    else:\n        raise","preventionTips":["Configure one STT path before enabling voice mode (faster-whisper is free and local)","Put API keys in ~/.hermes/.env, not just the shell, so the CLI sees them","Restart the CLI after adding keys — .env is read at startup"],"tags":["voice","stt","configuration","api-key"],"backgroundTag":null,"analyzedSha":"c896c09c42910c584c4c7d2325b58c14713ea42c","analyzedAt":"2026-08-14T17:18:01.089Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}