Edit on GitHub

Customization

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.

General

The following environment variables apply to balenaSound in general, modifying its behavior 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 advertised 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.AUTO
SOUND_INPUT_LATENCYInput 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_LATENCYOutput loopback latency in milliseconds. Note that this is only a friendly request, the actual latency might be higher.1 - 2000.200
SOUND_SUPERVISOR_PORTWeb port that is used for serving API and UI by sound supervisor.Any valid port number80

Multi-room

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

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 formatted IP address. Example: 192.168.1.10---
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---
SOUND_MULTIROOM_POLL_INTERVALSet how often multi-room devices sync up across the fleet.Time in seconds. Example: 12060
SOUND_MULTIROOM_DISALLOW_UPDATESPrevent a device to update it's multi-room master based on fleet activity.Boolean. true / falsefalse

Plugins

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

Environment variableDescriptionOptionsDefaults
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_BLUETOOTHPlugin will be disabled if the variable exists regardless of its 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 its value.---
SOUND_SPOTIFY_USERNAMEYour Spotify login username. Note: most Spotify clients on phones will authenticate via zeroconf so this is not usually required.------
SOUND_SPOTIFY_PASSWORDYour Spotify login password. Note: most Spotify clients on phones will authenticate via zeroconf so this is not usually required.------
SOUND_SPOTIFY_DISABLE_NORMALISATIONDisable volume normalization in Spotify.Disabled if the variable exists regardless of its value.---
SOUND_SPOTIFY_ENABLE_CACHEEnable 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_BITRATESpotify playback bitrate.Bitrate in kbps: 96, 160 or 320160