Customization

Some features of balenaSound can be configured by using 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:

Variable type	Scope	Instructions
Fleet-wide variable	all devices, all services	navigate to dashboard -> your fleet -> Variables -> Select All services
Fleet-wide service variable	all devices, specific service	navigate to dashboard -> your fleet -> Variables -> Select target service
Device variable	specific device, all services	navigate to dashboard -> your fleet -> your device -> Device variables -> Select All services
Device service variable	specific device, specific service	navigate to dashboard -> your fleet -> your device -> Select All services -> Select target service

You can read more about variables here.

General

The following variables apply to balenaSound in general, modifying its behavior across the board:

Variable	Description	Options	Default
SOUND_MODE	Select which mode of operation a device should use. For a detailed explanation see here.	MULTI_ROOM, MULTI_ROOM_CLIENT, STANDALONE	MULTI_ROOM, except for cases listed here.
SOUND_VOLUME	Output volume level at startup.	0 - 100, integer value without the % symbol.	75
SOUND_DEVICE_NAME / BLUETOOTH_DEVICE_NAME	Device name to be advertised by plugins (AirPlay device list, Spotify Connect and UPnP). For bluetooth use BLUETOOTH_DEVICE_NAME	Any valid string.	balenaSound <plugin> <xxxx>, where: - <plugin> is Spotify, AirPlay, UPnP - <xxxx> the first 4 chars of the device UUID.
AUDIO_OUTPUT	Select 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.	AUTO
SOUND_INPUT_LATENCY	Input loopback latency in milliseconds. Useful when experiencing frequent audio stuttering due to underruns. Note that this is only a friendly request, the actual latency might be higher.	1 - 2000.	200
SOUND_OUTPUT_LATENCY	Output loopback latency in milliseconds. Note that this is only a friendly request, the actual latency might be higher.	1 - 2000.	200
SOUND_SUPERVISOR_PORT	Web port that is used for serving API and UI by sound supervisor.	Any valid port number	80

Multi-room

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

Variable	Description	Options	Default
SOUND_MULTIROOM_MASTER	Force 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 formatted IP address. Example: 192.168.1.10	---
SOUND_MULTIROOM_LATENCY	Set 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	---
SOUND_MULTIROOM_POLL_INTERVAL	Set how often multi-room devices sync up across the fleet.	Time in seconds. Example: 120	60
SOUND_MULTIROOM_DISALLOW_UPDATES	Prevent a device to update it's multi-room master based on fleet activity.	Boolean. true / false	false

Plugins

The following variables control various aspects of each plugin behavior:

Variable	Description	Options	Defaults
SOUNDDISABLE< PLUGIN > where <PLUGIN> is the plugin name. See description.	Disable the selected plugin. Useful when you don't want to use a particular plugin. There is one variable per plugin: - SOUND_DISABLE_SPOTIFY - SOUND_DISABLE_AIRPLAY - SOUND_DISABLE_BLUETOOTH	Plugin will be disabled if the variable exists regardless of its value.	---
SOUND_ENABLE_SOUNDCARD_INPUT	If 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 its value.	---
SOUND_SPOTIFY_USERNAME	Your Spotify login username. Note: most Spotify clients on phones will authenticate via zeroconf so this is not usually required.	---	---
SOUND_SPOTIFY_PASSWORD	Your Spotify login password. Note: most Spotify clients on phones will authenticate via zeroconf so this is not usually required.	---	---
SOUND_SPOTIFY_DISABLE_NORMALISATION	Disable volume normalization in Spotify.	Disabled if the variable exists regardless of its value.	---
SOUND_SPOTIFY_ENABLE_CACHE	Enable the audio cache in Spotify. Note that over time the cache can take up large amounts of disk space.	Enabled if the variable exists regardless of its value.	---
SOUND_SPOTIFY_BITRATE	Spotify playback bitrate.	Bitrate in kbps: 96, 160 or 320	160