What it does
Turns your phone into a home intercom. Hold a button on a PWA, say something, and it plays on your smart speakers — one room or the whole house.
The built-in broadcast on smart speakers? “Hey Google/Alexa” → wait → “broadcast” → wait → speak your message. Three steps, inconsistent results, and half the time it fails silently. No TTS typing. No fumbling with voice assistants. Just push, talk, release, done.
Demo
Each room gets a card with a big round PTT button. Hold to record, release to play.
The “Broadcast All” card at the top sends to every room at once.- /
Each room has a live online indicator — green dot means the speaker is reachable via HA. - Recording: button turns green with ripple animation + bouncing sound bars.
- Sending: green spinner ring around the button.
- Sent: big green checkmark.
i18n: Chinese / English toggle in the top-right corner.
Architecture
Phone PWA → HA Native Integration → Home Assistant API → your speakers
↕
configuration.yaml / UI Config
(or Docker standalone — still supported)
v2.0.0+ runs natively inside Home Assistant — zero extra containers. Just drop it into custom_components/, configure via the UI (or YAML), done.
For Docker users: Flask + waitress handles audio receive → PCM → WAV, calls HA REST API directly. No ffmpeg (131MB image), no n8n, no SSH. Broadcast-all fires parallel play_media calls — fire and forget.
Quick Start
HA Integration (recommended · v2.0.0+)
Install (HACS or manual)
HACS: Add custom repository https://github.com/mdj2812/home-intercom → search “Home Intercom” → install.
Manual:
cd /config/custom_components
curl -LO https://github.com/mdj2812/home-intercom/releases/latest/download/home_intercom.zip
unzip -o home_intercom.zip -d home_intercom && rm home_intercom.zip
ha core restart
Configure
Settings → Devices & Services → Add Integration → search “Home Intercom” → pick area & media player → done.
Existing configuration.yaml rooms are auto-imported — no manual migration needed.
Add to sidebar
Create a dashboard → Add Webpage card → URL: /home_intercom.
Docker (legacy, fully supported)
git clone https://github.com/mdj2812/home-intercom.git
cd home-intercom
cat > docker/.env << EOF
HA_URL=http://192.168.1.10:8123
HA_TOKEN=your_ha_long_lived_token
EOF
export IMAGE=ghcr.io/mdj2812/home-intercom:v2.0.0
docker compose -f docker/docker-compose.example.yml up -d
HTTPS is required for microphone access — use Caddy or Nginx reverse proxy.
Tech Stack
| Item | Detail |
|---|---|
| Integration | Native HA custom_component (Config Flow + Options Flow + Device Registry) or Flask + waitress |
| Audio pipeline | MediaRecorder opus → decodeAudioData → resample 16kHz → pure Python WAV |
| Image size | 131 MB (zero external dependencies, Docker mode) |
| Tests | 127 pytest tests, 92% coverage |
| CI/CD | GitHub Actions — tag push → build → push to ghcr.io + release ZIP |
| i18n | Chinese / English, localStorage persistence, room names translate |
| HACS | Custom repository, hassfest + hacs/action validated |
Works With
Any HA media_player entity that supports play_media. Tested daily with Xiaomi smart speakers, but it’ll work with Google Nest, Sonos, or anything HA can send audio to.
Links
- GitHub: GitHub - mdj2812/home-intercom: Push-to-talk PWA family intercom for Home Assistant — works with any smart speaker. · GitHub
- Docker image:
ghcr.io/mdj2812/home-intercom:latest
Star it if you find it useful. Happy to answer setup questions in the thread!
ESP32 Physical Button — now open source
No phone needed. Press the button, speak, broadcast to all your smart speakers.
- Firmware: GitHub - mdj2812/intercom-button: ESP32-S3 push-to-talk desktop button for home-intercom — press, record, broadcast. · GitHub
- Announcement: Intercom Button — ESP32-S3 push-to-talk hardware for Home Intercom
Changelog
v2.0.0 (2026-07-16) — Stable Release
- Native HA Integration: Runs directly inside Home Assistant. Config Flow (UI room setup), Options Flow (UI manage rooms), Device Registry (auto-link to Areas).
- Dual Config Entry: YAML + UI coexist, auto-merge with UI precedence.
- PWA Auth Fix: Shared secret token works reliably in Companion App WebView.
- Xiaomi Screen Fix: Clears display metadata after announcements.
- HTTP Security Warning: Detects insecure origins, disables buttons with helpful message (#42, #45).
- Three-tier Playback: Music Assistant →
repeat_set(off)→ timed pause — auto-selects per speaker.
Docker: ghcr.io/mdj2812/home-intercom:v2.0.0
HACS: Add custom repository, one-click install.
Thanks to @ngocjohn for testing and suggestions!
v1.6.3: Device names on room cards, offline speaker buttons auto-disabled, STATE_TIMEOUT for slow Bluetooth/MA devices, UI overhaul.
v1.6.2: Doorbell chime before announcements. MA players native, standard players get it baked into WAV. Per-room announce volume, greyed-out unavailable speakers.
v1.6.1: Three-tier auto-stop. MA play_announcement → HomePod/Chromecast repeat_set(off) → Xiaomi PAUSE_BUFFER timer.
