Apppublic

Taikos/reachy_mini_speaker

sourceHugging Faceapache-2.0updated 5mo agoView on Hugging Face

3likes

App README

Reachy Mini Speaker

Turn your Reachy Mini into a smart speaker that any phone in the house can stream to — and watch it dance to the beat.

—AirPlay-compatible — works with anything an iPhone, iPad, or Mac can play (Apple Music, Spotify, YouTube, podcasts, system sounds). Powered by shairport-sync, the open-source AirPlay receiver. Not Apple-MFi-licensed.
—Spotify Connect-compatible — Reachy Mini appears in the Spotify app's device list. Lock-screen "Now Playing", multi-device queue, one-tap transfer all work. Powered by librespot, the open-source Spotify Connect client. Not officially licensed by Spotify.
—Beat-reactive motion — head bob, antenna pulse, and a subtle body sway, all synced to the music in real time. Hard-clamped to a conservative safety zone with a duty-cycle backoff for long playback sessions.
—Zero-config install — click Install in Reachy Mini Control. No curl | sh, no kernel modules, no systemd overrides.

Quick start

1.Open Reachy Mini Control on your phone or laptop.
2.Apps → search Reachy Mini Speaker → Install.
3.From the dashboard, hit Run.
4.First launch: the app auto-installs the two native dependencies (shairport-sync and raspotify, ~20 MB total). Reachy Mini OS configures user pollen with passwordless sudo, so this happens automatically — the web UI shows an "Installing audio codecs (~30 s)…" banner. Subsequent launches are instant.
5.On your phone:
6.iPhone / Mac: Control Center → AirPlay → pick Reachy Mini.
7.Spotify (any platform): Devices → pick Reachy Mini.
8.Play anything. The robot starts moving.

What "auto-install" actually does on first launch: adds the raspotify apt source (which ships an aarch64 librespot binary), runs apt install shairport-sync raspotify alsa-utils, disables the system shairport and raspotify services (we run our own per-app instances), and symlinks /usr/bin/librespot into the app's cache dir. All idempotent. If your robot's sudoers were customised to not be passwordless, the web UI will fall back to a clear message with the exact one-line install command to copy-paste.

How it works

   Phone (Spotify / AirPlay)
              │ Wi-Fi (mDNS discovery)
              ▼
   ┌─────────── Reachy Mini ───────────┐
   │  librespot   shairport-sync       │  ← per-app subprocesses
   │       │            │              │     spawned by main.py
   │       └──── PCM ───┘              │
   │              │                    │
   │              ▼                    │
   │   AudioTap (in-process tee)       │
   │        │              │           │
   │        ▼              ▼           │
   │     ALSA out    Beat detector     │  ← onset envelope autocorrelation
   │       (5W      (BPM + confidence) │
   │     speaker)         │            │
   │                      ▼            │
   │            TargetStore            │  ← single source of truth
   │                      │            │
   │                      ▼            │
   │      ControlLoop @ 100 Hz         │  ← only set_target call site
   │       │      │       │       │   │
   │     Head    Body  Antennas Pitch  │
   └────────────────────────────────────┘

No kernel modules. No systemd edits. No system-wide raspotify install. The whole audio path runs as subprocesses owned by this app, in this app's cache directory.

What's different from existing apps

This is not a fork of CreaturesDigital/spotify_dancer — credit to that project for being first, but it requires a curl | sh raspotify install, an snd-aloop kernel module load, and /etc/systemd/.../override.conf edits. We avoid all of that:

	spotify_dancer	reachy_mini_speaker
Spotify Connect	✅ system raspotify	✅ bundled per-app librespot
AirPlay	❌	✅
Install steps	curl install + systemd edits + kernel module	Click Install
Audio capture for beats	ALSA loopback (kernel)	In-process pipe tee (no kernel changes)
Survives Reachy OS updates	depends on systemd state	yes (lives in `~/.cache/`)

Controls

—Antenna press (bend forward or back, hold ~250 ms, release) — toggles reactive motion on/off.
—Antenna long-press (>1 s) — re-pairs (clears caches; phones will re-discover the speaker).
—Web UI — open http://reachy-mini.local:8042 for pair status and the on/off toggle.

Reactivity

One chill mode. Antennas are the primary rhythm cue — they swing at half-tempo (peak every other beat), small enough to stay quiet (~15° amplitude). The head bobs about 4 mm and nods ±2°. The body drifts ±5° on a slow 10-second cycle, ambient rather than beat-locked.

That's deliberate: the small antenna motors are nearly silent, the larger Stewart-platform and base motors stay calm so they don't whine over the music. Motion auto-pauses after 60 s of silence to keep motors cool.

Requirements

—Reachy Mini Wireless (Lite works for streaming, but mDNS auto-discovery is most reliable on Wireless's onboard Wi-Fi).
—Phone and robot on the same Wi-Fi network without client isolation (most home networks; many hotel/conference networks block this — use a phone hotspot if you hit issues).
—Spotify free or Premium (both work; Premium gets 320 kbps).

Troubleshooting

Symptom	Fix
First launch seems frozen	Codecs are downloading (~12 MB). The web UI banner says "downloading codecs…". On a slow network expect 30 s. Check `journalctl -u reachy-mini-daemon -f` to follow progress.
Robot doesn't appear in AirPlay menu	Phone and robot on same network? `shairport-sync` may not be installed — see SETUP.md "First-time setup" for the one-line apt install (or skip AirPlay and use Spotify only).
Robot doesn't appear in Spotify devices	Restart the app; Spotify caches device lists for a few minutes. Check the web UI's "Spotify Connect" tile — if it says "Hidden" the librespot subprocess isn't broadcasting.
Audio plays but no motion	Antenna short-press to enable reactivity, or use the web UI toggle. After 60 s of silence, motion auto-pauses to save the motors.
Audio glitchy	Move closer to your Wi-Fi router; check the network is uncongested.
Motion gets smaller over time	Duty-cycle backoff after 30 min of continuous play, by design — gives the antenna motors thermal headroom. Pause for a minute and full amplitude returns.
Motors stop responding	Daemon's thermal protection may have tripped. Stop and restart the app.
Conference / hotel Wi-Fi blocks discovery	Many such networks have client isolation. Use a phone hotspot, or USB-C-to-Ethernet directly to the robot.

Credits, trademarks & license

App source code: Apache-2.0. Bundled binaries (downloaded at runtime) keep their own licenses:

—librespot by librespot-org — MIT. Open-source reimplementation of the Spotify Connect protocol; not officially endorsed or licensed by Spotify AB.
—shairport-sync by Mike Brady — MIT. Open-source AirPlay 1 / AirPlay 2 audio receiver; not Apple-MFi-licensed and not officially endorsed by Apple Inc.

This is the same software stack used by community projects like raspotify, Snapcast, Volumio, and most non-MFi "AirPlay-compatible" hardware. Apple, AirPlay, and the AirPlay logo are trademarks of Apple Inc. Spotify and the Spotify logo are trademarks of Spotify AB. We don't claim any affiliation with either.

See THIRD_PARTY_NOTICES.md for full attributions.

Built by [Taikos](https://huggingface.co/Taikos). Inspired by Pollen Robotics' conversation app design system. Thanks to the Pollen team and the Reachy Mini community.