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-ttsresolvestorchfrom PyPI → pulls GBs ofnvidia-*CUDA wheels even with no GPU. Avoiduv tool installhere.- Setting
UV_INDEX_URL=https://download.pytorch.org/whl/cpureplaces PyPI entirely → "pocket-tts not found in the package registry". If you must use env-var indexes, add PyPI asUV_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. Useuv 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 PYTHONPATHor via a wrapper script (see Part 3). - First run downloads the model (~100M params) from Hugging Face into
~/.cache/huggingface.HF_TOKENavoids rate-limit warnings. - CLI entrypoint lands in
<venv>/bin/pocket-tts;~/.local/binis 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 includehey_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 ropedimension_sections3 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.pyon this machine (wake → record-until-silence → whisper → LLM → Pocket TTS;--pushmode 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
web-ui-verification
Verify web UIs via headless Chrome CDP, no vision needed.
test-driven-development
TDD: enforce RED-GREEN-REFACTOR, tests before code.
systematic-debugging
4-phase root cause debugging: understand bugs before fixing.
spike
Throwaway experiments to validate an idea before build.
simplify-code
Parallel 4-agent cleanup of recent code changes.
scroll-driven-3d-websites
Scroll-scrubbed 3D promo sites (Three.js + GSAP).