AGENT SKILL

local-voice-stack

Use when installing local TTS or wiring TTS into Hermes.

License 许可
MIT
最近更新
2026-08-16
Stars
★ 0
Forks
0

01 前言 Front Matter

name
local-voice-stack
author
Hermes Agent
license
MIT
version
1.0.0
metadata
{ "hermes": { "tags": [ "tts", "stt", "voice", "pocket-tts", "whisper", "wake-word", "hermes-config", "systemd" ] } }
platforms
[ "linux" ]
description
Use when installing local TTS or wiring TTS into Hermes.

02 资源文件 2

03 SKILL.md 正文

Local Voice Stack (TTS / STT / wake word + Hermes wiring)

Build a fully-local voice assistant on a Linux dev box: on-device neural TTS, speech-to-text, wake-word detection, and — the crown jewel — wiring the TTS engine into Hermes as a command TTS provider so text_to_speech speaks through it. Everything runs offline, no API keys.

When to Use

  • User asks to install Pocket TTS / Piper / another local TTS engine.
  • User wants Hermes to speak through a local engine (custom TTS provider).
  • User is assembling a voice loop: wake word → STT → LLM → TTS ("Jarvis").
  • Any install that needs CPU-only PyTorch (avoid CUDA wheels).

Part 1 — Install a local TTS engine (Pocket TTS recipe, verified)

Pocket TTS = kyutai-labs/pocket-tts (pip install pocket-tts), 100M params, ~6x real-time on CPU, 24 kHz mono 16-bit WAV out, voice cloning via wav file.

Recipe that works (two-step, CPU-only):

uv venv --python 3.12 ~/.venvs/pocket-tts
# 1) CPU torch FIRST, from the PyTorch CPU index (no nvidia-* wheels)
~/.venvs/pocket-tts/bin/python -m pip install --index-url https://download.pytorch.org/whl/cpu torch
# 2) then the app, via uv (see pitfalls for why not plain pip)
env -u PYTHONPATH uv pip install --python ~/.venvs/pocket-tts/bin/python pocket-tts

Pitfalls (each one cost a failed attempt):

  • uv tool install pocket-tts resolves torch from PyPI → pulls GBs of nvidia-* CUDA wheels even with no GPU. Avoid uv tool install here.
  • Setting UV_INDEX_URL=https://download.pytorch.org/whl/cpu replaces PyPI entirely → "pocket-tts not found in the package registry". If you must use env-var indexes, add PyPI as UV_EXTRA_INDEX_URL, and even then first-index resolution can still grab CUDA wheels. The two-step venv recipe above is the deterministic path.
  • uv-created venvs may lack pip: python -m pip ... fails with "No module named pip" when PYTHONPATH is unset. Use uv pip install --python <venv>/bin/python ... instead.
  • On this machine PYTHONPATH points at the Hermes venv → standalone venv scripts import the wrong numpy (cpython-311 vs 312 crash). Always run standalone venv code with env -u PYTHONPATH or via a wrapper script (see Part 3).
  • First run downloads the model (~100M params) from Hugging Face into ~/.cache/huggingface. HF_TOKEN avoids rate-limit warnings.
  • CLI entrypoint lands in <venv>/bin/pocket-tts; ~/.local/bin is on PATH — drop a wrapper there that clears PYTHONPATH.

Part 2 — Wire into Hermes as a command TTS provider (the key technique)

Hermes supports user-defined TTS providers that shell out to any command. Config shape (set via hermes config set, see pitfalls):

tts:
  provider: pocket
  providers:
    pocket:
      type: command
      command: /home/cybertron/.venvs/jarvis/bin/python /home/cybertron/jarvis/pocket_tts_cmd.py {input_path} {output_path}
      output_format: wav
      timeout: 60

Contract: Hermes writes the text to {input_path}, runs the command; the adapter must write audio to {output_path}. Placeholders available: {input_path} (text), {text_path}, {output_path}, {format}, {voice}, {model}, {speed}. Valid output_format values: mp3, wav, ogg, flac, m4a, aac, amr, opus. Defaults: timeout 120 s, max_text_length 5000, format mp3.

Set via CLI (dotted paths work; see references/hermes-command-tts-provider.md for source-level detail):

hermes config set tts.provider pocket
hermes config set tts.providers.pocket.type command
hermes config set tts.providers.pocket.command "<cmd> {input_path} {output_path}"
hermes config set tts.providers.pocket.output_format wav
hermes config set tts.providers.pocket.timeout 60

Pitfall: hermes config set prints "not a recognized config key — saved anyway" for tts.providers.* paths. This is expected and harmless: tts.providers is an open dict the tts_tool reads directly; the schema just doesn't enumerate it. Don't --force or panic — verify by testing instead.

Verification (do this, not eyeballing config):

cd ~/.hermes/hermes-agent
env -u PYTHONPATH ~/.hermes/hermes-agent/venv/bin/python -c "
from tools.tts_tool import text_to_speech_tool, check_tts_requirements
print('reqs:', check_tts_requirements())
import json; print(json.dumps(json.loads(text_to_speech_tool(text='test')), indent=1))"
# Look for: "provider": "pocket", "success": true, valid WAV at file_path

Then in-session: text_to_speech tool returns "provider": "pocket".

Part 3 — Keep the server alive (systemd user service)

The TTS HTTP server dies with the terminal → make it a user service (no sudo needed, survives logout, auto-restarts):

# ~/.config/systemd/user/pocket-tts.service
[Unit]
Description=Pocket TTS server (Kyutai) - local neural TTS
After=network.target
[Service]
Type=simple
ExecStart=/home/cybertron/.local/bin/pocket-tts serve --port 8020 --quantize
Restart=on-failure
RestartSec=3
Environment=PYTHONPATH=
[Install]
WantedBy=default.target
systemctl --user daemon-reload
systemctl --user enable --now pocket-tts
systemctl --user is-active pocket-tts && curl -sf http://localhost:8020/health

--quantize = int8, halves RAM. If a stray background process already holds the port, kill it first or the health check may hit the wrong owner.

CLI wrapper for the venv entrypoint (~/.local/bin/pocket-tts):

#!/usr/bin/env bash
exec env -u PYTHONPATH /home/cybertron/.venvs/pocket-tts/bin/pocket-tts "$@"

Part 4 — STT + wake word (verified legs of the loop)

  • Wake word: openwakeword (pip). Built-in models include hey_jarvis, alexa, timer, weather. Verify: env -u PYTHONPATH <venv>/bin/python -c "from openwakeword.model import Model; print(list(Model().models))"
  • STT: faster-whisper (pip). CPU int8: WhisperModel('small.en', device='cpu', compute_type='int8'). Model load ~2 min on first run; transcription is fast.
  • LLM (brain): any OpenAI-compatible endpoint (/v1/chat/completions). Note: ollama GGUFs may NOT load in upstream llama.cpp (qwen3.5 rope dimension_sections 3 vs 4) — prefer a matching ollama runtime or a compatible GGUF. (See memory for the current state of this machine's brain.)
  • Full loop scaffold lives at ~/jarvis/jarvis.py on this machine (wake → record-until-silence → whisper → LLM → Pocket TTS; --push mode for push-to-talk). Treat it as a starting point, not gospel.

Support files

  • templates/tts_command_adapter.py — verified adapter: reads {input_path}, POSTs to local TTS server, writes {output_path}.
  • references/hermes-command-tts-provider.md — source-level contract: valid formats, defaults, constraints, sanitized env.

04 同仓库更多 Skills