A Docker image for librespot

First and foremost, the reference to the awesome project:

Librespot

I am also currently relying on Raspotify because building images from crates.io fails for armhf platfrom. So here is the reference to this other excellent project:

Raspotify

The latest image is published daily, so it will include the same version of Librespot included in the current release of Raspotify.

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.

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 (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

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

Here is the repository on DockerHub.

Getting the image from DockerHub is as simple as typing:

docker pull giof71/librespot:latest

Mr. John Darko would be proud.

The following tables reports all the currently supported environment variables.

Please not 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.

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

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

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

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

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 here for a sample configuration using a specified user (uid) in a docker-compose file.

Please 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).

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

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.

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 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.

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.
Please note that even when using the "discovery" mode, the premium account is always required for playback.

I am currently relying, as mentioned before, to the Raspotify project to build this image. Of what Raspotify provides, this container only uses librespot.
I have a branch dedicated to this issue: the problem is with the build on GitHub via QEMU, which fails for the armhf architecture.
Any help in resolving this issue is welcome.

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

It will take very little time even on a Raspberry Pi. When it's finished, you can run the container following the previous instructions.
Just be careful to use the tag you have built.