Strategic STT Configuration

+15 Mana ✨
Use Voice Mode with Hermes(DOCUMENTATION)

Introduction

You now know the providers, the model ladder, and the accuracy factors. This lesson ties them into a configuration strategy: how to choose your STT settings deliberately rather than copying a snippet and hoping.

Key Concepts

  • config.yaml: The Hermes configuration file at ~/.hermes/config.yaml, where the stt block lives.
  • .env: The file at ~/.hermes/.env that holds secrets such as GROQ_API_KEY, so keys never sit in config.yaml.
  • Default-then-escalate: A strategy where you start with the safest configuration and change one setting at a time, driven by observed problems.
  • Silence detection: The mechanism that decides when you have stopped speaking, tuned by silence_threshold and silence_duration.

Real World Context

A developer pastes a complex multi-provider STT config from a forum, hits an authentication error, and cannot tell whether the problem is the model, the provider, or a missing key. A developer who instead starts from the minimal default config and changes one thing at a time always knows exactly what their last change was, and therefore what to blame.

Deep Dive

The strategy has three layers.

Layer one: start from the safe default. provider: local with model: base. This needs no keys, costs nothing, and keeps audio on-device. It is the configuration with the fewest ways to fail, which makes it the right baseline.

yaml
stt:
  provider: "local"
  local:
    model: "base"

Layer two: separate config from secrets. Non-secret settings (provider, model) belong in config.yaml. Secrets (API keys) belong in ~/.hermes/.env as GROQ_API_KEY, VOICE_TOOLS_OPENAI_KEY, and so on. This separation means you can share or version-control your config.yaml without leaking credentials, and it keeps key problems isolated to one file.

Layer three: escalate one change at a time. When something is wrong, name the symptom and change exactly one setting:

  • Transcription is slow on this hardware: set provider toward a cloud option, or first try a smaller model.
  • Transcription is inaccurate: climb the model ladder one rung, after ruling out noise.
  • Recording cuts off while you are still thinking: raise silence_duration so Hermes waits longer before deciding you are done.
  • Recording never stops in a noisy room: adjust silence_threshold so background noise is not mistaken for speech.

The discipline is one change per problem. If you alter the provider, the model, and the silence settings all at once and the result improves, you have learned nothing about why. Single-variable changes turn configuration into something you understand instead of something you guess at.

Common Pitfalls

  1. Putting API keys in config.yaml: Secrets belong in ~/.hermes/.env. Mixing them into config.yaml makes the file unsafe to share or commit.
  2. Changing several settings at once: If three changes ship together, an improvement teaches you nothing. Change one variable per observed problem.

Best Practices

  1. Baseline first: Begin with provider: local and model: base, confirm it works, and only then customize.
  2. Drive changes from symptoms: Tie every configuration edit to a named problem (slow, inaccurate, cuts off early) so you can reason about cause and effect.

Summary

  • Non-secret STT settings live in ~/.hermes/config.yaml; API keys live in ~/.hermes/.env.
  • Start from the safe default: local provider, base model.
  • Escalate one change at a time, each tied to a specific observed symptom.
  • Single-variable changes keep configuration understandable rather than a guessing game.

Code Examples

yaml
# ~/.hermes/config.yaml  -- non-secret settings only
stt:
  provider: "local"
  local:
    model: "base"
voice:
  silence_threshold: 200   # raise if a noisy room never stops recording
  silence_duration: 3.0    # raise if recording cuts off while you think

# ~/.hermes/.env  -- secrets only, never committed
# GROQ_API_KEY=...
# VOICE_TOOLS_OPENAI_KEY=...
✓ Completed