Skip to content

Latest commit

 

History

History
172 lines (109 loc) · 6.91 KB

getting-started.md

File metadata and controls

172 lines (109 loc) · 6.91 KB

Hear your first spoken notification

In this tutorial, we install Echo on your Mac and hear it speak. By the end, a background service on this machine will speak any JSON message sent to localhost:3246.

Turn the volume up before the last step. You should hear the words "Hello from Echo."

What you will build

A macOS LaunchAgent named com.echo that:

  • Speaks JSON POSTed to localhost:3246/notify
  • Starts when you log in
  • Can stay silent when you mute it

We prove it with curl. Wiring Claude Code, Pi, or another host comes after you have heard the smoke.

Prerequisites

You need:

  • A Mac. Echo installs as a LaunchAgent.
  • Bun. Install it with curl -fsSL https://bun.sh/install | bash.
  • Node.js, for npx. Any current version works.

You do not need git or a copy of the repository.

Check Bun:

bun --version

You should see a version number, for example 1.2.4.

Step 1: Install Echo

npx agent-echo install --adapter none

This copies Echo to ~/Library/Application Support/echo/source, registers the LaunchAgent com.echo and starts it. The output should end with:

OK echo is healthy on :3246

If you see Voice server did not respond. Check logs: ~/Library/Logs/echo.log, open that log. The last few lines say what failed. Fix the cause and rerun the same install command. Running it again is safe.

For installation from a clone, see How to install Echo.

Step 2: Confirm it is healthy

curl -fsS http://localhost:3246/health

You should see JSON that starts like this:

{"status":"healthy","port":3246,...}

Step 3: Hear Hello from Echo

Volume up. Then:

curl -X POST http://localhost:3246/notify \
  -H 'Content-Type: application/json' \
  -d '{"message":"Hello from Echo"}'

Omitting voice_id resolves as identity-default. That is voices.json identity, edge en-GB-RyanNeural, not the provider defaultVoice (Ava). You should hear that identity voice say "Hello from Echo" (if edge-tts is installed for /opt/homebrew/bin/python3) and see:

{"status":"accepted","message":"Notification queued","request_id":"..."}

HTTP 202 means the daemon accepted the line. Your ear is the check that it spoke. Anything on this machine can now speak by POSTing to localhost:3246/notify.

Step 4: Try a named persona

curl -X POST http://localhost:3246/notify \
  -H 'Content-Type: application/json' \
  -d '{"message":"Themis here. Ready to coordinate.","voice_id":"themis"}'

You should hear a different voice. Themis maps to edge en-US-MichelleNeural. When you omit voice_id, Echo uses the identity mapping from step 3 (identity-default). There is no atlas agent key.

If you hear nothing, or the wrong voice

Work through these checks in order.

  1. Confirm the daemon is running:

    npx agent-echo status

    You should see running on :3246 in the Daemon row with a loaded marker. See Status for the dashboard fields and offline behavior. If it says not running, rerun npx agent-echo install --adapter none. If the installer refuses because port 3246 is occupied but not answering, run npx agent-echo doctor. It names each degraded check and the command that fixes it.

  2. Check the daemon log:

    tail -20 ~/Library/Logs/echo.log
  3. Ask Echo why it chose the voice it did. Every spoken notification appends one line to the voice-resolution log:

    tail -3 ~/Library/Logs/echo/voice-resolution.jsonl

    You should see JSON with a provider field and an attempts array.

Wrong voice on the no-voice_id smoke? Check 3 should show "resolution":"identity-default" and "voice":"en-GB-RyanNeural". Ryan is a British male. That is the identity voice, not a fallback.

If "resolution" is fallback and the voice is en-US-AvaNeural, that is the edge provider defaultVoice, not identity. The smoke omitted voice_id, so that is the wrong path.

If you hear macOS say ("Daniel") instead of Ryan, Echo fell back to the built-in macOS voice. Read the latest attempts[]. Edge is skipped only when it is disabled or its circuit breaker is open. Otherwise a failed Edge attempt means real synthesis failed. A common cause is that edge-tts is not installed for Homebrew Python at /opt/homebrew/bin/python3:

/opt/homebrew/bin/python3 -m pip install edge-tts

If /opt/homebrew/bin/python3 does not exist, install Python first with brew install python, then rerun the command above. Restart Echo and repeat step 3. You should now hear Ryan (en-GB-RyanNeural).

No sound, but the curl returned "status":"accepted"? Check the output device and the volume, then the resolution log in check 3. If the last line has "success":false, the attempts array tells you which provider failed.

Mute it for a shared office

Echo is optional. If someone is in the room:

npx agent-echo mute on

You should see Mute: ON and Targets: speaker, microphone. Send the same "Hello from Echo" request again. You should still get "status":"accepted", and you should hear nothing. Then:

npx agent-echo mute off

That prints Mute: OFF. Mute is machine-wide. It does not stop Oh My Pi live chat. Layers and states: What Echo does.

Keep it up to date

One command fetches the newest release and reloads the service:

npx agent-echo@latest update

See Update for settings preservation and recovery details.

What you have done

You installed Echo as a self-starting macOS service, confirmed /health, heard "Hello from Echo", picked a persona, and proved that runtime mute turns the audio off without rejecting the request.

Next steps

  • Wire a supported host so it speaks on its own. How to install Echo
  • Hear a waiting agent from across the desk on hosts with needs-input support. Set ECHO_PREFERRED_NAME if you want the line to start with your name. When an agent needs you
  • After wiring Claude Code, Pi, or omp, give this project a persona with /echo-voice [name] [voice] inside the repo. Voices
  • Pick voices by ear in voices.md
  • Start, stop, restart, and mute vs daemon disable in operations.md
  • Look up /notify in http-api.md

Want an agent to ask you a question out loud and hear your answer? That is voice ask, Echo's speech-to-text feature: one spoken question, one spoken reply, transcribed on your Mac and returned to the agent. It is opt-in and needs sox (rec) and a local transcriber. The first ask needs macOS microphone permission, and on the measured Pi and omp path the prompt names your terminal application, not Echo. Set it up with Voice ask (speech-to-text).