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)

Ищем в базе…

Что это такое?Это способ разговаривать вслух с одним из ваших профилей Hermes Agent через Home Assistant Assist. В роли микрофона и динамика используется старый Amazon Echo с echo-dot-assist. На Echo Show экран показывает ход разговора.
Это отдельное приложение или дополнение к Home Assistant?В основном это дополнение: пользовательская интеграция Home Assistant, которая работает как агент для диалога и передаёт каждую реплику профилю Hermes. Также есть необязательный экран для Echo Show и небольшое Android-приложение, которое работает на Echo.
Как всё это запустить?Подготовьте голосовой профиль и запустите его API-сервер (docs/voice-profile.md). Затем добавьте интеграцию Hermes Voice в Home Assistant через HACS или zip-архив релиза, укажите адрес шлюза и API-ключ профиля и выберите её как агент для диалога в вашем голосовом конвейере. Установка навыка одной командой сейчас заблокирована сканером безопасности Hermes, поэтому рабочий путь — ручная установка.
Что нужно подготовить перед запуском?Установленный Hermes Agent с рабочим провайдером моделей (запустите hermes setup), установка Home Assistant (в примере Docker Desktop на macOS или уже имеющаяся), распознавание и синтез речи для конвейера (Wyoming Whisper и Piper либо HA Cloud) и голосовое устройство, например Echo Dot или Echo Show с echo-dot-assist. Для опции «Prefer handling commands locally» нужен Home Assistant 2026.10 или новее.
Можно ли управлять светом и другими устройствами?В версии v0.1 нельзя: интеграция не даёт Hermes никаких инструментов для Home Assistant. Чтобы агент мог управлять устройствами, передайте профилю MCP-сервер Home Assistant. Локальные команды самого Home Assistant, например про время или таймеры, можно обрабатывать до Hermes, если включить «Prefer handling commands locally». В таких репликах Hermes не участвует.
Можно попробовать без Echo?Частично. Другие сателлиты Home Assistant Assist, например Voice PE, должны работать с Hermes Voice как с агентом для диалога, но проект их не тестировал. Также можно посмотреть экран Echo Show в настольном браузере по адресу /hermesvoice/screen?demo.
С какими устройствами это работает?Протестировано от начала до конца на Echo Dot 2-го поколения и Echo Show 5 1-го поколения, оба с активацией «Hey Hermes». Другие модели Echo поддерживаются echo-dot-assist, но с Hermes Voice не тестировались, а некоторым нужны определённые сборки Fire OS, поэтому сначала проверьте таблицу моделей и прошивок.
Камера всё время включена?Нет. Hermes Eye необязателен. Камера выключена, если за последние 15 секунд её ничто не запрашивало и режим видео не включён. Шторка и отключение (mute) всегда имеют приоритет, индикатор REC горит всякий раз, когда камера включена, а изображения передаются модели вашего голосового профиля только тогда, когда Hermes смотрит. Ничего не сохраняется. Visual Memory, если вы его включите, — отдельная функция, которая хранит данные локально.
Что показывает экран Hermes на Echo Show?В режиме ожидания он показывает аватар, время, таймеры и фоновую работу Hermes, например выполняющиеся задачи и следующее запланированное задание. Пока вы говорите, на экране появляются ваши слова после распознавания, каждый инструмент, который использует Hermes (например, «Поиск в интернете»), и ответ по мере его написания.
Что если он меня неправильно понял?Коснитесь экрана, пока он думает или отвечает: он остановится, скажет «Говорите.» и снова начнёт слушать без слова-активатора. Hermes получит информацию о том, что было расслышано неверно.
Можно изменить оформление экрана?Да. Это одна HTML-страница (index.html, style.css, app.js), которая получает живые события из websocket Home Assistant. Аватар можно заменить, положив картинку в папку www/hermesvoice/ в Home Assistant. Оформление можно поменять или создать что-то своё на основе тех же данных.
Что такое Hermes Visual Memory?Необязательный плагин Hermes или самостоятельный сервис, который запоминает, что видела камера Echo Show, и отвечает на вопросы вроде «что изменилось?». Он выключен, пока его не включат, хранит данные в локальной SQLite. Модель распознавания изображений смотрит на кадры только когда функция включена, когда крышка камеры открыта или когда об этом попросили.
Какие есть похожие проекты?EchoMuse, echo-dot-assist, techo5, kiosk-satellite, Cornelius, espectre, local_roborock_server, leon
Автор
majorminorlabs
Размер
0.9 MB
Звёзды
719
Возраст
13 д
Коммиты · 90 дней