Echo Realtime Gateway

一个 Python asyncio 服务，可将已 root 的 Amazon Echo Dot 变成完整的语音到语音助手。它将设备桥接到 Google Gemini Live，实现原生音频输入与输出，并将 Echo 硬件（LED 灯环、音量、麦克风、扬声器、音乐）作为 MCP 接口暴露出来，任何本地 agent 都可以驱动它。

Echo 以开源 EchoMuse 固件作为其硬件运行时。本仓库是设备拨入的网关。模型 API 密钥保存在运行网关的主机上，绝不会复制到设备。

数据路径

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

设备空闲时云连接处于休眠状态。设备端唤醒词启动对话，模型侧的原生语音活动检测则负责话轮切换和打断。

Related MCP server: WEATHGARDS

功能特性

• 与 Gemini Live 的原生音频到音频桥接，支持全双工打断。

• 唤醒词启动，空闲自动关闭并回到低功耗唤醒聆听状态。

• 面向 Echo 本体的 MCP 控制接口：LED 灯环动画、音量、音乐、麦克风和扬声器。本地 agent 通过流式 HTTP 使用它。

• 基于文本的工具（echo_speak、echo_listen、echo_capture）拥有可替换的语音引擎，默认使用本地引擎。

• 在设备扬声器上播放音乐，并在助手语音响起时自动压低音量。

• （可选）实时控制面板，用于查看设备遥测数据并在运行时编辑系统提示词。

• 运行时角色切换：将实时通话转交给不同的助手角色（拥有自己的系统提示词和语音），且不会中断通话。

• 可选的 worker 集成：只读工具和操作工具让语音助手能够查看并驱动后台 agent worker，按 worker 进行门控。

• 可选的对话记忆：每段已结束的对话都会被录制、混音成一条对齐音轨，并交给一个维护共享记忆文件的后台 worker。每个新会话都会以该文件作为种子内容，从而在重启后保留上下文。

目录结构

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 或更高版本。

• 位于 PATH 中的 ffmpeg（用于音乐解码和录音混音）。

• 一台已取得 root 权限的、运行 EchoMuse 固件的 Echo Dot，并且可从网关主机访问。

• 一个有权访问 Gemini Live 模型的 Google API 密钥，用于 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 拨入的面向设备的服务器、MCP HTTP 端点（默认 127.0.0.1:8778），以及（启用时）控制面板。将 Echo 指向面向设备的服务器，说出唤醒词，然后开始对话。

配置

所有配置都基于环境变量。完整列表见 .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 控制唤醒和空闲行为。

密钥从环境变量中读取，绝不会写入本仓库中的任何文件。.env.example 文件特意保留了空白的密钥字段。

MCP 接口

网关提供一个 MCP 端点，它会路由到当前持有该连接的那个 Echo。本地 agent 作为普通 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

备注

• worker 集成工具和对话记忆功能需要一个位于同一主机上的配套后台 agent 运行时。它们都是可选的，没有它们网关也能正常运行。

• 面板中的 sample 音乐按钮需要本地 assets/sample.mp3。该文件未随本仓库提供；把任意 mp3 放到该路径即可启用按钮，或者忽略它。