# Implement: Configure Voice Notes for Hermes on Telegram via Local Speech-to-Text and Edge TTS

Inspect the target environment, install local speech-to-text dependencies inside Hermes's managed environment, configure faster-whisper with vocabulary prompting, optionally enable Edge TTS audio replies, verify end-to-end voice transcription and audio generation, and report the result. If you have terminal access on the host, perform the safe inspectable steps yourself and ask only for missing inputs you cannot derive. If you cannot execute commands directly, return the workflow as a structured human-run runbook with explicit commands, configuration parameters, and expected results. Inspect before modifying configuration, preserve existing gateway settings, and never ask the user to post secret credentials or bot tokens in chat.

## Outcome

Enable voice note processing on an existing Telegram-connected Hermes installation. Speech-to-text (STT) must use local `faster-whisper` running the `base` model on CPU without extra third-party STT API fees or credentials. Custom technical vocabulary must be supplied via an STT prompt to prevent misrecognizing proper nouns. Text-to-speech (TTS) must use Microsoft Edge TTS for selective audio responses.

The finished configuration must allow the allowlisted Telegram user to send an `.ogg` voice note in Telegram, have Hermes transcribe it locally on the server, process the transcript as a prompt, and return a text response by default or an Opus/OGG voice reply when voice output mode is active.

## Preconditions and inputs

Inspect or confirm these prerequisites before making configuration changes:

- An operational Hermes agent running on a Linux host or VPS.
- An existing Hermes Telegram gateway configuration linked to a specific Telegram bot.
- A functional model provider already configured for Hermes.
- Python 3.10+ and `uv` or `pip` available in Hermes's managed environment.
- Sufficient host resources for the `base` Whisper model (at least 2 vCPUs and ~150 MB free RAM/disk).

The user or operator must supply or confirm:

- `<HERMES_HOME>`: The path to the active Hermes environment. Defaults to `~/.hermes` for standard single-profile installations or `~/.hermes/profiles/<profile>` for named profiles.
- `<STT_PROMPT_VOCABULARY>`: A comma-separated string of proper nouns, technical terms, product names, and custom vocabulary (for example, `"Hermes, Nous Research, Teknium, Hetzner, Tailscale, Telegram, faster-whisper, Edge TTS"`).
- `<TELEGRAM_USER_ID>`: The allowlisted Telegram numeric user ID permitted to send messages and voice notes to the bot.

If Hermes is not installed, the Telegram gateway is inactive, or system resources are severely constrained, stop and report the unmet precondition. Do not attempt to re-architect host infrastructure.

## Safety constraints

- Run all commands as the unprivileged user that owns Hermes. Never run speech model downloads or gateway services as `root`.
- Do not transmit recorded audio files or user audio caches to external transcription APIs when local STT is selected. Voice notes pass through Telegram infrastructure to reach the server, but STT processing must remain on-host.
- Restrict file permissions on audio cache directories and ensure temporary OGG files inside `<HERMES_HOME>/cache` or profile directories are kept private (mode `700` or `600`).
- Do not hardcode or commit API secrets, bot tokens, or private conversation logs into source control or prompt files.
- Keep normal operational responses in text mode by default. Do not force TTS audio replies for complex code output or terminal diffs.

## Implementation

1. Connect to the host and inspect the active user, Hermes installation, managed environment, and gateway status:

   ```bash
   whoami
   command -v hermes
   hermes --version
   printf '%s\n' "${HERMES_HOME:-$HOME/.hermes}"
   hermes gateway status
   ```

   Confirm that the gateway is active and that the active profile location is identified.

2. Install local Speech-to-Text dependencies into Hermes's managed Python environment:

   ```bash
   hermes tools
   ```

   In the interactive menu under **Speech-to-Text**, select **Local Whisper**. Alternatively, install `faster-whisper` directly into Hermes's managed environment:

   ```bash
   VENV_PATH="${HERMES_HOME:-$HOME/.hermes}/hermes-agent/venv/bin/python"
   if [ -f "$VENV_PATH" ]; then
     uv pip install --python "$VENV_PATH" -U faster-whisper
   else
     pip install -U faster-whisper
   fi
   ```

3. Configure local STT parameters using official Hermes configuration commands:

   ```bash
   hermes config set stt.enabled true
   hermes config set stt.provider local
   hermes config set stt.local.model base
   hermes config set stt.language en
   ```

4. Configure custom vocabulary prompting to assist `faster-whisper` with domain-specific terms:

   ```bash
   hermes config set stt.prompt "<STT_PROMPT_VOCABULARY>"
   ```

   Confirm that proper nouns relevant to the environment are present in the prompt string.

5. Configure Edge Text-to-Speech (TTS) for optional audio replies:

   ```bash
   hermes config set tts.provider edge
   hermes config set tts.edge.voice en-US-AriaNeural
   ```

6. Inspect the resolved configuration parameters to verify settings before restart:

   ```bash
   hermes config get stt
   hermes config get tts
   ```

   Verify that `stt.enabled` is `true`, `stt.provider` is `local`, `stt.local.model` is `base`, and `tts.provider` is `edge`.

7. Restart the Hermes gateway to load the new STT/TTS modules:

   From an external SSH shell:

   ```bash
   hermes gateway restart
   ```

   Or send `/restart` directly in the Telegram chat with the bot.

### Sources

- Source article: [Adding Voice Notes to Hermes Through Telegram](https://vgagaleski.com/blogs/adding-voice-notes-to-hermes-through-telegram/)
- Official reference: [Hermes Agent Documentation](https://github.com/nousresearch/hermes-agent)
- Official reference: [faster-whisper Repository](https://github.com/SYSTRAN/faster-whisper)

## Verification

Confirm every pass criterion:

1. `hermes config get stt` returns `enabled: true`, `provider: local`, and `local.model: base`.
2. `hermes config get tts` returns `provider: edge` and `edge.voice: en-US-AriaNeural`.
3. Sending a voice note from Telegram produces a transcribed text message in Telegram logs or chat without throwing missing module errors.
4. Sending `/voice status` in Telegram returns the active voice mode status.
5. The gateway logs indicate successful loading of `faster-whisper` model `base`.

```bash
journalctl --user -u hermes-gateway -n 50 --no-pager
```

## Completion report

- Changes made: Configured local faster-whisper STT with base model, set vocabulary prompt hint, enabled Edge TTS, and restarted Hermes gateway.
- Verification performed: Inspected configuration keys via hermes config get, verified Python package installation in managed venv, and checked gateway service logs for clean startup.
- User actions still required: Send a sample Telegram voice note to test speech recognition accuracy and send /voice on to toggle voice replies.
- Unresolved risks or blockers: Cold-start latency on initial Whisper base model download; potential accuracy limits on complex code snippets when spoken.