hermes-voice README

项目的 README,来自 github.com/majorminorlabs/hermes-voice。合并为一个 markdown 文件:README.md。

Hermes Voice

Talk to one of your Hermes Agent profiles out loud, through Home Assistant Assist, on an old Amazon Echo running echo-dot-assist.

On an Echo Show, the screen follows along: what it heard, the answer as it is written, the tools Hermes is using, and, when idle, what it is working on in the background. The screen is a web page, so you can make it your own (The Hermes screen).

echo-dot-assist replaces the Alexa client while keeping Fire OS and the Echo's audio processing. Hermes Voice runs on the Home Assistant and Hermes hosts. It connects Assist to a Hermes profile once the Echo has been set up as an Assist satellite.

Echo compatibility: check before buying

[!WARNING] Check the exact model number and installed Fire OS build before buying an Echo for this project. A used unit can already have an Amazon update that blocks its unlock, even if the model is listed below. Ask the seller for a photo of the model label and the full software version. Treat compatibility as unknown if the seller can't confirm the build. A factory reset leaves the installed firmware in place.

The table lists the firmware builds that echo-dot-assist targets. To check a unit before buying, compare its currently installed build, and its bootloader where required, with the linked model guide. Some guides install the target build after unlocking, so the installed build and the target build can differ. Keep a stock unit off Wi-Fi until its model guide calls for a connection.

Echo Model number Target Fire OS build Model guide
Echo Dot 2nd gen (2016) RS03QR 6574.1 (NS65741, build 8146) biscuit
Echo 2nd gen (2017) XC56PY 6.5.7.2 (NS6572, build 6436) radar
Echo Dot 3rd gen (2018) D9N29T 6574.1 (NS65741, build 8138) donut
Echo Input (2018) C1125P 6.5.7.5 (NS6575, build 8338) cupcake
Echo Show 5 1st gen (2019) H23K37 6574.1 (NS65741, build 8149) checkers
Echo Show 8 1st gen (2019) C7H6N3 6.5.7.0 (NS6570, build 6074) crown
Echo Show 5 2nd gen (2021) C76N8S 6574.1 (NS65741, build 8149) cronos
Echo Show 8 2nd gen (2021) A8H3N2 7574.1 (PS75741.7080N, build 7080); the guide also covers builds 7077, 7082 and 7806 athena

Echo Show 5 1st gen (H23K37): Fire OS 6575.1 (NS65751, build 8848) blocks the unlock in our guide. Our working setup used build 8149. See the Echo Show 5 setup notes.

Echo Dot 3rd gen: Look for D9N29T. The 2019 refresh (C78MP8) and the version with a clock (36EBT3) are unsupported. See the upstream Echo model list.

Project components

 Echo (echo-dot-assist)          Home Assistant                        Hermes Agent
 ┌──────────────┐  audio  ┌──────────────────────────────┐  HTTPS/HTTP  ┌─────────────────────┐
 │ wake word,   │ ──────▶ │ Assist pipeline              │ ───────────▶ │ one profile's       │
 │ mic, speaker │ ◀────── │  speech-to-text (Whisper…)   │  /v1/chat/   │ API server          │
 └──────────────┘  audio  │  conversation: hermes_voice ─┼─ completions │ (SOUL.md, memory,   │
                          │  text-to-speech (Piper…)     │ ◀─────────── │  tools, provider)   │
                          └──────────────────────────────┘   reply      └─────────────────────┘

This repo adds only the missing pieces:

Piece What it does
custom_components/hermes_voice Home Assistant conversation agent that sends each turn to a Hermes profile with a stable X-Hermes-Session-Id, so Hermes keeps the conversation. Streams the reply so speech starts early, cleans it for speech, and speaks a short fallback instead of error text.
custom_components/hermes_voice/screen, devices/echo/screen-app The Hermes screen: a page Home Assistant serves with the conversation as it happens, and a small Android app that shows it full screen on an Echo Show.
devices/echo/eye-app, extras/eye Hermes Eye: a small app that lets Hermes use the Echo Show's camera (snapshots, video mode, a REC badge), and the look tool for the voice profile. The setup skill builds it on your computer with your own key.
extras/visual-memory Hermes Visual Memory (a Hermes plugin, or a standalone service): remembers what the Echo Show's camera saw, answers "what changed?" and "where did you last see …?", and shows before/after pictures on the Echo. Off until turned on; local SQLite; the vision model (Codex CLI or a local model such as qwen3.6 through Ollama) looks only when turned on, when the camera is uncovered and when asked.
extras/agent-tasks A read-only view of the other Hermes agents' task boards for a voice profile.
skill/hermes-voice-setup A Hermes skill: your own agent prepares a voice profile, installs/configures Home Assistant + hermes_voice, and verifies it.
docs/changes-and-undo.md Everything Hermes Voice changes in Home Assistant, Hermes and on the Echo, and how to undo each.
docs/voice-profile.md How to set up a dedicated voice profile by hand (SOUL.md, tools, thinking effort, separate provider).
wakeword/ Reproducible pipeline that trains a "hey hermes" microWakeWord model, plus the trained model (wakeword/model/).

