README

Minimalistic amixer-based volume control for the window manager StumpWM
-----------------------------------------------------------------------

Just support the three volume control keys on many keyboards.

Depends on amixer (which is executed via RUN-SHELL-COMMAND).

Hacked by Max-Gerd Retzlaff. The primary source for this module
is https://github.com/m-g-r/stumpwm-modules-mgr


loading and configuration
-------------------------

You can automatically load the module by adding this to your StumpWM
init file:

  (load-module "stump-volume-control")

Then assign the three commands volume-up, volume-down, and
volume-toggle-mute globally to some keys. If your keyboards has got
them you can use the typical volume control keys:

  (define-key *top-map* (kbd "XF86AudioRaiseVolume") "volume-up")
  (define-key *top-map* (kbd "XF86AudioLowerVolume") "volume-down")
  (define-key *top-map* (kbd "XF86AudioMute") "volume-toggle-mute")

You have to add it yourself to your StumpWM init file as I consider it
bad manners to define global keys in a module.


selecting the sound card
------------------------

The module uses the sound card that ALSA considers to be your first one
(that is, sound card number 0) by default. You can change this by
altering the value of the variable STUMP-VOLUME-CONTROL:*SOUND-CARD*.
For example, by adding to your StumpWM init file:

  (setf stump-volume-control:*sound-card* 1)

Alternatively, you can try to set the variable to NIL to not select
any specific sound card explicitly:

  (setf stump-volume-control:*sound-card* nil)

Or you can set it to a device name, for example "default":

  (setf stump-volume-control:*sound-card* "default")

Note, internally device numbers are translated to the device name
of pattern "hw:<number>", so these two calls have the same effect:

  (setf stump-volume-control:*sound-card* 1)
  (setf stump-volume-control:*sound-card* "hw:1")


PulseAudio compatibility
------------------------

This minimalistic volume control module works mainly for ALSA as it uses
amixer, the "command-line mixer for [the] ALSA sound card driver".
It might work also for PulseAudio as there are compatibility layers
but there might be some shortcomings.

Here is a little workaround to address one problem that was observed:
PulseAudio mutes more than it unmutes. So this module includes a hack
that will explicitly unmute the audio outputs when toggling audio back
on. It can be controlled by the list of audio outputs stored in the
variable STUMP-VOLUME-CONTROL:*PULSE-AUDIO-UNMUTE-OUTPUTS*.

By default, it is set to '("Speaker" "Headphone") as "Speaker" and
"Headphone" are the generic output names and thus it might just work.
But if your hardware uses special names, such as, for example,
"Megaphone" and "Leslie speaker", add this to your StumpWM init file:

  (setf stump-volume-control:*pulse-audio-unmute-outputs*
        '("Megaphone" "Leslie speaker"))

Change to NIL if you just use ALSA and do not want the extra calls to
be executed (which will fail silently if you do not have the outputs),
by adding to your  StumpWM init file instead:

  (setf stump-volume-control:*pulse-audio-unmute-outputs* nil)

(And now I have again spend more time on the dreaded PulseAudio...)