Getting Started with Spotify Soloist

This tutorial gets Spotify Soloist running as a Spotify Connect device on Linux.

Prerequisites

A Spotify account with Premium to create the Spotify Soloist API key.
A Linux device on the same local network as the Spotify app you will use for setup.
Working PipeWire or PulseAudio output on the Linux device.
Shell access to the Linux device.

Generate an API key

Log in to the Spotify for Developers dashboard.
Open Spotify Soloist API Key.
Review the Spotify Terms and Conditions of Use and accept them if prompted.
Generate an API key.

Keep the API key private. It is for the account that generated it and should not be shared with other users. Spotify Soloist sends it during Spotify Connect login to prove that the device is allowed to use Spotify Soloist.

The examples below pass the key to Spotify Soloist at startup, so treat shell history, process-manager configuration, screenshots, and logs containing the command as sensitive. Prefer loading the key from a private local environment file or secret manager:


_10soloist \
_10  --device-name "Kitchen speaker" \
_10  --api-key "$SOLOIST_API_KEY"

Download Spotify Soloist

We provide Spotify Soloist Linux builds for ARMv8/AArch64, ARMv7/ARM32, and x86_64 devices. The ARMv8/AArch64 build is primarily tested on Raspberry Pi 3 Model A+ running the Debian Trixie-based Raspberry Pi OS (glibc 2.41). The ARMv7/ARM32 build targets 32-bit ARM Linux devices.

Choose the archive for your device architecture. To check your architecture, run:


_10uname -m

`uname -m` output	Architecture	Archive
`aarch64`	ARMv8/AArch64 Linux	`soloist_release_arm64.tar.gz`
`armv7l`	ARMv7/ARM32 Linux	`soloist_release_arm32.tar.gz`
`x86_64`	x86_64 Linux	`soloist_release_x86_64.tar.gz`

See the Soloist Third-Party Licenses for applicable notices and license terms.

Do not redistribute Spotify Soloist archives or binaries directly. Link other users to Downloads and updates instead.

Download the archive, replacing <arch> with arm64, arm32, or x86_64:


_10curl --fail --location -o soloist.tar.gz https://soloist-builds.spotifycdn.com/soloist_release_<arch>.tar.gz

Install it:


_10tar -xzf soloist.tar.gz
_10test -x soloist
_10sudo install -m 755 soloist /usr/local/bin/soloist

Check that the executable works:


_10soloist --version
_10soloist --help

Spotify Soloist builds expire 90 days after their build date. Install a newer build before the current one expires. Expired builds exit with code 10.

Start Spotify Soloist

Run Spotify Soloist with a Spotify Connect device name and your API key:


_10soloist \
_10  --device-name "Kitchen speaker" \
_10  --api-key "$SOLOIST_API_KEY"

Spotify Soloist creates default data and cache directories on Linux:

Directory	Default
Data	`~/.local/share/soloist`
Cache	`~/.cache/soloist`

Use --data-dir if you want a different persistent location, and --cache-dir if you want a different cache location. Use the same data directory across restarts to keep the same device identity and stored Spotify Connect session.

Pair from the Spotify app

Keep Spotify Soloist running.
Open the Spotify app on a phone, tablet, or desktop on the same local network.
Open the device picker.
Select the Spotify Soloist device name you passed with --device-name.
Start playback.

Next steps

After Spotify Soloist is paired, you can use more local control surfaces:

Use soloist ctl for local shell control.
Use the WebSocket API to observe playback and send commands from another local process.
Use single-track mode for scripts that play one Spotify URI and then exit.

For all daemon options, see the command-line reference.

Troubleshooting

If the device does not appear in Spotify:

Make sure Spotify Soloist and the Spotify app are on the same local network.
Make sure your router, VPN, and firewall allow local device discovery and do not isolate wireless clients from each other.
Check that the API key was copied correctly.
Restart Spotify Soloist and look for login or startup warnings in the terminal.
If Spotify Soloist exits with code 10, download and install a newer build.

If playback starts but you do not hear audio:

Make sure PipeWire or PulseAudio is running and has a working default output.
Use --pipewire-device DEVICE if you need to route audio to a specific PipeWire node name or ID.