Everything else is existing open-source work, used as-is; see CREDITS.md.

How it works

The Hermes screen (Echo Show)

On an Echo Show the home screen becomes Hermes':

The camera and privacy. A ● REC badge shows on the screen whenever the camera is on. The camera's shutter and the mute button always win: with the shutter closed Hermes is told it sees nothing, and mute cuts the camera off in the Echo's kernel, where no app can override it. Pictures go to your voice profile's model only when Hermes looks, and nothing is saved. The camera is off unless something asked for it in the last 15 seconds, or video mode is on.

Make it yours. The screen is one HTML page (custom_components/hermes_voice/screen/: index.html, style.css, app.js) that gets a live feed of events from Home Assistant over its websocket: listening, thinking, each part of the reply, tool calls, timers, background work. Swap the avatar by dropping a picture in Home Assistant's www/hermes_voice/ folder, restyle it, or build something else on the same feed. Open /hermes_voice/screen?demo in a desktop browser to work on it without an Echo.

Set up: devices/echo/README.md. Design, options and the feed: docs/show-screen.md.

What you need

Quick start (let your Hermes agent set it up)

Skill installation is currently blocked by Hermes' security scanner. The command below is the intended installation path, but it does not currently succeed for an unverified community skill. Use the manual install while this is being resolved; do not disable scanning or use a force override. The setup scripts and device guide remain available in this repository. See the scan findings and release check and issue #4.

  1. Install the skill:
    hermes skills install majorminorlabs/hermes-voice/skill/hermes-voice-setup
    
    It carries everything it needs: setup scripts, the Home Assistant integration and the "Hey Hermes" wake word model.
  2. Ask your agent: "Use the hermes-voice-setup skill to make me a voice assistant." It asks you a few questions (which profile, what the voice assistant may do, whether you already run Home Assistant), shows a --dry-run of each step, and then runs:
    voice_profile.py --profile voice --create --write-soul --tools safe --reasoning low --service
    ha_setup.py --profile voice --docker --config-dir ~/hermes-voice/ha-config --set-default
    speech_setup.py --docker --data-dir ~/hermes-voice/speech --set-default --internal-url http://<LAN-IP>:8123 --piper-voice en_US-ryan-high
    verify.py --recall
    
    --tools decides what Hermes may do when spoken to: safe (web search, memory), home (+ Home Assistant control), full (terminal, files, code: for coding by voice) or your own list. See docs/voice-profile.md.
  3. Set up the Echo with echo-dot-assist and switch it to "Hey Hermes" (devices/echo/README.md).

