Echo Realtime Gateway

Сервис на Python asyncio, который превращает Amazon Echo Dot с root-доступом в полноценного ассистента «речь-в-речь». Он связывает устройство с Google Gemini Live для нативного аудиовхода и аудиовыхода, а также предоставляет аппаратные возможности Echo (кольцо LED, громкость, микрофон, динамик, музыку) как MCP-поверхность, которой может управлять любой локальный агент.

Echo использует открытую прошивку EchoMuse в качестве своей аппаратной среды выполнения. Этот репозиторий — шлюз, к которому подключается устройство. Ключ API модели остаётся на хосте, где запущен шлюз, и никогда не копируется на устройство.

Путь данных

EchoMuse mic (16 kHz PCM)  ->  gateway  ->  Gemini Live
Gemini Live audio (24 kHz) ->  gateway  ->  EchoMuse speaker (48 kHz PCM)

Облачное соединение находится в спящем режиме, пока устройство простаивает. Локальное wake-слово на устройстве запускает разговор, а нативная детекция голосовой активности на стороне модели управляет очерёдностью реплик и прерываниями.

Related MCP server: alexa-mcp

Возможности

• Нативный аудиомост «аудио-в-аудио» к Gemini Live с полнодуплексным прерыванием.

• Запуск по wake-слову и автоматическое закрытие при простое с возвратом в режим прослушивания wake-слова с низким энергопотреблением.

• MCP-поверхность управления аппаратной частью Echo: анимации LED-кольца, громкость, музыка, микрофон и динамик. Локальный агент использует её через потоковый HTTP.

• Сменяемые голосовые движки для текстовых инструментов (echo_speak, echo_listen, echo_capture), по умолчанию локальные.

• Воспроизведение музыки на динамике устройства с приглушением под голос ассистента.

• Панель управления в реальном времени (опционально) для просмотра телеметрии устройства и редактирования системного промпта во время работы.

• Переключение персоны во время работы: передача активного вызова другой персоне ассистента (с её собственным системным промптом и голосом) без разрыва вызова.

• Опциональная интеграция с воркерами: инструменты только для чтения и инструменты действий, которые позволяют голосовому ассистенту видеть фоновых воркеров-агентов и управлять ими, с разграничением прав для каждого воркера.

• Опциональная память разговоров: каждый завершённый разговор записывается, сводится в единый выровненный трек и передаётся фоновому воркеру, который ведёт один общий файл памяти. Каждая новая сессия инициализируется из этого файла, так что контекст сохраняется после перезапусков.

Структура

echo_gateway/
  main.py            process entry point and server wiring
  gateway.py         device link, Gemini bridge lifecycle, personas, recording
  gemini_bridge.py   Gemini Live client (audio, tools, text injection)
  echo_mcp.py        MCP server exposing the Echo body as tools
  orch_tools.py      optional worker control tools (gated)
  protocol.py        EchoMuse wire frames (mic, speaker, control)
  audio.py           resampling and speaker packetizing
  stt.py / tts.py    pluggable speech engines for the text tools
  telemetry.py       event hub for the control panel
  webui.py           optional live control panel
  assets/            earcon sounds (connect and disconnect)
tests/               unit tests for audio, protocol, MCP, and tools

Требования

• Python 3.12 или новее.

• ffmpeg в PATH (используется для декодирования музыки и сведения записей).

• Echo Dot с root-доступом, работающий на прошивке EchoMuse и доступный с хоста шлюза.

• Ключ Google API с доступом к модели Gemini Live, для режима gemini.

Установка

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

cp .env.example .env
# edit .env: set GOOGLE_API_KEY and ECHO_MODE=gemini, adjust ports as needed

Запуск

python -m echo_gateway.main

Шлюз запускает три компонента: сервер, с которым связывается Echo, HTTP-эндпоинт MCP (по умолчанию 127.0.0.1:8778) и, если включено, панель управления. Направьте Echo на этот сервер, произнесите wake-слово и говорите.

Конфигурация

Вся конфигурация задаётся через переменные окружения. Полный список см. в .env.example. Основные:

• ECHO_MODE выбирает мост. Используйте gemini для ассистента «речь-в-речь». diagnostic — это тест записи и воспроизведения, которому не нужен ключ.

• GOOGLE_API_KEY, GEMINI_LIVE_MODEL, GEMINI_LIVE_VOICE настраивают модель.

• ECHO_MCP_HTTP_HOST, ECHO_MCP_HTTP_PORT, ECHO_MCP_TOKEN настраивают эндпоинт MCP. Держите его привязанным к localhost, если только не задали токен.

• ECHO_WAKE_ENABLED, ECHO_WAKE_PHRASE, ECHO_CONVERSATION_IDLE_SECONDS управляют поведением wake-слова и простоя.

Ключи читаются из окружения и никогда не записываются ни в один файл в этом репозитории. Файл .env.example поставляется с намеренно пустыми полями ключей.

MCP-поверхность

Шлюз предос тавляет MCP-эндпоинт, который направляет запросы к той Echo, которой в данный момент принадлежит соединение. Локальный агент подключается к нему как обычный MCP-клиент и получает инструменты для аппаратной части устройства, например echo_set_led_solid, echo_animate_led, echo_set_volume, echo_music_play, echo_music_stop, echo_get_state, а также текстовые echo_speak, echo_listen и echo_capture. Нативная аудиомодель не использует аудиоинструменты, так как слышит и говорит напрямую.

Тесты

python -m pytest tests -q

Примечания

• Инструменты интеграции с воркерами и функция памяти разговоров предполагают наличие сопутствующей среды выполнения фонового агента на том же хосте. Они опциональны, и шлюз отлично работает без них.

• Кнопка sample на панели, запускающая музыку, ожидает локальный файл assets/sample.mp3. Этот файл не входит в поставку; положите любой mp3 по этому пути, чтобы включить кнопку, или игнорируйте её.