Boof2015Parallax OS
Parallax OS turns a Raspberry Pi into an always-on network speaker for Astra. Put a Pi beside a stereo, powered speakers, or a TV and Astra can play to it in sync with the rest of your Parallax speakers.
Everything runs on your local network. There are no Parallax accounts, no cloud service, and no telemetry. Once set up, the receiver and its security updates are handled automatically.
Parallax OS works with or without a screen:
| Mode | What happens | How you control it |
|---|---|---|
| Headless | The Pi runs quietly beside your speakers with no display attached. | Use http://parallax.local/ from a phone or computer for setup, pairing, status, and audio output. |
| TV-connected | Connect HDMI before boot to show artwork, track information, and setup instructions on the TV. | Use the TV remote when HDMI-CEC is available, or use parallax.local at any time. A compatible remote is not required. |
What you need
- A compatible Raspberry Pi from the table below
- A microSD card and a way to flash it
- Ethernet or Wi-Fi
- An audio output: HDMI, a built-in headphone jack where available, or a USB DAC
- Astra running on another computer on the same network
Install Parallax OS
1. Download the image
Open the Parallax OS releases
and download the .img.xz file from the newest release named Parallax OS.
This repository also contains releases named Astra Receiver with receiver-v* tags. Those are
used by the manual installer and Parallax OS's auto updater, they are not SD-card images.
2. Flash the microSD card
Flash the downloaded .img.xz file with
Raspberry Pi Imager using Use custom, or with
balenaEtcher. You do not need to extract the file first.
Insert the card into the Pi. If you want the TV display, connect HDMI before turning the Pi on.
3. Connect it to your network
The first boot takes about 2–3 minutes and may include an automatic reboot.
- Ethernet: plug in the cable before boot. No network setup is needed.
- Wi-Fi: after about two minutes, join the temporary Parallax-Setup Wi-Fi network from a phone or computer. The setup page will ask you to choose your home Wi-Fi and enter its password. A connected TV also shows the setup network and a QR code.
When the Pi is connected, open http://parallax.local/ from a device on the same network.
4. Pair it with Astra
On the computer where you play music:
- Open Astra's Settings, then Experimental, and turn on Enable Parallax.
- Open the new Parallax section and choose Plays music for this computer.
- Select Add a speaker, then choose the Parallax speaker found on your network.
- Enter the six-digit PIN shown at
parallax.localor on the connected TV. - Approve the pairing on the web page or TV before the pairing window closes.
After pairing, use the Audio output setting at parallax.local to choose HDMI, the headphone
jack, or a connected USB DAC. Start playing in Astra and the Pi will join the selected Parallax
speakers in sync.
Raspberry Pi compatibility
| Raspberry Pi | Status | Notes |
|---|---|---|
| Pi 5 | Tested | Headless and TV-connected setups tested. Use HDMI or USB audio; the Pi 5 has no built-in headphone jack. |
| Pi 4 | Expected compatible | 64-bit hardware and expected to support both modes, but currently untested. |
| Pi 3 Model B | Tested | Headless and TV-connected setups tested, including HDMI and the built-in headphone jack. |
| Pi 3 Model B+ | Expected compatible | Expected to behave like the Pi 3 Model B, but not currently tested. |
| Pi Zero 2 W | Unverified | Not currently recommended; it has not been tested for Parallax OS performance or TV mode. |
| Pi 2, Pi 1, Zero, Zero W, and other 32-bit-only models | Unsupported | Parallax OS and its prebuilt receiver require 64-bit ARM hardware. |
For a TV-connected setup, 720p, 1080p, and 4k displays are the tested targets. HDMI-CEC support varies between TV manufacturers and models, but it is never required for audio playback or pairing.
Already running Raspberry Pi OS?
If you already maintain a Pi with a current 64-bit Raspberry Pi OS installation, you can add the headless Astra receiver without replacing the operating system:
curl -fsSL https://raw.githubusercontent.com/Boof2015/astra/dev/receiver/deploy/install.sh -o /tmp/astra-receiver-install.sh && sudo bash /tmp/astra-receiver-install.sh
When installation finishes, open http://<pi-address>:38405/ and follow the same pairing steps.
This option installs the headless receiver only; it does not add Parallax OS's TV display, Wi-Fi
onboarding, boot experience, or appliance management.
Troubleshooting
parallax.local does not open
Make sure the phone or computer is on the same network as the Pi. Some networks do not resolve
.local names; find the Pi's address in your router's connected-device list and open
http://<pi-address>/ instead.
The Parallax-Setup network does not appear
The setup network appears only when the Pi cannot reach a network. Disconnect Ethernet if you intend to set up Wi-Fi, then allow about two minutes after boot. If a Wi-Fi password is rejected, Parallax-Setup will reappear so you can try again.
The TV does not wake, switch inputs, or respond to its remote
HDMI-CEC has different brand names and may need to be enabled in the TV's settings. CEC is
optional: open http://parallax.local/ on another device to finish pairing or manage the speaker.
Audio comes from the wrong output
Open http://parallax.local/, choose Audio output, select HDMI, the headphone jack, or your
USB DAC, and apply the change.
Updates
Parallax OS automatically keeps its receiver software and operating-system security patches up to date. Normal receiver updates do not require reflashing the card. You only need a newer image for OS-level changes or a fresh installation.