Edit on GitHub


Plugins are the sources from where you can stream audio to your device. balenaSound comes with a set of plugins installed by default and the possibility of adding some extra ones with a bit of tinkering. We are always on the lookout for adding new plugins so keep an eye out!

Why not include all plugins by default? We want to avoid deploying all installable plugins by default because of (a) increased build time, (b) increased deploy time, (c) impact on device performance. Given that most users typically don't use more than one or two plugins it seems reasonable to limit defaults to the most popular ones to prevent users paying the cost of having many plugins that will never be used.


The following plugins ship with balenaSound out of the box:

  • Spotify Connect
  • Bluetooth
  • AirPlay
  • Soundcard input (Requires setting SOUND_ENABLE_SOUNDCARD_INPUT, see details)

Default plugins can be disabled at runtime via environment variables. For more details see here.


Spotify Connect requires a premium account. There is two methods of authentication:

  • zeroconf: most Spotify clients on smartphones, computers and smart tvs will automatically connect to balenaSound and pass on credentials without the need for manual authentication.
  • manual: providing user and password via variables, see customization section for details.

Manual authentication will let you stream audio over the internet from a client that is on a different network than the balenaSound device. This is useful if your balenaSound device is on a separate WiFi network that's harder to reach (e.g. a backyard network).


The following plugins are available to be added to your balenaSound installation:

  • UPnP: Universal Plug and Play
  • (Work in progress) Tidal Connect: See PR #399
  • (Work in progress) Roon Bridge: See PR #388

Installing these plugins is a more involved process than just deploying the off the shelf version of balenaSound. You'll need to edit the contents of the docker-compose.yml file before deploying the application. This means that you won't be able to deploy using the "Deploy with balena" button; you either need to use the CLI to deploy or use "Deploy with balena" with a forked version of the project. If you don't feel comfortable performing these steps or need some help along the way hit us up at our forums and we'll gladly help you out.


To install UPnP plugin add the following to the sevices section on your docker-compose.yml file:

    build: ./plugins/upnp
    restart: on-failure
    network_mode: host
      - 49494:49494