This is the documentation of spotifyd
An open source Spotify client running as a UNIX daemon.
These docs should be regarded as an extension of the README so please check there first before looking through the docs.
We provide pre-built binaries through GitHub Actions for the more popular platforms: Linux, macOS and ARMv7. You can find them here. For extra integrity, the file's SHA-512 gets calculated and uploaded as well.
The provided binaries come in two flavours,
full. Each are compiled with different features.
slim only contains the platform's most used audio backend,
full has also all optional features enabled (see Feature Flags).
There are packages for the following systems:
It is also available as a snap package.
You can also compile
Spotifyd yourself, allowing you to make use of feature flags.
Spotifyd is written in Rust. You can download the toolchain (compiler and package manager) over at rustup.rs. Follow their instructions to get started.
Note: Please make sure that you compile the package using the most recent
stableverison of Rust available throug
rustup. Some distro versions are quite outdated and might result in compilation errors.
Spotifyd might require additional libraries during build and runtime, depending on your platform and the way to compile it (static or dynamic). The following table shows the libraries needed for each OS respectively.
|Fedora||alsa-lib-devel make gcc|
|openSUSE||alsa-devel make gcc|
|Debian||libasound2-dev libssl-dev libpulse-dev libdbus-1-dev|
|Arch||base-devel alsa-lib libogg libpulse dbus|
|macOS||dbus pkg-config portaudio|
Note: The package names for Linux are the ones used on Debian based distributions (like Ubuntu). You will need to adapt the packages for your distribution respectively.
To compile the binary, run
cargo build --release
To install the resulting binary, run
cargo install --path . --locked
If you have
cargo installed, you can directly install
spotifyd by running:
cargo install spotifyd --locked
That will compile and install
spotifyd's latest version under
$HOME/.cargo/bin for you.
You can use the
cargo-deb create in order to build a Debian package from source.
Install it by:
cargo install cargo-deb
Then you can build and install the Debian package with:
cargo deb --install
Note, that when building a Debian package, the
--release is passed to the
build command already and you do not need to specify it yourself. See for the
flags that are set by default in
Spotifyd is split into a base package plus additional features that can be toggled on or off during compilation. Those can be split into two groups: The audio backend features that are responsible for playing back the music and additional functionality features, which enhance your experience using
To enable an additional audio backend, pass
<audio_backend_name>_backend as a feature flag. We currently support
Spotifyd provides the following additional functionality:
|dbus_keyring||Provides password authentication over the system's keyring (supports all platforms)|
|dbus_mpris||Provides multimedia key support (Linux only)|
Note: Compiling Spotifyd with all features and the pulseaudio backend on Ubuntu would result in the following command:
cargo build --release --no-default-features --features pulseaudio_backend,dbus_keyring,dbus_mpris
This guide will help you to install
spotifyd on a Raspberry Pi and have it always running.
- Download the latest ARMv6 from https://github.com/Spotifyd/spotifyd/releases (use
- Unzip the file:
unzip spotifyd-*.zipYou will now see a file called
spotifyd. You can run it with
Create a systemd service file and copy the config from https://github.com/Spotifyd/spotifyd/blob/master/contrib/spotifyd.service into it. Change ExecStart to where you unzipped the
sudo nano /etc/systemd/user/spotifyd.service
if you want to run as user instead of root or have some
Failed to get D-Bus connection: Connection refused, you define
spotifyd.service in your home directory:
mkdir -p ~/.config/systemd/user/ nano ~/.config/systemd/user/spotifyd.service systemctl --user daemon-reload
Create your config:
mkdir ~/.config/spotifyd/ nano ~/.config/spotifyd/spotifyd.conf
Input the following data. Change the username, password, device_name, and the bitrate.
[global] username = "USER" password = "PASS" backend = "alsa" device = alsa_audio_device # Given by `aplay -L` mixer = "PCM" volume-controller = "alsa" # or alsa_linear, or softvol #onevent = command_run_on_playback_event device_name = "name_in_spotify_connect" bitrate = 96|160|320 cache_path = "cache_directory" volume-normalisation = true normalisation-pregain = -10
systemctl --user start spotifyd.service
Now see if you can find it in the normal Spotify client (Devices in right bottom corner). Retry the above steps if you can't find it.
sudo loginctl enable-linger <username> systemctl --user enable spotifyd.service
The first command is required to enable your user to run long-running services. Without it
systemd would kill the
spotifyd process as soon as you log out, and only run it when you log in.
spotifyd is always running on the Pi, so you can use it as a listening device remotely!
sudo apt install rustc cargo libasound2-dev libssl-dev pkg-config
git clone https://github.com/Spotifyd/spotifyd.git
This takes a while...
cd spotifyd cargo build --release
The resulting binary will be placed in
You can run it using
These are some notes on cross-compiling, that worked on WSL xenial Ubuntu.
dpkg --add-architecture armhf sed 's/deb http/deb \[arch=amd64,i386\] http/' -i /etc/apt/sources.list echo >/etc/apt/sources.list <<EOF deb [arch=armhf] http://ports.ubuntu.com/ $(lsb_release -cs) main universe restricted multiverse deb [arch=armhf] http://ports.ubuntu.com/ $(lsb_release -cs)-updates main universe restricted multiverse deb [arch=armhf] http://ports.ubuntu.com/ $(lsb_release -cs)-security main universe restricted multiverse EOF apt update
apt install libssl-dev:armhf libasound2-dev:armhf
apt remove rustc curl https://sh.rustup.rs -sSf | sh rustup target add arm-unknown-linux-gnueabihf
PKG_CONFIG_PATH=/usr/lib/arm-linux-gnueabihf/pkgconfig PKG_CONFIG_ALLOW_CROSS=1 cargo build --target=arm-unknown-linux-gnueabihf --release
spotifyd is available via Homebrew and can be installed as follows:
brew install spotifyd
One can then enable it as a service at startup:
brew services start spotifyd
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
Spotifyd can be configured using CLI arguments. For a detailed description as well as possible values for each flag, run
Spotifyd is able to load configuration values from a TOML file too. The file has to be named
spotifyd.conf and reside in the user's configuration directory (
~/.config/spotifyd) or the system configuration directory (
/etc/xdg/spotifyd). This also applies to macOS!
The configuration file consists of two sections,
spotifyd takes priority over
The configuration file has the following format:
[global] # Your Spotify account name. username = "username" # Your Spotify account password. password = "password" # A command that gets executed and can be used to # retrieve your password. # The command should return the password on stdout. # # This is an alternative to the `password` field. Both # can't be used simultaneously. password_cmd = "command_that_writes_password_to_stdout" # If set to true, `spotifyd` tries to look up your # password in the system's password storage. # # This is an alternative to the `password` field. Both # can't be used simultaneously. use_keyring = true # If set to true, `spotifyd` tries to bind to the session dbus # and expose MPRIS controls. When running headless, without a dbus session, # then set this to false to avoid binding errors use_mpris = true # 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 = "alsa_audio_device" # omit for macOS # The alsa control device. By default this is the same # name as the `device` field. control = "alsa_audio_device" # omit for macOS # The alsa mixer used by `spotifyd`. mixer = "PCM" # omit for macOS # The volume controller. Each one behaves different to # volume increases. For possible values, run # `spotifyd --help`. volume_controller = "alsa" # use softvol for macOS # A command that gets executed in your shell after each song changes. on_song_change_hook = "command_to_run_on_playback_events" # The name that gets displayed under the connect tab on # official clients. Spaces are not allowed! device_name = "device_name_in_spotify_connect" # The audio bitrate. 96, 160 or 320 kbit/s bitrate = 160 # The directory used to cache audio data. This setting can save # a lot of bandwidth when activated, as it will avoid re-downloading # audio files when replaying them. # # Note: The file path does not get expanded. Environment variables and # shell placeholders like $HOME or ~ don't work! cache_path = "cache_directory" # If set to true, audio data does NOT get cached. no_audio_cache = true # Volume on startup between 0 and 100 # NOTE: This variable's type will change in v0.4, to a number (instead of string) 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 # After the music playback has ended, start playing similar songs based on the previous tracks. autoplay = true # The port `spotifyd` uses to announce its service over the network. zeroconf_port = 1234 # The proxy `spotifyd` will use to connect to spotify. proxy = "http://proxy.example.org:8080" # 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"
This feature allows you to provide a command that prints your password to
stdout, which saves you from having to store your password in the config file directly. To use it, set the
password_cmdconfig entry to the command you would like to use and remove the
For example (using the password-management utility pass).
# ~/.config/spotifyd/spotifyd.conf password_cmd = "pass spotify"
use_keyringconfig entry /
This features leverages Linux's DBus Secret Service API or native macOS keychain in order to forgo the need to store your password directly in the config file. To use it, compile with the
dbus_keyringfeature and set the
use-keyringconfig entry to
trueor pass the
--use-keyringCLI flag during start to the daemon. Remove the
Your keyring entry needs to have the following attributes set:
application: rust-keyring service: spotifyd username: <your-spotify-username>
To add such an entry into your keyring, you can use
secret-tool, a CLI used to communicate with agents that support the Secret Service API:
secret-tool store --label='name you choose' application rust-keyring service spotifyd username <your-username>
You can use the keychain GUI on macOS to add an item respectively, or with the built-in
security add-generic-password -s spotifyd -D rust-keyring -a <your username> -w
If either of these options is given, the shell
spotifyd will use to run its commands is the shell indicated by the
SHELL environment variable, if set. If the
SHELL environment variable is not set,
spotifyd will use the user's default shell, which, on Linux and BSD, is the shell listed in
/etc/passwd. On macOS it is the shell listed in the output of
dscl . -read /Users/<username> UserShell.
systemd.service unit file is provided to help run spotifyd as a service on systemd-based systems. The file
contrib/spotifyd.service should be copied to either:
Packagers of systemd-based distributions are encouraged to include the file in the former location. End-user should prefer the latter. It should be noted that some targets are not available when running under the user directory, such as
Control of the daemon is handed over to systemd. The following example commands will run the service once and enable the service to always run on login in the future respectively:
systemctl --user start spotifyd.service systemctl --user enable spotifyd.service
On macOS the system wide and per-user daemon/agent manager is known as
launchd. Interfacing with
launchd is performed through
In order to use
spotifyd as a service on macOS one must specify a
.plist that represents the service, and place it in
Here is a .plist which works with macOS Catalina 10.15.3:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>Label</key> <string>rustlang.spotifyd</string> <key>ProgramArguments</key> <array> <string>/usr/local/bin/spotifyd</string> <string>--config-path=/users/YourUserName/.config/spotifyd/spotifyd.conf</string> <string>--no-daemon</string> </array> <key>UserName</key> <string>YourUserName</string> <key>KeepAlive</key> <true/> <key>ThrottleInterval</key> <integer>30</integer> </dict> </plist>
Once present in the
/Library/LaunchDaemons directory, the .plist must be loaded and started with the following commands.
sudo launchctl load -w /Library/LaunchDaemons/rustlang.spotifyd.plist
sudo launchctl start /Library/LaunchDaemons/rustlang.spotifyd.plist
One may also unload/stop the service in a similar fashion replacing load/start with unload/stop.
You should update "YourUserName" with your actual username for macOS (or remove "UserName" to run as root.
<string>--no-daemon</string>is needed as launchd won't receive a PID for the process and will lose its remit over spotifyd. So it's best to include it, there will be no difference in use, nor will you see any log output.
macOS tries to start the daemon immediately on boot, and spotifyd fails if Wifi isn't connected. So one must have a keep alive (which retries if it fails to launch on boot), that retries after 30 seconds, which is enough for wifi etc to come up.