Edit on GitHub

Getting started

Getting started with balenaSound is as simple as deploying it to a balenaCloud application; no additional configuration is required (unless you're using a DAC HAT). We've outlined the installation steps below. If you want a step-by-step tutorial on how to get balenaSound up and running, feel free to check these blog posts:

Hardware required


  • Any device from our supported devices list. For the best experience, we recommend using a Raspberry Pi 3B+ or 4B.
  • An SD Card! We recommend the Sandisk Extreme Pro series. 8GB should be plenty enough for this project.
  • Power supply
  • 3.5mm audio cable to the input on your speakers/Hi-Fi (usually 3.5mm or RCA). Alternatively you can use the HDMI port to get digital audio out.

Software required

One-click deploy

One-click deploy is the easiest way to get started with balenaSound as it allows you to deploy and configure the application with a single click and without the need of installing additional tools. Check out the CLI deploy instructions below if you are interested in an advanced alternative that enables you to achieve more complex deployments.

Deploy with balena

Click this button to go straight to application creation, where balenaSound will be pre-loaded to your application:

balena deploy button

Provision your device


Once your application has been created you'll need to add a device to it:

  1. Add a device to the application by clicking the add device button
  2. Download the OS and flash it to your SD card with balenaEtcher
  3. Power up your device and check it's online in the dashboard!

The balenaSound application will start downloading as soon as your device appears in the dashboard.

CLI deploy

This is the traditional and more advanced approach for deploying applications to balena powered devices. Installing and setting up the balena CLI is definitely more involved than using the Deploy with balena button, but it allows for more flexibility and customization when choosing what and when to deploy.

For example, if you don't plan on using the Spotify integration, you can edit the docker-compose.yml file and remove the Spotify service before deploying the application.

Provision your device

  1. Sign up for or login to the balenaCloud dashboard
  2. Create an application, selecting the correct device type. If you are using a Raspberry Pi (any model) we recommend setting the type as Raspberry Pi (v1 / Zero / Zero W) as your application will then be compatible with all Raspberry Pi versions.
  3. Add a device to the application, enabling you to download the OS
  4. Flash the downloaded OS to your SD card with balenaEtcher
  5. Power up your device and check it's online in the dashboard

Deploy the application

  • Install the balena CLI tools
  • Login with balena login
  • Download this project and from the project directory run balena push <appName> where <appName> is the name you gave your balenaCloud application in the first step.

Having trouble?

If you are running into issues getting your balenaSound application running, please try the following:

  1. Check the support and troubleshooting guide for common issues and how to resolve them.
  2. Post in the balenaSound forum for help from our growing community.
  3. Create an issue on the balenaSound GitHub project if you find your issue may be a problem with balenaSound.