Echo Realtime Gateway

ルート化された Amazon Echo Dot を完全な音声対音声アシスタントに変える、Python asyncio サービスです。デバイスを 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)

デバイスがアイドル状態の間、クラウド接続はスリープします。デバイス上のウェイクワードが会話を開始し、モデル側のネイティブな音声アクティビティ検出が、ターンテイキングとバージインを処理します。

Related MCP server: alexa-mcp

機能

• Gemini Live へのネイティブな音声対音声ブリッジ。全二重バージイン対応。

• ウェイクワードによる開始と、アイドル時の自動クローズによる低消費電力ウェイクリスニングへの復帰。

• Echo 本体のための MCP コントロールサーフェス: 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 以降。

• PATH 上の ffmpeg（音楽のデコードと録音ミックスに使用）。

• 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

ゲートウェイは次の 3 つを起動します: 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_TOEN は MCP エンドポイントを設定します。トークンを設定しない限り、localhost にバインドしたままにしてください。

• ECHO_WAKE_ENABLED、ECHO_WAKE_PHRASE、ECHO_CONVERSATION_IDLE_SECONDS はウェイクとアイドル動作を制御します。

キーは環境から読取られ、このリポジトリ内のいかなるファイルにも書込まれることはありません。.env.example は意図的にキー欄が空白の状態で同梱されています。

MCP サーフェス

ゲートウェイは、現在リンクを所有している Echo にルーテイングする MCP エンドポイントを提供します。ローカルエージェントは通常の 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 を置けばボタンが有効になります。無視してもかまいません。