[Feature] Drop support for PULSE as OUTPUT_MODE (already deprecated) #224 (#226)

Author: GioF71

Dockerfile

@@ -88,14 +88,11 @@ ENV INTEGER_UPSAMPLING ""
 ENV ALSA_AUTO_FIND_MIXER ""
 
 ENV OUTPUT_MODE ""
-ENV PULSEAUDIO_OUTPUT_NAME ""
-ENV PULSEAUDIO_OUTPUT_ENABLED ""
-ENV PULSEAUDIO_OUTPUT_MEDIA_ROLE ""
-ENV PULSEAUDIO_OUTPUT_SCALE_FACTOR ""
 
 ENV NULL_OUTPUT_NAME ""
 ENV NULL_OUTPUT_SYNC ""
 
+# ALSA Outputs
 ENV ALSA_OUTPUT_CREATE ""
 ENV ALSA_OUTPUT_ENABLED ""
 ENV ALSA_OUTPUT_NAME ""
@@ -116,13 +113,15 @@ ENV ALSA_OUTPUT_INTEGER_UPSAMPLING_ALLOWED ""
 ENV ALSA_OUTPUT_INTEGER_UPSAMPLING_ALLOWED_PRESET ""
 ENV ALSA_OUTPUT_DOP ""
 
+# PulseAudio Outputs
 ENV PULSE_AUDIO_OUTPUT_CREATE ""
 ENV PULSE_AUDIO_OUTPUT_ENABLED ""
 ENV PULSE_AUDIO_OUTPUT_NAME ""
 ENV PULSE_AUDIO_OUTPUT_SINK ""
 ENV PULSE_AUDIO_OUTPUT_MEDIA_ROLE ""
 ENV PULSE_AUDIO_OUTPUT_SCALE_FACTOR ""
 
+# HTTPD Outputs
 ENV HTTPD_OUTPUT_CREATE ""
 ENV HTTPD_OUTPUT_ENABLED ""
 ENV HTTPD_OUTPUT_NAME ""
@@ -135,6 +134,7 @@ ENV HTTPD_OUTPUT_TAGS ""
 ENV HTTPD_OUTPUT_FORMAT ""
 ENV HTTPD_MIXER_TYPE ""
 
+# ShoutCast/IceCast Outputs
 ENV SHOUT_OUTPUT_CREATE ""
 ENV SHOUT_OUTPUT_ENABLED ""
 ENV SHOUT_OUTPUT_NAME ""
@@ -154,6 +154,7 @@ ENV SHOUT_MIXER_TYPE ""
 
 ENV INPUT_CACHE_SIZE ""
 
+# Qobuz Input Plugin
 ENV QOBUZ_PLUGIN_ENABLED ""
 ENV QOBUZ_APP_ID ""
 ENV QOBUZ_APP_SECRET ""

README.md

@@ -1,6 +1,6 @@
 # mpd-alsa-docker
 
