Echo Realtime Gateway

Un servicio Python asyncio que convierte un Amazon Echo Dot rooteado en un asistente de voz a voz. Conecta el dispositivo a Google Gemini Live para audio nativo de entrada y salida, y expone el hardware del Echo (anillo LED, volumen, micrófono, altavoz, música) como una superficie MCP que cualquier agente local puede controlar.

El Echo ejecuta el firmware de código abierto EchoMuse como su runtime de hardware. Este repositorio es la puerta de enlace a la que el dispositivo se conecta. La clave de API del modelo permanece en el host que ejecuta la puerta de enlace y nunca se copia al dispositivo.

Ruta de datos

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

La conexión a la nube permanece inactiva mientras el dispositivo está en reposo. Una palabra de activación en el dispositivo inicia una conversación, y la detección nativa de actividad de voz en el lado del modelo se encarga de la alternancia de turnos y de las interrupciones.

Related MCP server: alexa-mcp

Características

• Puente nativo de audio a audio con Gemini Live, con interrupción full duplex.

• Inicio con palabra de activación y cierre automático por inactividad, de vuelta a la escucha de activación de bajo consumo.

• Superficie de control MCP para el cuerpo del Echo: animaciones del anillo LED, volumen, música, micrófono y altavoz. Un agente local la consume a través de streamable HTTP.

• Motores de voz intercambiables para las herramientas basadas en texto (echo_speak, echo_listen, echo_capture), locales por defecto.

• Reproducción de música en el altavoz del dispositivo, atenuada bajo la voz del asistente.

• Panel de control en vivo (opcional) para ver la telemetría del dispositivo y editar el prompt del sistema en tiempo de ejecución.

• Cambio de persona en tiempo de ejecución: transferir la llamada en vivo a una persona de asistente diferente (con su propio prompt del sistema y su propia voz) sin cortar la llamada.

• Integración opcional de workers: herramientas de solo lectura y de acción que permiten al asistente de voz ver y controlar workers de agentes en segundo plano, restringidas por worker.

• Memoria de conversación opcional: cada conversación finalizada se graba, se mezcla en una única pista alineada y se entrega a un worker en segundo plano que mantiene un archivo de memoria compartido. Cada nueva sesión se inicializa a partir de ese archivo para que el contexto sobreviva a los reinicios.

Estructura

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

Requisitos

• Python 3.12 o superior.

• ffmpeg en el PATH (se usa para decodificar música y mezclar grabaciones).

• Un Echo Dot rooteado que ejecute el firmware EchoMuse, accesible desde el host de la puerta de enlace.

• Una clave de API de Google con acceso a un modelo Gemini Live, para el modo gemini.

Instalación

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

Ejecución

python -m echo_gateway.main

La puerta de enlace inicia tres cosas: el servidor orientado al dispositivo al que el Echo llama, el endpoint HTTP de MCP (por defecto 127.0.0.1:8778) y, cuando está habilitado, el panel de control. Apunta el Echo al servidor orientado al dispositivo, di la palabra de activación y habla.

Configuración

Toda la configuración se basa en variables de entorno. Consulta .env.example para ver la lista completa. Las más importantes:

• ECHO_MODE selecciona el puente. Usa gemini para el asistente de voz a voz. diagnostic es una prueba de grabación y reproducción que no necesita clave.

• GOOGLE_API_KEY, GEMINI_LIVE_MODEL, GEMINI_LIVE_VOICE configuran el modelo.

• ECHO_MCP_HTTP_HOST, ECHO_MCP_HTTP_PORT, ECHO_MCP_TOKEN configuran el endpoint de MCP. Mantenlo enlazado a localhost a menos que establezcas un token.

• ECHO_WAKE_ENABLED, ECHO_WAKE_PHRASE, ECHO_CONVERSATION_IDLE_SECONDS controlan el comportamiento de activación e inactividad.

Las claves se leen del entorno y nunca se escriben en ningún archivo de este repositorio. El archivo .env.example se incluye con los campos de clave vacíos a propósito.

Superficie MCP

La puerta de enlace sirve un endpoint de MCP que enruta al Echo que posee actualmente el enlace. Un agente local se conecta a él como un cliente MCP normal y obtiene herramientas para el cuerpo del dispositivo, por ejemplo echo_set_led_solid, echo_animate_led, echo_set_volume, echo_music_play, echo_music_stop, echo_get_state, además de las basadas en texto echo_speak, echo_listen y echo_capture. El modelo de audio nativo no usa las herramientas de audio, ya que oye y habla directamente.

Pruebas

python -m pytest tests -q

Notas

• Las herramientas de integración de workers y la función de memoria de conversación requieren un runtime de agente en segundo plano complementario en el mismo host. Son opcionales y la puerta de enlace funciona bien sin ellas.

• El botón de música sample del panel requiere un assets/sample.mp3 local. Ese archivo no se incluye aquí; coloca cualquier mp3 en esa ruta para habilitar el botón, o ignóralo.