Manual install

  1. Prepare a voice profile and start its API server: docs/voice-profile.md.
  2. HACS → ⋮ → Custom repositories → add this repository's URL, category Integration → install Hermes Voice → restart Home Assistant. Or download hermes_voice-<version>.zip from the release, unzip it into <config>/custom_components/ to create <config>/custom_components/hermes_voice/, then restart.
  3. Settings → Devices & services → Add integration → Hermes Voice: gateway URL, the profile's API_SERVER_KEY, a display name. The URL is validated with GET /v1/models (no model call).
  4. Settings → Voice assistants → your pipeline → Conversation agent → the new Hermes entity. The pipeline also needs speech-to-text and text-to-speech (Wyoming Whisper + Piper, or HA Cloud); speech_setup.py in the skill sets those up.
  5. Options: session mode, idle reset, voice cleanup, voice instruction, fallback message, timeout, optional memory scope key (X-Hermes-Session-Key), stream replies (on), working phrase ("One moment.", said when Hermes starts a tool before saying anything; empty turns it off), tell Hermes the date and time (on: Hermes has no clock, so each turn carries Home Assistant's local date and time).
  6. Recommended: in the pipeline, turn on Prefer handling commands locally. Home Assistant then answers its own sentences at once (the time, timers on the device, lights and other devices) and sends everything else to Hermes. Those answers are Home Assistant's, not Hermes', and Hermes does not see those turns. ha_setup.py --set-default turns it on.

Requires Home Assistant 2026.10 or newer (the version tested).

Devices

We tested Hermes Voice end to end on the Echo Dot 2nd gen (flashed from Windows) and Echo Show 5 1st gen (flashed from an Ubuntu live USB), both with the "Hey Hermes" wake word and Home Assistant in Docker on macOS. The remaining Echo models have upstream support and are untested with Hermes Voice. See the model and firmware table.

Other Home Assistant Assist satellites, such as Voice PE, should work with an Assist pipeline that uses Hermes Voice as its conversation agent. These are untested by this project.

Flashing an Echo with echo-dot-assist can brick it. The Echo Show 5 setup uses a Linux PC and a 16 GB work drive.

The tested Echo Dot 2 required a hardware short after the unlock stalled. The device guide records the Windows driver issue, recovery point, firmware mismatch and subsequent slot inspection. It also explains why matching firmware in both slots does not establish a working fallback. Read the Echo Dot 2 recovery notes before recovering a stalled unlock.

The tested Echo Show 5 needed no opening, but its first unlock run reported success and left it locked; a rerun worked. The device guide has the exact downloads, disk space, timings and the full run (Echo Show 5 notes).

Research log

Everything tested on real hardware is written down in docs/research/: what was checked, the evidence, the decisions and why, and what went wrong.

Known limits

Development

tests/run.sh                   # pytest (pytest-homeassistant-custom-component), ruff, mypy in the pinned HA 2026.10.4 image
tools/sync_skill_assets.sh     # after changing the integration or the wake word model: refresh the skill's copies
tools/build_release.sh         # release files in dist/ (integration zip, skill zip, wake word zip, checksums)

Docs: architecture · voice profile · troubleshooting · what it changes, and undo · decisions

License

The code is MIT-licensed. The bundled hey_hermes.tflite wake word model is for non-commercial use only.

hermes-voice (majorminorlabs/hermes-voice)

正在搜索数据库…

这是什么?让你通过 Home Assistant Assist,与某个 Hermes Agent 配置文件(profile)进行语音对话。你可以用一台运行 echo-dot-assist 的旧款 Amazon Echo 作为麦克风和扬声器。在 Echo Show 上,屏幕会同步显示对话内容。
它是独立应用,还是 Home Assistant 的附加组件?主要是附加组件:这是一个自定义的 Home Assistant 集成,充当对话代理,并把每一轮对话发送到某个 Hermes 配置文件。它还包括可选的 Echo Show 屏幕显示,以及一个运行在 Echo 上的小型 Android 应用。
我该如何让它运行起来?先准备一个语音配置文件,并启动其 API 服务器(见 docs/voice-profile.md)。然后通过 HACS 或发布的 zip 包,在 Home Assistant 中添加 Hermes Voice 集成,填入网关 URL 和该配置文件的 API 密钥,并在语音管道中将其选为对话代理。目前一键安装技能的方式受 Hermes 的安全扫描器限制,暂时无法使用,因此手动安装是可行的方法。
开始之前我需要准备什么?一个可正常使用模型提供商的 Hermes Agent 安装(运行 hermes setup),一个 Home Assistant 安装(示例中为 macOS 上的 Docker Desktop,或已有的实例),管道所需的语音转文字和文字转语音服务(Wyoming Whisper 和 Piper,或 HA Cloud),以及一台运行 echo-dot-assist 的语音设备,例如 Echo Dot 或 Echo Show。“Prefer handling commands locally”选项需要 Home Assistant 2026.10 或更高版本。
它能控制我的灯和其他设备吗?v0.1 版本不能:该集成不为 Hermes 提供任何 Home Assistant 工具。若要让代理控制设备,需要为该配置文件配置 Home Assistant 的 MCP 服务器。Home Assistant 自带的本地命令(如时间或计时器),如果你启用了“Prefer handling commands locally”,可以在 Hermes 之前处理;这类对话轮次 Hermes 看不到。
没有 Echo 也能试用吗?可以部分试用。其他 Home Assistant Assist 卫星设备(如 Voice PE)应该能把 Hermes Voice 作为对话代理使用,但项目尚未对其进行测试。你还可以在桌面浏览器中访问 /hermesvoice/screen?demo,预览 Echo Show 屏幕。
它支持哪些设备?已在 Echo Dot 第二代和 Echo Show 5 第一代上完成端到端测试,两者均使用“Hey Hermes”唤醒词。其他 Echo 型号虽然上游的 echo-dot-assist 已支持,但尚未与 Hermes Voice 一起测试,部分型号还需要特定的 Fire OS 版本,因此请先查看型号和固件对照表。
摄像头会一直开着吗?不会。Hermes Eye 是可选功能。除非过去 15 秒内有人请求,或视频模式已开启,否则摄像头保持关闭。快门和静音始终优先,摄像头开启时会显示 REC 标识。只有当 Hermes 查看时,图片才会发送给你语音配置文件所用的模型。不会保存任何内容;Visual Memory 是一项独立功能,若你启用它,会将数据存储在本地。
Echo Show 上的 Hermes 屏幕会显示什么?待机时,屏幕显示头像、时间、计时器,以及 Hermes 的后台工作,例如正在运行的任务和下一个计划任务。你说话时,屏幕会显示转写完成后的文字、Hermes 使用的每个工具(例如“正在搜索网页”),以及逐字生成的回复。
如果它听错了我的话怎么办?在它思考或回答时点击屏幕:它会停止,说一声“请说。”,并且无需唤醒词即可重新聆听。Hermes 会被告知它听错了什么。
我能重新设计屏幕的样式吗?可以。它是一个 HTML 页面(index.html、style.css、app.js),数据来自 Home Assistant websocket 的实时事件。你可以把图片放入 Home Assistant 的 www/hermesvoice/ 文件夹来更换头像,也可以修改样式,或基于同一数据源开发其他界面。
什么是 Hermes Visual Memory?这是一个可选的 Hermes 插件或独立服务,能记住 Echo Show 摄像头看到的内容,并回答“有什么变化?”之类的问题。默认关闭,开启后数据存储在本地 SQLite 中。视觉模型仅在该功能开启、摄像头未被遮挡或有人提问时才会查看画面。
大小
0.9 MB
星标
719
时长
13天
提交 · 90 天