# Parallax OS Parallax OS turns a Raspberry Pi into an always-on network speaker for [Astra](https://github.com/Boof2015/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](https://github.com/Boof2015/astra) running on another computer on the same network ## Install Parallax OS ### 1. Download the image Open the [Parallax OS releases](https://github.com/Boof2015/parallax-os/releases?q=parallax-os-v&expanded=true) 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](https://www.raspberrypi.com/software/) using **Use custom**, or with [balenaEtcher](https://etcher.balena.io/). 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/](http://parallax.local/) from a device on the same network. ### 4. Pair it with Astra On the computer where you play music: 1. Open Astra's **Settings**, then **Experimental**, and turn on **Enable Parallax**. 2. Open the new **Parallax** section and choose **Plays music** for this computer. 3. Select **Add a speaker**, then choose the Parallax speaker found on your network. 4. Enter the six-digit PIN shown at `parallax.local` or on the connected TV. 5. 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: ```sh 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://: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:///` 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.