HiFiBerryOS Next: a Debian-based audio distribution for the Raspberry Pi

A rewrite onto a standard Debian

The next-generation HiFiBerryOS is a complete rewrite, now based on a standard Debian distribution. It uses Debian packages to install the tools, the audio players and the user interface, and the stated benefit is that this makes it more flexible and modular.

That is a significant change of approach for a vendor distribution, and the reasoning is visible throughout the documentation. Rather than shipping a bespoke image, the system is a set of packages on top of Raspberry Pi OS Lite, which means the normal Debian machinery does the work of installing, upgrading and removing pieces of the system.

The consequence for the user is that the player, the interface and the control service are not one binary. They are separate packages, and the system is assembled by installing the ones you want. The other consequence is that the base is a distribution you can also inspect, since the documentation tells you to start from Raspberry Pi OS Lite and add the required packages rather than flashing a vendor image.

The repository layout matches that model. There is a packages/ directory holding the Debian packages, scripts/ for the install helpers, a kiosk-mode/ directory for the on-device display mode, docs/ for the guides, and the addrepo and install-all scripts at the root, plus an upgrade-to-trixie file that suggests the migration path onto a newer Debian release.

The primary language is Python, the licence is not stated in the repository metadata, there are no GitHub releases, and the last push was on 2026-09-09.

PipeWire arbitrates the sound card, AudioControl routes the audio

The system is composed of several core components, and the first two decide what happens when two things want to play audio at once.

PipeWire is used as a system daemon to manage concurrent access to the sound card by multiple players. This is the part that makes the modular design viable. If MPD, Shairplay and Squeezelite each opened the device directly, the third one to start would fail or the audio would corrupt. With PipeWire in the middle as a daemon, the players become clients of a sound server, and the sharing is handled in one place.

AudioControl is the central control service, and it is a separate project at github.com/hifiberry/acr. It manages audio routing and integrates with the player backends and the web user interface. So the division of labour is clean: PipeWire is the mechanism, AudioControl is the policy, and the user interface is one of the consumers of that policy.

That is the architecture that lets players be packages. A player does not need to know about routing, it needs to register itself with AudioControl, and the WebUI needs to know which players exist and what they are doing, which is again AudioControl's job. The guide on adding your own player exists precisely to describe that registration contract.

The audio topics attached to the repository match this stack, with alsa, dsp, bluetooth and airplay among the tags, alongside the player names.

nginx is the single front door, and each package adds a route

The user interface and the API surface are the same thing in this design, and nginx is what joins them.

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, and the routing is built from the packages themselves. Each package ships its own nginx snippet, so a service's API prefix exists only when that package is installed. The routes are:

| 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, so /api/audiocontrol/ becomes /api/ on port 1080, and a service's own documentation describes paths without the prefix. That is a small but important detail, because it means the documentation of each backend is written in terms of its own API rather than the device's routing table.

The consequence of the package-driven design is that the device's surface changes with what is installed. A device with only mpd has no /api/roomeq/ route at all, and one with RoomEQ installed has it. There is no fixed list of endpoints for the whole system, which is convenient for the modularity and awkward for anyone writing a script against a device without knowing what is installed on it.

The authentication gate is an optional package

This is the detail to read twice before you put a device on a network you do not fully control.

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 documentation says plainly, the device is ungated.

The design is coherent. The services listen on loopback addresses, 127.0.0.1 for AudioControl, hifiberry-auth and RoomEQ, and localhost for the Configurator, so they are not directly reachable from the network, and the only door in is nginx on port 80. Authentication is therefore a property of the front door rather than of each backend, which is the right place for it and much less work for a package author.

But the gate is a package, and packages are optional. A minimal installation, hbos-minimal, brings only mpd, and if the authentication package is not in it, then the WebUI and every API it can reach are open to anything that can reach port 80. The word ungated is doing the work in that sentence.

The documentation does not leave you to infer the mitigation. There is a Tailscale guide, reach the device from anywhere without exposing it to the internet, and a power key guide for stopping a remote's power button from shutting the system down. The Tailscale route is the one to consider for a device that lives on your network, because it means the port is never exposed in the first place.

Players are packages you pick

Audio players are provided as standalone packages, and you only need to install the ones you intend to use. The available players are:

