Configuration

Spotifyd is able to run without configuration at all and will assume default values for most of the fields. However, running without configuration will only allow you to connect to it via Spotify Connect if you're on the same network as the daemon.

All configuration options can be specified directly as command line arguments or alternatively (in particular for permanent changes) be written into a configuration file. Throughout this section, we will always give both possibilities, e.g. --cli-arg for the cli variant / config_value for the config file variable.

Config File

spotifyd will look for its configuration at /etc/spotifyd.conf, $XDG_CONFIG_PATH/spotifyd/spotifyd.conf or if that is not set ~/.config/spotifyd/spotifyd.conf. For other needs, you can point spotifyd to it's config file with the command line argument --config-path <path-to-your-config>.

You can start with the following documented config as an example and read through the subpages of this section:

[global]

#---------#
# GENERAL #
#---------#

# The name that gets displayed under the connect tab on
# official clients.
#device_name = "device_name_in_spotify_connect"

# The displayed device type in Spotify clients.
# Can be unknown, computer, tablet, smartphone, speaker, t_v,
# a_v_r (Audio/Video Receiver), s_t_b (Set-Top Box), and audio_dongle.
#device_type = "speaker"

# The directory used to store credentials and audio cache.
# Default: infers a sensible cache directory (e.g. on Linux: $XDG_CACHE_HOME)
#
# Note: The file path does not get expanded. Environment variables and
# shell placeholders like $HOME or ~ don't work!
#cache_path = "/full/path/to/cache/directory"

# If set to true, audio data does NOT get cached.
# In this case, the cache is only used for credentials.
#no_audio_cache = true

# The maximal size of the cache directory in bytes
# The example value corresponds to ~ 1GB
#max_cache_size = 1000000000

# If set to true, `spotifyd` tries to bind to dbus (default is the session bus)
# and expose MPRIS controls. When running headless, without the session bus,
# you should set this to false, to avoid errors. If you still want to use MPRIS,
# have a look at the `dbus_type` option.
#use_mpris = true

# The bus to bind to with the MPRIS interface.
# Possible values: "session", "system"
# The system bus can be used if no graphical session is available
# (e.g. on headless systems) but you still want to be able to use MPRIS.
# NOTE: You might need to add appropriate policies to allow spotifyd to
# own the name.
#dbus_type = "session"

#-----------#
# DISCOVERY #
#-----------#

# If set to true, this disables zeroconf discovery.
# This can be useful, if one prefers to run a single-user instance.
#disable_discovery = false

# The port at which `spotifyd` is going to offer its service over the network (TCP).
# If not set, a random port > 1024 is used. For the service to be discoverable on the
# local network via mDNS, both the mDNS port (5353 UDP) and the random or fixed
# zeroconf port need to be allowed through any active firewall.
#zeroconf_port = 1234

#-------#
# AUDIO #
#-------#

# The audio backend used to play music. To get
# a list of possible backends, run `spotifyd --help`.
#backend = "alsa" # use portaudio for macOS [homebrew]

# The alsa audio device to stream audio. To get a
# list of valid devices, run `aplay -L`,
#device = "default"  # omit for macOS

# The PCM sample format to use. Possible values 
# are F32, S32, S24, S24_3, S16. 
# Change this value if you encounter errors like
# "Alsa error PCM open ALSA function 'snd_pcm_hw_params_set_format' failed with error 'EINVAL: Invalid argument'"
#audio_format = "S16"

# The volume controller. Each one behaves different to
# volume increases. For possible values, run
# `spotifyd --help`.
#volume_controller = "softvol"  # use softvol for macOS

# ! Only relevant for ALSA !
# The alsa control device. By default this is the same
# name as the `device` field.
#control = "default"

# ! Only relevant for ALSA !
# The alsa mixer used by `spotifyd`.
#mixer = "PCM"  # omit for macOS

# The audio bitrate. 96, 160 or 320 kbit/s
#bitrate = 160

# Volume on startup between 0 and 100
#initial_volume = 90

# If set to true, enables volume normalisation between songs.
#volume_normalisation = true

# The normalisation pregain that is applied for each song.
#normalisation_pregain = -10

#-------ä
# OTHER #
#-------#

# After the music playback has ended, start playing similar songs based on the previous tracks.
# By default, `spotifyd` infers this setting from the user settings.
#autoplay = true

# A command that gets executed in your shell after each song changes.
#on_song_change_hook = "echo \"hook executed on $PLAYER_EVENT\""

# The proxy `spotifyd` will use to connect to spotify.
#proxy = "http://proxy.example.org:8080"