swob (sway+wob helper)
======================

This is a simple/stupid helper script and config files to provide volume and
brightness controls under Wayland using [wob]. Sway is *not* mandatory (the
helper script doesn't depend on sway or any wlroots features); the name is
simply because sway was the first compositor I configured this for. Other
compositor configurations are available; see [§Installation](#installation).

[wob]: https://github.com/francma/wob

Calling wob from a script or config file is not too intuitive, because it
panics if the process it's reading from hangs up. The helper script ensures
that there is a process keeping wob open for a few seconds to allow it to
time out, and potentially respond without invoking a whole new wob instance
on successive taps of the volume/brightness controls, especially with pauses
between. It doesn't go the way of keeping an always-open wob instance,
instead trying to balance invoking as needed with not starting a whole new
binary unnecessarily with every tap.

Dependencies
------------

- POSIX sh, sed and mkfifo(1); non-POSIX mktemp(1) (all pretty universally
  available)
- [wob]
- [brightnessctl](https://github.com/Hummer12007/brightnessctl)
- For volume, at least one of:
  - amixer, for [ALSA](https://www.alsa-project.org)
  - [wireplumber and wpctl](https://pipewire.pages.freedesktop.org/wireplumber)
    for pipewire
  - pactl for [PulseAudio](https://www.freedesktop.org/wiki/Software/PulseAudio)
    - As with anything pertaining to Poettering, pactl doesn't play nice,
      so the pactl backend is the slowest of the three: requires three calls
      to pactl and two to sed, compared with two calls to wpctl and one to
      amixer (each with only one call to sed). It is generally recommended to
      use one of the other two wherever possible

Installation
------------

<ul>
<li>
Configure your wayland compositor to bind the XF86 volume/brightness
controls to swob.sh. Example configuration is provided for the following:
<dl>
<dt>Sway (options):</dt>
<dd>Copy the sway config snippet into your own sway config file...</dd>
<dd><em>Or</em> source it from that file...</dd>
<dd><em>Or</em> copy it into /etc/sway/config.d</dd>
<dt>dwl:</dt>
<dd>An example patch for config.h is available at <a
href="dwl-config.h.patch">dwl-config.h.patch</a></dd>
</dl>
</li>
<li> Put swob.sh on your PATH, or set your wayland compositor's config to
     point to its absolute location. </li>
</ul>

Environment variables
---------------------

You can set the `SWOB_MAX_VOLUME` environment variable to set the maximum volume.

```conf
# Your Sway config

set $SWOB_MAX_VOLUME 120

bindsym --locked XF86AudioLowerVolume exec exec env SWOB_MAX_VOLUME=$SWOB_MAX_VOLUME swob.sh volume 5%-
bindsym --locked XF86AudioRaiseVolume exec exec env SWOB_MAX_VOLUME=$SWOB_MAX_VOLUME swob.sh volume 5%+
```

Theming
-------

For wob styling when the value is above the threshold, there are styles: `overflow_bar_color`, `overflow_background_color`, `overflow_border_color`.

```ini
[style.mute]
background_color = af0000
background_color = af0000
overflow_bar_color = FF5555
overflow_border_color = 000000
```

Copying
-------

Copyright &copy; 2023-2025 The Remph <lhr@disroot.org>

This program is free software: you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the Free
Software Foundation, either version 3 of the License, or (at your option)
any later version.

This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
more details.

A copy of the full GPL can be found at <https://www.gnu.org/licenses/GPL>.