giof71/librespot repository overview

⁠librespot-docker

A Docker image for librespot⁠

⁠News

The newest latest image is based on the current v0.8.0 version of librespot⁠ at this commit⁠, is built using my fork of librespot⁠.
The purpose of that fork is just to set a version for this repository.

⁠Reference

First and foremost, the reference to the awesome project:

Librespot⁠

For a long time, I have also been relying on Raspotify because I could not build images using cargo build for the armhf platfrom. So here is the reference to this other excellent project:

Raspotify⁠

Since the first days of 2025, we are successfully building the images directly from source code.

⁠Support

Please see the Goal⁠.
Please note that support goal is limited to cover running costs for subscriptions to music services.

⁠Links

⁠Why

I prepared this Dockerfile Because I wanted to be able to install librespot easily on any machine (provided the architecture is amd64, armhf or arm64). Also I wanted to be able to configure and govern the parameter easily, maybe through a webapp like Portainer.

⁠Prerequisites

First, you need a Spotify⁠ premium account in order to be able to use any version of Librespot.
You need to have Docker up and running on a Linux machine, and the current user must be allowed to run containers (this usually means that the current user belongs to the "docker" group).

You can verify whether your user belongs to the "docker" group with the following command:

getent group | grep docker

This command will output one line if the current user does belong to the "docker" group, otherwise there will be no output.

The Dockerfile and the included scripts have been tested on the following distros:

• Manjaro Linux with Gnome/KDE (amd64)
• Raspberry Pi 3/4 (32 and 64 bit)
• Asus Tinkerboard with DietPi (don't let that board run at a very low minimum frequency⁠)
• OSMC on Raspberry Pi 4
• Moode Audio on Raspberry Pi 3/4

As I test the Dockerfile on more platforms, I will update this list.

⁠Get the image

Here is the repository⁠ on DockerHub.

Getting the image from DockerHub is as simple as typing:

docker pull giof71/librespot:latest

⁠Librespot is gapless

Mr. John Darko⁠ would be proud.

⁠Configuration

⁠Environment variables

The following tables reports all the currently supported environment variables.

⁠Pipe Mode

When using BACKEND=pipe, specify a device (using variable DEVICE) that is mounted to a fifo file. Example:

services:
  librespot:
    image: giof71/librespot:latest
    network_mode: host
    environment:
      - BACKEND=pipe
      - DEVICE=/mnt/pipe/spotipipe
      - BITRATE=320
      - INITIAL_VOLUME=100
      - DEVICE_NAME=SpotiPi
    volumes:
      - /path/to/folder/for/fifo-file:/mnt/pipe

Thank you @marco79cgn for your contributions on issue #111⁠.

⁠Volumes

Note that the volume /data/system-cache will contain the encrypted credentials. Enabling the system cache and using a dedicated volume will help keeping players discoverable by the Spotify web app when you don't provide credentials to LibreSpot.

⁠Examples

⁠Docker-compose

Using docker-compose is preferable for multiple reason, a notable one is the fact that it avoids a few headaches with password escaping, in case of special characters.

Among the docker-compose.yaml files hereby presented, those which use credentials require a .env file at the same level of the docker-compose.yaml file itself. The .env file should have the following format:

SPOTIFY_USERNAME=myusername
SPOTIFY_PASSWORD=mypassword

Note that username and password is deprecated as an authentication method in librespot.

⁠Docker-compose in Alsa mode

Discovery mode:

---
version: "3"

services:
  librespot:
    image: giof71/librespot:latest
    network_mode: host
    devices:
      - /dev/snd:/dev/snd
    environment:
      - DEVICE=hw:x20,0
      - BACKEND=alsa
      - BITRATE=320
      - INITIAL_VOLUME=100
      - DEVICE_NAME=gustard-u12

⁠Docker-compose in PulseAudio mode

Discovery mode:

---
version: "3"

services:
  librespot:
    image: giof71/librespot:latest
    network_mode: host
    environment:
      - BACKEND=pulseaudio
      - BITRATE=320
      - INITIAL_VOLUME=100
      - DEVICE_NAME=manjaro-xeon10-pulse
    volumes:
      - /run/user/1000/pulse:/run/user/1000/pulse

⁠Docker run

⁠Docker run in Alsa mode

Discovery mode:

docker run -d --name librespot \
    --device /dev/snd \
    --network host \
    -e DEVICE_NAME=kodi-living-pi4-tuner \
    -e INITIAL_VOLUME=100 \
    -e BACKEND=alsa \
    -e DEVICE=hw:D10,0 \
    -e FORMAT=S32 \
    -e BITRATE=320 \
    -e INITIAL_VOLUME=100 \
    --restart unless-stopped \
    giof71/librespot:latest

Discovery mode, using docker --user:

See this page⁠ for a sample configuration using a specified user (uid) in a docker-compose file.

Note that with this DAC I had to specify S32 as the format. It would not work with the default (which is S32 for librespot).

⁠Docker run in PulseAudio mode

Discovery mode:

docker run -d
    -e PUID=1000 \
    -e PGID=1000 \
    --network host \
    -e BACKEND=pulseaudio \
    -e BITRATE=320 \
    -e DEVICE_NAME=librespot-pulse \
    -v /run/user/1000/pulse:/run/user/1000/pulse \
    --name librespot-pulse \
    giof71/librespot:latest

⁠Run as a user-level systemd

When using a desktop system with PulseAudio, running a docker-compose with a restart=unless-stopped is likely to cause issues to the entire PulseAudio. At least that is what is systematically happening to me on my desktop systems.
You might want to create a user-level systemd unit. In order to do that, move to the pulse directory of this repo, create a valid envfile.txt with your credentials using envfile-sample.txt as a template, then run the following to install the service:

./install.sh

After that, the service can be controlled using ./start.sh, ./stop.sh, ./restart.sh.
You can completely uninstall the service by running:

./uninstall.sh`

Of course, you might simply want run the Spotify binary client or the web player instead of this service, but this alternative will allow you to control the player on your desktop system from e.g. a smartphone or any Spotify client. And it will consume significantly less resources.

⁠Running interactively

If you have set ENABLE_OAUTH to headless, you will need to run your docker-compose.yaml interactively the first time.
In order to do that, run your compose file using the following:

docker-compose run librespot

assuming that librespot is the name of the service. Tune the command if needed.
This command will let you see the container logs. You will have to open your browser at the displayed link, authenticated with Spotify and authorize the device, then paste the redirect URL to the terminal.
After the first start, you can start the container as usual using docker-compose up -d.

⁠Credentials file (DEPRECATED)

Credentials can be stored on a separate file and mounted as /user/config/credentials.txt. The format is the same as the standard .env file.
By defaults, SPOTIFY_USERNAME and SPOTIFY_PASSWORD entries found in this file have the priority against the correspondent environment variables, unless you set the variable PARAMETER_PRIORITY to env.

⁠Known issues

⁠Discovery

For discovery mode to work, you will need to specify network_mode=host on the compose file. Otherwise the player will not be discoverable.
In this mode, authentication is not required on the container itself, but OTOH any premium spotify user on your network will be able to use your Librespot Player.
Note that even when using the "discovery" mode, the premium account is always required for playback.

⁠Build

You can build (or rebuild) the image by opening a terminal from the root of the repository and issuing the following command:

docker build . -t giof71/librespot

Now that we are building from code, please note that the build will take quite a lot of time. When it's finished, you can run the container following the previous instructions.
Just be careful to use the tag you have built.

⁠Change History