SmartestHome/hosts/audio-endpoint

Headless audio endpoint

For rooms that don't get a Sway thin client (hosts/thin-client/) but still want a speaker: a small headless appliance running its own independent Spotify Connect receiver — its own device name, its own room, no shared/synced stream. Two completely separate build pipelines, one per architecture, because the hardware paths genuinely differ (see below) — not one image with a flag.

	arm64 (Raspberry Pi)	amd64 (mini PC)
Audio hardware	HiFiBerry Amp2 HAT (GPIO, 60W, drives 4–8Ω passive speakers directly)	A USB DAC/amp, e.g. Fosi Audio V3 (USB Audio Class, drives passive speakers directly)
Build tool	rpi-image-gen	live-build (same tool hosts/thin-client/ uses)
Output	A bootable .img	A bootable live ISO
Per-room identity	Baked in at build time from CoreSystemConfig.json — one build per room (set build.arm64_prebake: false to get one generic image named in Pi Imager instead)	Baked in at build time — one build per room

Both variants share one thing: configs/spotify-connect.service + configs/spotify-connect-start, an architecture-independent systemd unit/wrapper pair. Nothing else is shared — see each variant's own section below.

Why two separate pipelines, not one

• The HiFiBerry Amp2 is a Raspberry Pi GPIO HAT. There's no amd64 equivalent slot to attach one to — an x86 mini PC needs a USB DAC/amp instead, plug-in hardware, not a HAT.
• rpi-image-gen is Raspberry-Pi-specific. It doesn't target amd64. Rather than reach for a third, unfamiliar toolchain for the x86 side, the amd64 image reuses the exact tool this repo already has and has already proven for a bootable image: live-build, the same one tools/build-thin-client-iso.sh drives. Lower risk than learning a new toolchain for one variant.

Spotify Connect install: apt-first, documented fallback

Neither spotifyd nor librespot is in Debian bookworm main — same situation hosts/thin-client/live-build/config/hooks/normal/0500-spotify-connect.hook.chroot already solved for the thin client. Both variants here reuse that exact logic and package order (spotifyd then librespot): try apt-get install for each (in case a backport/third-party repo has been added), and if neither installs, stop with a documented message rather than hardcoding a release URL that would silently 404 later. If you hit that message on a real build:

• fetch a release binary from https://github.com/librespot-org/librespot/releases (check the current tag yourself) into /usr/bin/librespot, or
• cargo build librespot in the relevant hook script, or
• use raspotify instead — it wraps librespot with its own packaging and systemd unit. If you go this route, drop this repo's spotify-connect.service/spotify-connect-start in favour of raspotify's own unit rather than layering both, or
• add a third-party apt repo that carries one of the above.

Spotify Premium is required either way — Spotify Connect doesn't work on Free.

Audio output: direct ALSA, not PipeWire

Deliberately different from the thin client's PipeWire/WirePlumber stack: this is a single-purpose headless appliance with exactly one audio-producing process, so there's no multi-app mixing need PipeWire exists to solve, and neither image runs a desktop session that would start a per-session PipeWire daemon anyway. spotify-connect-start talks straight to ALSA via --device "${ALSA_DEVICE:-default}".

arm64: Raspberry Pi + HiFiBerry Amp2

⚠️ The biggest risk in this whole directory

rpi-image-gen/config/audio-endpoint.yaml and the build script were written from rpi-image-gen's own README/documentation summary, not hands-on validated — no ARM build environment or the tool itself was available while writing this. If rpi-image-gen build -c config/audio-endpoint.yaml rejects the config:

rpi-image-gen layer --list
rpi-image-gen layer --describe <name>

on the real build host is the authoritative source. Adjust the keys in audio-endpoint.yaml to match what that reports — the intent behind each section (device target, packages, files to inject, which service to enable, the build-time install hook) should carry over even if the exact key names don't.

Build

cd hosts/audio-endpoint/rpi-image-gen/scripts
./build-audio-endpoint-image-arm64.sh

Clones rpi-image-gen (to /opt/smart-home/src/rpi-image-gen by default, override with RPI_IMAGE_GEN_SRC) if not already present, then builds. Output is a .img under that clone's work/ directory.

Per-room identity

The hostname is baked in, one image per room — same as every other image in this repo. tools/build-audio-endpoint-image-arm64.sh substitutes the endpoint's hostname from CoreSystemConfig.json's audio_endpoints array into a generated copy of config/audio-endpoint.yaml, and build-all.sh builds one per entry.

That's a change from the original design, which built one generic .img and left identity to Raspberry Pi Imager's OS Customisation dialog at flash time. Imager still works and is still the right tool for Wi-Fi and SSH keys (neither is baked in) — but hostname was worth moving into the build for two reasons:

