Skip to content

Easily run mpd with Alsa or PulseAudio output with Docker. Upsampling 2x 4x 8x with "Goldilocks" settings by Archimago. Scrobbling support.

License

Notifications You must be signed in to change notification settings

GioF71/mpd-alsa-docker

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

mpd-alsa-docker

References

First and foremost, the reference to the awesome projects:

Music Player Daemon
MPDScribble

Support

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

Description

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.

Available Archs on Docker Hub

  • linux/amd64
  • linux/arm/v7
  • linux/arm64/v8
  • linux/arm/v5 (for debian-based builds)

Links

Source: GitHub
Images: DockerHub

Why

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.

Prerequisites

See this page.

Get the image

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.

MPD Source code

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:

Image tags

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

Usage

Important changes

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.

What has changed

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.

User mode

See this page.

Volumes

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

User Configuration volume

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.

Environment Variables

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

SOXR Plugin

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

ReplayGain Settings

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

Qobuz Plugin

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

Scrobbling

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

Additional Outputs

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

ALSA additional outputs

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.

PulseAudio additional outputs

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.

HTTPD additional outputs

See here.

Shout additional outputs

See here.

Null additional outputs

See here.

Examples

See some usage examples here.

Support for Scrobbling

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

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

Equalization support

Please find documentation here.

Build

See this document.

Change history

See this document.