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: WEATHGARDS

기능

• Gemini Live로의 네이티브 오디오-오디오 브리지, 전이중(full duplex) 끼어들기 지원.

• 웨이크 워드 시작 및 유휴 시 자동 종료 후 저전력 웨이크 리스닝으로 복귀.

• Echo 본체용 MCP 제어 표면: LED 링 애니메이션, 볼륨, 음악, 마이크, 스피커. 로컬 에이전트가 streamable 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 모드용 Gemini Live 모델에 접근할 수 있는 Google API 키.

설치

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 표면

게이트웨이는 현재 링크를 소유한 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 파일이나 넣어 버튼을 활성화하거나, 그냥 무시해도 됩니다.