README.md

   1 # 🎵 Zvuchno
   2
   3 Yet another simple PulseAudio volume notification service over `libnotify`. The service provides notification for:
   4
   5 - Volume up/down
   6 - Volume mute/unmute
   7
   8 ![In action](zvuchno-demo.gif)
   9
  10 Change of volume's level is visualized using a textual progress bar. No graphics, no other extra complex use-cases is an intention.
  11 The text **is customizable**: ASCII and Emojis.
  12
  13 The app was written as tiny entertainment to close a gap in my existing [i3wm](https://i3wm.org/) setup. My alternative to `volnoti` daemon.
  14
  15 ## Build & Configuration
  16
  17 Build:
  18 - `$ git clone https://git.thekondor.net/zvuchno.git` or (`$ git clone https://github.com/thekondor/zvuchno`)
  19 - `$ cd zvuchno && go build`
  20
  21 Run w/o any configuration file to use default settings. Or use `config.sample.yml` as a foundation for personal one.
  22 The configuration file could be stored either as `$HOME/.zvuchno.yml` or `$XDG_CONFIG_HOME/zvuchno.yml`.
  23
  24 The application heavily relies on running PulseAudio daemon as well as available DBus session.
  25
  26 ### Format
  27
  28 The final volume's level representation is defined via `appearance.format.full` key. The value's format is simply a Go's template.
  29 `{{ .Percent }}` is expanded to current volume's level in percent.
  30 `{{ .Bar}}` is expanded to a textual representation of current volume's level.
  31
  32 Bar's representation is defined via `appearance.format.bar` key. The value is 5-character string. Example: `[=>-]`, where
  33
  34 1. `[` is a left border of the bar.
  35 2. `=` is a floating part of the bar.
  36 3. `>` is a pointer of the floating part showing current volume's level.
  37 4. `-` is a remaining space for the bar to float to.
  38 5. `]` is a right border of the bar.
  39
  40 Any character here could be a regular ASCII one as well as a fancy Emoji (should be supported by active font)
  41
  42 ## Usage
  43
  44 As simple as:
  45
  46 ```shell
  47 $ zvuchno
  48 ```
  49
  50 or to be added to `~/.xinitrc` (or `i3wm/config`... whatever!) for a launch on WM startup:
  51
  52 ```
  53 # Mind '&' at the end!
  54 /path/to/zvuchno &
  55 ```
  56