Skip to content

Add built-in audio support, modify/uninstall scripts and Trixie fix #5

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ermanno00 wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Add built-in audio support, modify/uninstall scripts and Trixie fix #5

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
11a8d0e
Expand audio device support: added compatibility for built-in audio a…
ermanno00 May 18, 2026
9686254
Add uninstall, modify, and manager scripts for AirPlay setup. Added l…
ermanno00 May 18, 2026
b0b2ec8
Add optional Spotify Connect support via raspotify: installer, config…
ermanno00 May 18, 2026
0d59971
Add alternative repository clone option in README
ermanno00 May 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
181 changes: 142 additions & 39 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,83 +1,186 @@
# RaspberryPi-AirPlay-Installer 📻

Turn any Raspberry Pi (Zero 2 W, 3, 4, 5) into a modern, high-quality AirPlay 2 receiver in just 5 minutes. This project uses a set of robust scripts to automate the entire installation process, making it incredibly easy to revive your old home theater or favorite speakers.
Turn any Raspberry Pi (Zero 2 W, 3, 4, 5) into a modern, high-quality **AirPlay 2** receiver — and, optionally, a **Spotify Connect** endpoint — in just a few minutes. This project automates the entire build of [Shairport-Sync](https://github.com/mikebrady/shairport-sync) + [NQPTP](https://github.com/mikebrady/nqptp) and the install/configuration of [raspotify](https://github.com/dtcooper/raspotify) with a set of robust, interactive scripts.

> **If you find this project helpful, please consider giving it a ⭐ star on GitHub!** It helps others discover it and shows your appreciation for the work. Also, please like the video and **[subscribe to the channel](https://www.youtube.com/@ravis1ngh)**. It helps us create more content like this.
> **If you find this project helpful, please consider giving it a ⭐ star on GitHub!**

The goal of this project was to simplify the manual installation process, making it accessible to everyone.
---

## ✨ Features

| The Old, Manual Way (40+ Minutes) | The New, Automated Way (5 Minutes!) |
| :---: | :---: |
| [![Manual AirPlay 2 Pi Setup](https://img.youtube.com/vi/WeibcfMywXU/0.jpg)](https://www.youtube.com/watch?v=WeibcfMywXU) | **[Link to New Video Coming Soon!]** <br> *(Placeholder for your new, shorter video)* |
* **🚀 Fast setup** — From a fresh Raspberry Pi OS to a working AirPlay 2 speaker in minutes.
* **🤖 Fully automated** — Handles system update, dependencies, compiling and configuration.
* **✅ Smart pre-flight checks** — Validates internet, disk space, memory and detected hardware before changing anything.
* **🔊 Flexible audio** — Works with **USB DAC**, **audio HAT**, or the **Raspberry Pi's built-in audio** (3.5mm jack / HDMI). All detected devices are listed and labelled `[built-in]` / `[external/DAC]`.
* **🎧 Optional Spotify Connect** — Installer can also set up `raspotify` (librespot) so the same Pi appears as a Spotify Connect endpoint. Coexists with AirPlay; one source plays at a time.
* **🛠️ Idempotent management** — Dedicated scripts to **modify** or **uninstall** an existing installation without reinstalling from scratch.
* **🎚️ Volume control aware** — Auto-selects the best ALSA mixer (`PCM`, `Master`, `Speaker`, ...) and falls back to software volume if no hardware mixer is available.
* **🔁 Rollback on failure** — Backs up configuration files and cleans up on failed installs.
* **📋 Detailed logging** — Every installation writes a timestamped log under `/tmp/airplay_install_*.log`.

---

### ✨ Features
## 🧰 Hardware Requirements

| Component | Recommended |
| --- | --- |
| Raspberry Pi | Zero 2 W, 3, 4 or 5 |
| MicroSD card | Quality card, ≥ 8 GB |
| Power supply | Official PSU for your Pi |
| Audio output | USB DAC, audio HAT **or** built-in 3.5mm / HDMI |

* **🚀 5-Minute Setup:** Go from a fresh Raspberry Pi OS to a working AirPlay 2 speaker in minutes.
* **🤖 Fully Automated:** The script handles system updates, dependency installation, compiling, and configuration.
* **✅ Smart Pre-Checks:** A pre-installation script verifies your system is ready, checking for internet, disk space, and audio devices to prevent errors.
* **🔌 USB DAC Auto-Detection:** Intelligently finds your external USB sound card and lets you choose the correct one if you have multiple.
* **⚙️ Optimized for Performance:** Automatically configures settings for the best audio quality and prompts to disable Wi-Fi power saving to prevent dropouts.
* **🛠️ Robust & Reliable:** Includes error handling and detailed logging for easy troubleshooting.
> The older Pi 1 / Pi Zero W are not officially supported — they typically lack the CPU headroom for AirPlay 2.

---

### Hardware Requirements
## 📦 What's in the box

* **Raspberry Pi:** A Pi Zero 2 W, 3, 4, or 5 is recommended.
* **MicroSD Card:** A quality card with at least 8GB.
* **Power Supply:** The official power supply for your Pi model.
* **Audio Output:**
* For Pi Zero: An **OTG cable** and a **USB DAC** with a 3.5mm output.
* For Pi 3/4/5: The built-in 3.5mm jack or an optional USB DAC.
All scripts live under `RaspberryPi-AirPlay-Installer-Scripts/`:

| Script | Purpose |
| --- | --- |
| `pre_check_airplay_on_pi.sh` | Read-only system check before installing. |
| `install_airplay_v3.sh` | Main installer: deps, build, service, config. |
| `modify_airplay.sh` | Edit an existing install (name, audio device, mixer, volume...). |
| `uninstall_airplay.sh` | Cleanly remove Shairport-Sync, NQPTP, services and config. |
| `airplay_manager.sh` | Unified menu that dispatches to the three scripts above. |

---

### 🚀 Quick Start Installation
## 🚀 Quick Start

After flashing **Raspberry Pi OS** (Lite is fine) and connecting via SSH, you have two options.

After installing Raspberry Pi OS Lite and connecting to your Pi via SSH, run this single command. It will download the pre-check script and, if successful, automatically launch the main installer.
### Option A — Run from this repo (recommended for development)

```bash
git clone https://github.com/Techposts/RaspberryPi-AirPlay-Installer.git
or git clone https://github.com/ermanno00/RaspberryPi-AirPlay-Installer.git
cd RaspberryPi-AirPlay-Installer/RaspberryPi-AirPlay-Installer-Scripts
bash airplay_manager.sh # unified menu
```

The menu lets you install, modify or uninstall, and tail live service logs.

### Option B — One-shot install from upstream

```bash
curl -sSL https://raw.githubusercontent.com/Techposts/RaspberryPi-AirPlay-Installer/main/RaspberryPi-AirPlay-Installer-Scripts/pre_check_airplay_on_pi.sh | bash
curl -sSl https://raw.githubusercontent.com/Techposts/RaspberryPi-AirPlay-Installer/main/RaspberryPi-AirPlay-Installer-Scripts/install_airplay_v3.sh | bash
curl -sSL https://raw.githubusercontent.com/Techposts/RaspberryPi-AirPlay-Installer/main/RaspberryPi-AirPlay-Installer-Scripts/install_airplay_v3.sh | bash
```

The script is interactive and will guide you through the process. Once finished, it will reboot, and your AirPlay 2 receiver will be ready to use!
The installer is interactive: it will ask you to pick the audio device, give your AirPlay endpoint a name and decide on Wi-Fi power management. When it's done, the Pi will offer to reboot and your speaker is ready.

> **Do not run any of these scripts with `sudo`.** They invoke `sudo` only where needed and will refuse to start as `root`.

---

### ✅ The Final Result
## 🎛️ Modifying an existing installation

When you're done, your setup will be seamless. Your Raspberry Pi will appear as a native AirPlay device on your network, ready to stream from any Apple device.
Need to rename the speaker, change the audio output or adjust volume limits? You don't have to reinstall.

| Mobile Screenshot | Hardware Setup |
| :---: | :---: |
| **** <br> *Your new device, ready to connect.* | **** <br> *The simple and clean hardware setup.* |
```bash
bash modify_airplay.sh
```

The interactive menu provides:

1. Change AirPlay name
2. Change audio output device (USB DAC / HAT / built-in)
3. Change mixer / hardware volume control (or disable it)
4. Change volume limits (`volume_max_db`, `default_airplay_volume`)
5. Test audio output
6. View current configuration
7. Show service status
8. Restart service
9. Edit `/etc/shairport-sync.conf` manually (+ auto restart)

All changes are written to `/etc/shairport-sync.conf` and the service is restarted automatically.

The Spotify Connect section of the same menu lets you:

* Install / reconfigure Spotify Connect (raspotify)
* Change the Spotify device name (independent from the AirPlay one)
* Sync the Spotify audio device to the current AirPlay one
* Uninstall Spotify Connect

> **Spotify Premium is required** on the controller device.
> Shairport-Sync and raspotify share the same ALSA card, so only one source can play at a time — the inactive one releases the device automatically, no extra config needed.

---

### How It Works
## 🧹 Uninstalling

```bash
bash uninstall_airplay.sh
```

Removes:

* `shairport-sync` and `nqptp` binaries
* `/etc/shairport-sync.conf` and sample
* systemd units (`shairport-sync.service`, `nqptp.service`)
* The `shairport-sync` user and group
* UFW firewall rules added during install (`5353/udp`, `319/udp`, `320/udp`, `7000/tcp`)
* `raspotify` package + apt repository, if Spotify Connect was installed

This project uses a two-script system for a safe and reliable installation:
A backup of the current config is saved under `/tmp/airplay_uninstall_backup_<timestamp>/` before anything is deleted.

1. **`pre_check_airplay_on_pi.sh`:** A non-invasive script that checks your system for common issues without making any changes. If all checks pass, it automatically downloads and runs the main installer.
2. **`install_airplay_v3.sh`:** The powerful main installer that performs all the required actions to build and configure the AirPlay 2 software (`Shairport-Sync` and `nqptp`).
> APT build dependencies (`libsoxr-dev`, `libplist-dev`, ...) are intentionally **not** removed — other software on your system may rely on them. The uninstaller prints the `apt-get` command to remove them manually if you want a fully clean state.

---

### ❤️ Support the Project
## 🐛 Troubleshooting

**`configure: error: plistutil can not be found`** (Debian 13 "Trixie" / Pi OS Bookworm successor)

On recent releases the `plistutil` binary moved from `libplist-dev` to a separate package `libplist-utils`. The installer in this repo already pulls it in. If you hit this on an older copy:

```bash
sudo apt-get install -y libplist-utils
bash install_airplay_v3.sh
```

**The Pi doesn't appear in the AirPlay picker**

* Make sure iPhone/iPad and Pi are on the **same Wi-Fi network and same subnet**.
* Check that `avahi-daemon` is running: `systemctl status avahi-daemon`.
* Tail the service: `sudo journalctl -u shairport-sync -f`.

**Audio stutters / drops out**

If this installer helped you bring your old speakers back to life, please consider showing your support!
* Disable Wi-Fi power management: `sudo raspi-config` → Performance → Wireless LAN → Power Management → Disable.
* On Pi Zero 2, prefer a wired ethernet adapter or stay close to the access point.

* **⭐ Star the Repository:** Starring this project on GitHub is a great way to show your appreciation and helps others find it.
* **👍 Like & Subscribe:** If you came from the video tutorial, please **like the video** and **[subscribe to the channel](https://www.youtube.com/@ravis1ngh)**. It helps us create more content like this.
**Useful one-liners**

```bash
sudo systemctl status shairport-sync # service health
sudo journalctl -u shairport-sync -f # live logs
sudo nano /etc/shairport-sync.conf # manual edit (then restart)
sudo systemctl restart shairport-sync
```

---

## ⚙️ How it works

### License
1. **`pre_check_airplay_on_pi.sh`** — non-invasive system check (no changes made).
2. **`install_airplay_v3.sh`** — installs build deps, clones and compiles `nqptp` and `shairport-sync` with `--with-airplay-2`, writes `/etc/shairport-sync.conf`, creates a systemd service and a dedicated user, configures UFW if active.
3. **`modify_airplay.sh`** — edits `/etc/shairport-sync.conf` in place via targeted `sed` rules and restarts the service.
4. **`uninstall_airplay.sh`** — reverses everything the installer did, in dependency-safe order.
5. **`airplay_manager.sh`** — thin wrapper that picks the right script based on what's currently installed.

This project is licensed under the MIT License. See the `LICENSE` file for details.
---

## 🙏 Credits

* [Mike Brady](https://github.com/mikebrady) — author of Shairport-Sync and NQPTP, the upstream projects that make all of this possible.
* [David Cooper](https://github.com/dtcooper) — author of [raspotify](https://github.com/dtcooper/raspotify), used here for optional Spotify Connect support.
* Original installer scripts: [Techposts/RaspberryPi-AirPlay-Installer](https://github.com/Techposts/RaspberryPi-AirPlay-Installer).

---

## 📜 License

This project is licensed under the MIT License. See the `LICENSE` file for details.
132 changes: 132 additions & 0 deletions RaspberryPi-AirPlay-Installer-Scripts/airplay_manager.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,132 @@
#!/bin/bash

# ===================================================================================
# AirPlay 2 Manager — Unified menu for install / modify / uninstall
#
# Dispatches to the dedicated scripts in the same directory:
# install_airplay_v3.sh — First-time installation
# modify_airplay.sh — Modify existing installation
# uninstall_airplay.sh — Remove the installation
# ===================================================================================

set -eo pipefail
IFS=$'\n\t'

SCRIPT_VERSION="1.0"
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

cecho() {
local code="\033["
local color
case "$1" in
"red") color="${code}1;31m" ;;
"green") color="${code}1;32m" ;;
"yellow") color="${code}1;33m" ;;
"blue") color="${code}1;34m" ;;
"magenta") color="${code}1;35m" ;;
"cyan") color="${code}1;36m" ;;
*) color="${code}0m" ;;
esac
echo -e "${color}$2\033[0m"
}

run_script() {
local script_name="$1"
local script_path="$SCRIPT_DIR/$script_name"
if [ ! -f "$script_path" ]; then
cecho "red" "❌ Script not found: $script_path"
read -p "Press Enter to continue..." || true
return 1
fi
echo
bash "$script_path" || true
echo
read -p "Press Enter to return to the menu..." || true
}

is_installed() {
[ -f /etc/shairport-sync.conf ] && command -v shairport-sync >/dev/null 2>&1
}

service_status_line() {
if systemctl is-active --quiet shairport-sync 2>/dev/null; then
echo "active"
elif systemctl list-unit-files 2>/dev/null | grep -q '^shairport-sync\.service'; then
echo "inactive"
else
echo "not registered"
fi
}

current_name() {
[ -f /etc/shairport-sync.conf ] || { echo ""; return; }
grep -oE '^[[:space:]]*name[[:space:]]*=[[:space:]]*"[^"]*"' /etc/shairport-sync.conf 2>/dev/null \
| head -1 | sed -E 's/.*"([^"]*)".*/\1/' || true
}

spotify_installed() {
dpkg -l raspotify 2>/dev/null | grep -q '^ii'
}

spotify_status_line() {
if ! spotify_installed; then
echo "not installed"
elif systemctl is-active --quiet raspotify 2>/dev/null; then
echo "active"
else
echo "inactive"
fi
}

while true; do
clear
cecho "green" "╔═════════════════════════════════════════════════════╗"
cecho "green" "║ AirPlay 2 Manager (Raspberry Pi) v$SCRIPT_VERSION ║"
cecho "green" "╚═════════════════════════════════════════════════════╝"
echo
if is_installed; then
cecho "green" " ✓ Shairport-Sync installed"
cecho "blue" " AirPlay service: $(service_status_line)"
cecho "blue" " AirPlay name: $(current_name)"
cecho "blue" " Spotify Connect: $(spotify_status_line)"
else
cecho "yellow" " ⚠ Shairport-Sync NOT installed."
fi
echo
echo " 1) Install AirPlay 2"
echo " 2) Modify existing installation"
echo " 3) Uninstall"
echo " 4) Show service logs (live, Ctrl+C to exit)"
echo " 0) Exit"
echo
read -p "Choose: " choice || true
case "$choice" in
1) run_script "install_airplay_v3.sh" ;;
2)
if ! is_installed; then
cecho "red" "❌ No installation detected. Install first."
read -p "Press Enter..." || true
continue
fi
run_script "modify_airplay.sh"
;;
3)
if ! is_installed; then
cecho "red" "❌ No installation detected to uninstall."
read -p "Press Enter..." || true
continue
fi
run_script "uninstall_airplay.sh"
;;
4)
if ! is_installed; then
cecho "red" "❌ No installation detected."
read -p "Press Enter..." || true
continue
fi
sudo journalctl -u shairport-sync -f || true
;;
0|q|Q|"") cecho "blue" "Bye!"; exit 0 ;;
*) cecho "red" "Invalid choice."; sleep 1 ;;
esac
done
Loading