Echo Realtime Gateway

Ein Python-asyncio-Dienst, der einen gerooteten Amazon Echo Dot in einen vollwertigen Speech-to-Speech-Asistenten verwandelt. Er verbindet das Gerät mit Google Gemini Live für nativen Audio-Eingang und -Ausgang und stelt die Echo-Hardware (LED-Ring, Lautstärke, Mikrofon, Lautsprecher, Musik) als MCP-Steueroberfläche bereit, die jeder lokele Agent steurn kann.

Der Echo läuft mit der Open-Source-Firmware EchoMuse als Hardware-Runtime. Dieses Reository ist das Gateway, mit dem sich das Gerät verbindet. Der Modell-API-Schlüssel verbleibt auf dem Host, der das Gateway ausführt, und wird nie auf das Gerät kopiert.

Datenpfad

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

Die Cloud-Verbindung schläft, während das Gerät im Leerlauf ist. Ein Wakeword auf dem Gerät startet ein Gespräch, und die native Spracha-kitivitätserkennung auf der Modellseite übernimmt den Sprecherwechsel und das Barge-in.

Related MCP server: WEATHGARDS

Funktionen

• Nativer Audio-zu-Audio-Brücke zu Gemini Live, mit Vollduplex-Barge-in.

• Wakeword-Start und automatisches Schließen im Leerlauf zurück in den energiesparenden Wake-Listening-Modus.

• MCP-Steueroberfläche für den Echo-Körper: LED-Ring-Animtionen, Lautstärke, Musik, Mikrofon und Lautsprecher. Ein lokele Agent konsumiert diese über streamabes HTTP.

• Austauschbare Spra-ch-Engines für die textbasierten Tools (echo_speak, echo_listen, echo_capture), standardmäßig lokele.

• Musikwiedergabe auf dem Gerätelautsprecher, die unter der Asistentenstimme abgesenkt wird.

• Live-Kontrollpanel (optional) zum Betrachten der Geräte-Telemetrie und zum Bearbeiten des Systems-Prompts zur Laufzeit.

• Persona-Wechsel zur Laufzeit: das laufende Gespräch an eine andere Asistenten-Persona übergeben (mit eigenem Systems-Prompt und eigener Stimme), ohne das Gespräch zu unterbrechen.

• Optionale Worker-Integration: Nur-Lese- und Aktions-Tools, die es dem Spra-chasistenten ermöglichen, Hintergrund-Agent-Worker zu sehen und zu steurn, pro Woker freigeschaltet.

• Optionaer Gesprächsspeicher: Jedes abgeschlossene Gespräch wird aufgeeichnet, zu einem einzigen ausgerichteten Track gemischt und an einen Hintergrund-Woker übergeben, der eine gemeinsame Speicherdatei pflegt. Jede neue Sitzung wird aus dieser Datei gespeist, sodass der Kontet Neustarts übersteht.

Layout

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

Voraussetzungen

• Python 3.12 oder neuer.

• ffmpeg im PATH (für Musik-Dekodierung und Aufnahme-Mix).

• Ein gerooteter Echo Dot mit EchoMuse-Firmware, der vom Gateway-Host aus erreichbar ist.

• Ein Google-API-Schlüssel mit Zugriff auf ein Gemini-Live-Modell für den Gemini-Modus.

Einrichtung

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

Ausführung

python -m echo_gateway.main

Das Gateway startet drei Dinge: den gerätezugewandten Server, mit dem der Echo sich verbindet, den MCP-HTTP-Endpunkt (Standart: 127.0.0.1:8778) und, wenn aktiviert, das K ontrollpanel. Richte den Echo auf den gerätezugewandten Server aus, sage das Wakeword und sprich.

Konfiguration

Die gesamte Konfiguration erfolgt über Umgebungsvariablen. Siehe .env.example für die vollständige Liste. Die wichtigen:

• ECHO_MODE wählt die Brücke. Verwende gemini für den Speech-to-Speech-Assistenten. diagnostic ist ein Aufnahme- und Wiedergabetest, der keinen Schlüssel benötigt.

• GOOGLE_API_KEY, GEMINI_LIVE_MODEL, GEMINI_LIVE_VOICE konfigurieren das Modell.

• ECHO_MCP_HTTP_HOST, ECHO_MCP_HTTP_PORT, ECHO_MCP_TOKEN konfigurieren den MCP-Endpunkt. Binde ihn an localhost, es sei denn, du setzt ein Token.

• ECHO_WAKE_ENABLED, ECHO_WAKE_PHRASE, ECHO_CONVERSATION_IDLE_SECONDS steuern das Wake- und Leerlaufverhalten.

Schlüssel werden aus der Umgebung gelesen und nie in eine Datei in diesem Repository geschrieben. Die .env.example-Datei wird absichtlich mit leeren Schlüsselfeldern ausgeliefert.

MCP-Oberfläche

Das Gateway stellt einen MCP-Endpunkt bereit, der zu dem Echo weiterleitet, das die Verbindung aktuell besitzt. Ein lokaler Agent verbindet sich als gewöhnlicher MCP-Client damit und erhält Tools für den Gerätekörper, zum Beispiel echo_set_led_solid, echo_animate_led, echo_set_volume, echo_music_play, echo_music_stop, echo_get_state, plus die textbasierten echo_speak, echo_listen und echo_capture. Das native Audiomodell nutzt die Audio-Tools nicht, da es direkt hört und spricht.

Tests

python -m pytest tests -q

Hinweise

• Die Worker-Integrations-Tools und die Gesprächsspeicher-Funktion erwarten eine begleitende Hintergrund-Agent-Runtime auf demselben Host. Sie sind optional, und das Gateway läuft auch ohne sie einwandfrei.

• Der sample-Musik-Button im Panel erwartet eine lokale assets/sample.mp3. Diese Datei wird hier nicht mitgeliefert; lege eine beliebige MP3 unter diesem Pfad ab, um den Button zu aktivieren, oder ignoriere ihn.