pactl: A new volume widget using pactl only

Add a new volume widget that is using pactl only for controlling volume
and selecting sources and sinks. It therefore works with PulseAudio or
PipeWire as backend, unlike the original Volume widget.

The code is split as follows:
  - volume.lua contains the UI logic
  - pactl.lua contains the pactl interfacing and output parsing
  - utils.lua contains some shared helper routines

It is heavily based on the original Volume code and supports the same
configuration options and uses the same widget code.

1 files changed, 54 insertions, 0 deletions

diff --git a/pactl-widget/README.md b/pactl-widget/README.md
new file mode 100644
index 0000000..24e4471
--- /dev/null
+++ b/pactl-widget/README.md
@@ -0,0 +1,54 @@
+# Pactl volume widget
+
+This is a volume widget that uses `pactl` only for controlling volume and
+selecting sinks and sources. Hence, it can be used with PulseAudio or PipeWire
+likewise, unlike the original Volume widget.
+
+Other than that it is heavily based on the original widget, including its
+customization and icon options. For screenshots, see the original widget.
+
+## Installation
+
+Clone the repo under **~/.config/awesome/** and add widget in **rc.lua**:
+
+```lua
+local volume_widget = require('awesome-wm-widgets.pactl-widget.volume')
+...
+s.mytasklist, -- Middle widget
+	{ -- Right widgets
+    	layout = wibox.layout.fixed.horizontal,
+        ...
+        -- default
+        volume_widget(),
+        -- customized
+        volume_widget{
+            widget_type = 'arc'
+        },
+```
+
+### Shortcuts
+
+To improve responsiveness of the widget when volume level is changed by a shortcut use corresponding methods of the widget:
+
+```lua
+awful.key({}, "XF86AudioRaiseVolume", function () volume_widget:inc(5) end),
+awful.key({}, "XF86AudioLowerVolume", function () volume_widget:dec(5) end),
+awful.key({}, "XF86AudioMute", function () volume_widget:toggle() end),
+```
+
+## Customization
+
+It is possible to customize the widget by providing a table with all or some of
+the following config parameters:
+
+### Generic parameter
+
+| Name | Default | Description |
+|---|---|---|
+| `mixer_cmd` | `pavucontrol` | command to run on middle click (e.g. a mixer program) |
+| `step` | `5` | How much the volume is raised or lowered at once (in %) |
+| `widget_type`| `icon_and_text`| Widget type, one of `horizontal_bar`, `vertical_bar`, `icon`, `icon_and_text`, `arc` |
+| `device` | `@DEFAULT_SINK@` | Select the device name to control |
+
+For more details on parameters depending on the chosen widget type, please
+refer to the original Volume widget.