Getting Started with Spotify Soloist

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

Prerequisites

A Spotify account with Premium to create the Spotify Soloist API key.
A supported device on the same local network as the Spotify app you will use for setup.
On Apple Silicon Mac, macOS 13 or newer.
Working audio output. On Linux, use PipeWire or PulseAudio.
Terminal access to the device. On Windows, the examples use PowerShell.

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. Do not share it with other users. It is for the account that generated it. 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. Load the key from a private local environment file or secret manager. The startup examples show the command for each platform.

Download Spotify Soloist

Choose the build for your operating system and architecture:

Operating system	Architecture	Download
Linux	ARMv8/AArch64, ARMv7/ARM32, or x86_64	See the Linux archives below.
macOS on Apple Silicon	`arm64`	`soloist_release_osx_arm64.tar.gz`
Windows	`x86_64`	`soloist_release_windows_x86_64.zip`

Linux

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

Apple Silicon Mac

Download soloist_release_osx_arm64.tar.gz for macOS 13 or newer. Open Terminal in the download directory and extract the archive:


_10tar -xzf soloist_release_osx_arm64.tar.gz

In the same Terminal window, run:


_10./soloist --version
_10./soloist --help

x86_64 Windows

Download soloist_release_windows_x86_64.zip. Extract the ZIP archive before you run the executable. Open PowerShell in the directory that contains soloist.exe. Run these commands:


_10.\soloist.exe --version
_10.\soloist.exe --help

Build lifetime

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. Set SOLOIST_API_KEY in your shell environment before you run these commands.

Command examples on each platform

The examples below run from the directory that contains the extracted executable. Other guides use soloist for an executable on your PATH, the list of directories that your shell searches for commands. From the extracted directory, use ./soloist on Linux and macOS or .\soloist.exe in Windows PowerShell. If Soloist is on your PATH, use soloist instead.

For example, use ./soloist ctl status on Linux and macOS or .\soloist.exe ctl status in Windows PowerShell. In PowerShell, use $env:SOLOIST_API_KEY for the API key and put commands on one line instead of using Bash line continuations.

Linux and macOS


_10./soloist --device-name "Kitchen speaker" --api-key "$SOLOIST_API_KEY"

Windows PowerShell


_10.\soloist.exe --device-name "Kitchen speaker" --api-key "$env:SOLOIST_API_KEY"

Data and cache directories

Spotify Soloist creates data and cache directories automatically. See storage options for the default paths on each operating system and environment overrides.

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 that your device has a working default audio output.
On Linux, make sure that PipeWire or PulseAudio is running.
On Linux, use --pipewire-device DEVICE if you need to route audio to a specific PipeWire node name or ID.