The next-generation HiFiBerryOS is a complete rewrite, now based on a standard Debian distribution. It uses Debian packages to install tools, audio players, and the user interface, making it more flexible and modular.
- Add your own player
- Power key — stop the power button on a remote from shutting the system down
- Tailscale — reach the device from anywhere without exposing it to the internet
Bug reports and feature requests belong in the
issue tracker.
Bug reports ask for the output of config-supportinfo, which collects the
hardware, package versions and recent errors we need.
Questions about setup, hardware or purchases are better placed with HiFiBerry support.
The system is composed of several core components:
We use PipeWire as a system daemon to manage concurrent access to the sound card by multiple players.
AudioControl is our central control service. It manages audio routing and integrates with player backends and the web user interface.
The WebUI is a static Vue application, installed to /usr/share/hifiberry/webui
and served by nginx, which is the device's single front door on port 80.
nginx also reverse-proxies every backend service. Each package ships its own nginx snippet, so a service's API prefix exists only when that package is installed:
| Prefix | Upstream |
|---|---|
/api/audiocontrol/ |
AudioControl on 127.0.0.1:1080 |
/api/config/ |
Configurator on localhost:1081 |
/api/auth/ |
hifiberry-auth on 127.0.0.1:1089 |
/api/roomeq/ |
RoomEQ on 127.0.0.1:10315 |
The prefix is rewritten before the request reaches the backend — /api/audiocontrol/
becomes /api/ on port 1080 — so a service's own documentation describes paths
without the prefix.
When the hifiberry-auth package is installed it adds an auth_request at server
level, so nginx gates every /api/<service>/ location and the individual services
do not implement authentication themselves. Without that package the device is
ungated.
Audio players are provided as standalone packages. You only need to install the ones you intend to use. Available players include:
- MPD – plays local music files (MP3, WAV, FLAC, etc.)
- Librespot – provides Spotify Connect support
- Raat – Roon audio playback (via the Roon Bridge)
- Shairplay – AirPlay 2 implementation
- Squeezelite – Logitech Media Server client
More players may be added in the future. You can also package and install your own player. To make it visible and controllable through AudioControl/WebUI, see Add your own player.
HiFiBerryOS runs on any 64-bit Raspberry Pi (Pi 3, Pi 4, or Pi 5) with a compatible HiFiBerry HAT. The system requires:
- RAM: 1GB minimum (2GB+ recommended for better performance)
- Storage: 8GB microSD card minimum (16GB+ recommended)
- Network: Ethernet or Wi-Fi connectivity
For streaming applications only:
- Any Pi 3, Pi 4, or Pi 5 will provide excellent performance
- Standard microSD card storage is sufficient
- Wi-Fi connectivity works well for most use cases
For large local music libraries (1000+ albums):
- Pi 5 with SSD highly recommended for optimal performance
- SSD storage significantly improves library scanning and indexing
- Ethernet connection preferred for network-attached storage (NAS) access
- Consider Pi 4 with 4GB+ RAM as a cost-effective alternative
- microSD Card: Suitable for streaming and small local libraries
- USB 3.0 SSD: Best performance for large libraries and frequent database operations
- Network Storage: NAS or network shares work well with sufficient network bandwidth
HiFiBerryOS supports all current HiFiBerry audio HATs. No sound cards from other manufacturers are supported.
To install HiFiBerryOS, start with Raspberry Pi OS Lite and add the required packages.
Start adding the HiFiBerry debian repository:
curl -Ls https://raw.githubusercontent.com/hifiberry/hifiberry-os/refs/heads/main/addrepo | bash
The install-all script will install the minimal base packages:
curl -Ls https://raw.githubusercontent.com/hifiberry/hifiberry-os/refs/heads/main/install-all | bash
Install a full or minimal set of packages. The full set includes all players, while the minimal comes only with mpd. We recommend the full installation for most users:
sudo apt install -y hbos-full
If you prefer a minimal installation and want to install only the players you really need:
sudo apt install -y hbos-minimal
sudo config-configtxt --default-config --enable-i2c
sudo reboot
Activate a lightweight Kiosk mode that presents the UI on the device. This replaces either the default Desktop (Raspberry Pi OS), or the terminal output (Raspberry Pi OS Lite).
Open the WebUI at http://:80/ to start the initial setup wizard. It will guide you through sound card selection, system naming, and service configuration.