odio

Turns a Raspberry Pi or any Debian-based Linux into a multi-source audio streamer.

Release License Build GitHub Sponsors All Contributors

Bluetooth AirPlay Spotify Connect UPnP / DLNA MPD Multi-room Tidal & Qobuz PulseAudio TCP

Part of the odio project — Full documentation.

Debian Go htmx Tailwind CSS Python Ansible Bash GitHub Actions Svelte Astro Starlight

odios turns a 35ドル Raspberry Pi into what commercial streamers sell for 300ドル–500: Bluetooth A2DP (in & out), AirPlay, Snapcast multi-room, UPnP/DLNA, CD playback with metadata — all in one box, controlled from a web app, no account or subscription required. Other PCs running PulseAudio or PipeWire can also stream directly to it over the network, making it a true whole-home audio sink.

Built on modern foundations: everything runs as unprivileged systemd user services (no root daemons), orchestrated through a unified REST API written in Go. Battle-tested on a Raspberry Pi B+ (armv6l) for over 6 years without reinstall.

Full Home Assistant integration included — odios nodes appear as native media players in your HA dashboard.

Home Assistant integration

┌─────────────────────────────────────────────────────┐
│ odio-pwa (remote) │ ← manage multiple nodes from any device
└────────────────────────┬────────────────────────────┘
 │ HTTP
┌────────────────────────▼────────────────────────────┐
│ go-odio-api │ ← unified REST API + embedded UI
│ systemd · PulseAudio · MPRIS · Bluetooth │
│ │
└──────┬──────────┬──────────┬──────────┬─────────────┘
 │ │ │ │
 PulseAudio MPD Shairport Snapcast
 (network) Sync client
 Bluetooth MPD (AirPlay) upmpdcli
 (A2DP) Disc (UPnP/DLNA)
 Player

Most service run as systemd user services — no root daemons, full per-user isolation.

The fastest way to get started on a Raspberry Pi: flash a pre-built image with Raspberry Pi Imager.

1. Open Raspberry Pi Imager
2. Go to Options app > Content Repository > Use custom URL
3. Enter:

   https://github.com/b0bbywan/odios/releases/latest/download/odio.rpi-imager-manifest
   

4. Select your image, configure hostname/SSH/WiFi/user, and flash

See image-builder/README.md for details and manual flashing options.

curl -fsSL https://github.com/b0bbywan/odios/releases/latest/download/install.sh | bash

The installer works on both fresh and existing systems (idempotent, safe to re-run). It prompts for a target user — if the user doesn't exist it is created automatically. Installing for an existing user is supported: config files are backed up before any modification.

See installer/README.md for full installation options, environment variables, and testing.

Each release installs /usr/local/bin/odio-upgrade with two subcommands: check runs daily via a systemd user timer and refreshes /var/cache/odio/upgrades.json; apply performs the upgrade.

odio-upgrade # alias of `apply` — upgrade to the latest reported version
odio-upgrade apply --version 202650 # target a specific version
odio-upgrade apply --reinstall # re-run every role in full (repair a broken install)
odio-upgrade apply --progress # emit structured progress events for odio-api

odio-upgrade reads /var/lib/odio/state.json (or rebuilds from dpkg as a last resort) to preserve the feature selection and role opt-outs across upgrades. Run odio-upgrade --dry-run --force to see what would be invoked without running it. Use --reinstall to force every role through a full first-install pass (bypassing the smart-upgrade skips) when an install needs repairing. Use --progress to emit structured ODIO_PROGRESS JSON lines (one per role and phase) to stdout for odio-api to display, without altering the normal output.

• go-odio-api — REST API and embedded UI
• odio-ha — Full Home Assistant integration: odios nodes appear as native HA media players and can be mapped to official integrations to inherit their full capabilities
• odio-pwa — Progressive Web App to control multiple odios nodes (live)
• go-mpd-discplayer — CD/USB player daemon
• mpd2mpris — MPRIS bridge for MPD with CUE and remote cover art support
• Snapclientmpris — MPRIS bridge for snapclient

This project is licensed under the BSD 2-Clause License — see LICENSE.

The installer distribution (odio-*.tar.gz) includes ansible-core, which is licensed under the GNU General Public License v3.0. A copy of that license is included in the archive under licenses/ANSIBLE-LICENSE-GPLv3.

The odios playbooks and scripts are independent works that invoke ansible-core as an external tool and are not subject to the GPL.

Thanks goes to these wonderful people (emoji key):

This project follows the all-contributors specification. Contributions of any kind welcome!