MPD plays local music files, MP3, WAV, FLAC and the rest. Librespot provides Spotify Connect support. Raat is Roon audio playback, via the Roon Bridge. Shairplay is an AirPlay 2 implementation. Squeezelite is a Logitech Media Server client.

More players may be added in the future, and you can also package and install your own player. To make it visible and controllable through AudioControl and the WebUI, the documentation points at the Add your own player guide. That is the point of the design: a player is a package that talks to AudioControl, and adding one does not require modifying the control service or the interface.

The installation side has the same shape. The full set includes all players, while the minimal one comes only with mpd, and the documentation recommends the full installation for most users:

sudo apt install -y hbos-full

and for a minimal installation with only the players you really need:

sudo apt install -y hbos-minimal

Because these are ordinary Debian packages, they are also removable in the ordinary way, which matters for a device with limited storage. A Pi with a small card can carry the minimal set and add players later as the library grows.

Installing on Raspberry Pi OS Lite

The install path is a set of curl commands and two apt packages, and it starts from Raspberry Pi OS Lite rather than from a vendor image.

The first step adds the HiFiBerry Debian repository:

curl -Ls https://raw.githubusercontent.com/hifiberry/hifiberry-os/refs/heads/main/addrepo | bash

The second runs the install-all script, which installs the minimal base packages:

curl -Ls https://raw.githubusercontent.com/hifiberry/hifiberry-os/refs/heads/main/install-all | bash

Then the base configuration, which writes the default config.txt with I2C enabled and reboots:

sudo config-configtxt --default-config --enable-i2c
sudo reboot

The I2C flag is there for a reason specific to this hardware, since the HAT communicates over I2C, and the configuration has to be in place before the audio hardware is usable.

Kiosk mode is optional and replaces either the default Raspberry Pi OS desktop or, on Lite, the terminal output with the interface on the device itself. The instructions are in docs/kiosk-mode.md.

After the reboot you open the WebUI at http://<device-ip>:80/, and the initial setup wizard takes you through sound card selection, system naming and service configuration. That wizard is the first thing a user sees, and the fact that it is served from the device rather than from a phone app keeps the whole configuration on the box.

Hardware limits and where to ask for help

The hardware section is specific about what the software can expect, and it separates the streaming case from the local library case.

HiFiBerryOS runs on any 64-bit Raspberry Pi, the Pi 3, Pi 4 or Pi 5, with a compatible HiFiBerry HAT. The minimum is 1GB of RAM with 2GB or more recommended, an 8GB microSD card minimum with 16GB or more recommended, and Ethernet or Wi-Fi connectivity.

For streaming applications only, any of those Pi models will provide excellent performance, a standard microSD card is sufficient, and Wi-Fi works well for most use cases. For large local music libraries of a thousand albums or more, a Pi 5 with an SSD is highly recommended for optimal performance, because the SSD significantly improves library scanning and indexing, Ethernet is preferred for network-attached storage access, and a Pi 4 with 4GB or more of RAM is the cost-effective alternative.

The storage options follow the same logic. A microSD card suits streaming and small local libraries, a USB 3.0 SSD is best for large libraries and frequent database operations, and network storage works well given sufficient bandwidth.

The compatibility boundary is the one to note: HiFiBerryOS supports all current HiFiBerry audio HATs, and no sound cards from other manufacturers are supported. That is a vendor decision, and it means the software is not a general-purpose Raspberry Pi audio distribution.

Support is split in two, which is worth knowing before you file anything. Questions about setup, hardware or purchases go to the HiFiBerry support forum, while bug reports and feature requests belong in the issue tracker, where they ask for the output of config-supportinfo, which collects the hardware, package versions and recent errors. The repository also holds a TODO file, a progress-report.md, a .codereview.toml configuration and a githooks/ directory.

Editorial conclusion

Adopt HiFiBerryOS Next if you run a Raspberry Pi as a dedicated network player and want to choose your own players, keep the system on ordinary Debian packages so the software is updatable, and are comfortable with a device whose user interface is a local web page. Do not adopt it if you need third-party sound cards, since only HiFiBerry HATs are supported, or if you need a locked-down device on an untrusted network, because the authentication gate is an optional package. Before you start, install the hifiberry-auth package if the device will be reachable from anywhere, use the Tailscale guide instead of exposing port 80 to the internet, and attach the output of config-supportinfo to any bug report.

Frequently asked questions

Official sources

1. hifiberry/hifiberry-os on GitHub
2. Issues
3. README