First and foremost, the reference to the awesome projects:
Music Player Daemon
MPDScribble
Please see the Goal.
Please note that support goal is limited to cover running costs for subscriptions to music services.
A docker image for mpd with support for both Alsa and PulseAudio.
The container image also includes mpdscribble. In alternative, you can use mpd-scrobbler-docker as the scrobbler for this image.
User mode is now possible when using alsa outputs, and of course it is mandatory (enforced) when using pulse outputs.
Upsampling (even in integer mode) is now available via a patched version of MPD (an unmodified version is available as well).
Also, thanks to a feature request by user XxAcielxX, who also contributed with the necessary documentation, we have a certain degree of support for equalization.
- linux/amd64
- linux/arm/v7
- linux/arm64/v8
- linux/arm/v5 (for debian-based builds)
Source: GitHub
Images: DockerHub
I prepared this Dockerfile because I wanted to be able to install mpd easily on any machine (provided the architecture is amd64 or arm). Also I wanted to be able to configure and govern the parameters easily, allowing multiple output, also of different types.
See this page.
Here is the repository on DockerHub.
Getting the image from DockerHub is as simple as typing:
docker pull giof71/mpd-alsa
Legacy support OUTPUT_MODE, is still available in the legacy branch, as well as on the images tagged with the legacy prefix.
You might want to use those releases as a stop-gap solution should you encounter issues migrating to the new configuration methods.
Keep in mind that the legacy branch will not be updated with new features. Only relevant bugfix changes will be ported there.
The source code for the patched MPD is in this GitHub repo.
The version-0.23.15 tag is in-line with the GitHub upstream repo at version 0.23.15.
The version-0.23.15-ups tag contains a patch which is used when INTEGER_UPSAMPLING is set to yes. Use at your own risk.
Two binaries are available in the container image:
- /app/bin/compiled/mpd (upstream version)
- /app/bin/compiled/mpd-ups (patched version)
The current mpd version is v0.23.15 when using giof71/mpd-compiler-docker as the base image (Docker Repo here). The repo binary is installed also in this case.
Vanilla versions only have the repo binary.
The mpdscribble version depends on the base image. See the following table:
| Base Image | Tags | Compiled MPD version | Repo MPD version | MPDScribble version |
|---|---|---|---|---|
| giof71/mpd-compiler:bookworm | latest, stable, bookworm | 0.23.15 | 0.23.12 | 0.24 |
| giof71/mpd-compiler:noble | noble, ubuntu-current | 0.23.15 | 0.23.14 | 0.25 |
| debian:bookworm-slim | vanilla-latest, vanilla-stable, vanilla, vanilla-bookworm | - | 0.23.12 | 0.24 |
| ubuntu:noble | vanilla-noble, vanilla-ubuntu-current | - | 0.23.14 | 0.25 |
Starting with release 2023-02-04, you will not be able to use the deprecated PULSE and ALSA as OUTPUT_MODE. Refer to the next chapter for more information about how to change the configuration. Please note that Alsa and PulseAudio are still supported: you just need to slightly modify your docker configurations.
In case of difficulties, you can fall back to the legacy image versions (e.g.: giof71/mpd-alsa:legacy-latest), as those will still work with these deprecated configurations.
If you have been using this container image for a while, you might have seen that the output might contain some warnings, telling you that you are using a deprecated configuration. The message usually tries to suggest how to switch to a recommended configuration.
This is happening because this whole project started with the idea of supporting ALSA only (hence the name mpd-alsa-docker). Down the road, I added PulseAudio support, and eventually HTTPD outputs, SHOUTCAST outputs, also in multiple instances.
So now a few variables have a misleading name: the most misleading being ALSA_DEVICE_NAME which, despite the name, refers to the output name, and not to the device name.
So currently, OUTPUT_MODE is not available anymore.
In any case, I suggest you change the configuration as suggested, and use the variables from the appropriate sections below for Alsa and PulseAudio, otherwise, in time, your configurations will not be functional anymore.
Please refer to the legacy branch for the old documentation.
Feel free to contact me with an issue if you need support. I cannot guarantee a timing, but I will try to help if I can.
See this page.
The following tables lists the volumes:
| VOLUME | DESCRIPTION |
|---|---|
| /db | Where the mpd database is saved |
| /music | Where the music is stored. You might consider to mount your directory in read-only mode (:ro) |
| /playlists | Where the playlists are stored |
| /log | Where all logs are written (e.g. mpd.log, scrobbler.log etc) |
| /user/config | Additional user-provided configuration files, see this paragraph for the details |
Several files can be located in the user configuration (/user/config) volume. Here is a table of those files.
| FILE | DESCRIPTION |
|---|---|
| lastfm.txt | LastFM Credentials |
| librefm.txt | LibreFM Credentials |
| jamendo.txt | Jamendo Credentials |
| additional-alsa-presets.conf | Additional alsa presets |
| additional-outputs.txt | Additional outputs, which will be added to the configuration file during the container startup phase |
| asoundrc.txt | Alsa configuration file: this will be copied to /home/mpd-user/.asoundrc or to /root/.asoundrc, depending on user mode to be enabled or not |
| override.mpd.conf | User provided mpd configuration file (see #356). Use at your own risk. If this file is available, it will be used in the final phase of the run script instead of the generated file. |
For a reference for the structure of the credentials file, see the corresponding example file in the doc folder of the repository.
The following tables lists all the currently supported environment variables:
| VARIABLE | DESCRIPTION |
|---|---|
| DATABASE_MODE | Can be simple (default), proxy or upnp (requires host networking) |
| DATABASE_PROXY_HOST | MPD server hostname, only used when DATABASE_MODE is set to proxy |
| DATABASE_PROXY_PORT | MPD server port, only used when DATABASE_MODE is set to proxy |
| DATABASE_PROXY_PASSWORD | The password used to log in to the master MPD instance, only used when DATABASE_MODE is set to proxy |
| DATABASE_PROXY_KEEPALIVE | Send TCP keepalive packets to the master MPD instance (yes or no), only used when DATABASE_MODE is set to proxy |
| MUSIC_DIRECTORY | Location of music files, defaults to /music |
| MPD_BIND_ADDRESS | The MPD listen address, more than one can be specified (just use MPD_BIND_ADDRESS_1, MPD_BIND_ADDRESS_2, etc), defaults to 0.0.0.0 |
| MPD_PORT | The MPD port, defaults to 6600 |
| USER_MODE | Set to y or yes for user mode. Case insensitive. See User mode. Required when using any PulseAudio outputs (so when PULSE_AUDIO_OUTPUT_CREATE is set to yes) |
| PUID | User id. Defaults to 1000. The user/group will be created when a PulseAudio output is created unless USER_MODE is set to no. |
| PGID | Group id. Defaults to 1000. The user/group will be created when a PulseAudio output is created unless USER_MODE is set to no. |
| AUDIO_GID | audio group id from the host machine. Mandatory for alsa output in user mode. See User mode. |
| INPUT_CACHE_SIZE | Sets the input cache size. Example value: 1 GB |
| SAMPLERATE_CONVERTER | Configure samplerate_converter. Example value: soxr very high. Note that this configuration cannot be used when SOXR_PLUGIN_ENABLE is set to enabled. There are some preset values for sox: very_high and very-high map to soxr very high, high maps to soxr high, medium maps to soxr medium, low maps to soxr low and quick maps to soxr quick. Refer to this page for details. |
| MPD_ENABLE_LOGGING | Defaults to yes, set to no to disable |
| MPD_LOG_LEVEL | Can be default or verbose |
| FFMPEG_ENABLED | Enable ffmpeg decoder, defaults to no. Plugin documentation here |
| CURL_ENABLED | Enable CURL input plugin, defaults to yes. This is required if you plan to use upmpdcli. Input plugin documentation here |
| CURL_PROXY | Parameter for CURL input plugin |
| CURL_PROXY_USER | Parameter for CURL input plugin |
| CURL_PROXY_PASSWORD | Parameter for CURL input plugin |
| CURL_VERIFY_PEER | Parameter for CURL input plugin |
| CURL_VERIFY_HOST | Parameter for CURL input plugin |
| CURL_CACERT | Parameter for CURL input plugin |
| ZEROCONF_ENABLED | Set to yes to enable, disabled by default. |
| ZEROCONF_NAME | Set zeroconf name, used only if ZEROCONF_ENABLED is set to yes |
| HYBRID_DSD_ENABLED | Hybrid dsd is enabled by default, set to no to disable. Disabled when at least one PulseAudio output is created. |
| AUDIO_BUFFER_SIZE | Adjust the size of the internal audio buffer. Default is 4 MB (4 MiB). |
| MAX_ADDITIONAL_OUTPUTS_BY_TYPE | The maximum number of outputs by type, defaults to 20 |
| RESTORE_PAUSED | If set to yes, then MPD is put into pause mode instead of starting playback after startup. Default is no. |
| STATE_FILE_INTERVAL | Auto-save the state file this number of seconds after each state change, defaults to 10 seconds |
| ENFORCE_PLAYER_STATE | If set to yes, it will remove player state information from the state file, so the player state will only depend on the environment variables. Defaults to yes |
| FORCE_REPO_BINARY | If set to yes, the binary from the distro repository will be used |
| DEFAULT_PERMISSIONS | Sets default_permissions, see here |
| LOCAL_PERMISSIONS | Sets local_permissions, see here |
| HOST_PERMISSIONS | Adds a host_permissions, you can add multiple (up to MAX_PERMISSIONS), append _1, _2, etc to the variable name for additional entries, see here |
| PASSWORD | Adds a password, you can add multiple (up to MAX_PERMISSIONS), append _1, _2, etc to the variable name for additional entries, see here |
| MAX_PERMISSIONS | Specify the maximum number of host_permissions and passwords, defaults to 10 |
| STDERR_ENABLED | Print messages to the standard error, enabled by default. Set to no to disable |
| CONNECTION_TIMEOUT | If a client does not send any new data in this time period (seconds), the connection is closed. Clients waiting in “idle” mode are excluded from this. Default is 60 |
| MAX_CONNECTIONS | This specifies the maximum number of clients that can be connected to MPD at the same time, default is 100 |
| MAX_PLAYLIST_LENGTH | The maximum number of songs that can be in the playlist, default is 16384 |
| MAX_COMMAND_LIST_SIZE | The maximum size a command list in KBYTES, default is 2048 (2 MiB) |
| MAX_OUTPUT_BUFFER_SIZE | The maximum size of the output buffer to a client (maximum response size), in KBYTES, default is 8192 (8 MiB) |
| AUTO_UPDATE | Set to yes to enable autoupdate of database |
| AUTO_UPDATE_DEPTH | Limit the depth of the directories being watched, 0 means only watch the music directory itself. There is no limit by default. |
| STARTUP_DELAY_SEC | Delay before starting the application in seconds, defaults to 0 |
Please find here the variables used to configure the SOXR plugin.
| VARIABLE | DESCRIPTION |
|---|---|
| SOXR_PLUGIN_ENABLE | Enable the soxr plugin. Do not use in conjunction with variable SAMPLERATE_CONVERTER |
| SOXR_PLUGIN_PRESET | Presets for SOXR_PLUGIN configuration. Available presets: goldilocks and extremus |
| SOXR_PLUGIN_THREADS | The number of libsoxr threads. 0 means automatic. The default is 1 which disables multi-threading. |
| SOXR_PLUGIN_QUALITY | The quality of soxr resampler. Possible values: very high, high (the default), medium, low, quick, custom. When set to custom, the additional soxr parameters can be set. |
| SOXR_PLUGIN_PRECISION | The precision in bits. Valid values 16,20,24,28 and 32 bits. |
| SOXR_PLUGIN_PHASE_RESPONSE | Between the 0-100, where 0 is MINIMUM_PHASE and 50 is LINEAR_PHASE |
| SOXR_PLUGIN_PASSBAND_END | The % of source bandwidth where to start filtering. Typical between the 90-99.7. |
| SOXR_PLUGIN_STOPBAND_BEGIN | The % of the source bandwidth Where the anti aliasing filter start. Value 100+. |
| SOXR_PLUGIN_ATTENUATION | Reduction in dB’s to prevent clipping from the resampling process |
| SOXR_PLUGIN_FLAGS | Bitmask with additional options, see soxr documentation for specific flags |
Please find here the variables used to configure ReplayGain.
| VARIABLE | DESCRIPTION |
|---|---|
| REPLAYGAIN_MODE | ReplayGain Mode, defaults to off |
| REPLAYGAIN_PREAMP | ReplayGain Preamp, defaults to 0 |
| REPLAYGAIN_MISSING_PREAMP | ReplayGain missing preamp, defaults to 0 |
| REPLAYGAIN_LIMIT | ReplayGain Limit, defaults to yes |
| VOLUME_NORMALIZATION | Volume normalization, defaults to no |
Please find here the variables used to configure the Qobuz plugin.
| VARIABLE | DESCRIPTION |
|---|---|
| QOBUZ_PLUGIN_ENABLED | Enables the Qobuz plugin, defaults to no |
| QOBUZ_APP_ID | Qobuz application id |
| QOBUZ_APP_SECRET | Your Qobuz application Secret |
| QOBUZ_USERNAME | Qobuz account username |
| QOBUZ_PASSWORD | Qobuz account password |
| QOBUZ_FORMAT_ID | The Qobuz format identifier, i.e. a number which chooses the format and quality to be requested from Qobuz. The default is 5 (320 kbit/s MP3). |
Please find here the variables used to configure scrobbling. All of those are of course optional.
Credentials of course go in pairs, so in order to enable one serve, you must provide both username and password.
| VARIABLE | DESCRIPTION |
|---|---|
| LASTFM_USERNAME | Username for Last.fm |
| LASTFM_PASSWORD | Password for Last.fm |
| LIBREFM_USERNAME | Username for Libre.fm |
| LIBREFM_PASSWORD | Password for Libre.fm |
| JAMENDO_USERNAME | Username for Jamendo |
| JAMENDO_PASSWORD | Password for Jamendo |
| SCRIBBLE_VERBOSE | How verbose mpdscribble's logging should be. Default is 1. |
| SCROBBLER_MPD_HOSTNAME | Set when using host mode, defaults to localhost |
| SCROBBLER_MPD_PORT | Set when using host mode, defaults to 6600 |
| PROXY | Proxy support for mpdscribble. Example value: http://the.proxy.server:3128 |
You can define additional outputs of various types. Refer to the following paragraphs.
For each type, that you can add up to 20 (or what is specified for the variable MAX_ADDITIONAL_OUTPUTS_BY_TYPE) additional outputs for each type. In order to specify distinct values, you can add _1, _2 to every variable names in this set. The first output does not require to specify _0, that index is implicit.
The output name of those outputs, if not explicitly set, is created by appending with _1, _2, ... to the defaut name, so in the case of PulseAudio, the names of output will be PulseAudio_1, PulseAudio_2, ...
Additional alsa outputs can be configured using the following variables:
| VARIABLE | DESCRIPTION |
|---|---|
| ALSA_OUTPUT_CREATE | Set to yes if you want to create an additional alsa output |
| ALSA_OUTPUT_ENABLED | Sets the output as enabled if set to yes, otherwise mpd's default behavior applies |
| ALSA_OUTPUT_NAME | The name of the alsa output, defaults to alsa |
| ALSA_OUTPUT_PRESET | Use an Alsa preset for easier configuration |
| ALSA_OUTPUT_DEVICE | The audio device. Common examples: hw:DAC or hw:x20 or hw:X20 for usb dac based on XMOS chips. Defaults to default |
| ALSA_OUTPUT_AUTO_FIND_MIXER | Allows to auto-select the mixer for easy hardware volume configuration |
| ALSA_OUTPUT_MIXER_TYPE | Mixer type, defaults to hardware |
| ALSA_OUTPUT_MIXER_DEVICE | Mixer device, defaults to default |
| ALSA_OUTPUT_MIXER_CONTROL | Mixer Control, defaults to PCM |
| ALSA_OUTPUT_MIXER_INDEX | Mixer Index, defaults to 0 |
| ALSA_OUTPUT_ALLOWED_FORMATS_PRESET | Alternative to ALSA_OUTPUT_ALLOWED_FORMATS. Possible values: 8x, 4x, 2x, 8x-nodsd, 4x-nodsd, 2x-nodsd |
| ALSA_OUTPUT_ALLOWED_FORMATS | Sets allowed formats |
| ALSA_OUTPUT_FORMAT | Sets output format |
| ALSA_OUTPUT_AUTO_RESAMPLE | If set to no, then libasound will not attempt to resample. In this case, the user is responsible for ensuring that the requested sample rate can be produced natively by the device, otherwise an error will occur. |
| ALSA_OUTPUT_STOP_DSD_SILENCE | If enabled, silence is played before manually stopping playback (“stop” or “pause”) in DSD mode (native DSD or DoP). This is a workaround for some DACs which emit noise when stopping DSD playback. Can be left blank or to yes or no |
| ALSA_OUTPUT_THESYCON_DSD_WORKAROUND | If enabled, enables a workaround for a bug in Thesycon USB audio receivers. On these devices, playing DSD512 or PCM causes all subsequent attempts to play other DSD rates to fail, which can be fixed by briefly playing PCM at 44.1 kHz. Can be left blank or to yes or no |
| ALSA_OUTPUT_INTEGER_UPSAMPLING | If one or more ALSA_ALLOWED_FORMATS are set and INTEGER_UPSAMPLING is set to yes, the formats which are evenly divided by the source sample rate are preferred. The ALSA_ALLOWED_FORMATS list is processed in order as provided to the container. So if you want to upsample, put higher sampling rates first. Using this feature causes a patched version of mpd to be run. Use at your own risk. |
| ALSA_OUTPUT_INTEGER_UPSAMPLING_ALLOWED | Allows selection of sample rates to be upsampled. If set, only specified values are allowed. The values should respect the same format user for ALSA_OUTPUT_ALLOWED_FORMATS |
| ALSA_OUTPUT_INTEGER_UPSAMPLING_ALLOWED_PRESET | Preset for ALSA_OUTPUT_INTEGER_UPSAMPLING_ALLOWED. Allowed values are base (for 44.1kHz and 48.0kHz) and 44 for 44.1kHz only |
| ALSA_OUTPUT_DOP | Enables Dsd-Over-Pcm. Possible values: yes or no. Empty by default: this it lets mpd handle dop setting. |
Refer to the MPD documentation for the meaning of the variables.
Remember to setup user mode when using PulseAudio outputs, otherwise they won't work.
Additional PulseAudio outputs can be configured using the following variables:
| VARIABLE | DESCRIPTION |
|---|---|
| PULSE_AUDIO_OUTPUT_CREATE | Set to yes if you want to create an additional PulseAudio output |
| PULSE_AUDIO_OUTPUT_ENABLED | Sets the output as enabled if set to yes, otherwise mpd's default behavior applies |
| PULSE_AUDIO_OUTPUT_NAME | The name of the PulseAudio output, defaults to PulseAudio |
| PULSE_AUDIO_OUTPUT_SINK | Specifies the name of the PulseAudio sink MPD should play on |
| PULSE_AUDIO_OUTPUT_MEDIA_ROLE | Media role for the PulseAudio output |
| PULSE_AUDIO_OUTPUT_SCALING_FACTOR | Scaling factor for the PulseAudio output |
Refer to the MPD documentation for the meaning of the variables.
See here.
See here.
See here.
See some usage examples here.
If at least one set of credentials for Last.fm, Libre.fm or Jamendo are provided, mpdscribble will be started and it will scrobble the songs you play.
You can provide credential using the environment variables or using credential files stored in the volume /user/config.
The relevant files are:
- lastfm.txt
- librefm.txt
- jamendo.txt
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, 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
Please find documentation here.
See this document.
See this document.