-A Docker image for mpd with support for both Alsa (`alsa`) and PulseAudio (`pulse`).  
+A Docker image for mpd with support for both Alsa and PulseAudio.  
 It also includes `mpdscribble`. In alternative, you can use [mpd-scrobbler-docker](https://github.com/GioF71/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 (upstream version available as well).  
@@ -54,14 +54,18 @@ Getting the image from DockerHub is as simple as typing:
 
 ## Usage
 
+### Important changes
+
+Starting with release `2023-02-04`, you will not be able to use the deprecated `PULSE` as `OUTPUT_MODE`. Refer to the next chapter for more information about how to change the configuration.  
+In case of difficulties, you can fall back to any image before `2023-02-04`, as those will still work with this deprecated configuration.  
+
 ### What is about to change
 
 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` still defaults to `ALSA` for compatibility and will yield the creation of a ALSA *main* player, but the default for this variable will eventually become `NONE` (no *main* player). At the end of the process, the variable `OUTPUT_MODE` will completely disappear.  
-You can still use `OUTPUT_MODE` set to `PULSE`, which creates a PulseAudio *main* output.  
-In both cases, I suggest you change the configuration as suggested, and use the variables from the appropriate sections below for [Alsa](https://github.com/GioF71/mpd-alsa-docker#alsa-additional-outputs) and [PulseAudio](https://github.com/GioF71/mpd-alsa-docker#pulseaudio-additional-outputs), otherwise, in time, your configurations will not be functional anymore.  
+In any case, I suggest you change the configuration as suggested, and use the variables from the appropriate sections below for [Alsa](https://github.com/GioF71/mpd-alsa-docker#alsa-additional-outputs) and [PulseAudio](https://github.com/GioF71/mpd-alsa-docker#pulseaudio-additional-outputs), otherwise, in time, your configurations will not be functional anymore.  
 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
@@ -105,13 +109,13 @@ DATABASE_MODE|Can be `simple` (default) or `proxy`
 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`
 MUSIC_DIRECTORY|Location of music files, defaults to `/music`
-OUTPUT_MODE|Output mode, can be `alsa` (still default but **deprecated**, you should use `ALSA_OUTPUT_CREATE` set to `yes`), `pulse` (**deprecated**, you should use `PULSE_AUDIO_OUTPUT_CREATE` set to `yes`), `null` or `none`. For `pulse` mode, running in `user` mode is required. Note that `none` does not create any output, leaving the task to the variables dedicated to additional outputs
+OUTPUT_MODE|Output mode, can be `alsa` (still default but **deprecated**, you should use `ALSA_OUTPUT_CREATE` set to `yes`), `null` or `none`.
 MPD_BIND_ADDRESS|The MPD listen address, 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](#user-mode). Enforced when `OUTPUT_MODE` is set to `pulse` (**deprecated** value) or when `PULSE_AUDIO_OUTPUT_CREATE` is set to `yes`
-PUID|User id. Defaults to `1000`. The user/group will be created for `pulse` mode regardless of the `USER_MODE` variable.
-PGID|Group id. Defaults to `1000`. The user/group will be created for `pulse` mode regardless of the `USER_MODE` variable.
-AUDIO_GID|`audio` group id from the host machine. Mandatory for `alsa` output in user mode. See [User mode](#user-mode).
+USER_MODE|Set to `Y` or `YES` for user mode. Case insensitive. See [User mode](#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 regardless of the `USER_MODE` variable.
+PGID|Group id. Defaults to `1000`. The user/group will be created when a PulseAudio output is created regardless of the `USER_MODE` variable.
+AUDIO_GID|`audio` group id from the host machine. Mandatory for `alsa` output in user mode. See [User mode](https://github.com/GioF71/mpd-alsa-docker/blob/main/doc/user-mode.md).
 INPUT_CACHE_SIZE|Sets the input cache size. Example value: `1 GB`
 NULL_OUTPUT_NAME|Name of the `null` output
 NULL_OUTPUT_SYNC|Sync mode for the `null` output, can be `yes` (default) or `no`
@@ -120,7 +124,7 @@ MPD_ENABLE_LOGGING|Defaults to `yes`, set to `no` to disable
 MPD_LOG_LEVEL|Can be `default` or `verbose`
 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 using Pulse mode.
+HYBRID_DSD_ENABLED|Hybrid dsd is enabled by default, set to `no` to disable. Disabled when at least one PulseAudio output is created.
 MAX_OUTPUT_BUFFER_SIZE|The maximum size of the output buffer to a client (maximum response size). Default is 8192 (8 MiB). Value in KBytes.
 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`
@@ -151,21 +155,7 @@ THESYCON_DSD_WORKAROUND|If enabled, enables a workaround for a bug in Thesycon U
 ALSA_ALLOWED_FORMATS_PRESET|Alternative to `ALSA_ALLOWED_FORMATS`. Possible values: `8x`, `4x`, `2x`, `8x-nodsd`, `4x-nodsd`, `2x-nodsd`
 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.  
 
-Avoid deprecated configurations and refer to [this](#alsa-additional-outputs) section.
-
-#### Main output as PULSE (**Deprecated**)
-
-Please find here the relevant (but *deprecated*) variables when OUTPUT_MODE is set to `PULSE`
-
-VARIABLE|DESCRIPTION
-:---|:---
-PULSEAUDIO_OUTPUT_NAME|PulseAudio output name, defaults to `PulseAudio`
-PULSEAUDIO_OUTPUT_ENABLED|Sets the output as enabled if set to `yes`, otherwise mpd's default behavior applies
-PULSEAUDIO_OUTPUT_SINK|Specifies the name of the PulseAudio sink MPD should play on
-PULSEAUDIO_OUTPUT_MEDIA_ROLE|Specifies a custom media role that MPD reports to PulseAudio, defaults to `music`
-PULSEAUDIO_OUTPUT_SCALE_FACTOR|Specifies a linear scaling coefficient (ranging from `0.5` to `5.0`) to apply when adjusting volume through MPD. For example, chosing a factor equal to `0.7` means that setting the volume to 100 in MPD will set the PulseAudio volume to 70%, and a factor equal to `3.5` means that volume 100 in MPD corresponds to a 350% PulseAudio volume.  
-
-Avoid deprecated configurations and refer to [this](#pulseaudio-additional-outputs) section.
+Avoid deprecated configurations and refer to [this](https://github.com/GioF71/mpd-alsa-docker/blob/main/README.md#alsa-additional-outputs) section.
 
 #### SOXR Plugin
 
@@ -258,6 +248,7 @@ Note that you can add up to 20 (or what is specified for the variable `MAX_ADDIT
 
 #### PulseAudio additional outputs
 
+Remember to setup [user mode](https://github.com/GioF71/mpd-alsa-docker/blob/main/doc/user-mode.md) when using PulseAudio outputs, otherwise they won't work.  
 Additional PulseAudio outputs can be configured using the following variables:
 
 VARIABLE|OPTIONAL|DESCRIPTION

app/bin/any-of.sh

@@ -2,9 +2,6 @@
 
 any_pulse() {
     result=0
-    if [ "${OUTPUT_MODE^^}" == "PULSE" ]; then
-        result=1
-    fi
     if [[ $result -eq 0 ]]; then
         # if at least one additional pulse audio output is requested
         if [[ "${PULSE_AUDIO_OUTPUT_CREATE^^}" == "YES" ]]; then

app/bin/run-mpd.sh

@@ -259,7 +259,6 @@ if [ -n "${ZEROCONF_NAME}" ]; then
     echo "zeroconf_name \"${ZEROCONF_NAME}\"" >> $MPD_ALSA_CONFIG_FILE
 fi
 
-
 ## disable wildmidi decoder
 echo "decoder {" >> $MPD_ALSA_CONFIG_FILE
 echo "  plugin \"wildmidi\"" >> $MPD_ALSA_CONFIG_FILE
@@ -461,40 +460,6 @@ if [ "${OUTPUT_MODE^^}" == "ALSA" ]; then
     fi
     echo "  enabled \"yes\"" >> $MPD_ALSA_CONFIG_FILE
     echo "}" >> $MPD_ALSA_CONFIG_FILE
-elif [ "${OUTPUT_MODE^^}" == "PULSE" ]; then
-    echo "OUTPUT_MODE [$OUTPUT_MODE] is deprecated and will be removed in the future"
-    echo "You should use PULSE_AUDIO_OUTPUT_CREATE=yes instead"
-    echo "audio_output {" >> $MPD_ALSA_CONFIG_FILE
-    echo "  type \"pulse\"" >> $MPD_ALSA_CONFIG_FILE
-    if [ -z "${PULSEAUDIO_OUTPUT_NAME}" ]; then
-        PULSEAUDIO_OUTPUT_NAME="PulseAudio"
-    fi
-    echo "  name \"${PULSEAUDIO_OUTPUT_NAME}\"" >> $MPD_ALSA_CONFIG_FILE
-    pulse_enabled=""
-    if [ -n "${PULSEAUDIO_OUTPUT_ENABLED}" ]; then
-        if [[ "${PULSEAUDIO_OUTPUT_ENABLED^^}" == "YES" || "${PULSEAUDIO_OUTPUT_ENABLED^^}" == "Y" ]]; then
-            pulse_enabled=yes
-        elif [[ "${PULSEAUDIO_OUTPUT_ENABLED^^}" == "NO" || "${PULSEAUDIO_OUTPUT_ENABLED^^}" == "N" ]]; then
-            pulse_enabled=no
-        else
-            echo "Invalid PULSEAUDIO_OUTPUT_ENABLED=[${PULSEAUDIO_OUTPUT_ENABLED}]"
-            exit 9
-        fi        
-    fi
-    if [ -n "${pulse_enabled}" ]; then
-        echo "  enabled \"${pulse_enabled}\"" >> $MPD_ALSA_CONFIG_FILE
-    fi
-    unset pulse_enabled
-    if [ -n "${PULSEAUDIO_OUTPUT_MEDIA_ROLE}" ]; then
-        echo "  media_role \"${PULSEAUDIO_OUTPUT_MEDIA_ROLE}\"" >> $MPD_ALSA_CONFIG_FILE
-    fi
-    if [ -n "${PULSEAUDIO_OUTPUT_SINK}" ]; then
-        echo "  sink \"${PULSEAUDIO_OUTPUT_SINK}\"" >> $MPD_ALSA_CONFIG_FILE
-    fi
-    if [ -n "${PULSEAUDIO_OUTPUT_SCALE_FACTOR}" ]; then
-        echo "  scale_factor \"${PULSEAUDIO_OUTPUT_SCALE_FACTOR}\"" >> $MPD_ALSA_CONFIG_FILE
-    fi
-    echo "}" >> $MPD_ALSA_CONFIG_FILE
 elif [ "${OUTPUT_MODE^^}" == "NULL" ]; then
     echo "audio_output {" >> $MPD_ALSA_CONFIG_FILE
     echo "  enabled \"yes\"" >> $MPD_ALSA_CONFIG_FILE

doc/change-history.md

@@ -2,6 +2,7 @@
 
 Date|Major Changes
 :---|:---
+2023-02-04|Dropped support for `PULSE` as `OUTPUT_MODE`
 2023-02-03|Add support for `ALSA_OUTPUT_INTEGER_UPSAMPLING_ALLOWED`
 2023-02-03|Bump to mpd version `v0.23.12`
 2023-01-30|Add support for `AUDIO_BUFFER_SIZE`

doc/example-configurations.md

@@ -101,7 +101,7 @@ services:
 
 This configuration uses a custom soxr resampling configuration, inspired from this article: [Archimago - MUSINGS: More fun with digital filters!](https://archimago.blogspot.com/2018/01/musings-more-fun-with-digital-filters.html).  
 This particular configuration will upsample 44.1kHz, 88.2kHz, 176.4kHz streams to 352.8kHz and 48kHz, 96kHz, 192kHz to 384kHz, leaving dsd streams as they are.  
-AUDIO_GID here is 29, but you will need to find the gid of the `audio` group on your specific installation as described in [user mode](user-mode.md).
+AUDIO_GID here is 29, but you will need to find the gid of the `audio` group on your specific installation as described in [user mode](https://github.com/GioF71/mpd-alsa-docker/blob/main/doc/user-mode.md).
 
 ## Requirements for alsa mode