parallax-os/README.md

# 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://<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.