Edit on GitHub


Some features of balenaSound can be configured by using environment variables. Depending on how you set them they will apply to all your devices, a specific device or a specific service. Regardless of what you want, they can be set using the balena dashboard:

Environment variable typeScopeInstructions
Fleet-wide environment variableall devices, all servicesnavigate to dashboard -> your app -> Environment variables
Fleet-wide service variableall devices, specific servicenavigate to dashboard -> your app -> Service variables
Device environment variablespecific device, all servicesnavigate to dashboard -> your app -> your device -> Device variables
Device service variablespecific device, specific servicenavigate to dashboard -> your app -> your device -> Device service variables

Setting the device name

You can read more about environment variables here.


The following environment variables apply to balenaSound in general, modifying it's behaviour across the board:

Environment variableDescriptionOptionsDefault
SOUND_MODESelect which mode of operation a device should use. For a detailed explanation see here.MULTI_ROOM, MULTI_ROOM_CLIENT, STANDALONEMULTI_ROOM, except for cases listed here.
SOUND_VOLUMEOutput volume level at startup.0 - 100, integer value without the % symbol.75
SOUND_DEVICE_NAME / BLUETOOTH_DEVICE_NAMEDevice name to be advertized by plugins (AirPlay device list, Spotify Connect and UPnP). For bluetooth use BLUETOOTH_DEVICE_NAMEAny valid string.balenaSound <plugin> <xxxx>, where:
- <plugin> is Spotify, AirPlay, UPnP
- <xxxx> the first 4 chars of the device UUID.
AUDIO_OUTPUTSelect the default audio output interface. See audio block.For all device types:
- AUTO: Automatic detection. Priority is USB > DAC > HEADPHONES > HDMI
- DAC: Force default output to be an attached GPIO based DAC

For Raspberry Pi devices:
- RPI_AUTO: Official BCM2835 automatic audio switching as described here
- RPI_HEADPHONES: 3.5mm audio jack
- RPI_HDMI0: Main HDMI port
- RPI_HDMI1: Secondary HDMI port (only Raspberry Pi 4)

For Intel NUC:
- NUCs have automatic output detection and switching. If you plug both the HDMI and the 3.5mm audio jack it will use the latter.


These options only have an effect on multi-room behaviour:

Environment variableDescriptionOptionsDefault
SOUND_MULTIROOM_MASTERForce multi-room to use the specified IP address as the multi-room master device. This can't be changed unless the variable is removed.An IPv4 formated IP address. Example:
SOUND_MULTIROOM_LATENCYSet multi-room client latency. Usually used to compensate for latency that speaker hardware might introduce (some Hi-Fi systems add a noticeable latency).Time in milliseconds. Example: 300---


The following environment variables control various aspects of each plugin behaviour:

Environment variableDescriptionOptionsDefaults
SOUND_DISABLE_PLUGINDisable the selected plugin. Useful when you don't want to use a particular plugin. There is one variable per plugin:
Plugin will be disabled if the variable exists regardless of it's value.---
SOUND_ENABLE_SOUNDCARD_INPUTIf your soundcard has inputs you can enable soundcard input by setting this variable. Sound coming in through the audio card will be treated as a new plugin/audio source.

This feature is still experimental!
Plugin will be enabled if the variable exists regardless of it's value.---
SOUND_SPOTIFY_USERNAMEYour Spotify login username. Required to use Spotify Connect over the internet.------
SOUND_SPOTIFY_PASSWORDYour Spotify login passsword. Required to use Spotify Connect over the internet.------
SOUND_SPOTIFY_DISABLE_NORMALISATIONDisable volume normalisation in Spotify.Disabled if the variable exists regardless of it's value.---
SOUND_SPOTIFY_BITRATESpotify playback bitrate.Bitrate in kbps: 90, 160 or 320160