Spotifyd

spotifyd is a headless Spotify client that runs as a UNIX daemon and registers itself as a Spotify Connect device on your local network. It is built on top of librespot and is deliberately stripped down — there is no playback UI, no controls beyond what the Spotify app provides, and no overhead beyond what is needed to stream audio. Once running, any Spotify app on the same network can cast to it exactly as if it were an official Spotify speaker. Spotifyd is a popular choice for Raspberry Pi home audio setups and for headless servers where you want Spotify streaming without a desktop environment.

Note: Spotifyd requires a Spotify Premium account. Free accounts are not supported.

Features

• Spotify Connect receiver — appears as a castable device in the Spotify app on any platform; no pairing step required.
• UNIX daemon — designed to run under systemd or launchd, logging to the system journal rather than a terminal.
• Multiple audio backends — supports ALSA, PulseAudio, PipeWire (via PulseAudio compatibility), PortAudio, JACK, and Rodio, selectable at compile time.
• Credential caching — stores an authentication blob so the daemon can restart automatically without re-entering credentials.
• D-Bus MPRIS integration — exposes playback controls over the standard MPRIS2 D-Bus interface, enabling integration with desktop environments and tools like playerctl.
• Configurable bitrate — supports 96, 160, and 320 kbps streaming quality.
• Volume normalisation — built-in loudness normalisation keeps tracks at consistent levels.
• Shell hooks — run custom scripts on track change, device become active, and other events via the on_song_change_hook configuration option.

Installation

cargo install spotifyd

On Linux, ALSA development headers are required regardless of which audio backend you use:

# Debian / Ubuntu
apt install build-essential libasound2-dev libssl-dev pkg-config

# Fedora
dnf install alsa-lib-devel openssl-devel

Then install the binary:

cargo install spotifyd

# macOS
brew install spotifyd

# Arch Linux (AUR)
yay -S spotifyd

# Nix
nix-env -iA nixpkgs.spotifyd

Pre-built binaries for Linux (x86_64 and ARM) and macOS are available on the releases page. The ARM binaries are suitable for Raspberry Pi.

Configuration

Spotifyd reads its configuration from ~/.config/spotifyd/spotifyd.conf (or /etc/spotifyd.conf for system-wide installs). All options can also be passed as command-line flags.

[global]
username = "your_spotify_username"
password = "your_spotify_password"

# Or use a command to retrieve the password from a keychain/password manager
# password_cmd = "secret-tool lookup service spotify"

device_name = "Living Room"
bitrate = 320
device_type = "speaker"   # speaker, avr, computer, tv, stb, audiodongle
cache_path = "/home/user/.cache/spotifyd"
volume_normalisation = true
backend = "alsa"          # alsa, pulseaudio, portaudio, rodio

Avoid storing credentials in plaintext — use password_cmd to fetch them from a secrets manager:

[global]
username = "your_spotify_username"
password_cmd = "secret-tool lookup application spotifyd username your_spotify_username"

Running as a systemd service

User service (recommended)

# Copy the unit file from the repository, or create one manually
mkdir -p ~/.config/systemd/user/

cat > ~/.config/systemd/user/spotifyd.service << 'EOF'
[Unit]
Description=Spotifyd — Spotify daemon
After=network-online.target sound.target

[Service]
ExecStart=/home/%u/.cargo/bin/spotifyd --no-daemon
Restart=on-failure

[Install]
WantedBy=default.target
EOF

systemctl --user enable --now spotifyd

Checking status

systemctl --user status spotifyd
journalctl --user -u spotifyd -f

Usage

Running manually

# Start with defaults (reads ~/.config/spotifyd/spotifyd.conf)
spotifyd

# Run in the foreground (useful for debugging)
spotifyd --no-daemon

# Override the device name and bitrate at the command line
spotifyd --no-daemon --name "Kitchen" --bitrate 160

# Use a specific config file
spotifyd --config-path /etc/spotifyd.conf

Once running, open any Spotify client on the same network and the device appears in the Connect device picker.

Shell hooks

Run a script whenever the playing track changes:

[global]
on_song_change_hook = "/home/user/scripts/now-playing.sh"

The hook receives the track metadata as environment variables: TRACK_ID, TITLE, ARTIST, ALBUM, DURATION_MS, and PLAYER_EVENT.

Spotifyd vs librespot

Spotifyd is a thin daemon wrapper around the librespot library. The key differences from running librespot directly: