# Bluesound Intercom — Spec Overview

A standalone home intercom system built on Bluesound speakers. No dependency on colony, bots, or any specific consumer. Plays sounds, speaks text, and streams live audio through speakers with automatic interrupt/resume of whatever was playing.

## What It Does

**Play sounds** — presets (doorbell, tock, notification, alarm) or arbitrary audio URLs. Interrupts current playback, plays the sound, resumes what was playing before.

**Speak text** — TTS via ElevenLabs (primary) or espeak (fallback). Named voices. Streaming TTS so speech starts playing before full generation completes.

**Stream live audio** — accept audio from a browser mic (walkie talkie) and pipe it to speakers in real-time. ~2s latency target.

**Web UIs** — heart page (tap to tock), soundboard (grid of preset buttons), walkie talkie (hold to talk), doorbell (visitor-facing, PWA-installable).

## Key Design Decisions

**Queue with priority** — sounds queue up instead of stomping each other. Priority: alarm > doorbell > announcement > notification. Original playback state saved once at queue start, restored once when queue drains.

**Service-aware resume** — Spotify needs `Spotify:play`. Everything else (TuneIn, AirPlay, radio) uses pause toggle. The system knows which resume strategy to use based on what was playing.

**Quiet hours** — 2am-9am AEST default. Non-alarm sounds silently dropped (200 response, not error). Configurable.

**Auth** — token-based. Each token has a name for logging. Doorbell UI embeds token in URL hash for visitor simplicity. Rate limiting per token per endpoint.

**Self-hosted audio** — the server hosts its own audio files instead of depending on an external static server. Presets live in sounds/, TTS cache in /tmp/intercom-cache/, uploaded files in a managed directory.

**No build step** — all web UIs are single self-contained HTML files with inline CSS/JS. Mobile-first, dark backgrounds, large touch targets.

## Architecture

```
[Web UIs / API clients]
        |
   HTTP API (port 3210)
        |
   Queue Manager --- State Preservation
        |                    |
   Audio Pipeline      Speaker Control
   (TTS, streaming,    (pause, play, resume
    presets, files)      via forwarder)
        |                    |
   Self-hosted audio    Bluesound Forwarder
   (serve MP3/stream)   (SSH tunnel to Mac)
                             |
                        BluOS Speakers
```

## Specs

- **INTERCOM-SPEC.md** — core library: interrupt/resume, queue, state preservation, speaker discovery
- **AUDIO-SPEC.md** — TTS, streaming, encoding, caching, voice management
- **SERVER-SPEC.md** — HTTP API, auth, rate limiting, quiet hours, logging
- **UI-SPEC.md** — heart, soundboard, walkie talkie, doorbell web UIs
- **TEST-SPEC.md** — verification strategy, mock infrastructure, test cases