Audio cues

The Pi has no screen. Everything the device needs to tell the user — "I'm listening," "I'm thinking," "setup failed" — it says with sound. This is the conceptual version of docs/edge-audio-cues.md.

The three principles

1. Tones, not words. Status feedback is musical tones, not spoken sentences — they're language-neutral and instant.
2. Never raise. The cue layer must never crash the device. A missing audio dependency degrades gracefully; it doesn't take sudoedge down.
3. Never claim readiness before the mic is live. The "ready" cue only plays once the microphone is actually open and capturing. This was a real bug class: cueing "ready" while the mic was still wedged made the device look fine when it wasn't.

Where cues come from

• sudoedge/announce.py owns the lifecycle tones (boot, ready, error, pairing).
• sudoedge/lk_client.py owns the in-conversation cues tied to the agent's state (listening, thinking, speaking).

Why this matters for debugging

Because the cues are the only feedback channel, learning the tone vocabulary is the fastest way to triage a device in the field. "It plays the boot tone but never the ready tone" tells you the mic never came live — likely an audio device or reSpeaker problem, not a cloud issue.