• It was the only identity in the household still typed in by hand after a build, which is the exact step CoreSystemConfig.json exists to remove.
• It failed quietly when mistyped. spotify-connect-start reads $(hostname) at every service start, so a typo doesn't error — it just puts a Spotify Connect device with the wrong room name in the picker, and you find out when you cast to the wrong room.

The cost is real: one full rpi-image-gen run per room instead of one for all of them, and on an x86 build host each of those is a qemu-emulated arm64 bootstrap. If you have several arm64 rooms and a slow builder, set "arm64_prebake": false in the config's build section — that restores the single generic image, and build-all.sh will build it once no matter how many arm64 rooms are listed.

Hardware setup

dtoverlay=hifiberry-dacplus in /boot/firmware/config.txt (from HiFiBerry's own current docs, grouped under "DAC+ Standard/Amp2/Amp4" — worth confirming against your specific board revision before first boot) plus disabling onboard audio, so the HiFiBerry ends up as the only ALSA card (hw:0, which systemd/spotify-connect.service.d/10-alsa-device.conf pins ALSA_DEVICE to).

amd64: mini PC + USB DAC/amp

Build

cd hosts/audio-endpoint/live-build-amd64/scripts
sudo ./build-audio-endpoint-iso-amd64.sh

Same shape as tools/build-thin-client-iso.sh: installs live-build if missing, regenerates config/includes.chroot/ from the shared ../configs/ (git-ignored, generated — never hand-edit it), then runs lb config && lb build. Output is a hybrid ISO, written to a USB stick and live-booted — this image doesn't install itself to disk, same as the thin client.

Per-room identity

No Raspberry-Pi-Imager equivalent exists for a generic x86 ISO, so this variant uses the thin client's own already-proven pattern instead: IMAGE_HOSTNAME in the build script's CONFIGURATION block, baked in at build time. Edit it and re-run the script once per room — same convention as the thin client's own THINCLIENT_NAME/IMAGE_HOSTNAME. spotify-connect-start still just reads $(hostname) at start time; on this variant that value was set at build time instead of per-flash.

Hardware setup

Plug in a USB DAC/amp (e.g. Fosi Audio V3) — no driver needed, it's a standard USB Audio Class device. One manual step is required per physical unit: this repo can't know in advance which ALSA card index your specific mini PC assigns the USB device (it may also have onboard audio competing for card 0, and which one wins varies by board) — guessing one would be exactly the kind of "build against a guess" this project avoids elsewhere (gesture-config.json's camera_device, the ESP32 firmware's weather_entity_id). After first boot, over SSH:

aplay -l                      # find the USB DAC's card index, e.g. card 1
sudo mkdir -p /etc/systemd/system/spotify-connect.service.d
sudo tee /etc/systemd/system/spotify-connect.service.d/10-alsa-device.conf <<'EOF'
[Service]
Environment=ALSA_DEVICE=hw:1
EOF
sudo systemctl daemon-reload
sudo systemctl restart spotify-connect

Manual verification still outstanding

Nothing here has been built, flashed, or booted on real hardware — no Raspberry Pi, no HiFiBerry Amp2, no x86 test box, and no rpi-image-gen install were available while writing this. In rough order of what to check first:

1. rpi-image-gen's actual config/layer schema — see the risk callout above. The single most likely thing to need hand-adjustment.
2. The dtoverlay=hifiberry-dacplus line — cross-checked against HiFiBerry's own current docs, but not against your specific Amp2 board revision.
3. Whether spotifyd/librespot actually install from bookworm's apt sources at all — if not, the documented fallback list above is untested against which of those routes is actually easiest today.
4. The amd64 live-build tree's structure — checked for internal consistency against build-thin-client-iso.sh's own already-working structure, but the lb config/lb build invocation itself hasn't been run for this specific, much-smaller package/hook set.
5. USB DAC/amp enumeration — whether aplay -l reliably shows the DAC as a distinct, stable card index across reboots on a given mini PC, or whether it shifts (some boards' USB enumeration order isn't fully deterministic).
6. Restart=always behaviour — whether librespot/spotifyd/raspotify ever get into a crash-loop state that RestartSec=5 doesn't recover from cleanly on a headless box nobody is watching.
7. Neither image has Home Assistant integration of any kind — no MQTT, no HA entities, nothing reachable from the smart-home control surface at all. This is a deliberate scope decision (a self-contained per-room Spotify Connect appliance, matching the "per-room independent" choice this design started from), not an oversight — if remote control/monitoring from HA is wanted later, that's a separate addition, not assumed here.