Compiling

General instructions

The following is additional to COMPILING.md, which you should read first.

macOS

If you are building librespot on macOS, the Homebrew-provided Rust may fail due to the way in which Homebrew installs it. In this case, uninstall the Homebrew version of Rust and use rustup.

Linux

On Linux, a kernel version of 3.9 or higher is required. For info on compiling for older kernels see: Compile-librespot-for-kernel-prior-3.9

Features

The default for librespot is to build with native-tls (system TLS), Rodio for audio playback, and libmdns for discovery.

You can use cargo's feature flags to change these defaults like:

cargo build --release --no-default-features --features "rustls-tls alsa-backend with-libmdns"

Important: librespot requires at least one TLS backend to function. Building with --no-default-features alone will fail compilation. You must specify at least one TLS backend along with your desired audio and discovery backends.

Here is a full list of available "features" and a short description.

TLS Backends (mutually exclusive)

Flag	Feature
native-tls	Uses the system's native TLS stack (OpenSSL on Linux, Secure Transport on macOS, SChannel on Windows). Default TLS backend for maximum compatibility and system certificate store integration.
rustls-tls	Uses Rust-based rustls TLS implementation with platform certificate verification. Avoids external OpenSSL dependencies, good for reproducible builds and static linking.

Audio Backends

Flag	Feature
rodio-backend	Cross-platform audio backend using Rodio (default). Uses ALSA on Linux, WASAPI on Windows, CoreAudio on macOS.
alsa-backend	Advanced Linux Sound Architecture backend (Linux only). Low-latency audio output.
portaudio-backend	Cross-platform audio I/O library backend.
pulseaudio-backend	PulseAudio backend (Linux only). Integrates with PulseAudio sound server.
jackaudio-backend	JACK Audio Connection Kit backend. Professional audio backend for low-latency, high-quality audio routing.
rodiojack-backend	Rodio backend with JACK support for professional audio setups (Linux only).
sdl-backend	Simple DirectMedia Layer audio backend.
gstreamer-backend	GStreamer multimedia framework backend with extensive audio processing capabilities.

Network Discovery Backends

Flag	Feature
with-libmdns	Pure-Rust mDNS implementation (default). No external dependencies, works on all platforms.
with-dns-sd	DNS Service Discovery (cross-platform). Uses Bonjour on macOS, Avahi compatibility layer on Linux. Does not work on Windows.
with-avahi	Uses Avahi daemon for mDNS (Linux only). Integrates with system's Avahi service.

Audio Processing Features

Flag	Feature
passthrough-decoder	Enables direct passthrough of Ogg Vorbis streams without decoding. Useful for custom audio processing pipelines.

Dependencies

Rodio is the default cross-platform audio backend built on top of CPAL. It does not require any non-Rust dependencies on Windows or macOS, and uses native audio engines. On Linux the dependencies are the same as for the ALSA backend.

For other backends, please read COMPILING.md for their dependencies and how to install them.

TLS Backends

librespot supports two TLS backends that are mutually exclusive:

• native-tls (default): Uses the system's native TLS stack. Provides maximum compatibility and integrates with system certificate stores. On Linux uses OpenSSL, on macOS uses Secure Transport, on Windows uses SChannel.
• rustls-tls: Uses Rust-based rustls TLS implementation. Avoids external OpenSSL dependencies and provides reproducible builds. Uses rustls-platform-verifier to automatically integrate with your system's certificate trust store. Choose rustls-tls when you need to avoid system TLS dependencies, want static linking, or are targeting platforms where native TLS is problematic (musl, embedded systems). Important: Attempting to enable both TLS backends will result in a compile-time error.

GStreamer on Windows

On Windows, you can configure your build toolchain using one of two approaches: the Visual C++ toolchain or the MinGW64 toolchain. This Wiki does not currently document how to use the Visual C++ toolchain. The MinGW64 toolchain is quite straightforward.

For MinGW64, you should do the following things:

• Install MSYS2 from here.
• Install Rust within MSYS's environment (bash) using pacman -S mingw-w64-x86_64-rust.
• Install GStreamer and dependencies within MSYS using pacman -S mingw-w64-x86_64-gst-plugins-base mingw-w64-x86_64-gst-plugins-good mingw-w64-x86_64-gst-plugins-bad mingw-w64-x86_64-gst-plugins-ugly mingw-w64-x86_64-gstreamer mingw-w64-x86_64-gcc
• Build librespot normally using cargo.
• Copy the librespot.exe binary into the bin directory where all your MinGW DLLs are. You may have to copy some DLLs as well.
• If librespot.exe crashes or fails to launch due to missing DLLs, you can always copy them from wherever they are in the MinGW/MSYS folder structure into the same directory as librespot.

It is also possible to use third-party GStreamer builds in many cases, because Windows doesn't care whether compiled .DLL files were built with MinGW or Visual C++. There are official GStreamer binaries for Windows available here and you can drop the DLLs into the same directory as your librespot.exe to have it pick them up.

As a final option, in case commonly available builds don't have the plugins you're looking for, you can build GStreamer from source. By far, the easiest way to build GStreamer from source on Windows is using MSYS2.

With DNS-SD

This feature is currently not available for Windows, but we're working on better solutions.

On Debian / Ubuntu, the following command will install the build dependencies:

apt install libavahi-compat-libdnssd-dev pkg-config

On the target system, install the runtime dependency:

apt install libavahi-compat-libdnssd1

If with-dns-sd is enabled, librespot will crash if Avahi or Bonjour is not running. On the other hand, if with-dns-sd was not enabled, librespot might interfere with Avahi, Bonjour or other librespot instances if running, or even crash on some OSs. A typical symptom is that Avahi detects a host name conflict, and then retries with -2 appended to the host name, leading to hostname.local not being resolved any longer.